fulfil_api 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2971bc621921930210bce77c057d6da8ce549cfe476fb1fc29d72f10c4447303
-  data.tar.gz: 97658bf767d8909e359ad66441de0f81108982c6383070778eb04d3386c2fb3d
+  metadata.gz: 6f433cc5985d728b55fbc2d60bfc4b953c816ec0ca75dc46d33a30999571cef9
+  data.tar.gz: f66f3c19a009cd3592cbe73a97c04fea29654c6147c90c8000c2361cb5326309
 SHA512:
-  metadata.gz: 020e57b3a676a3c56f2d2b76e5b269010764d3a95f41ef19848f0477e4f77ac9db9871252c68efe77fe35af1fbd6f319d8283f43b578caf7e09e8de4651120a9
-  data.tar.gz: 51af4a10179668acf8977fca9dccfc133bbb25516c7464cb87bd05f9abf0a5926b1631620cf9265a9637b7b0ffa8c7b9a6618bf9ee7b75912005eb3f1722e1a3
+  metadata.gz: 6a4af75edfecaf1c3b9c64efa2be766b044153298da60af42df2c7e9bb3d8f5fdf43b9951ab62ad30868424b2eeaa5915c2add9059fedc48458cb99f3371eed9
+  data.tar.gz: 00b77b892735a6f29a569785c0795b4dd64c13e91091bbb840689a8fe689d76730dc4408041c6e3a0bef08b4fe02d77020cd9d25d66bfd40c170644fe277017a

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,20 @@
 ## [Unreleased]
 
+- 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.
 
 - Re-enable Ruby's built-in retry for idempotent requests on the persistent connection, which the `net_http_persistent` adapter disables by forcing `max_retries` to `0`. This recovers stale keep-alive sockets transparently instead of surfacing them as read timeouts.

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`.
@@ -178,6 +325,50 @@ A request that never reached Fulfil — a connection reset, a DNS failure, a tim
 
 `FulfilApi::HttpError` inherits from `FulfilApi::Error`, the base class of every error in this gem, so code that already rescues `FulfilApi::Error` keeps working unchanged.
 
+### Subscribing to Errors
+
+Rescuing tells you about the one call you wrapped. To report *every* failure of the Fulfil API — to count rate limit hits in your APM, to page on authentication failures, to log what Fulfil actually said — subscribe once instead.
+
+Every `FulfilApi::Error` publishes an `ActiveSupport::Notifications` event named `error.fulfil_api` when it is raised. `FulfilApi.on_error` is the shorthand for listening to it:
+
+```ruby
+# config/initializers/fulfil_api.rb
+
+FulfilApi.on_error do |error|
+  Appsignal.increment_counter("fulfil_api_errors", 1, error: error.class.name)
+end
+```
+
+Because every error carries its own class, you can report only the failures you care about:
+
+```ruby
+FulfilApi.on_error do |error|
+  next unless error.is_a?(FulfilApi::HttpError::TooManyRequests)
+
+  Appsignal.increment_counter("fulfil_api_rate_limit_exceeded")
+end
+```
+
+Subscribing through `ActiveSupport::Notifications` directly gives you the full payload, which carries the HTTP details of a `FulfilApi::HttpError` as separate keys — handy as metric dimensions:
+
+```ruby
+ActiveSupport::Notifications.subscribe(FulfilApi::Error::EVENT_NAME) do |event|
+  event.payload[:exception]        # => ["FulfilApi::HttpError::TooManyRequests", "Try again later."]
+  event.payload[:exception_object] # => the FulfilApi::HttpError::TooManyRequests instance
+  event.payload[:status_code]      # => 429
+  event.payload[:response_headers] # => { "retry-after" => "5", ... }
+  event.payload[:response_body]    # => the raw response of Fulfil
+end
+```
+
+Both methods return the subscriber, so you can stop listening again with `ActiveSupport::Notifications.unsubscribe(subscriber)`.
+
+A few things worth knowing:
+
+- The event is published when an error is **raised**, not when it is built. Rescuing it afterwards does not suppress the notification, and retrying a request publishes one event per attempt — which is exactly what you want when counting rate limit hits.
+- The subscriber runs on the thread that raised the error, while the error travels up the stack. Keep it cheap and hand anything slow to a background job.
+- A subscriber cannot change the behaviour of your application. If it raises, the exception is swallowed and reported on `$stderr` rather than replacing the `FulfilApi::Error` on its way up.
+
 ### 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.

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