vision_api 1.0.0

data/lib/vision_api/client.rb

@@ -0,0 +1,431 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+require_relative "errors"
+require_relative "multipart"
+
+module VisionAPI
+  DEFAULT_BASE_URL = "https://api.visionapi.io"
+
+  # The Vision API client.
+  #
+  # One object, one method per endpoint, plus the two things every integration ends up
+  # writing by hand: retry that honors +Retry-After+, and polling that knows when a task is
+  # done. Docs: https://docs.visionapi.io
+  #
+  #   vision = VisionAPI::Client.new              # reads ENV["VISION_API_KEY"]
+  #   res = vision.analyze(file: "invoice.pdf", preset: "invoice")
+  #   res["result"]["invoice_id"]["value"]        # => "A-10422"
+  #
+  # Responses are plain hashes with the wire's +snake_case+ keys, because the response
+  # shape *is* the public contract and renaming it here would make
+  # https://docs.visionapi.io stop matching what you see in your editor.
+  class Client
+    RETRYABLE_STATUS = [429, 500, 502, 503].freeze
+
+    attr_reader :base_url, :timeout, :max_retries
+
+    # @param api_key [String, nil] your secret key; defaults to <tt>ENV["VISION_API_KEY"]</tt>.
+    #   There is no publishable key and no test mode — this is a live spending credential,
+    #   so keep it server-side. Create one at https://app.visionapi.io/dashboard/keys
+    # @param base_url [String, nil] override for a self-hosted or staging deployment
+    # @param timeout [Numeric] per-request deadline in seconds. The server kills a
+    #   synchronous request at 60 s, so anything above that only covers upload time.
+    # @param max_retries [Integer] how many times to retry a *retryable* failure — 429,
+    #   500, 502 and network errors. Input errors and +insufficient_credits+ are never
+    #   retried.
+    # @param auto_idempotency [Boolean] generate an +Idempotency-Key+ for every billable
+    #   POST that does not carry one, so a retry replays the first response instead of
+    #   paying twice
+    # @param headers [Hash] extra headers sent on every request
+    def initialize(api_key: nil, base_url: nil, timeout: 120, max_retries: 3,
+                   auto_idempotency: true, headers: {})
+      @api_key = api_key || ENV.fetch("VISION_API_KEY", nil)
+      if @api_key.nil? || @api_key.empty?
+        raise UsageError, "No API key. Pass VisionAPI::Client.new(api_key: …) or set " \
+                          "VISION_API_KEY. Create one at https://app.visionapi.io/dashboard/keys"
+      end
+
+      @base_url = (base_url || ENV["VISION_API_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @auto_idempotency = auto_idempotency
+      @headers = headers
+      @user_agent = "visionapi-ruby/#{VisionAPI::VERSION} ruby/#{RUBY_VERSION}"
+    end
+
+    # ---------------------------------------------------------------- extraction
+
+    # Extracts structured data from one image or PDF and waits for the answer.
+    #
+    # Costs 1 credit per image, or 1 per *selected* PDF page. Failures cost nothing — the
+    # reservation is released in full on any non-2xx, so there is no compensating logic to
+    # write. Anything that might run past 60 s belongs on {#analyze_async}.
+    #
+    # @param file [String, Pathname, IO, String] a path, an open binary IO, or raw bytes
+    # @param file_url [String] a public URL for the API to fetch instead
+    # @param file_base64 [String] base64 bytes, with or without a +data:+ prefix
+    # @param preset [String] a catalog name, or +"auto"+ to have the API classify the file
+    #   first (free)
+    # @param schema [Hash] custom fields, alone or on top of a preset
+    # @param schema_name [String] a schema saved in the dashboard; excludes +preset+ and +schema+
+    # @param pages [String] PDF page selection, e.g. +"1-3,7"+. You pay for selected pages only.
+    # @param language_hint [String] ISO 639-1 code, e.g. +"es"+
+    # @param detail [String] +"high"+ renders pages at higher resolution; same cost, slower
+    # @param output [String] +"text"+ returns raw OCR text instead of fields
+    # @param include_raw_text [Boolean] adds +full_text+ alongside +result+
+    # @param min_confidence [String] fields below this level come back nil, confidence kept
+    # @param idempotency_key [String] supply your own when the *caller* may retry
+    # @return [Hash] the full response body
+    def analyze(file: nil, file_url: nil, file_base64: nil, idempotency_key: nil,
+                timeout: nil, **params)
+      submit("/v1/analyze", file, file_url, file_base64, analyze_fields(**params),
+             idempotency_key, timeout)
+    end
+
+    # Submits an extraction to the queue and returns as soon as it is accepted.
+    #
+    # Use it for long PDFs, <tt>detail: "high"</tt>, or any batch you do not want to hold a
+    # connection open for. Poll with {#wait_for_task}, or pass +webhook_url+ — an HTTPS
+    # endpoint that does not resolve to a private address — and let the result come to you.
+    #
+    # @return [Hash] <tt>{"task_id" => …, "status" => "queued"}</tt>
+    def analyze_async(file: nil, file_url: nil, file_base64: nil, webhook_url: nil,
+                      idempotency_key: nil, timeout: nil, **params)
+      fields = analyze_fields(**params).merge("async" => true, "webhook_url" => webhook_url)
+      submit("/v1/analyze", file, file_url, file_base64, fields, idempotency_key, timeout)
+    end
+
+    # {#analyze_async} followed by {#wait_for_task} — the shape most batch jobs want.
+    #
+    # @raise [TaskFailedError] the worker could not process the file (costs 0 credits)
+    # @raise [TaskTimeoutError] +max_wait+ elapsed while it was still running
+    def analyze_and_wait(poll_interval: 2, max_wait: 600, on_poll: nil, **params)
+      ref = analyze_async(**params)
+      wait_for_task(ref["task_id"], poll_interval: poll_interval, max_wait: max_wait, on_poll: on_poll)
+    end
+
+    # Asks up to 5 questions about one file.
+    #
+    # Priced exactly like an extraction — per image or per selected page — and the
+    # questions themselves are free. Branch on <tt>answer["verdict"]</tt>
+    # (+yes+ / +no+ / +uncertain+ / +n/a+) rather than parsing the prose.
+    def ask(questions:, file: nil, file_url: nil, file_base64: nil, pages: nil,
+            language_hint: nil, detail: nil, idempotency_key: nil, timeout: nil)
+      fields = ask_fields(questions, pages, language_hint, detail)
+      submit("/v1/ask", file, file_url, file_base64, fields, idempotency_key, timeout)
+    end
+
+    # Queues an {#ask} instead of waiting for it.
+    def ask_async(questions:, file: nil, file_url: nil, file_base64: nil, pages: nil,
+                  language_hint: nil, detail: nil, webhook_url: nil, idempotency_key: nil,
+                  timeout: nil)
+      fields = ask_fields(questions, pages, language_hint, detail)
+               .merge("async" => true, "webhook_url" => webhook_url)
+      submit("/v1/ask", file, file_url, file_base64, fields, idempotency_key, timeout)
+    end
+
+    # Identifies what a file is without paying to extract it.
+    #
+    # Metered at *1 credit per 10 calls* whatever the page count, because detection only
+    # ever reads page 1 — so nine calls out of ten report <tt>"credits_used" => 0</tt>.
+    # <tt>"recommended"</tt> is exactly what <tt>preset: "auto"</tt> would have run, so you
+    # can probe first and trust the answer.
+    #
+    # Reach for it when the *type* is the decision (routing a mixed inbox, refusing to
+    # spend on a 40-page PDF sight unseen); reach for <tt>preset: "auto"</tt> when you want
+    # the data and do not care which preset produced it.
+    def detect(file: nil, file_url: nil, file_base64: nil, detail: nil,
+               idempotency_key: nil, timeout: nil)
+      submit("/v1/detect", file, file_url, file_base64, { "detail" => detail },
+             idempotency_key, timeout)
+    end
+
+    # --------------------------------------------------------------------- tasks
+
+    # Status and, once finished, the result of an async task.
+    #
+    # Results stay retrievable for 7 days; after that this raises {ResultExpiredError}
+    # (the metadata survives, the payload does not).
+    def get_task(task_id, timeout: nil)
+      request(:get, "/v1/tasks/#{escape_segment(task_id)}", timeout: timeout)
+    end
+
+    # Polls until the task leaves +queued+/+processing+, then returns it.
+    #
+    # @param raise_on_failure [Boolean] when false, a failed task is returned as-is
+    # @param on_poll [Proc, nil] called with each non-final poll — a progress bar, a log line
+    # @raise [TaskFailedError] the task failed
+    # @raise [TaskTimeoutError] +max_wait+ elapsed; the task keeps running, so the id is
+    #   still worth polling later
+    def wait_for_task(task_id, poll_interval: 2, max_wait: 600, raise_on_failure: true, on_poll: nil)
+      deadline = monotonic + max_wait
+
+      loop do
+        task = get_task(task_id)
+        case task["status"]
+        when "completed" then return task
+        when "failed"
+          return task unless raise_on_failure
+
+          raise TaskFailedError.new(task_id, task["error"])
+        end
+
+        raise TaskTimeoutError.new(task_id, max_wait) if monotonic + poll_interval > deadline
+
+        on_poll&.call(task)
+        sleep(poll_interval)
+      end
+    end
+
+    # ------------------------------------------------------- account & catalog
+
+    # Balance and the per-bucket breakdown. Buckets are spent in order:
+    # subscription → rollover → pack → welcome.
+    def credits(timeout: nil)
+      request(:get, "/v1/credits", timeout: timeout)
+    end
+
+    # One page of usage history, newest first. Metadata only — the file and the extracted
+    # values are never kept. Pass <tt>cursor: page["next_cursor"]</tt> for the next page.
+    def requests(limit: nil, cursor: nil, timeout: nil)
+      request(:get, "/v1/requests", query: { "limit" => limit, "cursor" => cursor }, timeout: timeout)
+    end
+
+    # Enumerates the whole history, one record at a time, paging as it goes.
+    #
+    # @return [Enumerator] lazy — +each_request.first(10)+ fetches one page
+    def each_request(limit: 100, &block)
+      return enum_for(:each_request, limit: limit) unless block_given?
+
+      cursor = nil
+      loop do
+        page = requests(limit: limit, cursor: cursor)
+        page["data"].each(&block)
+        cursor = page["next_cursor"]
+        break if cursor.nil? || cursor.empty?
+      end
+    end
+
+    # The preset catalog. No API key required.
+    #
+    # Pick a preset from here rather than from memory — presets are versioned, and the
+    # catalog is the source of truth for both the names and the fields.
+    def presets(timeout: nil)
+      request(:get, "/v1/presets", auth: false, timeout: timeout)["data"]
+    end
+
+    # One preset with its full field definitions. Read this before mapping field names.
+    def preset(name, timeout: nil)
+      request(:get, "/v1/presets/#{escape_segment(name)}", auth: false, timeout: timeout)
+    end
+
+    # ----------------------------------------------------------- saved schemas
+
+    # Every schema saved on this account.
+    def schemas(timeout: nil)
+      request(:get, "/v1/schemas", timeout: timeout)["data"]
+    end
+
+    def schema(name, timeout: nil)
+      request(:get, "/v1/schemas/#{escape_segment(name)}", timeout: timeout)
+    end
+
+    # Saves a preset + custom-field combination under a name, for later use as
+    # <tt>analyze(schema_name: …)</tt>. The definition is compiled before it is stored, so
+    # an invalid schema fails here rather than on the first extraction that uses it.
+    def create_schema(name, preset: nil, schema: nil, timeout: nil)
+      body = { "name" => name }
+      body["preset"] = preset if preset
+      body["schema"] = schema if schema
+      request(:post, "/v1/schemas", json: body, timeout: timeout)
+    end
+
+    # Replaces a saved schema in place.
+    def update_schema(name, preset: nil, schema: nil, timeout: nil)
+      body = {}
+      body["preset"] = preset if preset
+      body["schema"] = schema if schema
+      request(:put, "/v1/schemas/#{escape_segment(name)}", json: body, timeout: timeout)
+    end
+
+    def delete_schema(name, timeout: nil)
+      request(:delete, "/v1/schemas/#{escape_segment(name)}", timeout: timeout)
+      nil
+    end
+
+    private
+
+    # Percent-encodes one path segment.
+    #
+    # +URI.encode_uri_component+ arrived with Ruby 3.1 (uri 0.11) and this gem supports 3.0,
+    # where the nearest stdlib equivalent is +CGI.escape+ — which form-encodes a space as
+    # +"+"+. Inside a path segment a +"+"+ is a literal plus, not a space, so it has to go
+    # back to +%20+. The fallback encodes a few sub-delimiters the 3.1 path leaves alone;
+    # both decode to the same string server-side.
+    def escape_segment(value)
+      value = value.to_s
+      return URI.encode_uri_component(value) if URI.respond_to?(:encode_uri_component)
+
+      require "cgi"
+      CGI.escape(value).gsub("+", "%20")
+    end
+
+    def analyze_fields(preset: nil, schema: nil, schema_name: nil, pages: nil,
+                       language_hint: nil, detail: nil, output: nil,
+                       include_raw_text: nil, min_confidence: nil)
+      if schema_name && (preset || schema)
+        raise UsageError, "schema_name: is mutually exclusive with preset: and schema:."
+      end
+      if output == "text" && (preset || schema || schema_name)
+        raise UsageError, 'output: "text" cannot be combined with a preset or a schema.'
+      end
+
+      {
+        "preset" => preset,
+        "schema" => schema,
+        "schema_name" => schema_name,
+        "pages" => pages,
+        "language_hint" => language_hint,
+        "detail" => detail,
+        "output" => output,
+        "include_raw_text" => include_raw_text,
+        "min_confidence" => min_confidence
+      }
+    end
+
+    def ask_fields(questions, pages, language_hint, detail)
+      list = questions.is_a?(String) ? [questions] : Array(questions)
+      raise UsageError, "Provide at least one question." if list.empty?
+      raise UsageError, "At most 5 questions per request — received #{list.size}." if list.size > 5
+
+      {
+        "questions" => list,
+        "pages" => pages,
+        "language_hint" => language_hint,
+        "detail" => detail
+      }
+    end
+
+    def submit(path, file, file_url, file_base64, fields, idempotency_key, timeout)
+      given = { "file" => file, "file_url" => file_url, "file_base64" => file_base64 }.compact
+      raise UsageError, "Provide exactly one of file:, file_url: or file_base64:." if given.empty?
+      raise UsageError, "Provide exactly one file source — received #{given.keys.join(" and ")}." if given.size > 1
+
+      clean = fields.compact
+
+      if file
+        # Local bytes go out as multipart.
+        body, content_type = Multipart.encode(clean, Multipart.resolve(file))
+        request(:post, path, body: body, content_type: content_type,
+                             idempotency_key: idempotency_key, billable: true, timeout: timeout)
+      else
+        # A URL or a base64 payload goes out as JSON — smaller, and no pointless encode
+        # step. Both forms use identical field names, so the endpoint cannot tell them apart.
+        payload = clean.dup
+        payload["file_url"] = file_url if file_url
+        payload["file_base64"] = file_base64 if file_base64
+        request(:post, path, json: payload, idempotency_key: idempotency_key,
+                             billable: true, timeout: timeout)
+      end
+    end
+
+    def request(method, path, query: nil, body: nil, json: nil, content_type: nil,
+                idempotency_key: nil, billable: false, auth: true, timeout: nil)
+      uri = URI.parse(@base_url + path)
+      if query
+        pairs = query.reject { |_, v| v.nil? || v.to_s.empty? }
+        uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      end
+
+      if json
+        body = JSON.generate(json)
+        content_type = "application/json"
+      end
+
+      headers = {
+        "Accept" => "application/json",
+        "User-Agent" => @user_agent
+      }.merge(@headers)
+      headers["Authorization"] = "Bearer #{@api_key}" if auth
+      headers["Content-Type"] = content_type if content_type
+
+      # A retried upload without a key is a second charge, so the client supplies one for
+      # every billable POST. A failed attempt releases the key server-side, so retrying
+      # with the same one is exactly the intended use.
+      key = idempotency_key || (billable && @auto_idempotency ? SecureRandom.uuid : nil)
+      headers["Idempotency-Key"] = key if key
+
+      attempt = 0
+      loop do
+        begin
+          status, payload, response_headers = perform(method, uri, headers, body, timeout || @timeout)
+        rescue ConnectionError => e
+          raise e if attempt >= @max_retries
+
+          sleep(backoff(attempt))
+          attempt += 1
+          next
+        end
+
+        return nil if status == 204 || payload.nil? || payload.empty?
+
+        parsed = parse(payload)
+        return parsed if status.between?(200, 299)
+
+        error = ErrorFactory.build(status, parsed, response_headers)
+        if RETRYABLE_STATUS.include?(status) && error.retryable? && attempt < @max_retries
+          # 429 carries the server's own number. Honor it; do not invent a backoff.
+          sleep(error.is_a?(RateLimitError) ? error.retry_after : backoff(attempt))
+          attempt += 1
+          next
+        end
+        raise error
+      end
+    end
+
+    def perform(method, uri, headers, body, timeout)
+      klass = {
+        get: Net::HTTP::Get, post: Net::HTTP::Post,
+        put: Net::HTTP::Put, delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      req = klass.new(uri)
+      headers.each { |name, value| req[name] = value }
+      req.body = body if body
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      response = http.request(req)
+      lowered = response.each_header.to_h { |name, value| [name.downcase, value] }
+      [response.code.to_i, response.body, lowered]
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise TimeoutError, "Request to #{uri} timed out after #{timeout}s (#{e.class})."
+    rescue SystemCallError, SocketError, OpenSSL::SSL::SSLError, IOError => e
+      raise ConnectionError, "Request to #{uri} failed: #{e.message}"
+    end
+
+    def parse(payload)
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      payload
+    end
+
+    # Exponential backoff with jitter, for the failures that carry no Retry-After.
+    def backoff(attempt)
+      [0.5 * (2**attempt), 8.0].min * (0.75 + (rand * 0.5))
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/vision_api/errors.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module VisionAPI
+  # Base class for everything this library raises.
+  class Error < StandardError; end
+
+  # Bad arguments, caught before any HTTP call — and therefore before any credit moves.
+  class UsageError < Error; end
+
+  # The request never produced a response: DNS, TLS, a reset connection, a local timeout.
+  class ConnectionError < Error; end
+
+  # The client-side deadline elapsed. The server may still be working on the request.
+  class TimeoutError < ConnectionError; end
+
+  # A structured failure from the API.
+  #
+  # Every failure carries the same envelope — <tt>{"error": {code, message, details?}}</tt>
+  # — and +code+ is contract while +message+ is prose that changes. Rescue the class you
+  # mean, or switch on +code+; never branch on the message text.
+  class APIError < Error
+    # @return [Integer] the HTTP status
+    attr_reader :status
+    # @return [String] the stable machine-readable value from the envelope
+    attr_reader :code
+    # @return [Hash] whatever the endpoint attached: +required+/+available+ on 402,
+    #   +request_id+ on 500, +max_pages+ on 413
+    attr_reader :details
+    # @return [Hash] the response headers, lower-cased
+    attr_reader :headers
+    # @return [String, nil] the correlation id. Quote it in support requests.
+    attr_reader :request_id
+
+    def initialize(status:, code:, message:, details: nil, headers: nil)
+      super("#{code}: #{message}")
+      @status = status
+      @code = code
+      @details = details || {}
+      @headers = headers || {}
+      @request_id = @details["request_id"] || @headers["x-request-id"]
+    end
+
+    # Whether the identical call could plausibly succeed on a second attempt. False for
+    # every input error, and for +insufficient_credits+ — no amount of retrying changes a
+    # balance.
+    def retryable?
+      RETRYABLE_CODES.include?(code)
+    end
+
+    # "too_many_tasks" is 429 but absent on purpose: it clears when the caller's own task
+    # finishes, so an automatic sleep-and-retry would block the very thing it waits for.
+    RETRYABLE_CODES = %w[rate_limited internal_error provider_error].freeze
+  end
+
+  # 400 — the call is malformed. Fix it; retrying will not help.
+  class InvalidRequestError < APIError; end
+
+  # 401 — key missing, unknown or revoked. https://app.visionapi.io/dashboard/keys
+  class AuthenticationError < APIError; end
+
+  # 403 — +forbidden+ or +email_not_verified+.
+  class PermissionDeniedError < APIError; end
+
+  # 402 — the account does not hold enough credits. Never retried: it cannot succeed.
+  class InsufficientCreditsError < APIError
+    # @return [Integer, nil] the credit cost of the request that was refused
+    def required = details["required"]
+
+    # @return [Integer, nil] the balance at the time of the refusal
+    def available = details["available"]
+  end
+
+  # 404 — wrong id, or it belongs to another account.
+  class NotFoundError < APIError; end
+
+  # 409 — a saved-schema name is taken, or an Idempotency-Key was reused differently.
+  class ConflictError < APIError; end
+
+  # 410 — past the 7-day window. Metadata survives, the payload does not. Re-submit the file.
+  class ResultExpiredError < APIError; end
+
+  # 413 — over 20 MB or over 50 pages. Split the input.
+  class PayloadTooLargeError < APIError; end
+
+  # 415 — the magic-byte check failed. Accepted: JPEG, PNG, WebP, TIFF, PDF.
+  class UnsupportedTypeError < APIError; end
+
+  # 422 — semantically invalid input: a bad page range, an encrypted PDF, an uncompilable schema.
+  class UnprocessableError < APIError; end
+
+  # 429 — sleep for #retry_after seconds. Do not invent a backoff.
+  class RateLimitError < APIError
+    # @return [Float] the server's own number, in seconds. Honor it rather than guessing.
+    def retry_after
+      header = headers["retry-after"]
+      value = header.to_f if header
+      return value if value&.positive?
+
+      detail = details["retry_after"]
+      return detail.to_f if detail.is_a?(Numeric) && detail.positive?
+
+      2.0
+    end
+  end
+
+  # 429 — the account's concurrent async task cap is reached.
+  #
+  # A subclass of {RateLimitError} so `rescue RateLimitError` keeps working, but deliberately
+  # not in {RETRYABLE_CODES}: unlike a rate limit this does not clear on a timer, it clears
+  # when one of your own in-flight tasks finishes. Sleeping in the client would just hold the
+  # slot you are waiting for. Poll or await your outstanding tasks, then resubmit.
+  class TooManyTasksError < RateLimitError
+    # @return [Integer, nil] the cap that was hit, from `details.max`.
+    def max_tasks
+      value = details["max"]
+      value.to_i if value.is_a?(Numeric)
+    end
+  end
+
+  # 500 — quote #request_id if you report it. Safe to retry once.
+  class InternalError < APIError; end
+
+  # 502 — the model provider failed after its own retries. Retry with backoff.
+  class ProviderError < APIError; end
+
+  # 504 — past the 60 s synchronous limit.
+  #
+  # Retrying synchronously will time out again. Re-submit through {Client#analyze_async} —
+  # that is what <tt>details["suggestion"]</tt> means by <tt>"async"</tt>.
+  class SyncTimeoutError < APIError; end
+
+  # An async task came back +failed+. A failed task costs 0 credits.
+  class TaskFailedError < Error
+    attr_reader :task_id, :code, :details
+
+    def initialize(task_id, error)
+      error ||= {}
+      @task_id = task_id
+      @code = error["code"] || "unknown"
+      @details = error["details"] || {}
+      super("Task #{task_id} failed — #{@code}: #{error["message"] || "no detail"}")
+    end
+  end
+
+  # {Client#wait_for_task} gave up while the task was still running. The task itself keeps
+  # going, so the id is still worth polling later.
+  class TaskTimeoutError < Error
+    attr_reader :task_id
+
+    def initialize(task_id, waited)
+      @task_id = task_id
+      super("Task #{task_id} did not finish within #{waited.round}s.")
+    end
+  end
+
+  # A delivery could not be trusted. Reject it with a 400; do not parse the body.
+  class WebhookSignatureError < Error; end
+
+  # Maps the wire's error codes onto the classes above. An unrecognised code still produces
+  # an {APIError} with the code intact, so a new server-side code degrades to "unknown but
+  # structured" rather than to a crash.
+  module ErrorFactory
+    BY_CODE = {
+      "invalid_request" => InvalidRequestError,
+      "invalid_api_key" => AuthenticationError,
+      "unauthorized" => AuthenticationError,
+      "forbidden" => PermissionDeniedError,
+      "email_not_verified" => PermissionDeniedError,
+      "insufficient_credits" => InsufficientCreditsError,
+      "task_not_found" => NotFoundError,
+      "schema_not_found" => NotFoundError,
+      "not_found" => NotFoundError,
+      "conflict" => ConflictError,
+      "result_expired" => ResultExpiredError,
+      "file_too_large" => PayloadTooLargeError,
+      "page_limit_exceeded" => PayloadTooLargeError,
+      "unsupported_type" => UnsupportedTypeError,
+      "pdf_encrypted" => UnprocessableError,
+      "invalid_page_selection" => UnprocessableError,
+      "invalid_schema" => UnprocessableError,
+      "schema_field_conflict" => UnprocessableError,
+      "too_many_questions" => UnprocessableError,
+      "rate_limited" => RateLimitError,
+      "too_many_tasks" => TooManyTasksError,
+      "internal_error" => InternalError,
+      "provider_error" => ProviderError,
+      "sync_timeout" => SyncTimeoutError
+    }.freeze
+
+    # Status fallback, for a code this version of the client has not seen yet.
+    BY_STATUS = {
+      400 => InvalidRequestError,
+      401 => AuthenticationError,
+      402 => InsufficientCreditsError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      410 => ResultExpiredError,
+      413 => PayloadTooLargeError,
+      415 => UnsupportedTypeError,
+      422 => UnprocessableError,
+      429 => RateLimitError,
+      500 => InternalError,
+      502 => ProviderError,
+      504 => SyncTimeoutError
+    }.freeze
+
+    module_function
+
+    # @return [APIError] the right subclass for a failed response
+    def build(status, body, headers)
+      envelope = body.is_a?(Hash) ? body["error"] : nil
+
+      if envelope.is_a?(Hash) && envelope["code"]
+        code = envelope["code"].to_s
+        message = envelope["message"].to_s
+        details = envelope["details"]
+      else
+        code = "http_#{status}"
+        message = if body.is_a?(String) && !body.empty?
+                    body[0,
+                         500]
+                  else
+                    "The API returned HTTP #{status} with no error envelope."
+                  end
+        details = nil
+      end
+
+      klass = BY_CODE[code] || BY_STATUS[status] || APIError
+      klass.new(
+        status: status,
+        code: code,
+        message: message,
+        details: details.is_a?(Hash) ? details : nil,
+        headers: headers
+      )
+    end
+  end
+end