fulfil_api 0.7.2 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a5ff8f7f8d9afe6a5130c2cf042875f2d79eabcdb53f61e7f229d03b2dc0c6e
-  data.tar.gz: 017f33c16b4562586e696724b8428f76bc27daeeaf61b0cd2d783f79a952b7e4
+  metadata.gz: b1e3793aadb8a9615fdddb8970acbc23564eec7965e8655558cc9062bdb43c00
+  data.tar.gz: fbae55d2bec65240dbbb44370411b452bb2461a8021668f70be3af67ee1decfe
 SHA512:
-  metadata.gz: 387283adc42ad86ed86cea9c20f0c65728fb942b7ef7db70286a2dac2fcc544b0bf49a78feb520ff918faec916dabadf94067f71003bab2adb4087219fe63437
-  data.tar.gz: 8a69f8a11d5152825c8648babbe9535e533d394e13f8da819759eca069aab66bc8656517b35b5d4275ad62ffcabe4e022e93952e09f2780508bca8d90ba6830e
+  metadata.gz: 4cd81653bfe993a17a6552adfaceef0c0ea22f351ae900cc63dd436eb8461767c9d494d372cdc9458f44b5e5af0f6e4860aad49eabdca079ce5e59a32df15c53
+  data.tar.gz: cbf055f30acca04e2eeaf6aa510d90345ca603e50e016154626e363adca1e92f9a8f4e01f98bb238e32bb656a9d39b597071fb94f20d62cf1f98e09974e523ff

data/.rubocop.yml

@@ -6,9 +6,11 @@ plugins:
 AllCops:
   Exclude:
     - bin/*
+    - lib/generators/**/templates/**/*
+    - tmp/**/*
     - vendor/**/*
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
 
 Layout/LineLength:
   Exclude:
@@ -33,3 +35,9 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Style/ArgumentsForwarding:
+  # The test helper is a documented, public API. Anonymous forwarding would hide
+  #   the keyword arguments it accepts from both the reader and its YARD docs.
+  Exclude:
+    - lib/fulfil_api/test_helper.rb

data/.ruby-version

@@ -1 +1 @@
-3.3.4
+4.0.7

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+- Send the `grant_type` and `redirect_uri` in the form body when exchanging an authorization code, the way OAuth 2.0 defines the token request. The grant type used to travel in the query string and the redirect URI was left out, which Fulfil accepts today but isn't required to.
+
+- Separate the requested OAuth scopes with spaces instead of commas. Fulfil didn't recognize the comma separated list, and a workspace granted every scope the approving user had rather than the ones that were asked for.
+
+- Require Rails 8.0 and Ruby 3.2 or newer. Every application using the gem is on Rails 8 already, so carrying support for older versions bought nothing.
+
+- Add support for Fulfil's OAuth 2.0 authorization flow, so applications no longer depend on personal access tokens now that Fulfil caps their lifetime. `FulfilApi::OAuth::Authorization` builds the consent screen URL and exchanges the authorization code for a token, and `config.oauth` holds the OAuth app's credentials.
+
+- Ship the flow as a Rails engine that is only loaded inside a Rails application. `bin/rails generate fulfil_api:install` writes the initializer, adds the migration for `FulfilApi::Installation`, and mounts the engine. Installing changes nothing about how an application behaves until `config.oauth.parent_controller` names the controller the flow runs under, so an application still on personal access tokens can move to OAuth in its own time. There is no default: the engine's controllers inherit from it, and guessing wrong leaves an endpoint a stranger can use to record their own Fulfil workspace over the application's.
+
+- Add the `FulfilApi::Authenticated` controller concern, which runs every action with a client authenticated as the current installation and sends a user without a usable token through the OAuth flow.
+
+- Add the `FulfilApi::Installable` model concern, so an application serving many merchants can keep one installation per record instead of one for the whole application. A record is connected to a single Fulfil workspace.
+
+- Add an optional circuit breaker, backed by [Faulty](https://github.com/ParentSquare/faulty), that stops sending requests to a Fulfil instance that keeps failing, so a struggling instance can't tie up every thread of an application that talks to several of them. Pass a `Faulty` instance as `circuit_breaker`; each Fulfil instance gets its own circuit, and while it's open requests raise a `FulfilApi::CircuitOpen` without touching the network.
+
+- Retry only the requests that are safe to retry. Ruby's built-in retry treated every `PUT` as idempotent, but Fulfil writes through `PUT` too (updating a record, holding a shipment), so a write that timed out could be sent twice. Retries now run through `faraday-retry`, configured to only retry `GET` requests and `PUT` requests to `search_read` and `search_count` by default, configurable through the new `retry_options`. The built-in retry is off by default again; `connection_options: { max_retries: ... }` still turns it on.
+
+- Expand a nested field into its relation even when the field carries the same name as the relation it hangs off. Selecting both `tracking_number` and `tracking_number.tracking_number` on a shipment used to drop the relation and leave the tracking number as a plain string on the shipment itself, because the gem decided where a field belonged by matching names in the path instead of counting positions.
+
 - Publish an `ActiveSupport::Notifications` event named `error.fulfil_api` whenever a `FulfilApi::Error` is raised, so an application can report failures of the Fulfil API to its APM without rescuing every call into the gem. Subscribe with `FulfilApi.on_error { |error| ... }`, or through `ActiveSupport::Notifications` directly to also reach the status code, response body and response headers of a `FulfilApi::HttpError`.
 
 - Raise a `FulfilApi::HttpError` instead of a generic `FulfilApi::Error` when a request to Fulfil fails, with a dedicated subclass per HTTP status code (e.g. `FulfilApi::HttpError::TooManyRequests` for a 429). The exception message is now the description reported by Fulfil rather than its serialized response body, and the status code, body and headers are available through `#status_code`, `#response_body` and `#response_headers`. `FulfilApi::HttpError` inherits from `FulfilApi::Error`, so existing rescues keep working.

data/README.md

@@ -57,7 +57,7 @@ This makes it easy to use different settings in contexts with different constrai
 ```ruby
 FulfilApi.with_config(
   request_options: { open_timeout: 5, read_timeout: 60, write_timeout: 30 },
-  connection_options: { max_retries: 3, idle_timeout: 10 }
+  retry_options: { max_retries: 3 }
 ) do
   # Long-running work against the Fulfil API
 end
@@ -77,13 +77,160 @@ The following configuration options are (currently) available throught both conf
 
 > **NOTE:** With the persistent (keep-alive) adapter there is no single whole-request `timeout`; Faraday resolves `read_timeout`, `open_timeout`, and `write_timeout` independently. `read_timeout` is the value that governs a slow or stalled response.
 
+- `retry_options` (`Hash`): Which requests [`faraday-retry`](https://github.com/lostisland/faraday-retry) retries when they fail before Fulfil answers them (a dropped keep-alive socket, a refused connection or a timeout). An error response from Fulfil is never retried. Supported keys:
+  - `max_retries` (default `1`): The maximum number of retries per request.
+  - `requests` (default: every `GET`, and `PUT` requests to `search_read` and `search_count`): A hash of HTTP verbs, each mapped to `true` for every endpoint or to a list of patterns matched against the request path. Fulfil reads through `PUT` as well as writes through it, so only the read endpoints are retried by default. Retrying a write that timed out could apply it twice.
+
+```ruby
+FulfilApi.configure do |config|
+  config.retry_options = {
+    max_retries: 2,
+    requests: { get: true, put: [%r{/search_read\z}, %r{/search_count\z}, %r{/model/sale\.sale/\d+\z}] }
+  }
+end
+```
+
+- `circuit_breaker` (`Faulty`, optional): A [Faulty](https://github.com/ParentSquare/faulty) instance to stop sending requests to a Fulfil instance that keeps failing. Off by default. See [Stopping requests to a failing Fulfil instance](#stopping-requests-to-a-failing-fulfil-instance).
+
 - `connection_options` (`Hash`): Tuning for the persistent (keep-alive) connection. Supported keys:
-  - `max_retries` (default `1`): Re-enables Ruby's built-in retry for **idempotent** requests (`GET`/`HEAD`/`PUT`/`DELETE`/`OPTIONS`). The `net_http_persistent` adapter disables this by forcing it to `0`, which makes a keep-alive socket the server has already dropped surface as a read timeout instead of being retried transparently on a fresh socket. `POST` is never auto-retried, so this is side-effect safe. Set to `0` to restore the adapter's default behaviour.
+  - `max_retries` (optional): Re-enables Ruby's built-in retry, which retries **every** idempotent request (`GET`/`HEAD`/`PUT`/`DELETE`/`OPTIONS`) whatever its endpoint, writes through `PUT` included. Off by default; prefer `retry_options`.
   - `idle_timeout` (`Integer`, optional): Seconds a pooled socket may sit idle before it is recycled. Lower this towards your server's keep-alive window to shrink the stale-socket window for non-idempotent requests.
   - `pool_size` (`Integer`, optional): Maximum number of concurrent connections kept in the pool.
 
 > **NOTE:** When retries are enabled, the worst-case time for a request is roughly `(max_retries + 1) × read_timeout`. On platforms with a hard request cap (e.g. Heroku's 30s router limit), keep `read_timeout` low enough that this product stays under the cap.
 
+- `oauth` (`FulfilApi::OAuth::Configuration`): The credentials and options of the OAuth app used by the [OAuth flow](#authenticating-with-oauth-rails). Assign it a `Hash`, or set its options one by one on `config.oauth`.
+
+### Stopping requests to a failing Fulfil instance
+
+An application that talks to several Fulfil instances shouldn't let one struggling instance tie up all of its threads. The gem can run every request through a [Faulty](https://github.com/ParentSquare/faulty) circuit breaker. Faulty isn't a dependency of the gem, so add it to your own `Gemfile` first:
+
+```ruby
+gem "faulty"
+```
+
+Then hand the gem a Faulty instance. Its `circuit_defaults` set the thresholds, and its storage decides whether the state is kept per process (in memory) or shared between processes (e.g. Redis):
+
+```ruby
+FulfilApi.configure do |config|
+  config.circuit_breaker = Faulty.new(
+    storage: Faulty::Storage::Redis.new(client: Redis.new),
+    circuit_defaults: { rate_threshold: 0.5, sample_threshold: 5, cool_down: 60 }
+  )
+end
+```
+
+Every Fulfil instance gets its own circuit, so one failing instance never stops requests to another. The `Client` and the `TplClient` of the same instance share a circuit. Timeouts, dropped connections and 5xx responses count as failures. A 4xx response is an answer and doesn't count, and a request that failed after retrying counts once.
+
+While a circuit is closed, failed requests raise the same `FulfilApi::HttpError` they always do. Once it opens, requests raise a `FulfilApi::CircuitOpen` without touching the network, until Faulty's cool-down lets a test request through.
+
+### Authenticating with OAuth (Rails)
+
+Fulfil caps the lifetime of personal access tokens, so an application that has to keep working unattended needs an OAuth token instead. The gem ships the whole flow as a Rails engine: a user is sent to Fulfil's consent screen, comes back with an authorization code, and the resulting token is stored as a `FulfilApi::Installation`.
+
+The Rails parts of the gem only load when the gem is used from within a Rails application. Everywhere else, `fulfil_api` stays the plain HTTP client it has always been.
+
+> **NOTE:** The engine requires Rails 8.0 or newer.
+
+#### Setting it up
+
+1. Create an app in Fulfil's [authentication dashboard](https://auth.fulfil.io/user/clients) and whitelist `https://your-app.example.com/fulfil/callback` as a redirection URL.
+2. Run the install generator and its migration:
+
+```shell
+  $ bin/rails generate fulfil_api:install
+  $ bin/rails db:migrate
+```
+
+The generator writes `config/initializers/fulfil_api.rb`, adds the migration for the `fulfil_api_installations` table, and mounts the engine at `/fulfil`. None of that changes how the application behaves: the routes have no callers, and the flow refuses to run until step 3 below. An application still on personal access tokens can install the gem and move to OAuth later.
+
+3. Fill in the app's credentials, and name the controller the flow runs under:
+
+```ruby
+# config/initializers/fulfil_api.rb
+
+FulfilApi.configure do |config|
+  config.merchant_id = ENV.fetch("FULFIL_MERCHANT_ID", nil)
+
+  config.oauth.client_id = ENV.fetch("FULFIL_OAUTH_CLIENT_ID", nil)
+  config.oauth.client_secret = ENV.fetch("FULFIL_OAUTH_CLIENT_SECRET", nil)
+  config.oauth.scopes = %w[sale.sale]
+
+  config.oauth.parent_controller = "AuthenticatedController"
+end
+```
+
+> **NOTE:** `parent_controller` has no default on purpose. The engine's controllers inherit from it, so it has to be a controller that authenticates the request — and, in an application serving many merchants, one that establishes the current tenant. An unauthenticated flow lets a stranger walk through it and record their own Fulfil workspace over yours; a flow outside the application's tenancy records installations against the wrong owner. Until it is set, the flow raises `FulfilApi::OAuth::ConfigurationError`.
+
+> **NOTE:** The access tokens are encrypted at rest with Active Record Encryption. Run `bin/rails db:encryption:init` and store the keys in your credentials if the application does not use it yet.
+
+#### Available OAuth options
+
+- `client_id` / `client_secret` (`String`): The app's credentials, found under **App Credentials** in Fulfil's authentication dashboard.
+- `scopes` (`Array<String>`, default `[]`): The scopes to request. See [https://developers.fulfil.io](https://developers.fulfil.io) for the full list.
+- `access_type` (`Symbol`, default `:offline_access`): `: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. Fulfil has no refresh token, so an expired `:user_session` token can only be replaced by walking through the flow again.
+- `after_install_path` (`String` or callable, default `"/"`): Where the user ends up after installing the app, unless they were sent to the flow from somewhere else. A callable receives the `FulfilApi::Installation` that was created.
+- `parent_controller` (`String`, **required**): The controller the engine's own controllers inherit from, so the flow picks up the application's authentication, layout, and multi-tenancy. No default — see the note above.
+- `redirect_uri` (`String`, optional): Defaults to the engine's callback URL, derived from the incoming request. Set it when the application sits behind a proxy that rewrites the host.
+
+#### Kicking off the flow automatically
+
+Include `FulfilApi::Authenticated` in a controller. Every action then runs with a client authenticated as the current installation, and a user without a usable token is sent through the flow and returned to where they were headed.
+
+```ruby
+class SalesOrdersController < ApplicationController
+  include FulfilApi::Authenticated
+
+  def index
+    @sales_orders = FulfilApi::Resource.set(model_name: "sale.sale").limit(50)
+  end
+end
+```
+
+#### One installation per tenant
+
+By default the installation belongs to the application as a whole, which is what an application built for a single merchant needs. An application serving many merchants ties the installation to a record instead:
+
+```ruby
+class Shop < ApplicationRecord
+  include FulfilApi::Installable
+end
+```
+
+A record is connected to a single Fulfil workspace. Installing it on another one replaces what came before rather than leaving the record connected to two, and drops the token the previous workspace granted.
+
+Point the flow at the current tenant by overriding two methods in `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+
+  def fulfil_installation_owner
+    Current.shop
+  end
+
+  def fulfil_merchant_id
+    Current.shop.fulfil_merchant_id
+  end
+end
+```
+
+Outside of a request — in a background job, for instance — go through the record:
+
+```ruby
+shop.with_fulfil_config do |client|
+  client.get("model/sale.sale")
+end
+```
+
+`FulfilApi::Installation` is a plain Active Record model, so an application-wide token works the same way:
+
+```ruby
+FulfilApi::Installation.global.sole.with_config do |client|
+  client.get("model/sale.sale")
+end
+```
+
 ### Querying the Fulfil API
 
 > **NOTE:** Currently, the gem is under heavy development. The querying interface of the gem is really basic at the moment. In the future, we will closer match the querying interface of `ActiveRecord`.

data/app/controllers/concerns/fulfil_api/authenticated.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # Guarantees that every action of a controller runs with a working Fulfil API
+  #   client, by sending the user through the OAuth flow when it does not.
+  #
+  # The user is returned to the action they were trying to reach once the app is
+  #   installed, so a missing or expired token is a detour rather than a dead
+  #   end.
+  #
+  # @example
+  #   class SalesOrdersController < ApplicationController
+  #     include FulfilApi::Authenticated
+  #
+  #     def index
+  #       @sales_orders = FulfilApi::Resource.set(model_name: "sale.sale").limit(50)
+  #     end
+  #   end
+  module Authenticated
+    extend ActiveSupport::Concern
+    include FulfilApi::InstallationScoped
+
+    included do
+      around_action :with_fulfil_installation
+    end
+
+    private
+
+    # @return [void]
+    def redirect_to_fulfil_installation
+      redirect_to fulfil_api.new_installation_path(
+        merchant_id: fulfil_merchant_id, return_to: request.fullpath
+      )
+    end
+
+    # @return [void]
+    def with_fulfil_installation(&)
+      return redirect_to_fulfil_installation unless fulfil_installation&.usable?
+
+      fulfil_installation.with_config(&)
+    end
+  end
+end

data/app/controllers/concerns/fulfil_api/installation_scoped.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # Answers which Fulfil installation a request belongs to.
+  #
+  # Out of the box that is the application-wide installation on the configured
+  #   merchant, which is what a Rails application built for a single merchant
+  #   needs. An application serving many merchants overrides these methods in
+  #   its own `ApplicationController` to scope the installation to the current
+  #   tenant.
+  #
+  # The engine's own controllers include this module below the application's
+  #   parent controller. The defaults therefore defer to an override further up
+  #   the chain, or the OAuth callback would ignore the tenant and record an
+  #   application-wide installation.
+  #
+  # @example An application with an installation per shop
+  #   class ApplicationController < ActionController::Base
+  #     private
+  #
+  #     def fulfil_installation_owner
+  #       Current.shop
+  #     end
+  #
+  #     def fulfil_merchant_id
+  #       Current.shop.fulfil_merchant_id
+  #     end
+  #   end
+  module InstallationScoped
+    extend ActiveSupport::Concern
+
+    private
+
+    # @return [FulfilApi::Installation, nil]
+    def fulfil_installation
+      return @fulfil_installation if defined?(@fulfil_installation)
+
+      @fulfil_installation = FulfilApi::Installation.installed_on(
+        merchant_id: fulfil_merchant_id, owner: fulfil_installation_owner
+      )
+    end
+
+    # The record the installation belongs to. `nil` means the installation is
+    #   shared by the whole application.
+    #
+    # @return [ActiveRecord::Base, nil]
+    def fulfil_installation_owner
+      defined?(super) ? super : nil
+    end
+
+    # @return [String, nil] The Fulfil workspace of the current request.
+    def fulfil_merchant_id
+      defined?(super) ? super : FulfilApi.configuration.merchant_id
+    end
+  end
+end

data/app/controllers/fulfil_api/application_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # Inherits from the controller named by `config.oauth.parent_controller`, so
+  #   the engine's controllers pick up the host application's authentication,
+  #   layout, and multi-tenancy.
+  #
+  # Until an application names one, the flow refuses to run rather than falling
+  #   back to something that looks reasonable. An unauthenticated OAuth flow lets
+  #   a stranger walk through it and record their own Fulfil workspace over the
+  #   application's, and a flow that runs outside the application's tenancy
+  #   silently records an installation against the wrong owner.
+  class ApplicationController < FulfilApi.configuration.oauth.parent_controller_class
+    include FulfilApi::InstallationScoped
+
+    before_action :verify_parent_controller!
+
+    private
+
+    # @raise [FulfilApi::OAuth::ConfigurationError]
+    # @return [void]
+    def verify_parent_controller!
+      return if FulfilApi.configuration.oauth.parent_controller_configured?
+
+      raise FulfilApi::OAuth::ConfigurationError,
+            "Set config.oauth.parent_controller to the controller that authenticates a request in this " \
+            "application before using the OAuth flow. Without one, anyone can reach the flow and record " \
+            "their own Fulfil workspace over yours."
+    end
+  end
+end

data/app/controllers/fulfil_api/installations_controller.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # Walks a user through Fulfil's OAuth 2.0 authorization flow.
+  #
+  # `GET /installation/new` sends the user to Fulfil's consent screen, and
+  #   `GET /callback` turns the authorization code they return with into an
+  #   {FulfilApi::Installation}. The callback URL is the one that has to be
+  #   whitelisted on the app in Fulfil's authentication dashboard.
+  class InstallationsController < FulfilApi::ApplicationController
+    MERCHANT_ID_SESSION_KEY = "fulfil_api.oauth.merchant_id"
+    RETURN_TO_SESSION_KEY = "fulfil_api.oauth.return_to"
+    STATE_SESSION_KEY = "fulfil_api.oauth.state"
+
+    # Handles the callback of the authorization flow.
+    #
+    # @raise [FulfilApi::OAuth::AuthorizationDenied] When the user cancelled the installation.
+    # @raise [FulfilApi::OAuth::StateMismatch] When the callback cannot be tied
+    #   to the authorization request that started it.
+    # @return [void]
+    def create
+      merchant_id = session.delete(MERCHANT_ID_SESSION_KEY)
+      return_to = session.delete(RETURN_TO_SESSION_KEY)
+      verify_state!
+
+      authorization = authorization_for(merchant_id)
+      installation = FulfilApi::Installation.install(
+        authorization.exchange(params[:code]),
+        merchant_id: authorization.merchant_id,
+        owner: fulfil_installation_owner
+      )
+
+      redirect_to return_to.presence || after_install_path(installation), allow_other_host: false
+    end
+
+    # Kicks off the authorization flow by sending the user to Fulfil.
+    #
+    # @return [void]
+    def new
+      authorization = authorization_for(params[:merchant_id])
+      remember_authorization_request(authorization)
+
+      redirect_to authorization.url(state: session[STATE_SESSION_KEY]), allow_other_host: true
+    end
+
+    private
+
+    # @param installation [FulfilApi::Installation] The installation that was just created.
+    # @return [String]
+    def after_install_path(installation)
+      path = FulfilApi.configuration.oauth.after_install_path
+      path.respond_to?(:call) ? path.call(installation) : path
+    end
+
+    # Fulfil does not send the workspace back to the callback, so the one the
+    #   flow started on is kept in the session. Without it, a workspace the user
+    #   picked when starting the flow would be lost, and the code exchanged on
+    #   whatever {#fulfil_merchant_id} returns instead.
+    #
+    # @param merchant_id [String, nil] The workspace to install the app on.
+    #   Defaults to the workspace of the current request.
+    # @return [FulfilApi::OAuth::Authorization]
+    def authorization_for(merchant_id)
+      FulfilApi::OAuth::Authorization.new(
+        merchant_id: merchant_id.presence || fulfil_merchant_id,
+        redirect_uri: FulfilApi.configuration.oauth.redirect_uri.presence || callback_url
+      )
+    end
+
+    # Only paths within the application are remembered, so the `return_to`
+    #   parameter cannot be used to bounce a user off to another host.
+    #
+    # @return [true, false]
+    def internal_return_to?
+      params[:return_to].present? && params[:return_to].to_s.start_with?("/") &&
+        !params[:return_to].to_s.start_with?("//")
+    end
+
+    # Keeps what the callback needs to finish the flow: the nonce to verify,
+    #   the workspace to exchange the code on, and where to send the user after.
+    #
+    # @param authorization [FulfilApi::OAuth::Authorization] The authorization being requested.
+    # @return [void]
+    def remember_authorization_request(authorization)
+      session[MERCHANT_ID_SESSION_KEY] = authorization.merchant_id
+      session[STATE_SESSION_KEY] = FulfilApi::OAuth::Authorization.generate_state
+      session[RETURN_TO_SESSION_KEY] = params[:return_to] if internal_return_to?
+    end
+
+    # @raise [FulfilApi::OAuth::AuthorizationDenied]
+    # @return [void]
+    def verify_authorization!
+      return if params[:error].blank?
+
+      raise FulfilApi::OAuth::AuthorizationDenied,
+            "Fulfil denied the authorization request: #{params[:error_description].presence || params[:error]}"
+    end
+
+    # @raise [FulfilApi::OAuth::AuthorizationDenied]
+    # @raise [FulfilApi::OAuth::StateMismatch]
+    # @return [void]
+    def verify_state!
+      state = session.delete(STATE_SESSION_KEY)
+      verify_authorization!
+
+      return if state.present? && ActiveSupport::SecurityUtils.secure_compare(state, params[:state].to_s)
+
+      raise FulfilApi::OAuth::StateMismatch, "The state of the callback does not match the authorization request"
+    end
+  end
+end

data/app/models/concerns/fulfil_api/installable.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # Gives a record its own Fulfil installation, so an application that serves
+  #   many merchants can keep one access token per tenant instead of one for the
+  #   whole application. A record is connected to a single Fulfil workspace:
+  #   installing on another one replaces what came before.
+  #
+  # @example
+  #   class Shop < ApplicationRecord
+  #     include FulfilApi::Installable
+  #   end
+  #
+  #   shop.with_fulfil_config do |client|
+  #     client.get("model/sale.sale")
+  #   end
+  #
+  # The concern deliberately leaves the Fulfil workspace of a record alone: that
+  #   is usually a column on the record itself, which the authorization flow
+  #   reads through `fulfil_merchant_id` in the host's ApplicationController.
+  module Installable
+    extend ActiveSupport::Concern
+
+    included do
+      has_one :fulfil_installation, as: :owner, class_name: "FulfilApi::Installation", dependent: :destroy
+    end
+
+    # @return [true, false] Whether the record can talk to the Fulfil API.
+    def fulfil_installed?
+      fulfil_installation&.usable? || false
+    end
+
+    # Runs a block against the Fulfil API as this record.
+    #
+    # @yieldparam [FulfilApi::Client] client A client authenticated as this record.
+    # @raise [FulfilApi::OAuth::Error] When the record has no usable installation.
+    # @return [void]
+    def with_fulfil_config(&)
+      unless fulfil_installed?
+        raise FulfilApi::OAuth::Error,
+              "#{self.class.name} #{id} has no usable Fulfil installation"
+      end
+
+      fulfil_installation.with_config(&)
+    end
+  end
+end