invoist 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ce6eaba5adba41bdf885b3552bd5c731c669d47928ad916a716c2b9b1ad8a18
+  data.tar.gz: c1d4bebb9df206e47d0f09cacde4b497c8eef247dbe2b31dc29a3519ceca9281
+SHA512:
+  metadata.gz: 945be9fe7ed66f181225c0e233da9299890bf33327d65a0449a2f869aa7c5cecda50d43165ab12cc1b2777739ab304cb722ecd3ed37507a9148ca952b0ee0f0b
+  data.tar.gz: 77a67ce410b0276f7f83908f4374771b8e56d45aaa3030ea5b310ae17429e915dcc2ce30161d64569e5bbce66a89f96ed94b7c3860aad84c4e9e295ea9d8d2ef

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to the `invoist` gem. It follows
+[Semantic Versioning](https://semver.org), and shares its version number
+with the other official Invoist SDKs.
+
+## 1.0.0 - 2026-11-01
+
+The first release.
+
+- `Invoist::Client` on Ruby's own Net::HTTP, with no other runtime gems.
+- Business workspaces: `extract`, `extract_batch`, `extract_and_wait`,
+  `wait_for_extraction`, `list_documents`, `get_document`,
+  `get_document_file`, `list_review_queue`, `resolve_review_item`,
+  `list_categories`, `get_usage`, `get_stats`, and webhook endpoints
+  (`list_webhook_endpoints`, `create_webhook_endpoint`,
+  `delete_webhook_endpoint`).
+- Households: `bills.list`, `bills.get`, `bills.get_file`, `bills.summary`,
+  `bills.stats`, `bills.mark_paid`, `bills.mark_unpaid` and
+  `held_emails.list`.
+- Typed, immutable response objects generated from the API's OpenAPI
+  description, with RBS signatures in `sig/`.
+- `Invoist::Error` with `status`, `code`, `request_id`, `body` and
+  predicates; automatic retries with `Retry-After` (up to 60 seconds) and
+  backoff.
+- `Invoist::Webhook.verify` for the `X-Invoist-Signature` header, and the
+  event types as constants.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invoist
+
+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,191 @@
+# Invoist for Ruby
+
+The official Ruby library for the [Invoist API](https://invoi.st/docs). Send
+Invoist an invoice, receipt or bill, and get its details back as data: who
+sent it, the totals, tax, line items, the due date, and anything worth a
+second look.
+
+It uses only Ruby's standard library (Net::HTTP, JSON, OpenSSL), so it adds
+no other gems to your app.
+
+## Install
+
+```sh
+bundle add invoist
+```
+
+or `gem install invoist`. Ruby 3.3 or newer.
+
+## A business: read an invoice
+
+```ruby
+require "invoist"
+
+client = Invoist::Client.new(api_key: ENV.fetch("INVOIST_API_KEY"))
+result = client.extract_and_wait("invoice.pdf")
+puts result.extraction.vendor_name, result.extraction.total_cents, result.extraction.currency
+```
+
+Amounts are whole numbers of the smallest unit: `total_cents: 48000` with
+`currency: "GBP"` is £480.00. There are no floats, so nothing is rounded on
+the way.
+
+`extract` returns as soon as the file is accepted, while it is still being
+read; `wait_for_extraction` (or the `extraction.completed` webhook) gives
+you the result. A reading that failed is returned, not raised: check
+`extraction.status` and `extraction.error_message`.
+
+```ruby
+result = client.extract(File.open("receipt.jpg", "rb"), idempotency_key: "upload-1842")
+extraction = client.wait_for_extraction(result.document.id, timeout: 60)
+
+client.list_documents(flagged: true, limit: 20).each { |doc| puts doc.original_filename }
+client.list_review_queue(status: "pending")
+client.get_document_file(result.document.id).save("copy.jpg")
+```
+
+A file can be a path, a `Pathname`, an open `File` or other IO, a file
+uploaded to a Rails or Rack app, or bytes:
+`Invoist::Upload.new(bytes, filename: "invoice.pdf")`.
+
+## A household: what is there to pay
+
+```ruby
+client = Invoist::Client.new(api_key: ENV.fetch("INVOIST_API_KEY"))
+client.bills.list(paid: false, month: "2026-10").each do |bill|
+  puts "#{bill.vendor_name}: #{bill.total_cents} #{bill.currency}, due #{bill.due_date}"
+end
+puts client.bills.summary.overdue
+```
+
+`month` takes `"YYYY-MM"` or a `Date` (a `Time` counts as the day it is
+where your program runs). There is also `bills.get(id)`,
+`bills.get_file(id)`, `bills.stats(month:, sender:)`, `bills.mark_paid(id)`
+and `bills.mark_unpaid(id)` (these two need a key that may mark bills paid),
+and `held_emails.list` for emails waiting for someone to approve the sender.
+
+## Responses
+
+Every method returns typed, immutable objects (`Invoist::Models::Bill`,
+`Invoist::Models::Extraction`, …) with a reader for each field, named as the
+API sends it. Fields the API leaves out are `nil`, and new fields the API
+adds later are ignored until you upgrade. `to_h`, `to_json` and
+`bill[:total_cents]` are there when you want plain data. Signatures for
+every type are in `sig/` for Steep and other RBS tools.
+
+## Errors
+
+Every failure is an `Invoist::Error`:
+
+```ruby
+begin
+  client.bills.mark_paid(bill_id)
+rescue Invoist::Error => e
+  e.status      # 403 (0 when no response arrived)
+  e.code        # "insufficient_scope": stable, branch on this
+  e.message     # for people; the wording can change
+  e.request_id  # quote this to support
+  e.body        # the raw response body
+  e.auth_error? || e.permission_error? || e.not_found? || e.rate_limited? || e.retryable?
+end
+```
+
+`code` is `network_error` when the API couldn't be reached, `timeout` when
+it didn't answer in time, and `unexpected_response` when something between
+you and the API (a proxy, a gateway) answered instead.
+
+## Retries and timeouts
+
+The client retries a request up to twice when it could succeed the second
+time: no response, a timeout, `429 Too Many Requests`, or a `5xx`. It never
+retries another `4xx`. It waits as long as the `Retry-After` header says,
+otherwise 0.5s, then 1s, … with a little randomness, at most 8s. When
+`Retry-After` asks for more than a minute, the call fails at once instead of
+hanging your program (`e.retry_after` says how long). Uploads are
+retried too: sending the same file twice gives back the same document.
+
+```ruby
+Invoist::Client.new(
+  api_key: ENV.fetch("INVOIST_API_KEY"),
+  timeout: 30,       # seconds to connect, and for each read and write (default 60)
+  max_retries: 5,    # 0 turns retrying off (default 2)
+  base_url: "https://api.invoi.st"
+)
+```
+
+Pass `transport:` (anything with `call(request) -> response`, see
+`Invoist::Transport`) to send requests through your own HTTP library or a
+test double.
+
+## Webhooks
+
+Check every delivery's `X-Invoist-Signature` before trusting it. Pass the
+**raw request body**: parsing the JSON and turning it back into a string
+changes it, and the check fails.
+
+Rails:
+
+```ruby
+class InvoistWebhooksController < ActionController::API
+  def create
+    event = Invoist::Webhook.verify(request.raw_post,
+                                    request.headers["X-Invoist-Signature"],
+                                    ENV.fetch("INVOIST_WEBHOOK_SECRET"))
+    if event.type == Invoist::Webhook::EXTRACTION_COMPLETED
+      ImportInvoiceJob.perform_later(event.data["document_id"])
+    end
+    head :ok
+  rescue Invoist::Error
+    head :bad_request
+  end
+end
+```
+
+Sinatra:
+
+```ruby
+post "/webhooks/invoist" do
+  event = Invoist::Webhook.verify(request.body.read, request.env["HTTP_X_INVOIST_SIGNATURE"],
+                                  ENV.fetch("INVOIST_WEBHOOK_SECRET"))
+  logger.info("#{event.type}: #{event.data['document_id']}")
+  200
+rescue Invoist::Error
+  400
+end
+```
+
+Signatures older than five minutes, or more than five minutes ahead, are
+refused (`tolerance:` changes that; `0` turns it off). The event types are
+constants: `Invoist::Webhook::DOCUMENT_CREATED`, `EXTRACTION_COMPLETED`,
+`EXTRACTION_FAILED`, `REVIEW_ITEM_CREATED`, `REVIEW_ITEM_RESOLVED` and
+`DOCUMENT_REQUEST_FULFILLED`. To manage endpoints from code:
+
+```ruby
+endpoint = client.create_webhook_endpoint(url: "https://example.com/webhooks/invoist",
+                                          events: [Invoist::Webhook::EXTRACTION_COMPLETED])
+endpoint.secret # shown only now: store it
+client.list_webhook_endpoints.endpoints
+client.delete_webhook_endpoint(endpoint.id)
+```
+
+`Invoist::Webhook.sign(payload, secret)` makes a valid header, for testing
+your own endpoint.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake            # rubocop, RBS validation and the tests
+bundle exec rake generate   # rebuild lib/invoist/models.rb from openapi.yaml (INVOIST_OPENAPI=path)
+gem build invoist.gemspec
+```
+
+Live tests run against a real API, read-only, when `INVOIST_API_KEY` (and
+optionally `INVOIST_BASE_URL`) is set.
+
+## Links
+
+- API documentation: https://invoi.st/docs
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Security: [SECURITY.md](SECURITY.md), report problems to security@invoi.st
+- License: [MIT](LICENSE)

data/SECURITY.md

@@ -0,0 +1,10 @@
+# Security
+
+Please report a security problem in this library, or in the Invoist API, to
+**security@invoi.st**, not in a public issue. Include what you found and how
+to reproduce it. We answer within two working days and credit you, if you
+like, when the fix ships.
+
+Never paste an API key, an access token or a webhook secret into an issue.
+If one has leaked, revoke it in Invoist straight away: a business under
+Integrations › API, a household under Settings › AI assistants.

data/lib/invoist/bills.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Invoist
+  # A household's bills (Invoist Personal), reached as `client.bills`. These
+  # routes answer a household's key, which holds `bills:read`, and
+  # `bills:write` when the household lets the key mark bills paid.
+  #
+  #   client.bills.list(paid: false).each { |bill| puts bill.vendor_name }
+  #   client.bills.summary.overdue # => 2
+  class Bills
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Lists bills as the app does: unpaid ones soonest-due first, with a
+    # reminder or collection letter folded into its bill (see `letter`).
+    #
+    # @param paid [Boolean, nil] true for paid bills, false for bills still
+    #   to pay, nil for both
+    # @param month [String, Date, Time, nil] `"YYYY-MM"`; by due date, or the
+    #   bill's own date when it has none
+    # @param sender [String, nil] one sender, matched ignoring case and spacing
+    # @param q [String, nil] matches filename, sender, bill number or
+    #   reference, in every month
+    # @param limit [Integer, nil] at most 200; the API's default is 50
+    # @param offset [Integer, nil]
+    # @return [Array<Models::Bill>]
+    # @raise [Error]
+    def list(paid: nil, month: nil, sender: nil, q: nil, limit: nil, offset: nil)
+      query = { paid: Params.boolean("paid", paid), month: Params.month("month", month), sender: sender, q: q,
+                limit: Params.integer("limit", limit), offset: Params.integer("offset", offset) }
+      Array(@http.json("GET", "/v1/bills", query: query)&.fetch("bills", nil)).map { |b| Models::Bill.from_h(b) }
+    end
+
+    # Everything about one bill: what was read from it, its open warnings,
+    # the household's record (paid, by whom, who pays) and its letters.
+    #
+    # @param id [String] the bill's id
+    # @return [Models::BillDetail]
+    # @raise [Error]
+    def get(id)
+      Models::BillDetail.from_h(@http.json("GET", "/v1/bills/#{Params.id(id)}"))
+    end
+
+    # Downloads the original bill, exactly as it was added.
+    #
+    # @param id [String]
+    # @return [Download]
+    # @raise [Error]
+    def get_file(id)
+      @http.binary("/v1/bills/#{Params.id(id)}/file")
+    end
+
+    # What there is to pay: unpaid and overdue counts, and what falls due in
+    # the next `days` days, per currency.
+    #
+    # @param today [String, Date, nil] the household's own date (`YYYY-MM-DD`),
+    #   within two days of the server's; defaults to the server's
+    # @param days [Integer, nil] how far ahead "due soon" reaches; the API's
+    #   default is 30
+    # @return [Models::BillsSummary]
+    # @raise [Error]
+    def summary(today: nil, days: nil)
+      query = { today: Params.date("today", today), days: Params.integer("days", days) }
+      Models::BillsSummary.from_h(@http.json("GET", "/v1/bills/summary", query: query))
+    end
+
+    # A month at a glance: totals billed and paid per currency, the twelve
+    # months up to it, the biggest senders, and every sender.
+    #
+    # @param month [String, Date, Time, nil] `"YYYY-MM"`; defaults to the current month
+    # @param sender [String, nil] narrows the totals and trend to one sender
+    # @return [Models::BillsStats]
+    # @raise [Error]
+    def stats(month: nil, sender: nil)
+      query = { month: Params.month("month", month), sender: sender }
+      Models::BillsStats.from_h(@http.json("GET", "/v1/bills/stats", query: query))
+    end
+
+    # Records a bill, and its letters, as paid by the key's creator. Needs
+    # `bills:write`.
+    #
+    # @param id [String]
+    # @return [Models::BillRecord] the household's record after the change
+    # @raise [Error]
+    def mark_paid(id)
+      record(@http.json("POST", "/v1/bills/#{Params.id(id)}/paid"))
+    end
+
+    # Marks a bill as not paid. Needs `bills:write`.
+    #
+    # @param id [String]
+    # @return [Models::BillRecord] the household's record after the change
+    # @raise [Error]
+    def mark_unpaid(id)
+      record(@http.json("DELETE", "/v1/bills/#{Params.id(id)}/paid"))
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def record(body)
+      Models::BillRecord.from_h(body&.fetch("bill", nil))
+    end
+  end
+
+  # Emails forwarded to a household's address that wait for a person to
+  # approve their sender, or for a plan; reached as `client.held_emails`.
+  # Read-only: approving a sender happens in the app.
+  class HeldEmails
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # @return [Array<Models::HeldEmail>] oldest first
+    # @raise [Error]
+    def list
+      Array(@http.json("GET", "/v1/held-emails")&.fetch("held_emails", nil)).map { |e| Models::HeldEmail.from_h(e) }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}>"
+    end
+  end
+end

data/lib/invoist/client.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Invoist
+  # The client for the Invoist API.
+  #
+  # A business workspace's key reads documents:
+  #
+  #   client = Invoist::Client.new(api_key: ENV.fetch("INVOIST_API_KEY"))
+  #   result = client.extract_and_wait("invoice.pdf")
+  #   result.extraction.total_cents # => 48000
+  #
+  # A household's key reads bills, through {#bills} and {#held_emails}:
+  #
+  #   client.bills.list(paid: false, month: "2026-10").each do |bill|
+  #     puts "#{bill.vendor_name}: #{bill.total_cents} #{bill.currency} by #{bill.due_date}"
+  #   end
+  #
+  # Every method raises {Invoist::Error} on failure and retries what is safe
+  # to retry (see {#initialize}). A client holds no connection state, so one
+  # instance can be shared between threads.
+  class Client
+    # Where requests go unless `base_url:` says otherwise.
+    DEFAULT_BASE_URL = "https://api.invoi.st"
+    # Seconds allowed to connect, and for each read and write.
+    DEFAULT_TIMEOUT = 60
+    # Retries after the first attempt.
+    DEFAULT_MAX_RETRIES = 2
+    # How long {#wait_for_extraction} waits, in seconds.
+    DEFAULT_WAIT_TIMEOUT = 120
+    # How often {#wait_for_extraction} asks, in seconds.
+    DEFAULT_POLL_INTERVAL = 2
+
+    # @return [Bills] a household's bills
+    attr_reader :bills
+    # @return [HeldEmails] emails a household's address is holding for approval
+    attr_reader :held_emails
+
+    # @param api_key [String] a key (`inv_sk_…`) or OAuth access token (`inv_at_…`)
+    # @param base_url [String] the API's address; trailing slashes are trimmed
+    # @param timeout [Numeric] seconds allowed to connect, and for each read and write
+    # @param max_retries [Integer] retries after the first attempt, for
+    #   network failures, timeouts, 429 and 5xx (never another 4xx). Waits
+    #   `Retry-After` when sent, otherwise 0.5s, 1s, 2s… with ±20% jitter, at
+    #   most 8s. 0 turns retrying off.
+    # @param transport [#call, nil] sends a {Transport::Request} and returns a
+    #   {Transport::Response}; defaults to {Transport::NetHTTP}
+    # @param sleeper [#call, nil] called with seconds to wait between retries
+    #   and polls; defaults to `Kernel#sleep` (replace it in tests)
+    # @raise [ArgumentError] when the key is missing or an option is invalid
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, transport: nil, sleeper: nil)
+      validate!(api_key, timeout, max_retries)
+
+      @http = HTTP.new(api_key: api_key.to_s, base_url: base_url.to_s.sub(%r{/+\z}, ""), timeout: timeout,
+                       max_retries: max_retries, transport: transport || Transport::NetHTTP.new,
+                       sleeper: sleeper || Kernel.method(:sleep))
+      @bills = Bills.new(@http)
+      @held_emails = HeldEmails.new(@http)
+    end
+
+    # @return [String] the API's address, without a trailing slash
+    def base_url = @http.base_url
+
+    # @return [Numeric] seconds allowed to connect, and for each read and write
+    def timeout = @http.timeout
+
+    # @return [Integer] retries after the first attempt
+    def max_retries = @http.max_retries
+
+    # @return [String] never shows the key
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+
+    # -- extraction ------------------------------------------------------------
+
+    # Submits a document to be read. Returns as soon as it is accepted, with
+    # the extraction still `pending`; use {#wait_for_extraction}, or the
+    # `extraction.completed` webhook, for the result.
+    #
+    # Uploading bytes this workspace already has returns the existing
+    # document with `duplicate: true`, so retrying is safe. `idempotency_key`
+    # covers re-sending the same logical file with different bytes: every
+    # later call with the key replays the first answer, and reusing it with
+    # another file raises a 422 {Error}.
+    #
+    # @param file [Upload, String, Pathname, IO, Hash] see {Upload.wrap}
+    # @param idempotency_key [String, nil] at most 255 characters
+    # @return [Models::ExtractResult]
+    # @raise [Error]
+    def extract(file, idempotency_key: nil)
+      form = Multipart.new([["file", Upload.wrap(file)]])
+      headers = idempotency_key ? { "Idempotency-Key" => idempotency_key.to_s } : {}
+      Models::ExtractResult.from_h(@http.multipart("/v1/extract", form, headers: headers))
+    end
+
+    # Submits up to ten documents in one request. Each is handled as by
+    # {#extract}; one bad file doesn't fail the others, and `results` keeps
+    # the order the files were given.
+    #
+    # @param files [Array<Upload, String, Pathname, IO, Hash>]
+    # @return [Models::BatchResult]
+    # @raise [Error]
+    def extract_batch(files)
+      files = Array(files)
+      raise ArgumentError, "extract_batch needs at least one file" if files.empty?
+
+      form = Multipart.new(files.map { |file| ["files", Upload.wrap(file)] })
+      Models::BatchResult.from_h(@http.multipart("/v1/extract/batch", form))
+    end
+
+    # -- documents -------------------------------------------------------------
+
+    # @param limit [Integer, nil] at most 200; the API's default is 50
+    # @param offset [Integer, nil]
+    # @param status [String, nil] one of {Models::DocumentStatus::ALL}
+    # @param flagged [Boolean, nil] true for documents with open review items only
+    # @param q [String, nil] matches filename, vendor, invoice number or reference
+    # @param category [String, nil] a category id, or `"none"` for uncategorized
+    # @return [Array<Models::DocumentListItem>]
+    # @raise [Error]
+    def list_documents(limit: nil, offset: nil, status: nil, flagged: nil, q: nil, category: nil)
+      query = { limit: Params.integer("limit", limit), offset: Params.integer("offset", offset), status: status,
+                flagged: flagged ? Params.boolean("flagged", flagged) : nil, q: q, category: category }
+      list(@http.json("GET", "/v1/documents", query: query), "documents", Models::DocumentListItem)
+    end
+
+    # @param id [String] the document's id
+    # @return [Models::DocumentDetail] the document, its extraction (once one
+    #   exists) and its review items
+    # @raise [Error]
+    def get_document(id)
+      Models::DocumentDetail.from_h(@http.json("GET", "/v1/documents/#{Params.id(id)}"))
+    end
+
+    # Downloads the original file, exactly as uploaded.
+    #
+    # @param id [String]
+    # @return [Download]
+    # @raise [Error]
+    def get_document_file(id)
+      @http.binary("/v1/documents/#{Params.id(id)}/file")
+    end
+
+    # Polls {#get_document} until the extraction is no longer `pending`, and
+    # returns it. A `failed` extraction is returned, not raised: it is an
+    # answer about the document (see its `error_message`).
+    #
+    # @param id [String] the document's id
+    # @param timeout [Numeric] seconds before giving up
+    # @param poll_interval [Numeric] seconds between polls
+    # @return [Models::Extraction]
+    # @raise [Error] code `extraction_timeout` (status 0) past the timeout,
+    #   or whatever a poll raised
+    def wait_for_extraction(id, timeout: DEFAULT_WAIT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL)
+      deadline = monotonic + timeout
+      loop do
+        extraction = get_document(id).extraction
+        return extraction if extraction && extraction.status != Models::ExtractionStatus::PENDING
+
+        if monotonic + poll_interval > deadline
+          raise Error.new("The extraction of document #{id} did not finish within #{timeout}s",
+                          status: 0, code: "extraction_timeout")
+        end
+        @http.sleep(poll_interval)
+      end
+    end
+
+    # Submits a document and waits for its extraction: {#extract} then
+    # {#wait_for_extraction}.
+    #
+    # @param file [Upload, String, Pathname, IO, Hash]
+    # @param timeout [Numeric] seconds to wait for the reading
+    # @param poll_interval [Numeric]
+    # @param idempotency_key [String, nil]
+    # @return [Models::ExtractResult] with the finished extraction
+    # @raise [Error]
+    def extract_and_wait(file, timeout: DEFAULT_WAIT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL,
+                         idempotency_key: nil)
+      result = extract(file, idempotency_key: idempotency_key)
+      extraction = result.extraction
+      if extraction.nil? || extraction.status == Models::ExtractionStatus::PENDING
+        extraction = wait_for_extraction(result.document.id, timeout: timeout, poll_interval: poll_interval)
+      end
+      result.with(extraction: extraction)
+    end
+
+    # -- review queue ----------------------------------------------------------
+
+    # @param status [String, nil] one of {Models::ReviewStatus::ALL}; nil for all
+    # @return [Array<Models::ReviewQueueListItem>]
+    # @raise [Error]
+    def list_review_queue(status: nil)
+      list(@http.json("GET", "/v1/review-queue", query: { status: status }), "review_queue",
+           Models::ReviewQueueListItem)
+    end
+
+    # @param id [String] the review item's id
+    # @param status [String] `"resolved"` or `"dismissed"`
+    # @return [Models::ReviewQueueItem]
+    # @raise [Error]
+    def resolve_review_item(id, status: Models::ReviewStatus::RESOLVED)
+      body = @http.json("POST", "/v1/review-queue/#{Params.id(id)}/resolve", body: { status: status })
+      Models::ReviewQueueItem.from_h(body&.fetch("review_queue_item", nil))
+    end
+    alias resolve_review_queue_item resolve_review_item
+
+    # -- workspace -------------------------------------------------------------
+
+    # @return [Array<Models::Category>]
+    # @raise [Error]
+    def list_categories
+      list(@http.json("GET", "/v1/categories"), "categories", Models::Category)
+    end
+
+    # @return [Models::Usage] usage in the current billing period
+    # @raise [Error]
+    def get_usage # rubocop:disable Naming/AccessorMethodName
+      Models::Usage.from_h(@http.json("GET", "/v1/usage"))
+    end
+
+    # @return [Models::StatsOverview]
+    # @raise [Error]
+    def get_stats # rubocop:disable Naming/AccessorMethodName
+      Models::StatsOverview.from_h(@http.json("GET", "/v1/stats/overview"))
+    end
+
+    # -- webhook endpoints -----------------------------------------------------
+
+    # @return [Models::WebhookEndpointList] the endpoints and every event type
+    # @raise [Error]
+    def list_webhook_endpoints
+      Models::WebhookEndpointList.from_h(@http.json("GET", "/v1/webhook-endpoints"))
+    end
+
+    # Subscribes a URL to signed events. The answer carries the signing
+    # secret, which is never shown again: store it now.
+    #
+    # @param url [String] an HTTP or HTTPS receiver
+    # @param events [Array<String>, nil] e.g. `[Invoist::Webhook::EXTRACTION_COMPLETED]`;
+    #   nil for everything
+    # @param description [String, nil]
+    # @return [Models::WebhookEndpointWithSecret]
+    # @raise [Error]
+    def create_webhook_endpoint(url:, events: nil, description: nil)
+      body = { url: url, events: events, description: description }.compact
+      response = @http.json("POST", "/v1/webhook-endpoints", body: body)
+      Models::WebhookEndpointWithSecret.from_h(response&.fetch("endpoint", nil))
+    end
+
+    # Unsubscribes an endpoint; deliveries to it stop at once.
+    #
+    # @param id [String]
+    # @return [nil]
+    # @raise [Error]
+    def delete_webhook_endpoint(id)
+      @http.json("DELETE", "/v1/webhook-endpoints/#{Params.id(id)}")
+      nil
+    end
+
+    private
+
+    def validate!(api_key, timeout, max_retries)
+      if api_key.nil? || api_key.to_s.strip.empty?
+        raise ArgumentError,
+              "An Invoist API key is required: Invoist::Client.new(api_key: ENV.fetch(\"INVOIST_API_KEY\"))"
+      end
+      unless timeout.is_a?(Numeric) && timeout.positive?
+        raise ArgumentError,
+              "timeout must be a positive number of seconds"
+      end
+      return if max_retries.is_a?(Integer) && !max_retries.negative?
+
+      raise ArgumentError, "max_retries must be a non-negative Integer"
+    end
+
+    def list(body, key, model)
+      Array(body&.fetch(key, nil)).map { |item| model.from_h(item) }
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end