gohighlevel 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79fd32db7abd8de22b946e8feb81e7dcd8ee457473c0519688599d46f22f869a
+  data.tar.gz: 2d5acf1de935a8c8ee59f57a31bc7b5aaab4b11f610b738a0bba6667ebc6da0e
+SHA512:
+  metadata.gz: dc32b529a415a681f940d61518dc4874e7493e0424b1df8ec9b111dbe5bb14ebab834fa5ad1e1e8475262a0b1aa6b22761031fab13dbbf418c728edd270dcf42
+  data.tar.gz: 938c84c8a33823b327445036625a89a1a36c570bee0458017c9e778ad94cd15a36785dc502a5cc79efe65e93bce413652a5edf6b1b2c5f0321856fc66e68ea21

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Zolkos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,246 @@
+# gohighlevel
+
+A Ruby SDK for the [HighLevel](https://highlevel.com) (GoHighLevel) API.
+
+- Resource methods generated from the official OpenAPI spec — 40 apps, 700+ endpoints.
+- Runtime behaviour (auth resolution, OAuth refresh, webhook verification) hand-written and tested against the canonical docs.
+- Faraday 2 transport, Zeitwerk loader, immutable per-client configuration — no global mutable state.
+- Ruby 3.3+.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "gohighlevel"
+```
+
+```sh
+bundle add gohighlevel
+```
+
+The storage-backend gems (`redis`, `activerecord`, `mongo`) are **not** runtime dependencies — add whichever you need to your own `Gemfile`. The default in-memory store needs nothing.
+
+## Quickstart
+
+```ruby
+require "gohighlevel"
+
+client = HighLevel::Client.new(private_integration_token: "pit-xxxxxxxx")
+
+# Every app is a resource on the client.
+contacts = client.contacts.search_contacts_advanced(
+  body: { locationId: "loc-123", pageLimit: 20 }
+)
+
+tasks = client.contacts.get_all_tasks(contact_id: "contact-456")
+```
+
+Resource method names are the spec's `operationId` in snake_case. Path parameters are required keyword arguments; query parameters are optional keyword arguments; a request body (when the endpoint declares one) is the `body:` keyword argument.
+
+## Authentication
+
+`HighLevel::Client.new` accepts one of four credential modes. Configuration is immutable and per-instance.
+
+```ruby
+# 1. Private Integration Token — simplest, always wins when present.
+HighLevel::Client.new(private_integration_token: "pit-xxxx")
+
+# 2. Agency access token.
+HighLevel::Client.new(agency_access_token: "agency-xxxx")
+
+# 3. Location access token.
+HighLevel::Client.new(location_access_token: "loc-xxxx")
+
+# 4. OAuth app credentials — required for the OAuth flows + 401 refresh.
+HighLevel::Client.new(client_id: "xxxx", client_secret: "xxxx")
+```
+
+You can also pass a prebuilt `HighLevel::Configuration`:
+
+```ruby
+config = HighLevel::Configuration.new(
+  private_integration_token: "pit-xxxx",
+  api_version: "2021-07-28",
+  session_storage: HighLevel::Storage::Memory.new,
+  instrumenter: ActiveSupport::Notifications
+)
+HighLevel::Client.new(config)
+```
+
+For OAuth-secured endpoints, the SDK resolves the right token per request from the operation's declared security requirements (`Agency-Access`, `Location-Access`, `bearer`, ...), falling back to session storage when no direct token is configured.
+
+### OAuth flows
+
+```ruby
+client = HighLevel::Client.new(
+  client_id: "xxxx",
+  client_secret: "xxxx",
+  redirect_uri: "https://your.app/oauth/callback"
+)
+
+# 1. Send the user here to authorize.
+url = client.oauth.authorization_url(scope: "contacts.readonly contacts.write")
+
+# 2. Exchange the code that comes back on your callback.
+tokens = client.oauth.exchange_code(code: params[:code], user_type: "Location")
+
+# 3. Refresh later.
+tokens = client.oauth.refresh_token(refresh_token: stored_refresh, user_type: "Location")
+
+# 4. Derive a location token from an agency token.
+tokens = client.oauth.get_location_access_token(company_id: "co-1", location_id: "loc-1")
+```
+
+When a request returns `401`, the SDK transparently attempts a refresh (using the session in storage), retries once, and — for location tokens — falls back to re-deriving from the company token. A second `401` is propagated, not looped.
+
+## Storage backends
+
+Session storage holds OAuth tokens keyed by resource (company/location) id. `HighLevel::Storage::Memory` is the default and needs no configuration.
+
+| Backend | When to use | Extra gem |
+|---|---|---|
+| `Storage::Memory` | Tests, single-process apps | — (default) |
+| `Storage::ActiveRecord` | Rails apps with an existing database | `activerecord` |
+| `Storage::Redis` | Multi-process workers sharing tokens | `redis` |
+| `Storage::Mongo` | Parity with TS SDK consumers sharing a Mongo store | `mongo` |
+
+```ruby
+# Redis
+store = HighLevel::Storage::Redis.new(url: "redis://localhost:6379/0")
+HighLevel::Client.new(client_id: "x", client_secret: "y", session_storage: store)
+
+# ActiveRecord — once, in a migration:
+HighLevel::Storage::ActiveRecord::Migration.create_table!(connection)
+store = HighLevel::Storage::ActiveRecord.new
+```
+
+All backends satisfy the same contract (`test/support/session_storage_contract.rb`). Writing your own: subclass `HighLevel::Storage::Base` and implement the seven methods.
+
+## Webhook verification
+
+HighLevel signs webhooks with its private key and publishes the public key — verification is asymmetric, not HMAC. Two schemes are supported: `:rsa` (signature on the `x-wh-signature` header) and `:ed25519` (`x-ghl-signature`).
+
+```ruby
+# Sinatra
+post "/webhooks/highlevel" do
+  body = request.body.read
+  HighLevel::Webhooks.verify(
+    payload: body,
+    signature: request.env["HTTP_X_WH_SIGNATURE"],
+    public_key: ENV.fetch("HIGHLEVEL_WEBHOOK_PUBLIC_KEY"),
+    scheme: :rsa
+  )
+  # raises HighLevel::Webhooks::InvalidSignatureError if it doesn't verify
+  process(JSON.parse(body))
+  status 200
+rescue HighLevel::Webhooks::InvalidSignatureError
+  halt 401
+end
+```
+
+```ruby
+# Rails controller
+def highlevel
+  HighLevel::Webhooks.verify(
+    payload: request.raw_post,
+    signature: request.headers["X-Wh-Signature"],
+    public_key: Rails.application.credentials.highlevel_webhook_public_key
+  )
+  ProcessWebhookJob.perform_later(request.raw_post)
+  head :ok
+rescue HighLevel::Webhooks::InvalidSignatureError
+  head :unauthorized
+end
+```
+
+Pass the **raw request body bytes** — re-serializing a parsed JSON object changes the canonical form and breaks verification.
+
+## Pagination
+
+The HighLevel API has no uniform pagination convention, so nothing is auto-paginated. `HighLevel::Pagination` is opt-in.
+
+```ruby
+# A proc that routes pagination params wherever the endpoint wants them.
+fetch = ->(**page) do
+  client.contacts.search_contacts_advanced(body: { locationId: "loc-1" }.merge(page))
+end
+
+# Each page (raw response):
+HighLevel::Pagination.each_page(fetch, cursor_field: :skip, items_field: "contacts") do |page|
+  puts page["contacts"].size
+end
+
+# Each item, flattened across pages:
+HighLevel::Pagination.each_item(fetch, cursor_field: :skip, items_field: "contacts") do |contact|
+  puts contact["id"]
+end
+
+# Without a block, you get an Enumerator:
+enum = HighLevel::Pagination.each_item(fetch, cursor_field: :skip, items_field: "contacts")
+enum.lazy.select { |c| c["type"] == "lead" }.first(10)
+```
+
+`cursor_field` is the parameter the endpoint advances on (`:offset`, `:skip`, ...). `limit_field` defaults to `:limit`; `page_size` defaults to `100`.
+
+## Error handling
+
+Every non-2xx response raises a typed exception carrying `#status`, `#response_body`, and `#request_id`.
+
+```ruby
+begin
+  client.contacts.get_all_tasks(contact_id: "missing")
+rescue HighLevel::NotFoundError => e
+  e.status        # => 404
+  e.response_body # => parsed JSON body
+  e.request_id    # => the x-request-id header, if present
+end
+```
+
+| Exception | Trigger |
+|---|---|
+| `HighLevel::BadRequestError` | 400 |
+| `HighLevel::UnauthorizedError` | 401 |
+| `HighLevel::ForbiddenError` | 403 |
+| `HighLevel::NotFoundError` | 404 |
+| `HighLevel::UnprocessableEntityError` | 422 |
+| `HighLevel::RateLimitError` | 429 |
+| `HighLevel::ServerError` | 5xx |
+| `HighLevel::Error` | other non-2xx |
+| `HighLevel::ConfigurationError` | bad/missing credentials |
+| `HighLevel::NetworkError` | transport-level failure |
+
+All inherit from `HighLevel::Error`, so `rescue HighLevel::Error` catches everything.
+
+## Instrumentation
+
+The SDK emits no logs. Pass any object responding to `#instrument(name, payload, &block)` — `ActiveSupport::Notifications` is the obvious one — as `instrumenter:` and subscribe to the `request.high_level` event.
+
+```ruby
+client = HighLevel::Client.new(
+  private_integration_token: "pit-xxxx",
+  instrumenter: ActiveSupport::Notifications
+)
+
+ActiveSupport::Notifications.subscribe("request.high_level") do |*, payload|
+  Rails.logger.info("HighLevel #{payload[:method].upcase} #{payload[:url]} → #{payload[:status]}")
+end
+```
+
+With no `instrumenter` configured, the instrumentation middleware is a transparent pass-through.
+
+## Differences from the official TypeScript SDK
+
+- **Naming** — methods are snake_case; arguments are keyword arguments.
+- **No global state** — every collaborator is injected through `HighLevel::Configuration`; there is no global mutable config. Thread-safe by construction.
+- **Webhook verification raises** — `HighLevel::Webhooks.verify` returns `true` or raises `InvalidSignatureError`, rather than returning a boolean.
+- **Pagination is explicit** — `HighLevel::Pagination` is opt-in; resource methods never auto-paginate.
+- **Storage gems are optional** — `redis`/`activerecord`/`mongo` are lazy-required, not runtime dependencies.
+- **Generated code is committed** — `bundle add gohighlevel` gives you a working library; there is no install-time codegen.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the spec-sync, regeneration, and drift-check workflows.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/gohighlevel.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/high_level/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "gohighlevel"
+  spec.version = HighLevel::VERSION
+  spec.authors = ["Rob Zolkos"]
+  spec.email = ["rob@zolkos.com"]
+
+  spec.summary = "Ruby SDK for the HighLevel (GoHighLevel) API."
+  spec.description = "A Ruby SDK for the HighLevel (GoHighLevel) API, generated from the " \
+                     "official OpenAPI spec with runtime behavior validated against the " \
+                     "official TypeScript SDK."
+  spec.homepage = "https://github.com/robzolkos/gohighlevel"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/master"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir["lib/**/*.rb"] + %w[README.md LICENSE.txt gohighlevel.gemspec]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base64", "~> 0.2"
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+end

data/lib/gohighlevel.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "high_level"

data/lib/high_level/client.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module HighLevel
+  # The entry point for the SDK. Construct one with credentials, then
+  # reach each API app as a resource: +client.contacts+,
+  # +client.calendars+, and so on (see +RESOURCE_REGISTRY+). OAuth flows
+  # live on +client.oauth+.
+  #
+  # @!attribute [r] config
+  #   @return [HighLevel::Configuration] the resolved, immutable configuration
+  # @!attribute [r] connection
+  #   @return [Faraday::Connection] the underlying HTTP connection with the
+  #     full middleware stack
+  # @!attribute [r] oauth
+  #   @return [HighLevel::Oauth] the OAuth flow client
+  class Client
+    attr_reader :config, :connection, :oauth
+
+    # @param config [HighLevel::Configuration, Hash, nil] a configuration
+    #   object, a hash of configuration options, or nil to build one
+    #   entirely from keyword arguments
+    # @param opts [Hash] configuration options, merged over +config+
+    # @raise [ConfigurationError] when no usable credentials are supplied
+    def initialize(config = nil, **opts)
+      @config = coerce_config(config, opts)
+      validate!
+      initialize_storage
+      @oauth = Oauth.new(config: @config)
+      @connection = build_connection
+    end
+
+    # @return [Boolean] whether +name+ is a registered resource accessor
+    def respond_to_missing?(name, include_private = false)
+      RESOURCE_REGISTRY.key?(name) || super
+    end
+
+    # Resolves +client.<app>+ to a memoized resource instance via
+    # +RESOURCE_REGISTRY+.
+    def method_missing(name, *args, **kwargs, &block)
+      klass = RESOURCE_REGISTRY[name]
+      return super unless klass && args.empty? && kwargs.empty? && block.nil?
+
+      @resources ||= {}
+      @resources[name] ||= klass.new(self)
+    end
+
+    private
+
+    def coerce_config(config, opts)
+      case config
+      when Configuration then config
+      when Hash          then Configuration.new(**config, **opts)
+      when nil           then Configuration.new(**opts)
+      else
+        raise ConfigurationError,
+              "expected HighLevel::Configuration or Hash, got #{config.class}"
+      end
+    end
+
+    def validate!
+      return if any_token? || oauth_client_pair?
+
+      raise ConfigurationError,
+            "HighLevel::Client requires one of: private_integration_token, " \
+            "agency_access_token, location_access_token, or client_id+client_secret"
+    end
+
+    def any_token?
+      @config.private_integration_token ||
+        @config.agency_access_token ||
+        @config.location_access_token
+    end
+
+    def oauth_client_pair?
+      @config.client_id && @config.client_secret
+    end
+
+    def initialize_storage
+      storage = @config.session_storage
+      return if storage.nil?
+
+      storage.set_client_id(@config.client_id) if @config.client_id
+      storage.init
+    end
+
+    def build_connection
+      resolver = TokenResolver.new(config: @config, storage: @config.session_storage)
+      refresher = TokenRefresher.new(config: @config, oauth: @oauth, storage: @config.session_storage)
+      build_faraday(resolver, refresher)
+    end
+
+    def build_faraday(resolver, refresher)
+      Faraday.new(url: @config.base_url) do |f|
+        f.use Middleware::Instrumentation, instrumenter: @config.instrumenter
+        f.use Middleware::RefreshOn401, refresher: refresher, resolver: resolver
+        f.use Middleware::Authentication, config: @config, resolver: resolver
+        f.request :json
+        f.use Middleware::ErrorHandler
+        f.response :json, content_type: /\bjson\b/
+        f.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/high_level/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module HighLevel
+  # Immutable, per-client configuration. Every collaborator a {Client}
+  # needs — credentials, base URL, session storage, instrumenter — is
+  # supplied here; there is no global mutable state.
+  #
+  # @!attribute [r] api_version
+  #   @return [String] the +Version+ header value sent on every request
+  # @!attribute [r] base_url
+  #   @return [String] the API base URL
+  # @!attribute [r] private_integration_token
+  #   @return [String, nil] a Private Integration Token
+  # @!attribute [r] agency_access_token
+  #   @return [String, nil] an agency-level access token
+  # @!attribute [r] location_access_token
+  #   @return [String, nil] a location-level access token
+  # @!attribute [r] client_id
+  #   @return [String, nil] the OAuth app client id
+  # @!attribute [r] client_secret
+  #   @return [String, nil] the OAuth app client secret
+  # @!attribute [r] redirect_uri
+  #   @return [String, nil] the OAuth redirect URI
+  # @!attribute [r] session_storage
+  #   @return [HighLevel::Storage::Base] the session store (defaults to a
+  #     fresh {Storage::Memory})
+  # @!attribute [r] logger
+  #   @return [Logger, nil] an optional Ruby logger
+  # @!attribute [r] instrumenter
+  #   @return [#instrument, nil] an optional instrumenter (e.g.
+  #     +ActiveSupport::Notifications+)
+  Configuration = Data.define(
+    :api_version,
+    :base_url,
+    :private_integration_token,
+    :agency_access_token,
+    :location_access_token,
+    :client_id,
+    :client_secret,
+    :redirect_uri,
+    :session_storage,
+    :logger,
+    :instrumenter
+  ) do
+    # @see Configuration the attribute list for every keyword argument
+    def initialize(
+      api_version: "2021-07-28",
+      base_url: "https://services.leadconnectorhq.com",
+      private_integration_token: nil,
+      agency_access_token: nil,
+      location_access_token: nil,
+      client_id: nil,
+      client_secret: nil,
+      redirect_uri: nil,
+      session_storage: Storage::Memory.new,
+      logger: nil,
+      instrumenter: nil
+    )
+      super
+    end
+  end
+end

data/lib/high_level/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module HighLevel
+  # Base class for every error the SDK raises. Carries the HTTP context
+  # of the failed request where one is available.
+  #
+  # @!attribute [r] status
+  #   @return [Integer, nil] the HTTP status code, when the error came
+  #     from a response
+  # @!attribute [r] response_body
+  #   @return [Object, nil] the parsed response body, when available
+  # @!attribute [r] request_id
+  #   @return [String, nil] the +x-request-id+ response header, when present
+  class Error < StandardError
+    attr_reader :status, :response_body, :request_id
+
+    # @param message [String, nil] human-readable error message
+    # @param status [Integer, nil] HTTP status code
+    # @param response_body [Object, nil] parsed response body
+    # @param request_id [String, nil] the +x-request-id+ header value
+    def initialize(message = nil, status: nil, response_body: nil, request_id: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+      @request_id = request_id
+    end
+  end
+
+  # Raised on a missing or malformed client configuration.
+  class ConfigurationError < Error; end
+  # Raised on a transport-level failure (connection refused, timeout, ...).
+  class NetworkError < Error; end
+  # Raised on an HTTP 400 response.
+  class BadRequestError < Error; end
+  # Raised on an HTTP 401 response.
+  class UnauthorizedError < Error; end
+  # Raised on an HTTP 403 response.
+  class ForbiddenError < Error; end
+  # Raised on an HTTP 404 response.
+  class NotFoundError < Error; end
+  # Raised on an HTTP 422 response.
+  class UnprocessableEntityError < Error; end
+  # Raised on an HTTP 429 response.
+  class RateLimitError < Error; end
+  # Raised on an HTTP 5xx response.
+  class ServerError < Error; end
+end

data/lib/high_level/middleware/authentication.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module HighLevel
+  # Faraday middleware that implements the HighLevel client's request
+  # pipeline: instrumentation, 401-refresh, authentication, and typed
+  # error mapping.
+  module Middleware
+    # Injects the +Authorization+ and +Version+ headers. When the
+    # request carries a {CONTEXT_KEY} entry in its Faraday options
+    # context (set by generated resource methods), the bearer token is
+    # resolved through {TokenResolver}; otherwise it falls back to a
+    # simple credential-priority chain.
+    class Authentication < Faraday::Middleware
+      # The request-options context key under which generated resource
+      # code stashes the operation's security requirements.
+      CONTEXT_KEY = :high_level_security
+
+      # @param app [#call] the next middleware in the stack
+      # @param config [HighLevel::Configuration] the client configuration
+      # @param resolver [HighLevel::TokenResolver, nil] an explicit
+      #   resolver; built from +config+/+storage+ when omitted
+      # @param storage [HighLevel::Storage::Base, nil] session storage,
+      #   used only when +resolver+ is not supplied
+      def initialize(app, config:, resolver: nil, storage: nil)
+        super(app)
+        @config = config
+        @resolver = resolver || TokenResolver.new(config: config, storage: storage)
+      end
+
+      # Faraday request callback. Sets the +Version+ header and, unless
+      # one is already present, an +Authorization: Bearer+ header.
+      def on_request(env)
+        env.request_headers["Version"] ||= @config.api_version
+        return if env.request_headers["Authorization"]
+
+        env.request_headers["Authorization"] = "Bearer #{resolve_token(env)}"
+      end
+
+      private
+
+      def resolve_token(env)
+        ctx = security_context(env)
+        return simple_priority_token unless ctx
+
+        @resolver.resolve(
+          security_requirements: ctx[:security_requirements] || [],
+          headers: env.request_headers,
+          query: parse_query(env.url&.query),
+          body: env.body,
+          preference: ctx[:preference]
+        ).token
+      end
+
+      def security_context(env)
+        opts = env.request
+        return nil unless opts.respond_to?(:context)
+
+        ctx = opts.context
+        return nil unless ctx.is_a?(Hash)
+
+        ctx[CONTEXT_KEY]
+      end
+
+      def simple_priority_token
+        @config.private_integration_token ||
+          @config.agency_access_token ||
+          @config.location_access_token ||
+          raise(HighLevel::ConfigurationError, "no token available for request")
+      end
+
+      def parse_query(query_string)
+        return {} if query_string.nil? || query_string.empty?
+
+        URI.decode_www_form(query_string).to_h
+      end
+    end
+  end
+end

data/lib/high_level/middleware/error_handler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module HighLevel
+  module Middleware
+    # Maps non-2xx responses to typed {HighLevel::Error} subclasses,
+    # raising one with the response's status, body, and request id.
+    class ErrorHandler < Faraday::Middleware
+      # HTTP status code to exception class. Unmapped 5xx codes raise
+      # {HighLevel::ServerError}; any other unmapped non-2xx raises the
+      # base {HighLevel::Error}.
+      STATUS_MAP = {
+        400 => HighLevel::BadRequestError,
+        401 => HighLevel::UnauthorizedError,
+        403 => HighLevel::ForbiddenError,
+        404 => HighLevel::NotFoundError,
+        422 => HighLevel::UnprocessableEntityError,
+        429 => HighLevel::RateLimitError
+      }.freeze
+
+      # Faraday response callback. Raises the mapped error for any
+      # non-2xx status; a no-op otherwise.
+      def on_complete(env)
+        return if env.status.between?(200, 299)
+
+        klass = STATUS_MAP[env.status] ||
+                (env.status >= 500 ? HighLevel::ServerError : HighLevel::Error)
+
+        raise klass.new(
+          "HTTP #{env.status} on #{env.method.to_s.upcase} #{env.url&.path}",
+          status: env.status,
+          response_body: env.body,
+          request_id: request_id_from(env)
+        )
+      end
+
+      private
+
+      def request_id_from(env)
+        headers = env.response_headers
+        return nil unless headers
+
+        headers["x-request-id"] || headers["X-Request-Id"]
+      end
+    end
+  end
+end