runearc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff088997a6f1f5b35201d2db5050fe8d77acb58fdd26e934e58df59e5cca1383
+  data.tar.gz: 94f737ea26643155d1c3b4d66d0465385757965dde162273920d954a11abac77
+SHA512:
+  metadata.gz: 2a398b853957db2a9621d5ab7b661e569a0a421db349083baa72e12834eee29f59010221b3e899460c19545060b8ecb49b946be971f9530b81720d05a797f07c
+  data.tar.gz: b21f2290cd6b2b8dcb8a203f17721c2aa2760f11297bca7cf945b145c7cb4c7709dbd5a373c258ba285ad18f6d515efa8bc9315362637677158966eef9291e77

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runearc
+
+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,369 @@
+<p align="center">
+  <a href="https://runearc.com/integrations/ruby">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/runearc-labs/runearc-ruby/main/.github/assets/banner-light.png">
+      <img alt="Runearc for Ruby. Install with the command shown, then send email and give agents inboxes." src="https://raw.githubusercontent.com/runearc-labs/runearc-ruby/main/.github/assets/banner-dark.png" width="100%">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/runearc-labs/runearc-ruby/blob/main/CHANGELOG.md"><img alt="version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-0007cd?style=flat-square&labelColor=0f0f0f"></a> <a href="https://github.com/runearc-labs/runearc-ruby/blob/main/LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-2b2b2b?style=flat-square&labelColor=0f0f0f"></a> <a href="https://runearc.com/integrations/ruby"><img alt="requires ruby 3.0+" src="https://img.shields.io/badge/requires-ruby%203.0%2B-2b2b2b?style=flat-square&labelColor=0f0f0f"></a> <a href="https://runearc.com/docs/sdk"><img alt="tested against the real API" src="https://img.shields.io/badge/tests-real%20API-14833b?style=flat-square&labelColor=0f0f0f"></a>
+</p>
+
+<p align="center">
+  <a href="https://runearc.com"><b>Website</b></a> ·
+  <a href="https://runearc.com/docs/sdk">Docs</a> ·
+  <a href="https://runearc.com/integrations/ruby">Ruby guide</a> ·
+  <a href="https://runearc.com/docs/mcp">MCP</a> ·
+  <a href="https://runearc.com/status">Status</a> ·
+  <a href="https://runearc.com/changelog">Changelog</a>
+</p>
+
+# runearc
+
+The official Ruby SDK for [Runearc](https://runearc.com), email infrastructure for apps and AI agents. Send email and give your agents an inbox, from Ruby.
+
+```sh
+gem install runearc
+```
+
+```ruby
+require "runearc"
+
+runearc = Runearc::Client.new(ENV["RUNEARC_API_KEY"])
+email = runearc.emails.deliver(from: "Acme <noreply@acme.com>", to: "bob@example.com", subject: "Welcome to Acme", html: "<p>Thanks for signing up.</p>")
+```
+
+See [runearc.com/integrations/ruby](https://runearc.com/integrations/ruby) for the guide and more examples.
+
+The official Ruby SDK for [Runearc](https://runearc.com): send, batch and schedule email, create inboxes your agents can read, manage domains and verify webhooks.
+
+Standard library only (`net/http`, `json`, `openssl`), no runtime dependencies. Ruby 3.0 or later.
+
+## Install
+
+```sh
+gem install runearc
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "runearc"
+```
+
+## Quick start
+
+```ruby
+require "runearc"
+
+runearc = Runearc::Client.new(ENV["RUNEARC_API_KEY"])
+
+email = runearc.emails.deliver(
+  from: "Acme <noreply@acme.com>",
+  to: "bob@example.com",
+  subject: "Welcome to Acme",
+  html: "<p>Thanks for signing up.</p>"
+)
+email[:id] # => "eml_..."
+```
+
+`Runearc::Client.new` with no key reads `RUNEARC_API_KEY`. Keyword options:
+
+| Option | Default | |
+|---|---|---|
+| `base_url:` | `RUNEARC_BASE_URL`, else `https://api.runearc.com` | A trailing `/v1` is fine. |
+| `max_retries:` | `2` | Retries after the first attempt (see [Retries](#retries)). |
+| `timeout:` | `60` | Seconds, per attempt. |
+| `headers:` | none | Sent with every request. |
+
+Responses are the API's JSON as Hashes with symbol keys, and field names are the API's own snake case (`reply_to`, `scheduled_at`, `next_cursor`), so the [API reference](https://runearc.com/docs) and this SDK read the same. Every method also takes `request_timeout:` (seconds, overrides `timeout:` for that call), and the methods that send mail take `idempotency_key:`.
+
+Ruby already has `Object#send`, so sending is `emails.deliver` and `messages.deliver`.
+
+To try things without sending real mail, send to `delivered@test.runearc.com`. `bounced@` and `complained@` at the same domain simulate those outcomes.
+
+## Errors
+
+Methods return the parsed response and raise a `Runearc::Error` when something fails. There is no result wrapper.
+
+```ruby
+begin
+  runearc.emails.deliver(from: "noreply@acme.com", to: "bob@example.com", subject: "Hi", text: "Hi")
+rescue Runearc::Error => e
+  e.status  # => 403
+  e.code    # => "sender_not_verified", a stable string to branch on
+  e.kind    # => "forbidden"
+  e.message
+  e.fix     # what to do about it, when there is something to do
+  raise
+end
+```
+
+`Runearc::Error` has `status` (the HTTP status, or `0` when no response came back), `code`, `kind`, `message`, `fix`, `retry_after` (seconds, when the API sent `Retry-After`) and, for a refused batch, `errors`. `to_h` gives all of it as a Hash. `kind` is the API's error kind (`invalid`, `unauthorized`, `limit_reached`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `unavailable`, `internal`), worked out from the status, or `connection` when no response came back.
+
+Rescue one class for everything, or a narrower one:
+
+```
+Runearc::Error
+  ConfigurationError        no API key (code missing_api_key)
+  ConnectionError           network failed (code network_error)
+    TimeoutError            code timeout
+  WebhookVerificationError  see Verifying webhooks
+  ApiError                  the API answered with an error
+    InvalidRequestError     400
+    AuthenticationError     401
+    LimitReachedError       402
+    PermissionError         403
+    NotFoundError           404
+    ConflictError           409
+    RateLimitError          429
+    ServerError             5xx
+```
+
+Lists come back as the API sends them: `{ data: [...] }`, plus `next_cursor` on paginated lists.
+
+## Emails
+
+```ruby
+# Send
+id = runearc.emails.deliver(
+  from: "Acme <noreply@acme.com>",
+  to: ["bob@example.com"],
+  cc: "carol@example.com",
+  reply_to: "support@acme.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>",
+  text: "Thanks for your order.",
+  attachments: [{ filename: "receipt.pdf", content: Base64.strict_encode64(pdf) }],
+  tags: [{ name: "kind", value: "receipt" }]
+)[:id]
+
+# Read
+email = runearc.emails.get(id) # :status, :last_event, :recipients, :html, :text
+page = runearc.emails.list(limit: 50)
+more = runearc.emails.list(cursor: page[:next_cursor]) if page[:next_cursor]
+```
+
+### Scheduled send
+
+Pass `scheduled_at:` as a `Time`, an RFC 3339 time with an offset, or the relative form `in <n> <unit>`. Up to 30 days ahead.
+
+```ruby
+id = runearc.emails.deliver(
+  from: "Acme <noreply@acme.com>",
+  to: "bob@example.com",
+  subject: "Your trial ends tomorrow",
+  text: "Here is what happens next.",
+  scheduled_at: Time.now + 24 * 60 * 60 # or "2026-10-20T09:00:00Z", or "in 1 day"
+)[:id]
+
+runearc.emails.get(id)                     # status: "scheduled", scheduled_at: "..."
+runearc.emails.reschedule(id, "in 2 days") # same as emails.update(id, scheduled_at: ...)
+runearc.emails.cancel(id)                  # status: "canceled"
+```
+
+Rescheduling or canceling an email that is no longer scheduled raises `ConflictError` with the code `email_not_scheduled`.
+
+### Batch send
+
+Up to 100 emails in one request. Each item has the shape of `emails.deliver`, `scheduled_at` included.
+
+```ruby
+ids = runearc.emails.batch([
+  { from: "Acme <noreply@acme.com>", to: "bob@example.com", subject: "Hi Bob", text: "..." },
+  { from: "Acme <noreply@acme.com>", to: "carol@example.com", subject: "Hi Carol", text: "..." }
+])[:data] # [{ id: }, { id: }] in request order
+```
+
+By default validation is strict: if any item is invalid nothing is sent, and the error lists every bad item.
+
+```ruby
+begin
+  runearc.emails.batch(emails)
+rescue Runearc::InvalidRequestError => e
+  e.errors.each { |item| puts [item[:index], item[:code], item[:message], item[:fix]].inspect } if e.code == "invalid_batch"
+end
+```
+
+With `batch_validation: :permissive` the valid items are sent and the invalid ones are reported:
+
+```ruby
+result = runearc.emails.batch(emails, batch_validation: :permissive)
+result[:data]   # the emails sent
+result[:errors] # the items refused, each with its :index
+```
+
+### Senders
+
+```ruby
+runearc.senders.list[:data] # addresses you can use as `from`
+```
+
+## Inboxes and messages
+
+Inboxes receive mail. Give one to an agent, wait for a message, read the code in it, reply.
+
+```ruby
+inbox = runearc.inboxes.create(local_part: "signup-bot", display_name: "Signup bot")
+runearc.inboxes.list
+runearc.inboxes.get(inbox[:id])
+
+# Wait up to 120 seconds for a matching message. Returns nil when none arrived.
+got = runearc.messages.wait(inbox[:id], from: "github.com", subject: "verify", timeout: 60)
+puts got[:codes], got[:links], got[:message][:subject] if got
+
+page = runearc.messages.list(inbox[:id], limit: 20)
+message = runearc.messages.get(page[:data].first[:id])
+rfc822 = runearc.messages.raw(message[:id])
+
+# Send from the inbox, and reply in a thread
+runearc.messages.deliver(inbox[:id], to: "bob@example.com", subject: "Hello", text: "Hi Bob")
+runearc.messages.reply(message[:id], text: "Thanks, on it", reply_all: false)
+
+# Threads
+runearc.threads.list(inbox[:id])
+thread = runearc.threads.get(message[:thread_id]) # with :messages
+
+runearc.inboxes.delete(inbox[:id])
+```
+
+## Conversations
+
+The shared support inbox view across every inbox you can read.
+
+```ruby
+conversations = runearc.conversations.list(status: "open", assignee: "none", q: "refund")[:data]
+id = conversations.first[:id]
+runearc.conversations.counts
+runearc.conversations.update(id, status: "closed")
+runearc.conversations.update(id, snoozed_until: Time.now + 3600)
+runearc.conversations.update(id, assignee_user_id: nil) # an explicit nil is sent as null: unassigns
+runearc.conversations.read(id)
+runearc.conversations.unread(id)
+```
+
+## Domains
+
+```ruby
+domain = runearc.domains.create(name: "acme.com")
+domain[:records]   # the DNS records to publish
+domain[:next_step]
+
+runearc.domains.verify(domain[:id]) # checks DNS now
+runearc.domains.list
+runearc.domains.get("acme.com")     # id or name
+runearc.domains.delete(domain[:id])
+```
+
+## Webhooks
+
+```ruby
+hook = runearc.webhooks.create(
+  url: "https://acme.com/runearc/webhook",
+  event_types: ["message.received", "message.delivered", "message.bounced"]
+)
+# hook[:secret] ("whsec_...") is shown once: store it, you need it to verify deliveries.
+
+runearc.webhooks.list
+deliveries = runearc.webhooks.deliveries(hook[:id], limit: 20)[:data]
+runearc.webhooks.replay(hook[:id], deliveries.first[:id])
+runearc.webhooks.delete(hook[:id])
+```
+
+### Verifying webhooks
+
+Runearc signs every delivery with [Standard Webhooks](https://www.standardwebhooks.com): headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,<base64 HMAC SHA256>`). `Runearc::Webhook.verify` (also `runearc.webhooks.verify` and `Runearc.verify_webhook`) checks the signature with OpenSSL and a constant time comparison, refuses timestamps more than 5 minutes off (`tolerance:` changes that), and returns the parsed event. It raises `Runearc::WebhookVerificationError`, a `Runearc::Error`, otherwise; its `code` is one of `missing_headers`, `invalid_timestamp`, `timestamp_out_of_range`, `invalid_secret`, `invalid_signature` or `invalid_payload`. Always pass the raw body, not JSON you parsed and serialized again.
+
+`headers:` is a Hash with keys in any case, a Rack env (`HTTP_WEBHOOK_ID` keys), or any object that answers `headers["webhook-id"]`, such as Rails' `request.headers`.
+
+Rails controller:
+
+```ruby
+class RunearcWebhooksController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    event = Runearc::Webhook.verify(
+      payload: request.raw_post,
+      headers: request.headers,
+      secret: ENV.fetch("RUNEARC_WEBHOOK_SECRET")
+    )
+    if event[:type] == "message.received"
+      # event[:data][:message_id], event[:data][:inbox_id], ...
+    end
+    head :no_content
+  rescue Runearc::WebhookVerificationError => e
+    render plain: e.message, status: :bad_request
+  end
+end
+```
+
+Sinatra or plain Rack:
+
+```ruby
+post "/runearc/webhook" do
+  event = Runearc::Webhook.verify(
+    payload: request.body.read,
+    headers: request.env,
+    secret: ENV.fetch("RUNEARC_WEBHOOK_SECRET")
+  )
+  puts event[:type], event[:id] # event[:id] is the webhook-id: use it to drop duplicates
+  status 204
+rescue Runearc::WebhookVerificationError
+  halt 400, "invalid signature"
+end
+```
+
+## API keys, suppressions and events
+
+```ruby
+created = runearc.keys.create(name: "app", permissions: "sending", domain_id: "acme.com")
+created[:secret] # shown once
+runearc.keys.list
+runearc.keys.delete(created[:key][:id]) # revokes at once
+
+runearc.suppressions.list
+runearc.suppressions.delete("bob@example.com") # lets mail go to bob again
+
+page = runearc.events.list(limit: 100) # oldest first
+page = runearc.events.list(after: page[:next_after])
+```
+
+## Retries
+
+The SDK retries a request up to `max_retries` times (default 2) with exponential backoff and jitter, and waits as long as the API's `Retry-After` header asks (seconds or an HTTP date, at most 60 seconds). It retries:
+
+* 429 (rate limited), always;
+* 5xx, network errors and timeouts, when the request is safe to repeat: GET, PATCH and DELETE, and any POST that carries an `Idempotency-Key`.
+
+It never retries other 4xx errors. A POST that could create something twice (such as creating an inbox) is not repeated after a 5xx or a network error; the error is raised instead.
+
+## Idempotency
+
+Every call that sends mail (`emails.deliver`, `emails.batch`, `messages.deliver`, `messages.reply`) gets an `Idempotency-Key` automatically when you do not give one, and every retry reuses it, so a retry never sends twice. Runearc remembers keys for 24 hours. To make your own retries safe too, for example from a job queue, pass a key that is stable for that piece of work:
+
+```ruby
+runearc.emails.deliver(idempotency_key: "welcome/#{user.id}", **email)
+```
+
+Repeating a key with the same body returns the first result. The same key with a different body raises `ConflictError` with the code `idempotency_conflict`.
+
+## Types
+
+RBS signatures for the whole public surface ship in `sig/runearc.rbs`, and every public method has YARD docs.
+
+## Development
+
+Tests run against a real local API and Postgres: `Stack` in `test/support/stack.rb` creates a throwaway database, bootstraps the API, and starts `runearc-api` and `runearc-worker` from `RUNEARC_BIN_DIR` (default `../../target/agent-sdk/debug`). Build them with `CARGO_TARGET_DIR=../../target/agent-sdk cargo build -p runearc-api -p runearc-worker`. Postgres must be on localhost with `createdb`, `dropdb` and `psql` on `PATH`.
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE). Copyright Runearc.

data/lib/runearc/client.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module Runearc
+  # The Runearc API client. Create one and use its resources:
+  #
+  #   runearc = Runearc::Client.new(ENV["RUNEARC_API_KEY"])
+  #   runearc.emails.deliver(from: "Acme <noreply@acme.com>", to: "bob@example.com", subject: "Hi", text: "Hi")
+  #
+  # Responses are the API's JSON as Hashes with symbol keys, so the API reference and the
+  # SDK read the same (+:next_cursor+, +:scheduled_at+). Failures raise {Runearc::Error}.
+  #
+  # Every method takes the per call options +idempotency_key:+ and +request_timeout:+ (seconds).
+  class Client
+    # Retries after the first attempt, on 429, 5xx and network errors.
+    DEFAULT_MAX_RETRIES = 2
+
+    # Per attempt timeout in seconds.
+    DEFAULT_TIMEOUT = 60
+
+    # Longest wait between attempts, in seconds, even when +Retry-After+ asks for more.
+    MAX_RETRY_WAIT = 60
+
+    NETWORK_ERRORS = [
+      SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError, Net::ProtocolError
+    ].freeze
+    private_constant :NETWORK_ERRORS
+
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
+    private_constant :TIMEOUT_ERRORS
+
+    HTTP_METHODS = {
+      get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+    }.freeze
+    private_constant :HTTP_METHODS
+
+    # @return [String] the API origin, without a trailing +/v1+
+    attr_reader :base_url
+
+    # @return [Integer] retries after the first attempt
+    attr_reader :max_retries
+
+    # @return [Numeric] per attempt timeout in seconds
+    attr_reader :timeout
+
+    # @return [Emails]
+    attr_reader :emails
+    # @return [Senders]
+    attr_reader :senders
+    # @return [Inboxes]
+    attr_reader :inboxes
+    # @return [Messages]
+    attr_reader :messages
+    # @return [Threads]
+    attr_reader :threads
+    # @return [Conversations]
+    attr_reader :conversations
+    # @return [Domains]
+    attr_reader :domains
+    # @return [Webhooks]
+    attr_reader :webhooks
+    # @return [Keys]
+    attr_reader :keys
+    # @return [Suppressions]
+    attr_reader :suppressions
+    # @return [Events]
+    attr_reader :events
+
+    # @param api_key [String, nil] the API key; +RUNEARC_API_KEY+ when nil
+    # @param base_url [String, nil] API origin. Default +RUNEARC_BASE_URL+ or https://api.runearc.com.
+    #   A trailing +/v1+ is fine.
+    # @param max_retries [Integer] retries after the first attempt, on 429, 5xx and network errors (default 2)
+    # @param timeout [Numeric] per attempt timeout in seconds (default 60)
+    # @param headers [Hash{String => String}] extra headers sent with every request
+    # @raise [ConfigurationError] when there is no API key
+    def initialize(api_key = nil, base_url: nil, max_retries: DEFAULT_MAX_RETRIES, timeout: DEFAULT_TIMEOUT,
+                   headers: {})
+      @api_key = present(api_key) || present(ENV.fetch("RUNEARC_API_KEY", nil)) || raise(missing_key)
+      base = present(base_url) || present(ENV.fetch("RUNEARC_BASE_URL", nil)) || DEFAULT_BASE_URL
+      @base_url = base.sub(%r{/+\z}, "").sub(%r{/v1\z}, "")
+      @max_retries = [max_retries, 0].max
+      @timeout = timeout
+      @headers = headers.to_h { |k, v| [k.to_s, v.to_s] }
+      build_resources
+    end
+
+    # Hides the API key.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+
+    # Every API call goes through here.
+    #
+    # @api private
+    # @return [Hash, Array, String, nil] the parsed JSON, the body when +text+, or nil for an empty body
+    def request(method, path, query: nil, body: nil, headers: nil, sends_mail: false, idempotent: false,
+                text: false, idempotency_key: nil, request_timeout: nil)
+      uri = build_uri(path, query)
+      idem = idempotency_key || (SecureRandom.uuid if sends_mail)
+      head = build_headers(headers, idem, body)
+      payload = JSON.generate(body) unless body.nil?
+      # Repeating must not create a second resource: GET, DELETE and PATCH are idempotent,
+      # and a POST is when it carries an Idempotency-Key.
+      repeatable = method != :post || !idem.nil? || idempotent
+      seconds = request_timeout || timeout
+
+      attempt = 0
+      loop do
+        last = attempt >= max_retries
+        begin
+          res = perform(method, uri, head, payload, seconds)
+        rescue *TIMEOUT_ERRORS, *NETWORK_ERRORS => e
+          raise connection_error(e, idem, seconds) unless repeatable && !last
+
+          sleep(backoff(attempt))
+          attempt += 1
+          next
+        end
+        return parse_success(res, text) if res.is_a?(Net::HTTPSuccess)
+
+        wait = retry_after(res["retry-after"])
+        status = res.code.to_i
+        if (status == 429 || (status >= 500 && repeatable)) && !last
+          sleep([wait || backoff(attempt), MAX_RETRY_WAIT].min)
+          attempt += 1
+          next
+        end
+        raise api_error(res, wait)
+      end
+    end
+
+    private
+
+    def present(value)
+      value unless value.nil? || value.to_s.empty?
+    end
+
+    def missing_key
+      ConfigurationError.new(
+        "no Runearc API key was given",
+        code: "missing_api_key",
+        fix: "Pass it as Runearc::Client.new('mb_...') or set RUNEARC_API_KEY"
+      )
+    end
+
+    def build_resources
+      @emails = Emails.new(self)
+      @senders = Senders.new(self)
+      @inboxes = Inboxes.new(self)
+      @messages = Messages.new(self)
+      @threads = Threads.new(self)
+      @conversations = Conversations.new(self)
+      @domains = Domains.new(self)
+      @webhooks = Webhooks.new(self)
+      @keys = Keys.new(self)
+      @suppressions = Suppressions.new(self)
+      @events = Events.new(self)
+    end
+
+    def build_uri(path, query)
+      uri = URI.parse(base_url + path)
+      pairs = (query || {}).compact.map { |k, v| [k.to_s, Support.time(v).to_s] }
+      uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      uri
+    end
+
+    def build_headers(extra, idempotency_key, body)
+      head = { "Accept" => "application/json", "User-Agent" => "runearc-ruby/#{VERSION}" }
+      head.merge!(@headers)
+      head.merge!(extra) if extra
+      head["Authorization"] = "Bearer #{@api_key}"
+      head["Idempotency-Key"] = idempotency_key if idempotency_key
+      head["Content-Type"] = "application/json" unless body.nil?
+      head
+    end
+
+    def perform(method, uri, headers, payload, seconds)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = http.read_timeout = http.write_timeout = seconds
+      # Net::HTTP would repeat idempotent requests by itself; the SDK owns retries.
+      http.max_retries = 0
+      req = HTTP_METHODS.fetch(method).new(uri.request_uri, headers)
+      req.body = payload if payload
+      http.start { |conn| conn.request(req) }
+    end
+
+    # Seconds to wait from a Retry-After header (seconds or an HTTP date).
+    def retry_after(value)
+      return nil if value.nil? || value.empty?
+
+      seconds = Float(value, exception: false)
+      return [seconds, 0].max if seconds&.finite?
+
+      at = http_date(value)
+      at && [at - Time.now, 0].max
+    end
+
+    def http_date(value)
+      Time.httpdate(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def backoff(attempt)
+      cap = [8.0, 0.5 * (2**attempt)].min
+      (cap / 2) + (rand * (cap / 2))
+    end
+
+    def parse_success(res, text)
+      raw = res.body.to_s.dup.force_encoding(Encoding::UTF_8)
+      return raw if text
+      return nil if raw.empty?
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError => e
+      raise ApiError.build(
+        "the API sent a response that is not JSON (#{e.message[0, 80]})",
+        status: res.code.to_i, code: "invalid_response", fix: "Check that base_url points at the Runearc API"
+      )
+    end
+
+    def connection_error(cause, idempotency_key, seconds)
+      fix = if idempotency_key
+              "Retry with the same idempotency_key (#{idempotency_key}) so the email is not sent twice"
+            else
+              "Check your network and base_url, then retry"
+            end
+      if TIMEOUT_ERRORS.any? { |k| cause.is_a?(k) }
+        TimeoutError.new("no response from #{base_url} within #{seconds} s", fix: fix)
+      else
+        ConnectionError.new("could not reach #{base_url}: #{cause.message}", fix: fix)
+      end
+    end
+
+    def api_error(res, wait)
+      status = res.code.to_i
+      text = res.body.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      info = begin
+        JSON.parse(text, symbolize_names: true)[:error]
+      rescue JSON::ParserError, TypeError, NoMethodError
+        nil
+      end
+      info = {} unless info.is_a?(Hash)
+      fallback = text.empty? ? "HTTP #{status}" : text[0, 500]
+      ApiError.build(
+        info[:message] || fallback,
+        status: status,
+        code: info[:code] || "http_#{status}",
+        kind: info[:kind],
+        fix: info[:fix],
+        errors: (info[:errors] if info[:errors].is_a?(Array)),
+        retry_after: wait&.ceil
+      )
+    end
+  end
+end