ShipEngine Ruby SDK
The Official Ruby SDK for ShipEngine API offering low-level access as well as convenience methods.
Quick Start
Install the ShipEngine SDK Gem via RubyGems
gem install shipengine_sdk
- The only configuration requirement is an API Key.
Methods
-
create_label_from_rate
- When retrieving rates for shipments using theget_rates
method, the returned information contains arate_id
property that can be used to purchase a label without having to refill in the shipment information repeatedly. -
create_label_from_shipment_details
- Purchase and print a label for shipment. -
get_rates
- Given some shipment details and rate options, this method returns a list of rate quotes. -
list_carrier_accounts
- Returns a list of carrier accounts that have been connected through the ShipEngine dashboard. -
track_by_label_id
- Track a package by its associated label ID. -
track_using_carrier_code_and_tracking_number
- Track a package by its associated trackng number. -
validate_addresses
- Indicates whether the provided addresses are valid. If the addresses are valid, the method returns a normalized version based on the standards of the country in which the address resides. If an address cannot be normalized, an error is returned. -
void_label_by_id
- Void a label by its ID.
Class Objects
- ShipEngine - A configurable entry point to the ShipEngine API SDK, this class provides convenience methods for various ShipEngine API Services.
Instantiate ShipEngine Class
require "shipengine"
api_key = ENV["SHIPENGINE_API_KEY"]
shipengine = ShipEngine::Client.new(api_key)
Contributing
Install dependencies
- You will need to
gem install bundler
before using the following command to install dependencies from the Gemfile.
./bin/setup
Committing
This project adheres to the Conventional Commits specification.
Pre-Commit/Pre-Push Hooks
This project makes use of Overcommit to enforce pre-commit/push hooks
.
Overcommit will be downloaded and initialized as part of running the ./bin/setup
script, as outlined in the previous section.
- From then on when you commit code
rake lint
will run, and when you push coderake test
andrake lint
will run. Upon failure of either of these, you can runrake fix
to auto-fix lint issues and format code, and re-commit/push.
Testing & Development
- While you are writing tests as you contribute code you can run tests ad-hoc via
rake
using the following command:
rake test
- You can run tests and have them re-run when you save changes to a given file with
guard
.
guard
Lastly, you can format code & auto-fix lint errors
with the following:
rake fix
Note:
guard
also provides a repl after tests run for quick repl development.
Repl Development
- You can start a
pry
repl that already hasshipengine
required bun running the following command.
./bin/console
If you prefer
irb
overpry
, you can follow the instructions in the ./bin/console file. Please DO NOT commit any changes you make to that file, unless they are improvements to the console workflow.
Publishing
Publishing new versions of the SDK to RubyGems is handled on GitHub via the Release Please GitHub Actions workflow. Learn more about about Release PRs, updating the changelog, and commit messages here.