easyship 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c050cd7909443866f9f0365555f577024aa49ce0065be2a961018385409972d
-  data.tar.gz: a827b2cdaa8207b8723f5a7c2b65efba7c6b7f9e10cf16b46ea36f34aebae763
+  metadata.gz: 7b584f647a6c1e9cd0379a94b3fc479c8f82691ab1ff8a36d797dae1c24e9c89
+  data.tar.gz: 5f288ce157f0b0b1c5e19f6c8a0a7851bf2bf1c5acb1c22b6660656ceed10204
 SHA512:
-  metadata.gz: 959f2149e8e0d3f33ce0592de28df9718a0fb1c24cdb78909acffbdcecbeab71449b29a1000c03589d24616603214f0f9aa0dc05bad67e96ee413b2acad2a25c
-  data.tar.gz: 0ba62b8bf714db84417d4c2abb13e66738b0510dd0f57997c9403cdbfb81e2fa78029fb9b058d07a5ed943bb5eb8a9054be8929f6a7975b816fc59dda360b781
+  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,6 +1,17 @@
 ## [Unreleased]
 
-## [v.0.2.0](https://github.com/mmarusyk/easyship/tree/v0.2.0) - 2025-05-04
+## [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
+- Rate limiting for cursor by @mmarusyk in https://github.com/mmarusyk/easyship/pull/13
+
+
+## [v0.2.0](https://github.com/mmarusyk/easyship/tree/v0.2.0) - 2025-05-04
 
 ### Added
 - Add response_body and response_header to Easyship::Error

data/README.md

@@ -58,10 +58,10 @@ Easyship.configure do |config|
 end
 ```
 
-Configuration supports the next keys: `url`, `api_key`, `per_page`.
+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')
 ```
@@ -131,7 +131,146 @@ end
 shipments # Returns all shipments from all pages
 ```
 
-To setup items perpage, use the key `per_page` in your configuration.
+To setup items per page, use the key `per_page` in your configuration.
+
+For Example:
+
+```ruby
+# Global defaults
+Easyship.configure do |config|
+  config.per_page = 100
+end
+
+# Per-call overrides (any of these are supported)
+shipments = []
+Easyship::Client.instance.get('/2023-01/shipments', {
+  per_page: 50,
+}) do |page|
+  shipments.concat(page[:shipments])
+end
+```
+
+Rate limiting during pagination:
+- The cursor has no default rate limiting; it uses nil to indicate that rate limiting is disabled.
+  - Use [Rate limiting documentation](https://developers.easyship.com/reference/rate-limit) for more details which values to set.
+- You can override the limits per call, by passing `requests_per_second` and `requests_per_minute`.
+
+Examples:
+
+```ruby
+# Global defaults
+Easyship.configure do |config|
+  config.requests_per_second = 10
+  config.requests_per_minute = 60
+end
+
+# Per-call overrides (any of these are supported)
+shipments = []
+Easyship::Client.instance.get('/2023-01/shipments', {
+  requests_per_second: 5,
+  requests_per_minute: 40,
+}) do |page|
+  shipments.concat(page[: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
 

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,12 +3,15 @@
 module Easyship
   # Represents the configuration settings for the Easyship client.
   class Configuration
-    attr_accessor :url, :api_key, :per_page
+    attr_accessor :url, :api_key, :per_page, :requests_per_second, :requests_per_minute, :headers
 
     def initialize
       @url = nil
       @api_key = nil
       @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/pagination/cursor.rb

@@ -4,20 +4,26 @@ module Easyship
   module Pagination
     # Represents a pagination object
     class Cursor
-      attr_reader :client, :path, :params, :key, :per_page
+      CONFIGURATION_VARIABLES = %i[requests_per_second requests_per_minute].freeze
+
+      attr_reader :client, :path, :params, :key, :per_page, :requests_per_second, :requests_per_minute
 
       def initialize(client, path, params)
         @client = client
         @path = path
         @params = params
         @per_page = params[:per_page] || Easyship.configuration.per_page
+        @requests_per_second = params[:requests_per_second] || Easyship.configuration.requests_per_second
+        @requests_per_minute = params[:requests_per_minute] || Easyship.configuration.requests_per_minute
       end
 
       def all
         page = 1
 
         loop do
-          body = client.get(path, params.merge(page: page, per_page: per_page))
+          limiter.throttle!
+
+          body = client.get(path, build_request_params(page: page))
 
           break if body.nil? || body.empty?
 
@@ -28,6 +34,19 @@ module Easyship
           page += 1
         end
       end
+
+      private
+
+      def build_request_params(page:)
+        params.merge(page: page, per_page: per_page).except(*CONFIGURATION_VARIABLES)
+      end
+
+      def limiter
+        @limiter ||= Easyship::RateLimiting::WindowRateLimiter.new(
+          requests_per_second: requests_per_second,
+          requests_per_minute: requests_per_minute
+        )
+      end
     end
   end
 end

data/lib/easyship/rate_limiting/rate_limiter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Easyship
+  module RateLimiting
+    # Represents RateLimiter
+    class RateLimiter
+      def throttle!
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/easyship/rate_limiting/window_rate_limiter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Easyship
+  module RateLimiting
+    # Represents WindowRateLimiter
+    class WindowRateLimiter < RateLimiter
+      attr_reader :timestamps, :requests_per_second, :requests_per_minute
+
+      def initialize(requests_per_second:, requests_per_minute:)
+        super()
+        @requests_per_second = requests_per_second
+        @requests_per_minute = requests_per_minute
+        @timestamps = []
+      end
+
+      def throttle!
+        now = Time.now
+
+        timestamps << now
+
+        # Remove timestamps older than a minute
+        timestamps.reject! { |t| t < now - 60 }
+
+        check_second_window(now)
+        check_minute_window(now)
+      end
+
+      private
+
+      def check_second_window(now)
+        second_requests = timestamps.count { |t| t > now - 1 }
+
+        return if !requests_per_second || second_requests < requests_per_second
+
+        first_in_seconds = timestamps.find { |t| t > now - 1 }
+        sleep_time = (first_in_seconds + 1) - now
+
+        sleep(sleep_time) if sleep_time.positive?
+      end
+
+      def check_minute_window(now)
+        return if !requests_per_minute || timestamps.size < requests_per_minute
+
+        sleep_time = (timestamps.first + 60) - now
+
+        sleep(sleep_time) if sleep_time.positive?
+      end
+    end
+  end
+end

data/lib/easyship/version.rb

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

data/lib/easyship.rb

@@ -3,6 +3,8 @@
 require_relative 'easyship/version'
 require_relative 'easyship/configuration'
 require_relative 'easyship/client'
+require_relative 'easyship/rate_limiting/rate_limiter'
+require_relative 'easyship/rate_limiting/window_rate_limiter'
 
 # Provides configuration options for the Easyship gem.
 module Easyship

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easyship
 version: !ruby/object:Gem::Version
-  version: 0.2.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
@@ -56,6 +57,8 @@ files:
 - lib/easyship/handlers/response_body_handler.rb
 - lib/easyship/middleware/error_handler_middleware.rb
 - lib/easyship/pagination/cursor.rb
+- lib/easyship/rate_limiting/rate_limiter.rb
+- lib/easyship/rate_limiting/window_rate_limiter.rb
 - lib/easyship/version.rb
 - sig/easyship.rbs
 homepage: https://rubygems.org/gems/easyship
@@ -67,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
@@ -81,7 +85,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+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.