easypost 5.0.1 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be1297ea7c20b21f3f959cb281001d7435902ede623ca47ac981dba2b19309c6
-  data.tar.gz: 73e65fb3a6dc6a00635d0ae1f4351edcdaf427d5d29c7cf8254f43a770208033
+  metadata.gz: 74cc993ead7c401dc7dbd719667872b1317a83e31c93bf85e3489cdc5b322a51
+  data.tar.gz: 17095956ef150f649b12b9b974db4098b495bbfe7710fe368d594e7e6410e6ea
 SHA512:
-  metadata.gz: 99d4ded392e0e2b5a3a30c3eb58c9b9dff59997d479ae0174fa59a6b0d8dec1260f3861fd3d3a965545fc910c48cd137ccd1b24704db0f56d0287e15890c4f94
-  data.tar.gz: c31978176d4f25898021b9306180171e86826e48409de7a007cd0aeff371e528dfe8b690963c9cc97df3288ba61db27658b8780add0e29943db13a99d095f6df
+  metadata.gz: 8708b3ed757fdcec975e84a585bbbdc5e428de0f32b34b047b3d1860fb663db7b48748a49a5841de405adb00bc3102c3bc7ffea56d7d4ff0bf7ff6a74e81015d
+  data.tar.gz: 4fb43956853af9c440f7b84a804250e5e817ea3261e9900f821236bf2ae4fc623d1a68a36a899628b655ca6b1833e9095b3b943d2224224a95af24fb6c732bca

data/.github/workflows/ci.yml

@@ -48,8 +48,6 @@ jobs:
         run: make install-styleguide
       - name: Lint Project
         run: make lint
-      - name: Run security analysis
-        run: make scan
   docs:
     if: github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest

data/.gitignore

@@ -25,4 +25,15 @@ test/version_tmp
 tmp
 vendor/
 /easycop.yml
-/.rubocop.yml
+/.rubocop.yml
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+Session.vim
+Sessionx.vim
+.netrwhist
+*~
+tags
+[._]*.un~

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## v5.1.0 (2023-07-28)
+
+- Adds hooks to introspect the request and response of API calls (see `HTTP Hooks` section in the README for more details)
+- Maps 400 status code responses to the new `BadRequestError` class
+
 ## v5.0.1 (2023-06-20)
 
 - Fixes a bug where the params of a `customs_info` on create weren't wrapped properly which led to an empty set of `customs_items`

data/Makefile

@@ -20,10 +20,6 @@ coverage:
 docs:
 	bundle exec rdoc lib -o docs --title "EasyPost Ruby Docs"
 
-## format - Fix Rubocop errors
-format:
-	bundle exec rubocop -a
-
 ## install-styleguide - Import the style guides (Unix only)
 install-styleguide: | update-examples-submodule
 	sh examples/symlink_directory_files.sh examples/style_guides/ruby .
@@ -32,14 +28,11 @@ install-styleguide: | update-examples-submodule
 install: | update-examples-submodule
 	bundle install
 
-## update-examples-submodule - Update the examples submodule
-update-examples-submodule:
-	git submodule init
-	git submodule update --remote
-
 ## lint - Lint the project
-lint:
-	bundle exec rubocop
+lint: rubocop scan
+
+## lint-fix - Fix Rubocop errors
+lint-fix: rubocop-fix
 
 ## publish - Publishes the built gem to Rubygems
 publish:
@@ -50,6 +43,14 @@ publish:
 release:
 	gh release create ${tag} dist/*
 
+## rubocop - lints the project with rubocop
+rubocop:
+	bundle exec rubocop
+
+## rubocop-fix - fix rubocop errors
+rubocop-fix:
+	bundle exec rubocop -a
+
 ## scan - Runs security analysis on the project with Brakeman
 scan:
 	bundle exec brakeman lib --force
@@ -61,4 +62,9 @@ test:
 ## update - Updates dependencies
 update: | update-examples-submodule
 
-.PHONY: help build clean coverage docs format install install-styleguide lint publish release scan test update update-examples-submodule
+## update-examples-submodule - Update the examples submodule
+update-examples-submodule:
+	git submodule init
+	git submodule update --remote
+
+.PHONY: help build clean coverage docs install install-styleguide lint lint-fix publish release rubocop rubocop-fix scan test update update-examples-submodule

data/README.md

@@ -61,6 +61,7 @@ puts bought_shipment
 ### Custom Connections
 
 Pass in a lambda function as `custom_client_exec` when initializing a client that responds to `call(method, uri, headers, open_timeout, read_timeout, body = nil)` where:
+
 - `uri` is the fully-qualified URL of the EasyPost endpoint, including query parameters (`Uri` object)
 - `method` is the lowercase name of the HTTP method being used for the request (e.g. `:get`, `:post`, `:put`, `:delete`)
 - `headers` is a hash with all headers needed for the request pre-populated, including authorization (`Hash` object)
@@ -69,7 +70,8 @@ Pass in a lambda function as `custom_client_exec` when initializing a client tha
 - `body` is a string of the body data to be included in the request, or nil (e.g. GET or DELETE request) (string or `nil`)
 
 The lambda function should return an object with `code` and `body` attributes, where:
-- `code` is the HTTP response status code (integer) 
+
+- `code` is the HTTP response status code (integer)
 - `body` is the response body (string)
 
 #### Faraday
@@ -116,6 +118,49 @@ my_client = described_class.new(
 )
 ```
 
+### HTTP Hooks
+
+Users can audit HTTP requests and responses being made by the library by subscribing to request and response events. To do so, pass a block to the `subscribe_request_hook` and `subscribe_response_hook` methods of an instance of `EasyPost::Client`:
+
+```ruby
+require 'easypost'
+
+client = EasyPost::Client.new(api_key: ENV['EASYPOST_API_KEY'])
+
+# Returns a randomly-generated symbol which you can use to later unsubscribe the request hook
+client.subscribe_request_hook do |request_data|
+  # Your code goes here
+end
+# Returns a randomly-generated symbol which you can use to later unsubscribe the response hook
+client.subscribe_response_hook do |response_data|
+  # Your code goes here
+end
+```
+
+You can also name your hook subscriptions by providing an optional parameter to the methods above:
+
+```ruby
+require 'easypost'
+
+client = EasyPost::Client.new(api_key: ENV['EASYPOST_API_KEY'])
+
+request_hook = client.subscribe_request_hook(:my_request_hook) do |request_data|
+  # Your code goes here
+end
+response_hook = client.subscribe_response_hook(:my_response_hook) do |response_data|
+  # Your code goes here
+end
+
+puts request_hook  # :my_request_hook
+puts response_hook # :my_response_hook
+```
+
+Keep in mind that subscribing a hook with the same name of an existing hook will replace the existing hook with the new one. A request hook and a response hook can share the same name.
+
+#### Custom HTTP Connections with HTTP Hooks
+
+If you're using a custom HTTP connection, keep in mind that the `response_data` parameter that a response hook receives *will not be hydrated* with all the response data. You will have to inspect the `client_response_object` property in `response_data` to inspect the response code, response headers and response body.
+
 ## Documentation
 
 API documentation can be found at: <https://easypost.com/docs/api>.
@@ -141,9 +186,7 @@ make install-style
 
 # Lint project
 make lint
-
-# Fix linting errors
-make format
+make lint-fix
 
 # Run tests (coverage is generated on a successful test suite run)
 EASYPOST_TEST_API_KEY=123... EASYPOST_PROD_API_KEY=123... make test
@@ -155,8 +198,7 @@ make scan
 make docs
 
 # Update submodules
-git submodule init
-git submodule update --remote
+make update-examples-submodule
 ```
 
 ### Testing

data/VERSION

@@ -1 +1 @@
-5.0.1
+5.1.0

data/lib/easypost/client.rb

@@ -4,6 +4,7 @@ require_relative 'services'
 require_relative 'http_client'
 require_relative 'internal_utilities'
 require 'json'
+require 'securerandom'
 
 class EasyPost::Client
   attr_reader :open_timeout, :read_timeout, :api_base
@@ -90,6 +91,54 @@ class EasyPost::Client
     EasyPost::InternalUtilities::Json.convert_json_to_object(response.body, cls)
   end
 
+  # Subscribe a request hook
+  #
+  # @param name [Symbol] the name of the hook. Defaults ot a ranom hexadecimal-based symbol
+  # @param block [Block] a code block that will be executed before a request is made
+  # @return [Symbol] the name of the request hook
+  def subscribe_request_hook(name = SecureRandom.hex.to_sym, &block)
+    EasyPost::Hooks.subscribe(:request, name, block)
+  end
+
+  # Unsubscribe a request hook
+  #
+  # @param name [Symbol] the name of the hook
+  # @return [Block] the hook code block
+  def unsubscribe_request_hook(name)
+    EasyPost::Hooks.unsubscribe(:request, name)
+  end
+
+  # Unsubscribe all request hooks
+  #
+  # @return [Hash] a hash containing all request hook subscriptions
+  def unsubscribe_all_request_hooks
+    EasyPost::Hooks.unsubscribe_all(:request)
+  end
+
+  # Subscribe a response hook
+  #
+  # @param name [Symbol] the name of the hook. Defaults ot a ranom hexadecimal-based symbol
+  # @param block [Block] a code block that will be executed upon receiving the response from a request
+  # @return [Symbol] the name of the response hook
+  def subscribe_response_hook(name = SecureRandom.hex.to_sym, &block)
+    EasyPost::Hooks.subscribe(:response, name, block)
+  end
+
+  # Unsubscribe a response hook
+  #
+  # @param name [Symbol] the name of the hook
+  # @return [Block] the hook code block
+  def unsubscribe_response_hook(name)
+    EasyPost::Hooks.unsubscribe(:response, name)
+  end
+
+  # Unsubscribe all response hooks
+  #
+  # @return [Hash] a hash containing all response hook subscriptions
+  def unsubscribe_all_response_hooks
+    EasyPost::Hooks.unsubscribe_all(:response)
+  end
+
   private
 
   def http_config

data/lib/easypost/errors/api/api_error.rb

@@ -77,6 +77,8 @@ class EasyPost::Errors::ApiError < EasyPost::Errors::EasyPostError
       EasyPost::Errors::ConnectionError
     when 300, 301, 302, 303, 304, 305, 306, 307, 308
       EasyPost::Errors::RedirectError
+    when 400
+      EasyPost::Errors::BadRequestError
     when 401
       EasyPost::Errors::UnauthorizedError
     when 402

data/lib/easypost/errors/api/bad_request_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'api_error'
+
+class EasyPost::Errors::BadRequestError < EasyPost::Errors::ApiError
+end

data/lib/easypost/errors.rb

@@ -12,6 +12,7 @@ require_relative 'errors/invalid_parameter_error'
 require_relative 'errors/missing_parameter_error'
 require_relative 'errors/signature_verification_error'
 require_relative 'errors/api/api_error'
+require_relative 'errors/api/bad_request_error'
 require_relative 'errors/api/connection_error'
 require_relative 'errors/api/forbidden_error'
 require_relative 'errors/api/gateway_timeout_error'

data/lib/easypost/hooks/request_context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class EasyPost::Hooks::RequestContext
+  attr_reader :method, :path, :headers, :request_body, :request_timestamp, :request_uuid
+
+  def initialize(method:, path:, headers:, request_body:, request_timestamp:, request_uuid:)
+    @method = method
+    @path = path
+    @headers = headers
+    @request_body = request_body
+    @request_timestamp = request_timestamp
+    @request_uuid = request_uuid
+
+    freeze
+  end
+end

data/lib/easypost/hooks/response_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class EasyPost::Hooks::ResponseContext
+  attr_reader :http_status, :method, :path, :headers, :response_body,
+              :request_timestamp, :response_timestamp, :request_uuid,
+              :client_response_object
+
+  def initialize(http_status:, method:, path:, headers:, response_body:,
+                 request_timestamp:, response_timestamp:, request_uuid:,
+                 client_response_object:)
+    @http_status = http_status
+    @method = method
+    @path = path
+    @headers = headers
+    @response_body = response_body
+    @request_timestamp = request_timestamp
+    @response_timestamp = response_timestamp
+    @request_uuid = request_uuid
+    @client_response_object = client_response_object
+
+    freeze
+  end
+end

data/lib/easypost/hooks.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module EasyPost::Hooks
+  def self.subscribe(type, name, block)
+    subscribers[type][name] = block
+
+    name
+  end
+
+  def self.unsubscribe(type, name)
+    subscribers[type].delete(name)
+  end
+
+  def self.unsubscribe_all(type)
+    subscribers.delete(type)
+  end
+
+  def self.notify(type, context)
+    subscribers[type].each_value { |subscriber| subscriber.call(context) }
+  end
+
+  def self.any_subscribers?(type)
+    !subscribers[type].empty?
+  end
+
+  def self.subscribers
+    @subscribers ||= Hash.new { |hash, key| hash[key] = {} }
+  end
+
+  private_class_method :subscribers
+end
+
+require_relative 'hooks/request_context'
+require_relative 'hooks/response_context'

data/lib/easypost/http_client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 class EasyPost::HttpClient
   def initialize(base_url, config, custom_client_exec = nil)
     @base_url = base_url
@@ -20,17 +22,67 @@ class EasyPost::HttpClient
 
     uri = URI.parse("#{@base_url}/#{api_version}/#{path}")
     headers = @config[:headers].merge(headers || {})
-    body = JSON.dump(EasyPost::InternalUtilities.objects_to_ids(body)) if body
+    serialized_body = JSON.dump(EasyPost::InternalUtilities.objects_to_ids(body)) if body
     open_timeout = @config[:open_timeout]
     read_timeout = @config[:read_timeout]
+    request_timestamp = Time.now
+    request_uuid = SecureRandom.uuid
+
+    if EasyPost::Hooks.any_subscribers?(:request)
+      request_context = EasyPost::Hooks::RequestContext.new(
+        method: method,
+        path: uri.to_s,
+        headers: headers,
+        request_body: body,
+        request_timestamp: request_timestamp,
+        request_uuid: request_uuid,
+      )
+      EasyPost::Hooks.notify(:request, request_context)
+    end
 
     # Execute the request, return the response.
 
-    if @custom_client_exec
-      @custom_client_exec.call(method, uri, headers, open_timeout, read_timeout, body)
-    else
-      default_request_execute(method, uri, headers, open_timeout, read_timeout, body)
+    response = if @custom_client_exec
+                 @custom_client_exec.call(method, uri, headers, open_timeout, read_timeout, serialized_body)
+               else
+                 default_request_execute(method, uri, headers, open_timeout, read_timeout, serialized_body)
+               end
+    response_timestamp = Time.now
+
+    if EasyPost::Hooks.any_subscribers?(:response)
+      response_context = {
+        http_status: nil,
+        method: method,
+        path: uri.to_s,
+        headers: nil,
+        response_body: nil,
+        request_timestamp: request_timestamp,
+        response_timestamp: response_timestamp,
+        client_response_object: response,
+        request_uuid: request_uuid,
+      }
+
+      # If using a custom HTTP client, the user will have to infer these from the raw
+      # client_response_object attribute
+      if response.is_a?(Net::HTTPResponse)
+        response_body = begin
+          JSON.parse(response.body)
+        rescue JSON::ParseError
+          response.body
+        end
+        response_context.merge!(
+          {
+            http_status: response.code.to_i,
+            headers: response.each_header.to_h,
+            response_body: response_body,
+          },
+        )
+      end
+
+      EasyPost::Hooks.notify(:response, EasyPost::Hooks::ResponseContext.new(**response_context))
     end
+
+    response
   end
 
   def default_request_execute(method, uri, headers, open_timeout, read_timeout, body = nil)

data/lib/easypost.rb

@@ -24,5 +24,8 @@ require 'easypost/errors'
 # Internal Utilities
 require 'easypost/internal_utilities'
 
+# Hooks
+require 'easypost/hooks'
+
 module EasyPost
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easypost
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.1.0
 platform: ruby
 authors:
 - EasyPost Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-20 00:00:00.000000000 Z
+date: 2023-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: brakeman
@@ -237,6 +237,7 @@ files:
 - lib/easypost/constants.rb
 - lib/easypost/errors.rb
 - lib/easypost/errors/api/api_error.rb
+- lib/easypost/errors/api/bad_request_error.rb
 - lib/easypost/errors/api/connection_error.rb
 - lib/easypost/errors/api/external_api_error.rb
 - lib/easypost/errors/api/forbidden_error.rb
@@ -262,6 +263,9 @@ files:
 - lib/easypost/errors/invalid_parameter_error.rb
 - lib/easypost/errors/missing_parameter_error.rb
 - lib/easypost/errors/signature_verification_error.rb
+- lib/easypost/hooks.rb
+- lib/easypost/hooks/request_context.rb
+- lib/easypost/hooks/response_context.rb
 - lib/easypost/http_client.rb
 - lib/easypost/internal_utilities.rb
 - lib/easypost/models.rb