easyship 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e185adc98f576e3cf15ffc1ca38edf2dca8a0ffa580f68a731c900c3632392b
-  data.tar.gz: e15d52b3f530c58883fb8f50b086db537939ceed2fc1afff3579ea6aa82373c1
+  metadata.gz: 7b584f647a6c1e9cd0379a94b3fc479c8f82691ab1ff8a36d797dae1c24e9c89
+  data.tar.gz: 5f288ce157f0b0b1c5e19f6c8a0a7851bf2bf1c5acb1c22b6660656ceed10204
 SHA512:
-  metadata.gz: 707860b193dbc25e916f8d0e5e68a2a3c8e34498e523871e243cf487f1e5c4c2469ed274099899b1b50c22598dc085906eca132f9e537515c43bf03428040c02
-  data.tar.gz: ec38670ff9d6626bc62485d8c836d00c1efb8e4a8218214c5c6b36b01570ad3b71906511c2459dc4a74b3a5ed91e3d3f91bd5f07586e75d481dc2ebf142a4d9a
+  metadata.gz: 22a0cbabb4582b714d56827fdd6f29bee92958900b2204ba3fce15a62ed85139e327dcfaa39dcf3f935cdeab0440424fa00bf044f003282ac9212837c97a83a2
+  data.tar.gz: fd30c1f4d75e89f2cc01ea8b97040cd19717af6f5e7d6bdb26a661507de197882be0f10f9cfaae2f49ed92d65e8aa5c8cd9f6ee3b24e4ef747da158012a94abc

data/.rubocop.yml

@@ -12,3 +12,6 @@ Style/Copyright:
 
 RSpec/ExampleLength:
   Max: 10
+
+RSpec/NestedGroups:
+  Max: 5

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [v0.4.0](https://github.com/mmarusyk/easyship/tree/v0.4.0) - 2026-01-24
+
+### Added
+- Support for custom headers by @mmarusyk in https://github.com/mmarusyk/easyship/pull/14
+
 ## [v0.3.0](https://github.com/mmarusyk/easyship/tree/v0.3.0) - 2025-11-29
 
 ### Added

data/README.md

@@ -58,10 +58,10 @@ Easyship.configure do |config|
 end
 ```
 
-Configuration supports the next keys: `url`, `api_key`, `per_page`, `requests_per_second`, `requests_per_minute`.
+Configuration supports the next keys: `url`, `api_key`, `per_page`, `requests_per_second`, `requests_per_minute`, `headers`.
 
 ### Making Requests
-`Easyship::Client` supports the next methods: `get`, `post`, `put`, `delete`.
+`Easyship::Client` supports the next methods: `get`, `post`, `put`, `patch`, `delete`.
 ```ruby
 Easyship::Client.instance.get('/2023-01/account')
 ```
@@ -174,6 +174,104 @@ Easyship::Client.instance.get('/2023-01/shipments', {
 end
 ```
 
+### Custom Headers
+
+You can pass custom headers both globally (via configuration) and per-request.
+
+**Global Headers (via Configuration):**
+
+```ruby
+Easyship.configure do |config|
+  config.url = 'api_url'
+  config.api_key = 'your_easyship_api_key'
+  config.headers = {
+    'X-Custom-Header' => 'custom-value'
+  }
+end
+```
+
+**Per-Request Headers:**
+
+```ruby
+# Override or add headers for a specific request
+Easyship::Client.instance.get('/2023-01/account', {}, headers: {
+  'X-Request-ID' => 'unique-request-id'
+})
+
+# POST with custom headers
+Easyship::Client.instance.post('/2023-01/shipment', payload, headers: {
+  'X-Idempotency-Key' => 'unique-key'
+})
+
+# PUT with custom headers
+Easyship::Client.instance.put('/2023-01/shipment/123', payload, headers: {
+  'X-Custom-Header' => 'value'
+})
+
+# PATCH with custom headers
+Easyship::Client.instance.patch('/2023-01/shipment/123', payload, headers: {
+  'X-Custom-Header' => 'value'
+})
+
+# DELETE with custom headers
+Easyship::Client.instance.delete('/2023-01/shipment/123', {}, headers: {
+  'X-Custom-Header' => 'value'
+})
+```
+
+**Note:** Per-request headers will override global headers if the same header key is used.
+
+### Using Idempotency Keys
+
+Idempotency keys are essential for safely retrying requests without accidentally performing the same operation twice. This is particularly important for POST requests that create resources (like shipments, orders, or payments).
+
+**Example - Creating a Shipment with Idempotency:**
+
+```ruby
+# Generate a unique key (e.g., UUID, database record ID, or any unique identifier)
+idempotency_key = SecureRandom.uuid
+
+payload = {
+  origin_country_alpha2: "SG",
+  destination_country_alpha2: "US",
+  tax_paid_by: "Recipient",
+  is_insured: false,
+  items: [
+    {
+      description: "Product",
+      actual_weight: 1.2,
+      height: 10,
+      width: 15,
+      length: 20,
+      declared_currency: "USD",
+      declared_customs_value: 50
+    }
+  ]
+}
+
+begin
+  response = Easyship::Client.instance.post(
+    '/2023-01/shipments',
+    payload,
+    headers: { 'X-Idempotency-Key' => idempotency_key }
+  )
+  
+  # If this request fails due to network issues and you retry with the same key,
+  # the API will return the same shipment without creating a duplicate
+rescue Easyship::Errors::EasyshipError => e
+  # Safe to retry with the same idempotency_key
+  retry
+end
+```
+
+**Best Practices:**
+
+- Use unique, random keys (UUIDs are recommended)
+- Store the idempotency key with your order/shipment record in your database
+- Reuse the same key when retrying a failed request
+- Don't reuse keys across different operations or resources
+- Keys typically expire after 24 hours (check API documentation)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. Then, eun `rake rubocop` to run the rubocop. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/easyship/client.rb

@@ -16,46 +16,65 @@ module Easyship
       @api_key = Easyship.configuration.api_key
     end
 
-    def get(path, params = {}, &block)
+    def get(path, params = {}, headers: {}, &block)
       if block
         Easyship::Pagination::Cursor.new(self, path, params).all(&block)
       else
-        response = connection.get(path, params)
+        response = connection(headers).get(path, params)
 
         handle_response(response)
       end
     end
 
-    def post(path, params = {})
-      response = connection.post(path, params.to_json)
+    def post(path, params = {}, headers: {})
+      response = connection(headers).post(path, params.to_json)
 
       handle_response(response)
     end
 
-    def put(path, params = {})
-      response = connection.put(path, params.to_json)
+    def put(path, params = {}, headers: {})
+      response = connection(headers).put(path, params.to_json)
 
       handle_response(response)
     end
 
-    def delete(path, params = {})
-      response = connection.delete(path, params)
+    def delete(path, params = {}, headers: {})
+      response = connection(headers).delete(path, params)
+
+      handle_response(response)
+    end
+
+    def patch(path, params = {}, headers: {})
+      response = connection(headers).patch(path, params.to_json)
 
       handle_response(response)
     end
 
     private
 
-    def connection
+    def connection(custom_headers = {})
       Faraday.new(url: @url) do |faraday|
         faraday.request :url_encoded
         faraday.adapter Faraday.default_adapter
         faraday.headers['Authorization'] = "Bearer #{@api_key}"
         faraday.headers['Content-Type'] = 'application/json'
+        merge_headers(faraday, custom_headers)
         faraday.use Easyship::Middleware::ErrorHandlerMiddleware
       end
     end
 
+    def merge_headers(faraday, custom_headers)
+      # Merge global configuration headers
+      Easyship.configuration.headers.each do |key, value|
+        faraday.headers[key] = value
+      end
+
+      # Merge request-specific headers (override globals)
+      custom_headers.each do |key, value|
+        faraday.headers[key] = value
+      end
+    end
+
     def handle_response(response)
       Easyship::Handlers::ResponseBodyHandler.handle_response(response)
     end

data/lib/easyship/configuration.rb

@@ -3,7 +3,7 @@
 module Easyship
   # Represents the configuration settings for the Easyship client.
   class Configuration
-    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute
+    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute, :headers
 
     def initialize
       @url = nil
@@ -11,6 +11,7 @@ module Easyship
       @per_page = 100 # Maximum possible number of items per page
       @requests_per_second = nil
       @requests_per_minute = nil
+      @headers = {}
     end
   end
 end

data/lib/easyship/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Easyship
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easyship
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michael Marusyk
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -69,6 +70,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/mmarusyk/easyship
   changelog_uri: https://github.com/mmarusyk/easyship/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,7 +85,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A Ruby client for integrating with Easyship's API for shipping and logistics
   management.