fulfil_api 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fd9d19ce17cb0e08c7c53cedf565ac90c16dd16bb12e027caa674a70e6e98f0
-  data.tar.gz: c3d01131d48cafd5de51823fe8281709ed3c00992d1853cc672d6c40a2016ff1
+  metadata.gz: 22b6b63d1460a3a0d6b6c5ef3b33b018291d6919a27c32664c7649922a930852
+  data.tar.gz: 0a87ce490bca0026c5764ded0e887a3cdffd4cf0d9a3f13bcfd8e5a5a888cb43
 SHA512:
-  metadata.gz: f8adecf2a1becece7421a498c0fe28f626c29273241ac9c7cd2a8494f9b352db790b988f766a472cd804ff0a620349ed2c4c039d0d85eb20138dd2dc7f2a0b73
-  data.tar.gz: bf380b8c367f887cd024886fc582787220e36565715d6dcd2308b56759575548e6f80a10250faef50c5c56ae6d67981b7c7a6205e97d9d049f05dd6c09a0c8c0
+  metadata.gz: dedeecd3042e63045c2a5215d5bc6121c99a0863a65db953657cef068ff75f060271533d8ce2dd39a9b24ca94834b5b0b1282778ba6f0fb8d18efd419ecdff32
+  data.tar.gz: b39a10b911e3c9909cb7f21bfdf4cde91db64438eb6060a54700e4596ec4fe32961b691e49f4370211fdca0f8b343b0c63421ccfeb6d5959b6c05524ba415a94

data/README.md

@@ -127,6 +127,47 @@ line_items = FulfilApi::Resource.set(model_name: "sale.line").where(["id", "in",
 line_items = FulfilApi::Resource.set(model_name: "sale.line").find_by(["sale.id", "=", 100])
 ```
 
+### Using the 3PL (TPL) Client
+
+The gem also includes a client for Fulfil's [3PL Integration API](https://fulfil-3pl-integration-api.readme.io/reference/getting-started-with-your-api). This is a separate API that allows third-party logistics providers to interact with Fulfil on behalf of a merchant.
+
+#### Configuration
+
+Configure the 3PL client through the `tpl` option in the configuration block:
+
+```ruby
+FulfilApi.configure do |config|
+  config.merchant_id = "the-id-of-the-merchant"
+
+  config.tpl = {
+    auth_token: ENV["FULFIL_3PL_AUTH_TOKEN"], # required
+    merchant_id: "a-different-merchant-id",   # optional, falls back to config.merchant_id
+    api_version: "v1"                         # optional, defaults to "v1"
+  }
+end
+```
+
+#### Making Requests
+
+The 3PL client is accessible via `FulfilApi.tpl_client` and supports the standard HTTP methods:
+
+```ruby
+# GET request with optional URL parameters
+FulfilApi.tpl_client.get("inbound-transfers", url_parameters: { page: 1, per_page: 25 })
+
+# POST request with a request body
+FulfilApi.tpl_client.post("inbound-transfers/receive.json", body: { tracking_number: "ABC123" })
+
+# PUT request with a request body
+FulfilApi.tpl_client.put("inbound-transfers/receive.json", body: { status: "received" })
+
+# PATCH request with a request body
+FulfilApi.tpl_client.patch("inbound-transfers/receive.json", body: { status: "received" })
+
+```
+
+> **NOTE:** For the full list of available 3PL API endpoints, refer to the [Fulfil 3PL Integration API documentation](https://fulfil-3pl-integration-api.readme.io/reference/getting-started-with-your-api).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/fulfil_api/configuration.rb

@@ -6,7 +6,7 @@ module FulfilApi
   # This model holds configuration settings and provides thread-safe access
   #   to these settings.
   class Configuration
-    attr_accessor :access_token, :api_version, :merchant_id, :request_options
+    attr_accessor :access_token, :api_version, :merchant_id, :request_options, :tpl
 
     DEFAULT_API_VERSION = "v2"
     DEFAULT_REQUEST_OPTIONS = { open_timeout: 1, read_timeout: 5, write_timeout: 5, timeout: 5 }.freeze

data/lib/fulfil_api/test_helper.rb

@@ -41,8 +41,49 @@ module FulfilApi
         .and_return(status: status, body: response.to_json, headers: { "Content-Type": "application/json" })
     end
 
+    # Stubs an HTTP request to the Fulfil 3PL API based on the provided parameters.
+    #
+    # @param [String, Symbol] method The HTTP method to be stubbed (e.g., :get, :post).
+    # @param [Hash] response The response body to return as a JSON object (default is {}).
+    # @param [Integer] status The HTTP status code to return (default is 200).
+    # @param [Hash] options Additional options for the request URL.
+    # @option options [String] :path The relative path to the 3PL endpoint
+    #   (e.g., 'inbound-transfers/receive.json').
+    #
+    # @return [WebMock::RequestStub] The WebMock request stub object.
+    #
+    # @example Stub a GET request for the inbound transfers endpoint
+    #   stub_fulfil_tpl_request(:get, path: "inbound-transfers", response: [{ id: 1 }])
+    #
+    # @example Stub a POST request for receiving an inbound transfer
+    #   stub_fulfil_tpl_request(:post, path: "inbound-transfers/receive.json", response: { id: 123 })
+    #
+    # @example Stub all 3PL requests for a given method
+    #   stub_fulfil_tpl_request(:get)
+    def stub_fulfil_tpl_request(method, response: {}, status: 200, **options)
+      stubbed_tpl_request_for(method, **options)
+        .and_return(status: status, body: response.to_json, headers: { "Content-Type": "application/json" })
+    end
+
     private
 
+    # Builds the WebMock request stub for the Fulfil 3PL API based on the provided method and options.
+    #
+    # @param [String, Symbol] method The HTTP method to be stubbed (e.g., :get, :post).
+    # @param [Hash] options Additional options for the request URL.
+    # @option options [String] :path The relative path to the 3PL endpoint
+    #   (e.g., 'inbound-transfers/receive.json').
+    #
+    # @return [WebMock::RequestStub] The WebMock request stub object.
+    def stubbed_tpl_request_for(method, **options)
+      case options.transform_keys(&:to_sym)
+      in { path: }
+        stub_request(method.to_sym, %r{fulfil.io/services/3pl/v\d+/#{path}(.*)}i)
+      else
+        stub_request(method.to_sym, %r{fulfil.io/services/3pl/v\d+}i)
+      end
+    end
+
     # Builds the WebMock request stub for the Fulfil API based on the provided method and options.
     #
     # @param [String, Symbol] method The HTTP method to be stubbed (e.g., :get, :post).

data/lib/fulfil_api/tpl_client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http_persistent"
+
+module FulfilApi
+  # The {FulfilApi::TplClient} allows making proxy requests to Fulfil's 3PL
+  # carrier API endpoint. It provides a simple interface for interacting with
+  # the 3PL supplier API using standard HTTP methods.
+  #
+  # @example Using the TPL client
+  #   FulfilApi.tpl_client.get("inbound-transfers", url_parameters: { page: 1 })
+  #   FulfilApi.tpl_client.post("inbound-transfers/receive.json", body: { tracking_number: "123" })
+  class TplClient
+    class ConfigurationError < FulfilApi::Error; end
+
+    DEFAULT_API_VERSION = "v1"
+
+    # @param configuration [FulfilApi::Configuration]
+    def initialize(configuration)
+      @configuration = configuration
+
+      tpl_config = configuration.tpl || {}
+
+      @auth_token = tpl_config[:auth_token].presence ||
+                    raise(ConfigurationError,
+                          "Please provide a 3PL authentication token via config.tpl = { auth_token: ... }")
+      @merchant_id = tpl_config[:merchant_id].presence || configuration.merchant_id.presence ||
+                     raise(ConfigurationError, "Please provide a merchant ID")
+      @api_version = tpl_config[:api_version].presence || DEFAULT_API_VERSION
+    end
+
+    # Performs an HTTP GET request to a 3PL API endpoint.
+    #
+    # @param relative_path [String] The relative path to the endpoint.
+    # @param url_parameters [Hash, nil] The optional URL parameters for the API endpoint.
+    # @return [Array, Hash, String] The parsed response body.
+    def get(relative_path, url_parameters: nil)
+      request(:get, relative_path, url_parameters)
+    end
+
+    # Performs an HTTP PATCH request to a 3PL API endpoint.
+    #
+    # @param relative_path [String] The relative path to the endpoint.
+    # @param body [Array, Hash, nil] The request body for the PATCH HTTP request.
+    # @return [Array, Hash, String] The parsed response body.
+    def patch(relative_path, body: {})
+      request(:patch, relative_path, body)
+    end
+
+    # Performs an HTTP POST request to a 3PL API endpoint.
+    #
+    # @param relative_path [String] The relative path to the endpoint.
+    # @param body [Array, Hash, nil] The request body for the POST HTTP request.
+    # @return [Array, Hash, String] The parsed response body.
+    def post(relative_path, body: {})
+      request(:post, relative_path, body)
+    end
+
+    # Performs an HTTP PUT request to a 3PL API endpoint.
+    #
+    # @param relative_path [String] The relative path to the endpoint.
+    # @param body [Array, Hash, nil] The optional request body for the PUT HTTP request.
+    # @return [Array, Hash, String] The parsed response body.
+    def put(relative_path, body: nil)
+      return request(:put, relative_path) if body.nil?
+
+      request(:put, relative_path, body)
+    end
+
+    private
+
+    attr_reader :api_version, :auth_token, :configuration, :merchant_id
+
+    # @return [String] The absolute URL to the API base URL.
+    def api_endpoint
+      @api_endpoint ||= "https://#{merchant_id}.fulfil.io"
+    end
+
+    # @return [Faraday::Connection]
+    def connection
+      @connection ||= Faraday.new(
+        headers: request_headers,
+        url: api_endpoint,
+        request: configuration.request_options
+      ) do |connection|
+        connection.adapter :net_http_persistent
+
+        # Configuration of the request middleware
+        connection.request :json
+
+        # Configuration of the response middleware
+        connection.response :json
+        connection.response :raise_error
+      end
+    end
+
+    # @param relative_path [String] The relative path to the API endpoint.
+    # @return [String] The absolute path for the request to the API endpoint.
+    def expand_relative_path(relative_path)
+      path = relative_path.start_with?("/") ? relative_path[1..] : relative_path
+      "/services/3pl/#{api_version}/#{path}"
+    end
+
+    # @param exception [Faraday::Error] Any error raised by Faraday during the execution
+    #   of the HTTP request to the API endpoint.
+    def handle_request_error(exception)
+      raise FulfilApi::Error.new(
+        exception.message,
+        details: {
+          response_body: exception.response_body,
+          response_headers: exception.response_headers,
+          response_status: exception.response_status
+        }
+      )
+    end
+
+    # @param method [Symbol, String] The HTTP verb for the HTTP request.
+    # @param relative_path [String] The relative path to the API endpoint.
+    # @return [Array, Hash, String] The parsed response body.
+    def request(method, relative_path, *args, **kwargs)
+      connection.send(method.to_sym, expand_relative_path(relative_path), *args, **kwargs).body
+    rescue Faraday::Error => e
+      handle_request_error(e)
+    end
+
+    # @return [Hash] The HTTP headers for any HTTP request to the 3PL API.
+    def request_headers
+      {
+        "Authorization" => "Bearer #{auth_token}",
+        "Content-Type" => "application/json"
+      }
+    end
+  end
+
+  # Builds an HTTP client to interact with Fulfil's 3PL API endpoint.
+  #
+  # @example
+  #   FulfilApi.tpl_client.get("inbound-transfers")
+  #   FulfilApi.tpl_client.post("inbound-transfers/receive.json", body: { tracking_number: "123" })
+  #
+  # @return [FulfilApi::TplClient]
+  def self.tpl_client
+    TplClient.new(FulfilApi.configuration)
+  end
+end

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Stefan Vermaas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-19 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -100,6 +100,7 @@ files:
 - lib/fulfil_api/resource/persistable.rb
 - lib/fulfil_api/resource/serializable.rb
 - lib/fulfil_api/test_helper.rb
+- lib/fulfil_api/tpl_client.rb
 - lib/fulfil_api/version.rb
 - sig/fulfil_api.rbs
 homepage: https://www.github.com/codeturebv/fulfil_api