fulfil_api 0.7.2 → 0.8.1

data/lib/fulfil_api/oauth/configuration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  module OAuth
+    # Holds the credentials and options of the OAuth app that was registered in
+    #   Fulfil's authentication dashboard, plus the Rails-specific settings used
+    #   by {FulfilApi::Engine}.
+    #
+    # @see https://auth.fulfil.io/user/clients
+    class Configuration
+      ACCESS_TYPES = %i[offline_access user_session].freeze
+
+      # Fulfil's own default is `user_session`, but the gem defaults to
+      #   `offline_access`. An app that talks to Fulfil from background jobs
+      #   needs a token that outlives the user's web session, and personal
+      #   access tokens are no longer a viable alternative now that they expire.
+      DEFAULT_ACCESS_TYPE = :offline_access
+      DEFAULT_AFTER_INSTALL_PATH = "/"
+      DEFAULT_MOUNT_PATH = "/fulfil"
+      DEFAULT_SCOPES = [].freeze
+
+      # What the engine's controllers inherit from until {#parent_controller} is
+      #   set. It carries no authentication, which is why the flow refuses to run
+      #   before an application has named a controller of its own.
+      UNCONFIGURED_PARENT_CONTROLLER = "ActionController::Base"
+
+      attr_accessor :after_install_path, :client_id, :client_secret, :parent_controller, :redirect_uri
+      attr_reader :access_type, :scopes
+
+      # @param options [Hash, nil] An optional list of configuration options.
+      def initialize(options = {})
+        (options || {}).each_pair do |key, value|
+          public_send(:"#{key}=", value) if respond_to?(:"#{key}=")
+        end
+
+        set_default_options
+      end
+
+      # @param value [Symbol, String] Either `:offline_access` or `:user_session`.
+      # @raise [ArgumentError] When the access type is not supported by Fulfil.
+      # @return [void]
+      def access_type=(value)
+        @access_type = value.to_sym
+
+        return if ACCESS_TYPES.include?(@access_type)
+
+        raise ArgumentError, "#{value} is not a valid access type. Use :offline_access or :user_session instead."
+      end
+
+      # @return [true, false] Whether an access token can be requested at all.
+      def configured?
+        client_id.present? && client_secret.present?
+      end
+
+      # @return [true, false] Whether a permanent, user-independent token is requested.
+      def offline_access?
+        access_type == :offline_access
+      end
+
+      # The class the engine's controllers inherit from.
+      #
+      # @return [Class]
+      def parent_controller_class
+        (parent_controller.presence || UNCONFIGURED_PARENT_CONTROLLER).constantize
+      end
+
+      # Whether the application named the controller the OAuth flow runs under.
+      #
+      # There is no sensible default: the flow has to run behind whatever the
+      #   application uses to authenticate a request, and guessing wrong leaves
+      #   an endpoint that lets a stranger install their own Fulfil workspace
+      #   over the application's.
+      #
+      # @return [true, false]
+      def parent_controller_configured?
+        parent_controller.present?
+      end
+
+      # @param value [Array<String>, String, nil] A list of scopes, or a string
+      #   of scopes separated by commas or spaces.
+      # @return [void]
+      def scopes=(value)
+        @scopes = Array(value).flat_map { |scope| scope.to_s.split(Token::SCOPE_SEPARATOR) }.reject(&:empty?).uniq
+      end
+
+      private
+
+      # @return [void]
+      def set_default_options
+        self.access_type = DEFAULT_ACCESS_TYPE if access_type.nil?
+        self.after_install_path = DEFAULT_AFTER_INSTALL_PATH if after_install_path.nil?
+        self.scopes = DEFAULT_SCOPES if scopes.nil?
+      end
+    end
+  end
+end

data/lib/fulfil_api/oauth/token.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  module OAuth
+    # Wraps the payload returned by Fulfil's `POST /oauth/token` endpoint.
+    #
+    # @example An `offline_access` payload
+    #   {
+    #     "access_token" => "user-xxxxx-xxxxxxx",
+    #     "associated_user" => { "email" => "first.last@example.com", "id" => 1, "name" => "First Last" },
+    #     "expires_in" => 3600,
+    #     "offline_access_token" => "bot-xxxx",
+    #     "scope" => ["user_session,party.party"],
+    #     "token_type" => "Bearer"
+    #   }
+    class Token
+      DEFAULT_TOKEN_TYPE = "Bearer"
+      SCOPE_SEPARATOR = /[\s,]+/
+
+      attr_reader :access_token, :associated_user, :expires_in, :offline_access_token, :scopes, :token_type
+
+      # @param payload [Hash] The parsed response body of the token endpoint.
+      def initialize(payload)
+        payload = (payload || {}).with_indifferent_access
+
+        @access_token = payload[:access_token].presence
+        @associated_user = (payload[:associated_user] || {}).with_indifferent_access
+        @expires_in = payload[:expires_in]&.to_i
+        @offline_access_token = payload[:offline_access_token].presence
+        @scopes = extract_scopes(payload[:scope])
+        @token_type = payload[:token_type].presence || DEFAULT_TOKEN_TYPE
+      end
+
+      # The moment the short-lived {#access_token} stops working. The
+      #   {#offline_access_token} is not covered by this: it stays valid until
+      #   the app is uninstalled from the workspace.
+      #
+      # @return [Time, nil]
+      def expires_at
+        return if expires_in.nil?
+
+        Time.now.utc + expires_in
+      end
+
+      # @return [true, false] Whether a permanent token was granted.
+      def offline?
+        offline_access_token.present?
+      end
+
+      # Prefers the permanent token over the short-lived one, so a token used
+      #   outside of the request it was granted in keeps working.
+      #
+      # @return [FulfilApi::AccessToken]
+      def to_access_token
+        FulfilApi::AccessToken.new(value, type: :oauth)
+      end
+
+      # @return [String, nil] The token to authenticate API requests with.
+      def value
+        offline_access_token || access_token
+      end
+
+      private
+
+      # Fulfil returns the granted scopes as an array holding a single string
+      #   rather than as a list of scopes. Its docs show that string comma
+      #   separated (`["user_session,party.party"]`), but a real workspace
+      #   separates them with spaces (`["sale.order stock.move.view"]`), so both
+      #   are flattened into a plain list.
+      #
+      # @param scope [Array<String>, String, nil] The granted scopes.
+      # @return [Array<String>]
+      def extract_scopes(scope)
+        Array(scope).flat_map { |value| value.to_s.split(SCOPE_SEPARATOR) }.reject(&:empty?).uniq
+      end
+    end
+  end
+end

data/lib/fulfil_api/oauth.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::OAuth} namespace contains everything needed to obtain an
+  #   access token through Fulfil's OAuth 2.0 authorization flow.
+  #
+  # Fulfil's flow has two access modes. The `user_session` mode returns a
+  #   short-lived token tied to the user's web session, while the
+  #   `offline_access` mode additionally returns an `offline_access_token` that
+  #   remains valid until the app is uninstalled. There is no refresh token in
+  #   either mode: an expired `user_session` token can only be replaced by
+  #   sending the user through the flow again.
+  #
+  # @see https://docs.fulfil.io/developers/rest-api/authentication/oauth
+  module OAuth
+    class Error < FulfilApi::Error; end
+
+    # Raised when the flow is started without a client ID or secret.
+    class ConfigurationError < Error; end
+
+    # Raised when the merchant's workspace ID is missing or malformed. The
+    #   workspace ID ends up in the host of the URL the user is redirected to,
+    #   so an unchecked value would allow redirecting to an arbitrary host.
+    class MerchantIdInvalid < Error; end
+
+    # Raised when the user cancelled the installation, or when Fulfil reported
+    #   an error on the callback.
+    class AuthorizationDenied < Error; end
+
+    # Raised when the `state` on the callback does not match the one generated
+    #   when the flow was started, which means the callback cannot be trusted.
+    class StateMismatch < Error; end
+
+    # Raised when exchanging the authorization code for an access token failed.
+    class TokenExchangeFailed < Error; end
+  end
+end

data/lib/fulfil_api/relation.rb

@@ -48,8 +48,8 @@ module FulfilApi
     #
     # @yield [resource] Yields each resource object to the given block.
     # @return [Enumerator, self] Returns an Enumerator if no block is given; otherwise, returns self.
-    def each(&block)
-      all.each(&block)
+    def each(&)
+      all.each(&)
     end
 
     # Resets any of the previously provided query conditions.

data/lib/fulfil_api/resource/attribute_assignable.rb

@@ -76,23 +76,23 @@ module FulfilApi
       #   $ build_attribute("warehouse.id", 10)
       #   => { "warehouse" => { "id" => 10 } }
       #
-      # @param attribute_names [String, Symbol] The expanded list of attribute names
+      # @example attribute where the relation and its field share a name
+      #   $ build_attribute("tracking_number.tracking_number", "T04DDA5014242536")
+      #   => { "tracking_number" => { "tracking_number" => "T04DDA5014242536" } }
+      #
+      # @param name [String, Symbol] The attribute name
       # @param value [Any] The attribute value
       # @return [Hash] The newly build attribute
-      def build_attribute(name, value) # rubocop:disable Metrics/MethodLength
-        attribute_names = name.to_s.split(".")
-        attribute = {}
-        attribute_level = attribute
+      def build_attribute(name, value)
+        *relation_names, attribute_name = name.to_s.split(".")
+        return {} if attribute_name.nil?
 
-        attribute_names.each do |attribute_name|
-          if attribute_name == attribute_names.last
-            attribute_level[attribute_name] = type_cast_attribute_value(value)
-          else
-            attribute_level[attribute_name] ||= {}
-            attribute_level = attribute_level[attribute_name]
-          end
+        attribute = {}
+        attribute_level = relation_names.reduce(attribute) do |level, relation_name|
+          level[relation_name] ||= {}
         end
 
+        attribute_level[attribute_name] = type_cast_attribute_value(value)
         attribute
       end
 

data/lib/fulfil_api/tpl_client.rb

@@ -128,6 +128,9 @@ module FulfilApi
           configure_persistent_connection(http)
         end
 
+        # Retries and other safeguards wrap every request, so they're added first
+        FulfilApi::Middleware.apply(connection, configuration)
+
         # Configuration of the request middleware
         connection.request :json
 
@@ -151,11 +154,9 @@ module FulfilApi
     # Tunes the underlying Net::HTTP::Persistent connection.
     #
     # The `net_http_persistent` adapter forces `max_retries` to 0 on every
-    #   request, which disables Ruby's built-in retry for idempotent requests.
-    #   Restoring it lets a stale keep-alive socket — one the server has already
-    #   closed — be retried transparently on a fresh socket instead of surfacing
-    #   as a read timeout. The config block runs after the adapter zeroes the
-    #   value, so this takes effect.
+    #   request. Retries are handled by {FulfilApi::Middleware::Retry} instead, so
+    #   `max_retries` is only restored when it's configured explicitly. The config
+    #   block runs after the adapter zeroes the value, so this takes effect.
     #
     # @param http [Net::HTTP::Persistent] The live persistent connection.
     # @return [void]
@@ -170,7 +171,10 @@ module FulfilApi
 
     # @return [Array] The cache key identifying a unique connection.
     def connection_cache_key
-      [merchant_id, api_version, configuration.request_options, configuration.connection_options]
+      [
+        merchant_id, api_version, configuration.request_options, configuration.connection_options,
+        configuration.retry_options, configuration.circuit_breaker
+      ]
     end
 
     # @param relative_path [String] The relative path to the API endpoint.

data/lib/fulfil_api/version.rb

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

data/lib/fulfil_api.rb

@@ -3,18 +3,29 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect("oauth" => "OAuth")
+loader.ignore("#{__dir__}/fulfil_api/engine.rb")
 loader.ignore("#{__dir__}/fulfil_api/test_helper.rb")
+loader.ignore("#{__dir__}/generators")
 loader.setup
 
 require "active_support"
+require "active_support/cache"
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/hash/deep_merge"
 require "active_support/core_ext/hash/indifferent_access"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/object/blank"
 require "active_support/notifications"
+require "faraday"
+require "faraday/retry"
 
 module FulfilApi
 end
 
 loader.eager_load
+
+# The Rails-specific parts of the gem — the engine, its models, its controllers,
+#   and its generators — are only loaded when the gem is used from within a
+#   Rails application.
+require "fulfil_api/engine" if defined?(Rails::Engine)

data/lib/generators/fulfil_api/install/install_generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module FulfilApi
+  module Generators
+    # Sets a Rails application up for Fulfil's OAuth flow: it writes an
+    #   initializer, adds the migration for {FulfilApi::Installation}, and mounts
+    #   {FulfilApi::Engine}.
+    #
+    # @example
+    #   bin/rails generate fulfil_api:install
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs the Fulfil OAuth initializer, migration, and engine route."
+
+      # @return [void]
+      def copy_initializer
+        template "fulfil_api.rb", "config/initializers/fulfil_api.rb"
+      end
+
+      # @return [void]
+      def create_migration_file
+        migration_template "create_fulfil_api_installations.rb",
+                           "db/migrate/create_fulfil_api_installations.rb"
+      end
+
+      # @return [void]
+      def mount_engine
+        route %(mount FulfilApi::Engine => "#{FulfilApi::OAuth::Configuration::DEFAULT_MOUNT_PATH}")
+      end
+
+      # @return [void]
+      def show_readme
+        say(remaining_steps)
+      end
+
+      private
+
+      # @return [String] The Active Record migration version to generate against.
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      # Nothing changes in the application until these are done, so an existing
+      #   application can install the gem without switching to OAuth yet.
+      #
+      # @return [String]
+      def remaining_steps
+        <<~MESSAGE
+
+          Fulfil's OAuth flow is installed. To finish setting it up:
+
+            1. Run `bin/rails db:migrate` to create the fulfil_api_installations table.
+            2. Run `bin/rails db:encryption:init` and store the keys in your credentials,
+               unless Active Record encryption is already configured. The access tokens
+               are encrypted at rest.
+            3. Create an app on https://auth.fulfil.io/user/clients and whitelist
+               #{FulfilApi::OAuth::Configuration::DEFAULT_MOUNT_PATH}/callback as a redirection URL.
+            4. Fill in FULFIL_OAUTH_CLIENT_ID and FULFIL_OAUTH_CLIENT_SECRET.
+            5. Set config.oauth.parent_controller to the controller that authenticates
+               a request in this application. The OAuth flow refuses to run without it.
+
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/generators/fulfil_api/install/templates/create_fulfil_api_installations.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class CreateFulfilApiInstallations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :fulfil_api_installations do |t|
+      # An installation without an owner is the application-wide installation.
+      t.references :owner, polymorphic: true, null: true, index: false
+
+      t.string :merchant_id, null: false
+
+      # Fulfil grants the permanent token only in `offline_access` mode, and the
+      #   short-lived one is the only token in `user_session` mode. Neither is
+      #   required on its own; FulfilApi::Installation requires one of the two.
+      t.text :access_token
+      t.text :offline_access_token
+
+      # The gem fills the token type in rather than relying on Fulfil to send it.
+      t.string :token_type, null: false, default: "Bearer"
+
+      # Nullable because Active Record serialization writes an empty list as
+      #   NULL and reads it back as one, so the column is never meaningfully
+      #   blank even though it can be NULL.
+      t.text :scopes
+
+      # Describes the short-lived token only. A permanent token has no expiry:
+      #   it is revoked by uninstalling the app, not by time.
+      t.datetime :expires_at
+
+      # Who walked through the authorization flow. Recorded for support, nothing
+      #   in the gem depends on it, and Fulfil is free to leave parts of it out.
+      t.integer :associated_user_id
+      t.string :associated_user_email
+      t.string :associated_user_name
+
+      t.timestamps
+    end
+
+    # An owner is connected to a single Fulfil workspace. Databases treat NULLs
+    #   as distinct, so this index does not constrain the application-wide
+    #   installation; FulfilApi::Installation validates that case.
+    add_index :fulfil_api_installations, %i[owner_type owner_id], unique: true
+  end
+end

data/lib/generators/fulfil_api/install/templates/fulfil_api.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+FulfilApi.configure do |config|
+  # The subdomain of the Fulfil workspace this application talks to. Leave it
+  #   blank when every tenant brings its own workspace, and override
+  #   `fulfil_merchant_id` in ApplicationController instead.
+  config.merchant_id = ENV.fetch("FULFIL_MERCHANT_ID", nil)
+
+  # The credentials of the app registered on https://auth.fulfil.io/user/clients.
+  config.oauth.client_id = ENV.fetch("FULFIL_OAUTH_CLIENT_ID", nil)
+  config.oauth.client_secret = ENV.fetch("FULFIL_OAUTH_CLIENT_SECRET", nil)
+
+  # The scopes to request. See https://developers.fulfil.io for the full list.
+  config.oauth.scopes = []
+
+  # `:offline_access` grants a permanent token that keeps working when no user
+  #   is around, which is what background jobs need. `:user_session` grants a
+  #   token that expires with the user's Fulfil session.
+  config.oauth.access_type = :offline_access
+
+  # Where the user ends up after installing the app, unless they were sent to
+  #   the flow from somewhere else. Accepts a path or a callable taking the
+  #   FulfilApi::Installation that was created.
+  config.oauth.after_install_path = "/"
+
+  # REQUIRED before the OAuth flow can be used. The engine's controllers inherit
+  #   from this one, so it has to be a controller that authenticates the request
+  #   and — in an application serving many merchants — establishes the current
+  #   tenant. There is deliberately no default: an unauthenticated flow lets a
+  #   stranger record their own Fulfil workspace over yours, and a flow outside
+  #   the application's tenancy records installations against the wrong owner.
+  #
+  # config.oauth.parent_controller = "AuthenticatedController"
+
+  # Fulfil requires the redirect URL to be whitelisted on the app. It defaults
+  #   to the engine's callback URL, which is derived from the incoming request.
+  # config.oauth.redirect_uri = "https://example.com/fulfil/callback"
+end

metadata

@@ -1,29 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.1
 platform: ruby
 authors:
 - Stefan Vermaas
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '7'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -80,14 +93,29 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- app/controllers/concerns/fulfil_api/authenticated.rb
+- app/controllers/concerns/fulfil_api/installation_scoped.rb
+- app/controllers/fulfil_api/application_controller.rb
+- app/controllers/fulfil_api/installations_controller.rb
+- app/models/concerns/fulfil_api/installable.rb
+- app/models/fulfil_api/installation.rb
+- config/routes.rb
 - lib/fulfil_api.rb
 - lib/fulfil_api/access_token.rb
+- lib/fulfil_api/circuit_open.rb
 - lib/fulfil_api/client.rb
 - lib/fulfil_api/configuration.rb
 - lib/fulfil_api/customer_shipment.rb
+- lib/fulfil_api/engine.rb
 - lib/fulfil_api/error.rb
 - lib/fulfil_api/error/notifiable.rb
 - lib/fulfil_api/http_error.rb
+- lib/fulfil_api/middleware.rb
+- lib/fulfil_api/middleware/circuit_breaker.rb
+- lib/fulfil_api/oauth.rb
+- lib/fulfil_api/oauth/authorization.rb
+- lib/fulfil_api/oauth/configuration.rb
+- lib/fulfil_api/oauth/token.rb
 - lib/fulfil_api/relation.rb
 - lib/fulfil_api/relation/batchable.rb
 - lib/fulfil_api/relation/countable.rb
@@ -105,6 +133,9 @@ files:
 - lib/fulfil_api/test_helper.rb
 - lib/fulfil_api/tpl_client.rb
 - lib/fulfil_api/version.rb
+- lib/generators/fulfil_api/install/install_generator.rb
+- lib/generators/fulfil_api/install/templates/create_fulfil_api_installations.rb
+- lib/generators/fulfil_api/install/templates/fulfil_api.rb
 - sig/fulfil_api.rbs
 homepage: https://www.github.com/codeturebv/fulfil_api
 licenses:
@@ -114,7 +145,13 @@ metadata:
   source_code_uri: https://www.github.com/codeturebv/fulfil_api
   changelog_uri: https://www.github.com/codeturebv/fulfil_api/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: |+
+  Using fulfil_api in a Rails application? Run the install generator to set up
+  Fulfil's OAuth flow, then run the migration it adds:
+
+    bin/rails generate fulfil_api:install
+    bin/rails db:migrate
+
 rdoc_options: []
 require_paths:
 - lib
@@ -122,15 +159,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A HTTP client to interact the Fulfil.io API
 test_files: []
+...