sendclipper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3f2ca79b7b603e79b2a71e81fd3bf8033e705b0c76171c8a69197db1e08cf45
+  data.tar.gz: f97e10cb672f61fb581b866d02fb884b62485bfbc1c63a2721d3e1c116d6223b
+SHA512:
+  metadata.gz: cef70da38935cb7581232e23fe51041f5b0a9f2d3cb845b956dfdb3608762b4165c78b7fd17af857f99ba2301102167a841139e37c0cdb00b3337f3ebe21d95e
+  data.tar.gz: fb85cd253f346b37a46907366bf8cfa8ce8459b3f731ce1d4d7089ff17bf0839094f2d1826950cf1f644e54c0d7f128140fbe0d1b465acd1bd1bf9ef60faed8e

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-10-16
+
+First release.
+
+- `emails.send`, `batch.send`, `emails.get`, `emails.list`, `emails.each`, `emails.stats`.
+- Templates (with tags and image assets), domains, sandboxes (including the JSON door and `wait_for`), webhooks and their dispatches, contacts, audiences, suppressions, mailboxes, automations, workspace and API keys.
+- Every method returns a `SendClipper::Result` with `data`, `error` and `headers`; it destructures to `data, error` and pattern-matches.
+- Fields can be keyword arguments in snake_case (`template_id:`), turned into the API's camelCase.
+- Automatic `Idempotency-Key` on every JSON write; retries on network errors, 429 and 5xx.
+- `SendClipper.verify_webhook` for `X-SendClipper-Signature-V2`, rotation-aware.
+- Ruby 3.1 or newer; no runtime dependencies.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SendClipper
+
+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,206 @@
+# SendClipper Ruby SDK
+
+The official Ruby library for the [SendClipper](https://sendclipper.com) email API.
+
+```bash
+gem install sendclipper
+# or, in a Gemfile
+bundle add sendclipper
+```
+
+Ruby 3.1 or newer. No runtime dependencies.
+
+## Setup
+
+Create an API key in the dashboard under **API keys**.
+
+```ruby
+require "sendclipper"
+
+client = SendClipper::Client.new("sc_live_xxxxxxxxxxxxxxxx")
+# or: SendClipper::Client.new  reads SENDCLIPPER_API_KEY
+```
+
+## Send an email
+
+```ruby
+data, error = client.emails.send(
+  from: "hello@send.acme.io",
+  to: "ada@lumen.io",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order.</p>",
+  text: "Thanks for your order."
+)
+
+if error
+  puts "#{error.name}: #{error.message}" # e.g. domain_not_verified
+else
+  puts "Email #{data["id"]} accepted"
+end
+```
+
+Fields are keyword arguments (or a Hash). Top-level names may be snake_case (`template_id:`, `send_class:`), which the SDK turns into the API's camelCase, or the API's own names exactly as the [API reference](https://sendclipper.com/docs) writes them. Values, such as the `variables` map, are sent exactly as given. Responses are Hashes with the API's string keys (`data["id"]`).
+
+`from` must be a bare address on a domain you verified in SendClipper. Each message has one recipient in `to`; for several, use `batch.send`.
+
+## Send with a template
+
+Design and publish a template in the dashboard, then send it by id or by its send name:
+
+```ruby
+client.emails.send(
+  from: "hello@send.acme.io",
+  to: "ada@lumen.io",
+  template_id: "tpl_9f2b7c10ad42", # or template: "welcome"
+  variables: { first_name: "Ada" }
+)
+```
+
+A tag with no value and no `{{tag|fallback}}` is refused by name (`template_variables_missing`), never sent blank.
+
+## Send a batch
+
+Up to 500 messages in one request. Each item is accepted or refused on its own:
+
+```ruby
+data, = client.batch.send([
+  { from: "hello@send.acme.io", to: "ada@lumen.io", subject: "Hi Ada", html: "<p>Hi</p>" },
+  { from: "hello@send.acme.io", to: "alan@lumen.io", template_id: "tpl_9f2b7c10ad42", variables: { first_name: "Alan" } }
+])
+
+data["data"].each do |item|
+  puts "#{item["index"]} #{item["error"]["code"]}" if item["status"] == "failed"
+end
+```
+
+## Errors
+
+API methods never raise for an API refusal or a network failure. They return a `SendClipper::Result` with `data`, `error` and `headers`, and exactly one of `data` and `error` is set. A Result destructures to `data, error` and pattern-matches:
+
+```ruby
+result = client.domains.list
+result.data     # the parsed response, or nil
+result.error    # a SendClipper::ErrorResponse, or nil
+result.headers  # response headers (lower-case names), or nil when no answer arrived
+result.ok?      # error.nil?
+
+domains = client.domains.list.unwrap # data, or raises SendClipper::ApiError
+
+case client.emails.send(**params)
+in { error: nil, data: }    then puts data["id"]
+in { error: { name: "rate_limited" } } then retry_later
+in { error: }               then warn error.message
+end
+```
+
+`ErrorResponse` has `name` (SendClipper's code: `validation_failed`, `rate_limited`, `network_error`, ...), `message` (a sentence for a person), `status_code` (`nil` when no answer arrived) and `detail` (code-specific facts).
+
+The iterators (`emails.each` and friends) raise a `SendClipper::ApiError` instead, since a loop has no `error` to hand back. `e.code` is the API's code and `e.status` the HTTP status.
+
+## Retries and idempotency
+
+Network errors, `429` and `5xx` answers are retried twice with backoff, honouring `Retry-After`. Every JSON write carries an `Idempotency-Key`, and the API answers a repeated key with the first result for 24 hours. A retried send therefore never goes out twice.
+
+To make your own retries safe as well (a job that runs again after a crash), pass a key that names the logical operation:
+
+```ruby
+client.emails.send(**params, idempotency_key: "order-#{order.id}-receipt")
+```
+
+## Request options
+
+Every method takes request options as keyword arguments alongside its fields:
+
+```ruby
+client.emails.list(status: "bounced", timeout: 5, headers: { "X-Trace-Id" => trace_id })
+```
+
+| Option | Meaning |
+|---|---|
+| `idempotency_key:` | Your own key for a write |
+| `timeout:` | Per-attempt timeout in seconds (default 30) |
+| `max_retries:` | Retries for this call (default 2) |
+| `headers:` | Extra request headers |
+
+Client options: `SendClipper::Client.new(key, base_url:, timeout:, max_retries:, default_headers:, transport:)`. `base_url` also reads `SENDCLIPPER_BASE_URL`. `transport:` replaces the Net::HTTP sender: anything that responds to `call(SendClipper::TransportRequest)` and returns a `SendClipper::TransportResponse`.
+
+## Iterate
+
+Lists that span pages have an `each` method; without a block it returns a lazy Enumerator:
+
+```ruby
+client.emails.each(status: "bounced") { |email| puts email["to"] }
+first_ten = client.suppressions.each.first(10)
+```
+
+## Verify webhooks
+
+SendClipper signs each delivery. Verify it against the **raw** body, before parsing:
+
+```ruby
+class SendClipperWebhooksController < ActionController::API
+  def create
+    event = SendClipper.verify_webhook(
+      request.raw_post, # the raw body, not params
+      request.headers,
+      ENV.fetch("SENDCLIPPER_WEBHOOK_SECRET")
+    )
+    # event["id"] is stable across retries: deduplicate on it
+    Rails.logger.info("#{event["event"]} #{event["data"]["to"]}")
+    head :ok
+  rescue SendClipper::WebhookVerificationError => e
+    render plain: e.reason, status: :bad_request
+  end
+end
+```
+
+In Rack or Sinatra pass `request.body.read` and `request.env`. During a secret rotation a delivery carries two signatures and either one is accepted. A delivery signed more than five minutes away from now is refused. `client.webhooks.verify(...)` is the same function.
+
+To test your handler locally, `SendClipper.webhook_signature_header(secret, raw_body)` builds a valid header.
+
+## Sandboxes
+
+A sandbox traps mail while you develop: nothing is delivered.
+
+```ruby
+box = client.sandboxes.create(name: "my-app-dev").unwrap
+creds = client.sandboxes.credentials(box["id"]).unwrap # SMTP host, port, username, password
+
+# Or send through the sandbox's JSON door with its own token, using the same fields as emails.send:
+token = client.sandboxes.reset_credentials(box["id"]).unwrap
+client.sandboxes.send(token["apiToken"], from: "app@example.com", to: "test@example.com", subject: "Hi", html: "<p>Hi</p>")
+
+# In a test: wait for the message to arrive
+msg, error = client.sandboxes.messages.wait_for(box["id"]) { |m| m["subject"] == "Hi" }
+```
+
+## Everything else
+
+| Resource | Methods |
+|---|---|
+| `emails` | `send`, `get`, `list`, `each`, `stats` |
+| `batch` | `send` |
+| `domains` | `list`, `create`, `records`, `verify`, `enable_receiving`, `disable_receiving`, `set_region`, `deletion_preview`, `remove` |
+| `templates` | `list`, `get`, `html`, `create`, `update`, `remove`, `duplicate`, `publish`, `unpublish`, `preview`, `set_tags`, `projects` |
+| `templates.tags` | `list`, `create`, `update`, `remove` |
+| `templates.assets` | `list`, `upload` |
+| `sandboxes` | `list`, `get`, `create`, `update`, `remove`, `credentials`, `reset_credentials`, `send` |
+| `sandboxes.messages` | `list`, `get`, `raw`, `remove`, `clear`, `mark_all_read`, `wait_for` |
+| `webhooks` | `list`, `create`, `update`, `remove`, `rotate_secret`, `deliveries`, `verify` |
+| `webhooks.dispatches` | `list`, `each`, `get`, `replay`, `replay_all` |
+| `contacts` | `list`, `each`, `create`, `import`, `import_preview`, `export` |
+| `audiences` | `list` |
+| `suppressions` | `list`, `each`, `create`, `remove`, `export` |
+| `mailboxes` | `list`, `get`, `create`, `update`, `archive` |
+| `mailboxes.messages` | `list`, `each`, `get`, `attachment` |
+| `automations` | `enroll` |
+| `workspace` | `get` |
+| `api_keys` | `list` |
+
+`contacts.import` takes the file's contents (`File.read("contacts.csv")`) and `templates.assets.upload` the image's bytes (`File.binread("logo.png")`). Management routes need a key with **Full access**. A sending-only key can call `emails.send` and `batch.send`.
+
+Full API reference: <https://sendclipper.com/docs>.
+
+## License
+
+MIT

data/lib/sendclipper/client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SendClipper
+  # The SendClipper API client.
+  #
+  #   client = SendClipper::Client.new("sc_live_...") # or Client.new: reads SENDCLIPPER_API_KEY
+  #   data, error = client.emails.send(from: "hello@acme.io", to: "ada@lumen.io", subject: "Hi", html: "<p>Hi</p>")
+  class Client
+    attr_reader :emails, :batch, :domains, :templates, :sandboxes, :webhooks, :contacts,
+                :audiences, :suppressions, :mailboxes, :automations, :workspace, :api_keys
+
+    # +api_key+ defaults to SENDCLIPPER_API_KEY. +base_url:+ defaults to
+    # SENDCLIPPER_BASE_URL, then https://sendclipper.com (no /v1). +timeout:+ is
+    # per attempt, in seconds. +max_retries:+ is how often a network error, a
+    # 429 or a 5xx is retried; a write is only retried with an
+    # Idempotency-Key, which the SDK adds to every JSON write, so a retried
+    # send can never go out twice. +transport:+ replaces the Net::HTTP sender.
+    def initialize(api_key = nil, base_url: nil, timeout: 30, max_retries: 2, default_headers: {}, transport: nil, sleeper: nil)
+      @http = HttpClient.new(api_key: api_key, base_url: base_url, timeout: timeout, max_retries: max_retries,
+                             default_headers: default_headers, transport: transport, sleeper: sleeper)
+      @emails = Resources::Emails.new(@http)
+      @batch = Resources::Batch.new(@http)
+      @domains = Resources::Domains.new(@http)
+      @templates = Resources::Templates.new(@http)
+      @sandboxes = Resources::Sandboxes.new(@http)
+      @webhooks = Resources::Webhooks.new(@http)
+      @contacts = Resources::Contacts.new(@http)
+      @audiences = Resources::Audiences.new(@http)
+      @suppressions = Resources::Suppressions.new(@http)
+      @mailboxes = Resources::Mailboxes.new(@http)
+      @automations = Resources::Automations.new(@http)
+      @workspace = Resources::Workspace.new(@http)
+      @api_keys = Resources::ApiKeys.new(@http)
+    end
+
+    # The API origin requests go to, without /v1.
+    def base_url = @http.base_url
+
+    def inspect = "#<SendClipper::Client base_url=#{base_url.inspect}>"
+  end
+end

data/lib/sendclipper/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SendClipper
+  # Base class for everything this SDK raises on purpose.
+  class Error < StandardError; end
+
+  # The API answered with a non-2xx status. +code+ is the API's own
+  # machine-readable reason (+domain_not_verified+, +template_variables_missing+,
+  # +rate_limited+, ...) and is the field to branch on; the message is a
+  # sentence meant for a person.
+  class ApiError < Error
+    attr_reader :status, :code, :detail, :headers
+
+    def initialize(status, code, message, detail = nil, headers = {})
+      super(message)
+      @status = status
+      @code = code
+      @detail = detail
+      @headers = headers || {}
+    end
+
+    # The API answers refusals in two shapes: the house envelope
+    # { error: { code, message, detail? } } and Nest's default
+    # { statusCode, message: string | string[], error } (request validation).
+    def self.from_response(status, text, headers = {})
+      parsed = begin
+        JSON.parse(text)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+      obj = parsed.is_a?(Hash) ? parsed : {}
+
+      env = obj["error"]
+      return from_envelope(status, env, headers) if env.is_a?(Hash)
+
+      msg = obj["message"]
+      return from_envelope(status, msg["error"], headers) if msg.is_a?(Hash) && msg["error"].is_a?(Hash)
+      return new(status, "validation_failed", msg.map(&:to_s).join("; "), msg, headers) if msg.is_a?(Array)
+      return new(status, code_for_status(status), msg, nil, headers) if msg.is_a?(String)
+
+      snippet = text.to_s.strip[0, 300]
+      new(status, code_for_status(status), snippet.empty? ? "HTTP #{status}" : snippet, nil, headers)
+    end
+
+    def self.from_envelope(status, env, headers)
+      code = env["code"].to_s
+      message = env["message"].to_s
+      detail = env.key?("detail") ? env["detail"] : env["details"]
+      new(status, code.empty? ? code_for_status(status) : code, message.empty? ? "HTTP #{status}" : message, detail, headers)
+    end
+
+    def self.code_for_status(status)
+      {
+        400 => "bad_request", 401 => "unauthorized", 403 => "forbidden", 404 => "not_found",
+        409 => "conflict", 413 => "payload_too_large", 429 => "rate_limited"
+      }.fetch(status, "http_#{status}")
+    end
+    private_class_method :from_envelope
+  end
+
+  # The request never got an answer: DNS, TLS, a reset socket or the timeout.
+  class ConnectionError < Error; end
+
+  # SendClipper.verify_webhook refused a delivery. +reason+ says which check
+  # failed: +missing_header+, +malformed_header+, +timestamp_out_of_tolerance+,
+  # +signature_mismatch+ or +invalid_payload+.
+  class WebhookVerificationError < Error
+    attr_reader :reason
+
+    def initialize(reason, message)
+      super(message)
+      @reason = reason
+    end
+  end
+end

data/lib/sendclipper/http_client.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+module SendClipper
+  # One request as a transport receives it. +timeout+ is in seconds.
+  TransportRequest = Struct.new(:method, :url, :headers, :body, :timeout, keyword_init: true)
+
+  # One response as a transport returns it. Header names are lower-case.
+  TransportResponse = Struct.new(:status, :headers, :body, keyword_init: true)
+
+  # Raised by a transport when no answer arrived. +timed_out+ marks a timeout.
+  class TransportError < StandardError
+    attr_reader :timed_out
+
+    def initialize(message, timed_out: false)
+      super(message)
+      @timed_out = timed_out
+    end
+  end
+
+  # The default transport: Net::HTTP from the standard library. Redirects
+  # are not followed. Anything that responds to +call(TransportRequest)+ and
+  # returns a TransportResponse can replace it.
+  class NetHttpTransport
+    def call(req)
+      uri = URI(req.url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = [req.timeout, 10].min
+      http.read_timeout = req.timeout
+      http.write_timeout = req.timeout
+      klass = Net::HTTP.const_get(req.method.capitalize)
+      request = klass.new(uri.request_uri)
+      req.headers.each { |k, v| request[k] = v }
+      request.body = req.body if req.body
+      response = http.request(request)
+      headers = {}
+      response.each_header { |k, v| headers[k.downcase] = v }
+      TransportResponse.new(status: response.code.to_i, headers: headers, body: response.body.to_s)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      raise TransportError.new(e.message, timed_out: true)
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, EOFError, Net::ProtocolError => e
+      raise TransportError, "#{e.class}: #{e.message}"
+    end
+  end
+
+  # @api private Reach the API through SendClipper::Client's resources.
+  class HttpClient
+    DEFAULT_BASE_URL = "https://sendclipper.com"
+    RETRYABLE_STATUS = [408, 429, 500, 502, 503, 504].freeze
+    MAX_RETRY_AFTER = 60.0
+    OPTION_KEYS = %i[idempotency_key timeout max_retries headers].freeze
+
+    attr_reader :base_url
+
+    def initialize(api_key: nil, base_url: nil, timeout: 30, max_retries: 2, default_headers: {}, transport: nil, sleeper: nil)
+      @api_key = api_key || ENV["SENDCLIPPER_API_KEY"]
+      @api_key = nil if @api_key == ""
+      raw = base_url || ENV.fetch("SENDCLIPPER_BASE_URL", nil)
+      raw = DEFAULT_BASE_URL if raw.nil? || raw.empty?
+      @base_url = raw.sub(%r{/+\z}, "").sub(%r{/v1\z}, "")
+      @timeout = timeout.to_f
+      @max_retries = [max_retries.to_i, 0].max
+      @default_headers = default_headers.to_h.transform_keys(&:to_s)
+      @transport = transport || NetHttpTransport.new
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) if seconds.positive? }
+    end
+
+    # The public face of every API method: never raises for an API refusal
+    # or a network failure, it answers a Result.
+    def call(method, path, query: nil, body: nil, form: nil, as: :json, bearer: nil, options: {})
+      data, headers = request(method, path, query: query, body: body, form: form, as: as, bearer: bearer, options: options)
+      Result.new(data, nil, headers)
+    rescue ApiError => e
+      Result.new(nil, ErrorResponse.new(name: e.code, message: e.message, status_code: e.status, detail: e.detail),
+                 e.headers.empty? ? nil : e.headers)
+    rescue ConnectionError => e
+      Result.new(nil, ErrorResponse.new(name: "network_error", message: e.message, status_code: nil), nil)
+    end
+
+    # Like #call, but raises SendClipper::ApiError / SendClipper::ConnectionError.
+    def request(method, path, query: nil, body: nil, form: nil, as: :json, bearer: nil, options: {})
+      unknown = options.keys - OPTION_KEYS
+      raise ArgumentError, "Unknown request option #{unknown.first.inspect}. Allowed: #{OPTION_KEYS.join(", ")}." if unknown.any?
+
+      token = bearer || @api_key
+      if token.nil? || token.empty?
+        raise ApiError.new(401, "api_key_missing",
+                           'No SendClipper API key. Pass one to SendClipper::Client.new("sc_live_...") or set SENDCLIPPER_API_KEY.')
+      end
+
+      url = "#{@base_url}/v1#{path.start_with?("/") ? path : "/#{path}"}"
+      pairs = (query || {}).filter_map do |k, v|
+        next if v.nil? || v == ""
+
+        # true/false are written the way the API reads them.
+        "#{escape(k.to_s)}=#{escape(v.to_s)}"
+      end
+      url += "?#{pairs.join("&")}" unless pairs.empty?
+
+      headers = {
+        "Authorization" => "Bearer #{token}",
+        "Accept" => as == :json ? "application/json" : "*/*",
+        "User-Agent" => "sendclipper-ruby/#{VERSION}"
+      }.merge(@default_headers).merge((options[:headers] || {}).transform_keys(&:to_s))
+
+      payload = nil
+      if form
+        payload, headers["Content-Type"] = form
+      elsif !body.nil?
+        headers["Content-Type"] = "application/json"
+        payload = JSON.generate(body.empty? ? {} : body)
+      end
+
+      read = %w[GET HEAD].include?(method)
+      key = options[:idempotency_key]
+      # The API de-duplicates every JSON mutation on this header for 24 hours.
+      # A multipart body is not fingerprinted server-side, so it gets no key
+      # and is never retried.
+      if !read && form.nil?
+        headers["Idempotency-Key"] = key.to_s.empty? ? "sc-ruby-#{SecureRandom.uuid}" : key.to_s
+      elsif !key.to_s.empty?
+        headers["Idempotency-Key"] = key.to_s
+      end
+      retries = read || headers.key?("Idempotency-Key") ? [(options[:max_retries] || @max_retries).to_i, 0].max : 0
+      timeout = (options[:timeout] || @timeout).to_f
+
+      attempt = 0
+      loop do
+        begin
+          res = @transport.call(TransportRequest.new(method: method, url: url, headers: headers, body: payload, timeout: timeout))
+        rescue TransportError => e
+          if attempt < retries
+            @sleeper.call(self.class.backoff(attempt))
+            attempt += 1
+            next
+          end
+          message = if e.timed_out
+                      "SendClipper did not answer within #{format_seconds(timeout)} s (#{method} #{URI(url).path})."
+                    else
+                      "Could not reach SendClipper at #{@base_url}: #{e.message}"
+                    end
+          raise ConnectionError, message
+        end
+
+        res_headers = (res.headers || {}).transform_keys { |k| k.to_s.downcase }
+        ok = res.status >= 200 && res.status < 300
+
+        if !ok && RETRYABLE_STATUS.include?(res.status) && attempt < retries
+          @sleeper.call(retry_after(res_headers) || self.class.backoff(attempt))
+          attempt += 1
+          next
+        end
+
+        unless ok
+          err = ApiError.from_response(res.status, res.body.to_s, res_headers)
+          # Our own earlier attempt is still running server-side (a timeout
+          # that was not a failure). Its result is replayed once it finishes.
+          if err.code == "idempotency_key_in_flight" && attempt < retries
+            @sleeper.call(retry_after(res_headers) || self.class.backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise err
+        end
+
+        return [parse(res, res_headers, as), res_headers]
+      end
+    end
+
+    def self.backoff(attempt)
+      base = [8.0, 0.5 * (2**attempt)].min
+      (base / 2) + (rand * (base / 2))
+    end
+
+    # +multipart/form-data+: fields are [name, value], files [name, filename, type, bytes].
+    def self.multipart(fields, files)
+      boundary = "----sendclipper#{SecureRandom.hex(12)}"
+      q = ->(s) { s.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"').tr("\r\n", "  ") }
+      out = +"".b
+      fields.each do |name, value|
+        out << "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{q.call(name)}\"\r\n\r\n".b << value.to_s.b << "\r\n".b
+      end
+      files.each do |name, filename, type, bytes|
+        out << "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{q.call(name)}\"; filename=\"#{q.call(filename)}\"\r\n".b
+        out << "Content-Type: #{type}\r\n\r\n".b << bytes.to_s.b << "\r\n".b
+      end
+      out << "--#{boundary}--\r\n".b
+      [out, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    # Percent-encode one path segment.
+    def self.seg(value) = escape(value.to_s)
+
+    def self.escape(s) = s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
+
+    private
+
+    def escape(s) = self.class.escape(s)
+
+    def parse(res, headers, as)
+      body = res.body.to_s
+      case as
+      when :bytes
+        DownloadedFile.new(content: body.b, content_type: headers["content-type"], filename: filename_of(headers["content-disposition"]))
+      when :text
+        text(body, headers)
+      else
+        return nil if body.strip.empty?
+
+        begin
+          JSON.parse(text(body, headers))
+        rescue JSON::ParserError
+          text(body, headers)
+        end
+      end
+    end
+
+    def text(body, headers)
+      charset = headers["content-type"].to_s[/charset=([\w-]+)/i, 1] || "UTF-8"
+      body.dup.force_encoding(charset).encode("UTF-8", invalid: :replace, undef: :replace)
+    rescue ArgumentError, Encoding::ConverterNotFoundError
+      body.dup.force_encoding("UTF-8").scrub
+    end
+
+    def retry_after(headers)
+      raw = headers["retry-after"]
+      return nil if raw.nil? || raw.empty?
+
+      if raw.match?(/\A\d+(\.\d+)?\z/)
+        [raw.to_f, MAX_RETRY_AFTER].min
+      else
+        at = Time.httpdate(raw)
+        [[at - Time.now, 0.0].max, MAX_RETRY_AFTER].min
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    def filename_of(disposition)
+      return nil if disposition.nil? || disposition.empty?
+
+      if (m = disposition.match(/filename\*\s*=\s*(?:UTF-8'')?([^;]+)/i))
+        decoded = m[1].strip.delete('"').gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }.force_encoding("UTF-8")
+        return decoded if decoded.valid_encoding?
+      end
+      m = disposition.match(/filename\s*=\s*"?([^";]+)"?/i)
+      m && m[1].strip
+    end
+
+    def format_seconds(s) = s == s.to_i ? s.to_i.to_s : s.to_s
+  end
+end