fulfil_api 0.7.2 → 0.8.0

data/config/routes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+FulfilApi::Engine.routes.draw do
+  resource :installation, only: %i[new]
+
+  # Fulfil sends the user back with a `GET`, so the installation cannot be
+  #   created through the resourceful `POST /installation` route.
+  get "callback", to: "installations#create", as: :callback
+end

data/lib/fulfil_api/circuit_open.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::CircuitOpen} is raised instead of sending a request while the
+  #   circuit breaker has the Fulfil instance marked as failing.
+  #
+  # @see FulfilApi::Middleware::CircuitBreaker
+  class CircuitOpen < Error; end
+end

data/lib/fulfil_api/client.rb

@@ -113,6 +113,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
 
@@ -136,11 +139,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]
@@ -155,7 +156,10 @@ module FulfilApi
 
     # @return [Array] The cache key identifying a unique connection.
     def connection_cache_key
-      [configuration.merchant_id, configuration.request_options, configuration.connection_options]
+      [
+        configuration.merchant_id, 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/configuration.rb

@@ -7,22 +7,43 @@ module FulfilApi
   #   to these settings.
   class Configuration
     attr_accessor :access_token, :api_version, :merchant_id, :request_options, :tpl
-    attr_reader :connection_options
+    attr_reader :connection_options, :oauth, :retry_options
+
+    # @!attribute [rw] circuit_breaker
+    #   @return [Faulty, nil] The Faulty instance that runs every request through a
+    #     circuit per Fulfil instance, or nil to turn the circuit breaker off. See
+    #     {FulfilApi::Middleware::CircuitBreaker}.
+    attr_accessor :circuit_breaker
 
     DEFAULT_API_VERSION = "v2"
     DEFAULT_REQUEST_OPTIONS = { open_timeout: 1, read_timeout: 5, write_timeout: 5, timeout: 5 }.freeze
 
     # Tuning for the persistent (keep-alive) HTTP connection.
     #
-    # `max_retries` re-enables Ruby's built-in retry for idempotent requests
-    #   (GET/HEAD/PUT/DELETE/OPTIONS). The `net_http_persistent` adapter forces
-    #   it to 0, which means a keep-alive socket the server has already dropped
-    #   surfaces as a read timeout instead of being transparently retried on a
-    #   fresh socket. POST is never auto-retried, so this is side-effect safe.
-    #
     # `idle_timeout` and `pool_size` are passed through to the underlying
     #   Net::HTTP::Persistent connection when set.
-    DEFAULT_CONNECTION_OPTIONS = { max_retries: 1 }.freeze
+    #
+    # `max_retries` re-enables Ruby's built-in retry, which retries every request
+    #   Net::HTTP considers idempotent (GET/HEAD/PUT/DELETE/OPTIONS) whatever its
+    #   endpoint. Fulfil writes through PUT too, so it is off by default in favour
+    #   of the endpoint scoped {#retry_options}.
+    DEFAULT_CONNECTION_OPTIONS = {}.freeze
+
+    # Retries for requests that failed before Fulfil could answer them: a dropped
+    #   keep-alive socket, a refused connection or a timeout.
+    #
+    # `max_retries` caps the number of retries per request. `requests` maps an
+    #   HTTP verb onto the endpoints that are safe to retry, either `true` for every
+    #   endpoint or a list of patterns matched against the request path. Reads in
+    #   Fulfil go out as PUT requests to `search_read` and `search_count`, so those
+    #   are retried; every other PUT may write and is not.
+    DEFAULT_RETRY_OPTIONS = {
+      max_retries: 1,
+      requests: {
+        get: true,
+        put: [%r{/search_read\z}, %r{/search_count\z}]
+      }
+    }.freeze
 
     # Initializes the configuration with optional settings.
     #
@@ -48,8 +69,49 @@ module FulfilApi
       @connection_options = DEFAULT_CONNECTION_OPTIONS.merge(options || {})
     end
 
+    # Assigns the credentials of the OAuth app that was registered in Fulfil's
+    #   authentication dashboard. Assigning `nil` resets to the defaults.
+    #
+    # @param options [Hash, FulfilApi::OAuth::Configuration, nil] The OAuth options to apply.
+    # @return [void]
+    def oauth=(options)
+      @oauth =
+        case options
+        when OAuth::Configuration then options
+        when Hash, NilClass then OAuth::Configuration.new(options)
+        else raise ArgumentError, "Expected Hash or FulfilApi::OAuth::Configuration, got #{options.class} instead"
+        end
+    end
+
+    # Merges the provided retry options over the defaults. Assigning `nil` resets
+    #   to the defaults.
+    #
+    # @example retrying reads three times, and one write endpoint as well
+    #   config.retry_options = {
+    #     max_retries: 3,
+    #     requests: { get: true, put: [%r{/search_read\z}, %r{/stock.shipment.out/hold\z}] }
+    #   }
+    #
+    # @param options [Hash, nil] The retry options to apply.
+    # @return [void]
+    def retry_options=(options)
+      @retry_options = DEFAULT_RETRY_OPTIONS.merge(options || {})
+    end
+
     private
 
+    # {FulfilApi.with_config} duplicates the active configuration, which would
+    #   otherwise share the very same OAuth configuration object with the copy.
+    #   A block that changes an OAuth option would then leak that change into
+    #   the configuration it was supposed to be reverted to.
+    #
+    # @param source [FulfilApi::Configuration] The configuration being copied.
+    # @return [void]
+    def initialize_copy(source)
+      super
+      @oauth = source.oauth.dup
+    end
+
     # Sets the default options for the gem configuration.
     #
     # This method is called during initialization to ensure all configuration
@@ -60,6 +122,8 @@ module FulfilApi
       self.api_version = DEFAULT_API_VERSION if api_version.nil?
       self.request_options = DEFAULT_REQUEST_OPTIONS if request_options.nil?
       self.connection_options = nil if connection_options.nil?
+      self.oauth = nil if oauth.nil?
+      self.retry_options = nil if retry_options.nil?
     end
   end
 

data/lib/fulfil_api/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module FulfilApi
+  # Ships the OAuth flow as a mountable engine, so a Rails application only has
+  #   to mount it and point Fulfil's whitelisted redirect URL at its callback.
+  #
+  # @example config/routes.rb
+  #   mount FulfilApi::Engine => "/fulfil"
+  class Engine < ::Rails::Engine
+    isolate_namespace FulfilApi
+  end
+end

data/lib/fulfil_api/middleware/circuit_breaker.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  module Middleware
+    # The {FulfilApi::Middleware::CircuitBreaker} runs every request through a
+    #   [Faulty](https://github.com/ParentSquare/faulty) circuit, so a Fulfil instance
+    #   that keeps failing is skipped for a while instead of tying up the threads of an
+    #   application that talks to several of them.
+    #
+    # Each Fulfil instance gets its own circuit, shared by the {FulfilApi::Client} and
+    #   the {FulfilApi::TplClient}. The thresholds and the storage come from the
+    #   configured Faulty instance.
+    #
+    # It wraps the retries, so a request that failed after retrying counts as one
+    #   failure. A response with a 4xx status code is an answer, and doesn't count.
+    class CircuitBreaker < Faraday::Middleware
+      # The errors that count as a failure of the Fulfil instance.
+      FAILURES = [Faraday::ConnectionFailed, Faraday::ServerError, Faraday::TimeoutError].freeze
+
+      # Faulty wraps the error of a failed request into one of its own. Raising the
+      #   original error instead keeps the gem's errors the same with or without a
+      #   circuit breaker. Only an open circuit, which has no original error, raises
+      #   a {FulfilApi::CircuitOpen}.
+      ERROR_MAPPER = lambda do |_error_name, cause, circuit|
+        cause || FulfilApi::CircuitOpen.new("#{circuit.name} is open after repeated failures", details: {})
+      end
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @raise [FulfilApi::CircuitOpen] When the circuit of the Fulfil instance is open.
+      # @return [Faraday::Response]
+      def call(env)
+        circuit_for(env).run { @app.call(env) }
+      end
+
+      private
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @return [Faulty::Circuit]
+      def circuit_for(env)
+        options[:faulty].circuit("fulfil_api:#{env.url.host}", errors: FAILURES, error_mapper: ERROR_MAPPER)
+      end
+    end
+  end
+end

data/lib/fulfil_api/middleware.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::Middleware} sets up the Faraday middleware that both the
+  #   {FulfilApi::Client} and the {FulfilApi::TplClient} run their requests through.
+  module Middleware
+    # The errors raised when a request never got an answer from Fulfil. An HTTP
+    #   error response is an answer, and is never retried.
+    RETRYABLE_ERRORS = [Faraday::ConnectionFailed, Faraday::TimeoutError].freeze
+
+    class << self
+      # Adds the gem's middleware to a Faraday connection. Middleware runs in the
+      #   order it's added, so the first one wraps everything after it.
+      #
+      # @param connection [Faraday::Connection] The connection being built.
+      # @param configuration [FulfilApi::Configuration] The configuration of the client.
+      # @return [void]
+      def apply(connection, configuration)
+        connection.use CircuitBreaker, faulty: configuration.circuit_breaker if configuration.circuit_breaker
+        connection.request :retry, retry_middleware_options(configuration.retry_options)
+      end
+
+      private
+
+      # Translates the {FulfilApi::Configuration#retry_options} into the options of
+      #   the `faraday-retry` middleware.
+      #
+      # Ruby's built-in retry, and `faraday-retry` by default, treat every PUT as
+      #   idempotent, while Fulfil uses PUT both to read (`search_read`,
+      #   `search_count`) and to write (updating a record, holding a shipment).
+      #   Retrying a write that timed out could apply it twice, so no HTTP verb is
+      #   retried wholesale and every request is matched against the configured
+      #   endpoints instead.
+      #
+      # @param options [Hash] The retry options of the configuration.
+      # @return [Hash]
+      def retry_middleware_options(options)
+        requests = options.fetch(:requests, {})
+
+        {
+          max: options.fetch(:max_retries, 0),
+          methods: [],
+          exceptions: RETRYABLE_ERRORS,
+          retry_if: ->(env, _exception) { retryable_request?(env, requests) }
+        }
+      end
+
+      # @param env [Faraday::Env] The environment of the request.
+      # @param requests [Hash] The HTTP verbs mapped onto their retryable endpoints.
+      # @return [true, false] Whether the endpoint of the request is safe to retry.
+      def retryable_request?(env, requests)
+        patterns = requests[env.method]
+        return true if patterns == true
+
+        Array(patterns).any? { |pattern| pattern.match?(env.url.path) }
+      end
+    end
+  end
+end

data/lib/fulfil_api/oauth/authorization.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "base64"
+require "faraday"
+require "securerandom"
+require "uri"
+
+module FulfilApi
+  module OAuth
+    # Drives Fulfil's OAuth 2.0 authorization flow for a single merchant
+    #   workspace: it builds the URL the user is sent to, and exchanges the
+    #   authorization code they come back with for an access token.
+    #
+    # @example
+    #   authorization = FulfilApi::OAuth::Authorization.new(merchant_id: "acme")
+    #   state = FulfilApi::OAuth::Authorization.generate_state
+    #
+    #   redirect_to authorization.url(state: state)
+    #   # ... the user installs the app and returns with a `code` ...
+    #   token = authorization.exchange(params[:code])
+    #
+    # @see https://docs.fulfil.io/developers/rest-api/authentication/oauth
+    class Authorization
+      AUTHORIZE_PATH = "/oauth/authorize"
+      MERCHANT_ID_FORMAT = /\A[a-z0-9][a-z0-9-]*\z/
+      TOKEN_PATH = "/oauth/token"
+
+      attr_reader :access_type, :client_id, :merchant_id, :redirect_uri, :scopes
+
+      # Fulfil requires a nonce that is unique per authorization request, so the
+      #   callback can be verified to belong to the request that started it.
+      #
+      # @return [String]
+      def self.generate_state
+        SecureRandom.hex(24)
+      end
+
+      # Strips the parts of a Fulfil instance URL that surround the workspace ID.
+      #   Unlike {.normalize_merchant_id} it accepts whatever it is given, which
+      #   is what a database normalization needs to do.
+      #
+      # @param merchant_id [String, nil] The raw workspace ID.
+      # @return [String]
+      def self.normalize(merchant_id)
+        merchant_id.to_s.strip.downcase
+                   .delete_prefix("https://").delete_prefix("http://")
+                   .delete_suffix("/")
+                   .delete_suffix(".fulfil.io")
+      end
+
+      # Normalizes a merchant's workspace ID into the bare subdomain of their
+      #   Fulfil instance, so `acme`, `acme.fulfil.io`, and
+      #   `https://acme.fulfil.io` are all accepted.
+      #
+      # The workspace ID ends up in the host of the URL the user is redirected
+      #   to, so anything that is not a bare subdomain is rejected rather than
+      #   coerced into one.
+      #
+      # @param merchant_id [String, nil] The raw workspace ID.
+      # @raise [FulfilApi::OAuth::MerchantIdInvalid] When the workspace ID is
+      #   missing or is not a valid subdomain.
+      # @return [String]
+      def self.normalize_merchant_id(merchant_id)
+        normalized = normalize(merchant_id)
+
+        return normalized if MERCHANT_ID_FORMAT.match?(normalized)
+
+        raise MerchantIdInvalid, "#{merchant_id.inspect} is not a valid Fulfil workspace ID."
+      end
+
+      # @param merchant_id [String, nil] The workspace ID of the merchant to
+      #   install the app on. Defaults to the configured merchant.
+      # @param redirect_uri [String, nil] The URL Fulfil redirects back to.
+      #   Defaults to the configured redirect URI. It has to be whitelisted on
+      #   the app in Fulfil's authentication dashboard.
+      # @param configuration [FulfilApi::Configuration] The configuration to
+      #   read the OAuth app's credentials from.
+      def initialize(merchant_id: nil, redirect_uri: nil, configuration: FulfilApi.configuration)
+        @configuration = configuration
+        @oauth = configuration.oauth
+
+        raise ConfigurationError, "Please configure the OAuth app's client ID and secret" unless @oauth.configured?
+
+        @access_type = @oauth.access_type
+        @client_id = @oauth.client_id
+        @merchant_id = self.class.normalize_merchant_id(merchant_id.presence || configuration.merchant_id)
+        @redirect_uri = redirect_uri.presence || @oauth.redirect_uri
+        @scopes = @oauth.scopes
+      end
+
+      # Exchanges the authorization code from the callback for an access token.
+      #
+      # @param code [String] The authorization code Fulfil sent to the callback.
+      # @raise [FulfilApi::OAuth::TokenExchangeFailed] When Fulfil rejected the code.
+      # @return [FulfilApi::OAuth::Token]
+      def exchange(code)
+        raise TokenExchangeFailed, "No authorization code was provided" if code.blank?
+
+        response = connection.post(TOKEN_PATH, { code: code }) do |request|
+          request.params["grant_type"] = "authorization_code"
+          request.headers["Authorization"] = "Basic #{basic_credentials}"
+        end
+
+        Token.new(response.body)
+      rescue Faraday::Error => e
+        raise TokenExchangeFailed.new(e.message, details: response_details(e))
+      end
+
+      # The URL of Fulfil's consent screen. Sending the user here is the first
+      #   step of the flow.
+      #
+      # @param state [String] The nonce to verify the callback with.
+      # @return [String]
+      def url(state:)
+        uri = URI.parse("#{api_endpoint}#{AUTHORIZE_PATH}")
+        uri.query = URI.encode_www_form(url_parameters(state))
+        uri.to_s
+      end
+
+      private
+
+      attr_reader :configuration
+
+      # @return [String]
+      def api_endpoint
+        "https://#{merchant_id}.fulfil.io"
+      end
+
+      # @return [String] The client's credentials as HTTP basic auth credentials.
+      def basic_credentials
+        Base64.strict_encode64("#{@oauth.client_id}:#{@oauth.client_secret}")
+      end
+
+      # The token endpoint lives outside of the versioned API namespace and
+      #   expects a form encoded body, so it cannot reuse {FulfilApi::Client}.
+      #
+      # @return [Faraday::Connection]
+      def connection
+        Faraday.new(url: api_endpoint, request: configuration.request_options) do |connection|
+          connection.request :url_encoded
+
+          connection.response :json
+          connection.response :raise_error
+        end
+      end
+
+      # @param exception [Faraday::Error] The error raised while exchanging the code.
+      # @return [Hash]
+      def response_details(exception)
+        {
+          response_body: exception.response_body,
+          response_headers: exception.response_headers,
+          response_status: exception.response_status
+        }
+      end
+
+      # @param state [String] The nonce to verify the callback with.
+      # @return [Hash]
+      def url_parameters(state)
+        {
+          access_type: access_type,
+          client_id: client_id,
+          redirect_uri: redirect_uri,
+          response_type: "code",
+          state: state
+        }.tap do |parameters|
+          parameters[:scope] = scopes.join(",") if scopes.any?
+        end.compact
+      end
+    end
+  end
+end

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