easyship 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26a4f14b66c264e247eba786be5a7e7c69e364b15bd82fb3a0b972d3738a2291
-  data.tar.gz: a602f6940102161c1b6e2e9e8a9714f7cd2e2576f5d4d5e04621d8119d7dbc06
+  metadata.gz: 0e185adc98f576e3cf15ffc1ca38edf2dca8a0ffa580f68a731c900c3632392b
+  data.tar.gz: e15d52b3f530c58883fb8f50b086db537939ceed2fc1afff3579ea6aa82373c1
 SHA512:
-  metadata.gz: 2548182a0a00f80abe3096a247f1a85b0878f8ed737f370813e169de5a0db67fc982080fc7650eae22a931f844adfc465566e27cfb331d381744ca53e038693d
-  data.tar.gz: c5be671de26cefaa90af42d8b5f22ddb32af00e84dcc4ad57db9a8fd193b05902a6b60fdc093968e7781ac523ca066cd322c9a478ea637cf8ca775f79fce329e
+  metadata.gz: 707860b193dbc25e916f8d0e5e68a2a3c8e34498e523871e243cf487f1e5c4c2469ed274099899b1b50c22598dc085906eca132f9e537515c43bf03428040c02
+  data.tar.gz: ec38670ff9d6626bc62485d8c836d00c1efb8e4a8218214c5c6b36b01570ad3b71906511c2459dc4a74b3a5ed91e3d3f91bd5f07586e75d481dc2ebf142a4d9a

data/.rubocop.yml

@@ -1,4 +1,5 @@
-require:
+plugins:
+  - rubocop-rake
   - rubocop-rspec
   - rubocop-performance
 
@@ -8,3 +9,6 @@ AllCops:
 
 Style/Copyright:
   Enabled: false
+
+RSpec/ExampleLength:
+  Max: 10

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [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
+- Deprecate body_error by @mmarusyk in https://github.com/mmarusyk/easyship/pull/9
+- Add badges by @mmarusyk in https://github.com/mmarusyk/easyship/pull/10
+
+
 ## [v0.1.5](https://github.com/mmarusyk/easyship/tree/v0.1.5) - 2025-05-03
 
 ### Fixed

data/README.md

@@ -1,5 +1,9 @@
 # Easyship
 
+[![Gem Version](https://badge.fury.io/rb/easyship.svg)](https://badge.fury.io/rb/easyship)
+[![Build Status](https://github.com/mmarusyk/easyship/workflows/Ruby/badge.svg)](https://github.com/mmarusyk/easyship/actions?query=workflow%3ARuby)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 This gem provides a simple client for Easyship, offering accessing to Easyship's
     shipping, tracking, and logistics services directly from Ruby applications.
 
@@ -54,7 +58,7 @@ 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`.
 
 ### Making Requests
 `Easyship::Client` supports the next methods: `get`, `post`, `put`, `delete`.
@@ -103,6 +107,15 @@ rescue Easyship::Errors::RateLimitError => e
 end
 ```
 
+Each error instance provides these methods:
+
+- `message`: Returns the error message text.
+- `body_error`: Returns an error details **(Deprecated)**.
+- `error`: Returns a hash containing original detailed error object from Easyship.
+- `response_body`: Returns the full response body from the API.
+- `response_headers`: Returns the HTTP headers from the API response.
+
+
 ### Pagination
 The `get` method in the `Easyship::Client` class is designed to support pagination seamlessly when interacting with the Easyship API by passing block of code. This method abstracts the complexity of managing pagination logic, allowing you to retrieve all items across multiple pages with a single method call.
 
@@ -118,7 +131,48 @@ 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
+```
 
 ## Development
 

data/lib/easyship/configuration.rb

@@ -3,12 +3,14 @@
 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
 
     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
     end
   end
 end

data/lib/easyship/errors/easyship_error.rb

@@ -4,12 +4,20 @@ module Easyship
   module Errors
     # Represents an error that is raised when an error occurs in the Easyship API.
     class EasyshipError < StandardError
-      attr_reader :message, :body_error
+      attr_reader :message, :error, :response_body, :response_headers
 
-      def initialize(message: '', body_error: {})
+      def initialize(message: '', body_error: {}, error: {}, response_body: nil, response_headers: {})
         super(message)
+        @error = error
         @message = message
         @body_error = body_error
+        @response_body = response_body
+        @response_headers = response_headers
+      end
+
+      def body_error
+        warn '[DEPRECATION] `body_error` is deprecated. Please use `error` instead.'
+        @body_error
       end
     end
   end

data/lib/easyship/middleware/error_handler_middleware.rb

@@ -9,20 +9,33 @@ module Easyship
       def on_complete(env)
         status_code = env[:status].to_i
         body = response_body(env[:body])
+        headers = env[:response_headers]
 
-        handle_status_code(status_code, body)
+        handle_status_code(status_code, headers, body)
       end
 
       private
 
-      def handle_status_code(status_code, body)
+      def handle_status_code(status_code, headers, body)
         error_class = Easyship::Error.for_status(status_code)
 
-        raise_error(error_class, body) if error_class
+        raise_error(error_class, headers, body) if error_class
       end
 
-      def raise_error(class_error, body)
-        raise class_error.new(message: message(body), body_error: body_error(body))
+      def raise_error(class_error, headers, body)
+        raise class_error.new(
+          message: message(body),
+          body_error: body_error(body),
+          error: build_error(body),
+          response_body: body,
+          response_headers: headers
+        )
+      end
+
+      def build_error(body)
+        return default_error unless body.is_a?(Hash)
+
+        body[:error]
       end
 
       def body_error(body)
@@ -55,6 +68,10 @@ module Easyship
         { details: body, message: 'Something went wrong.' }
       end
 
+      def default_error
+        { details: [], message: 'Something went wrong.' }
+      end
+
       def response_body(body)
         JSON.parse(body, symbolize_names: true)
       rescue JSON::ParserError

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.1.5'
+  VERSION = '0.3.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easyship
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Marusyk
@@ -56,6 +56,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
@@ -81,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A Ruby client for integrating with Easyship's API for shipping and logistics
   management.