api2convert 10.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3d6b5c540037362377c06e4096518c623017c17882b39233f932f73f0b70d14
+  data.tar.gz: 37b28638fbef0fd35e3eff63abb8557fd27c4400a4c4e63bab170dbf86d0fd8e
+SHA512:
+  metadata.gz: 83f600ae36bd429c61df404004a744b2cb51dad8aedab4c739c79ed83b8c95d77542c5162d0c356a84cb7515d369457f6264c92c1d03c898a84c74768148444c
+  data.tar.gz: 63031c428a7bb3ea8e976ac2861c38dc27b83585ab41c0927ad24660a3c1d9a2aee10724b6b9b743ea947019e026f941ab84272fefb472b88a0fbd5710c3a4e0

data/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS — maintaining the API2Convert Ruby SDK
+
+This SDK is **hand-written** (not generated from OpenAPI) and kept in sync with the API by a human
+**or an AI agent**. This file is the playbook. The model: a committed spec snapshot is the diff
+baseline, a fixed behavior contract protects the ergonomics, and the RSpec suite is the guardrail.
+
+It is one of five official ports (PHP, Python, Java, Node.js, Ruby) that all implement the same
+language-agnostic contract in [`docs/SDK_CONTRACT.md`](docs/SDK_CONTRACT.md).
+
+## Why hand-written
+
+The conversion flow is multi-step (create → upload → poll → download) and the **upload step is not in
+the OpenAPI spec at all**, so a generator cannot produce a usable client. We optimise for a
+junior-friendly surface — one-call `convert` — and use AI to keep it current.
+
+## Repo layout
+
+| Path                                     | What it is                                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------------------- |
+| `lib/api2convert/client.rb`              | The client + the `convert` / `convert_async` façade. **Hand-authored.**          |
+| `lib/api2convert/result.rb`              | `ConversionResult` + `FileDownload` helpers. **Hand-authored.**                  |
+| `lib/api2convert/upload/*`               | Streamed multipart upload to the per-job server. **Hand-authored** (not in spec).|
+| `lib/api2convert/webhook/*`              | Webhook HMAC verification + parsing. **Hand-authored.**                          |
+| `lib/api2convert/resource/*`             | One class per API tag (Jobs, Conversions, Presets, Stats, Contracts). **Derived.**|
+| `lib/api2convert/model/*`, `*_status.rb` | Value objects (`from_hash` factories) / enum modules. **Derived** from the spec. |
+| `lib/api2convert/http/*`                 | Transport: auth, retries/backoff, error mapping, redirect policy, the sender seam.|
+| `lib/api2convert/errors.rb`              | The typed exception hierarchy.                                                   |
+| `openapi/api2convert.openapi.json`       | **Committed spec snapshot** the SDK targets — the diff baseline (md5-identical to siblings). |
+| `docs/SDK_CONTRACT.md`                   | The fixed, language-agnostic public surface + semantics (md5-identical to siblings). |
+| `spec/unit/*`                            | Offline golden specs (`FakeHttpSender`). **The guardrail.**                      |
+| `spec/security/*`                        | The independent security suite (real loopback servers). **The redirect/leak guardrail.** |
+| `spec/live/*`                            | Live conformance (auto-skips without `API2CONVERT_API_KEY`).                     |
+
+## How to update the SDK to a new API version
+
+1. **Refresh the snapshot.** Overwrite `openapi/api2convert.openapi.json` from
+   `https://api.api2convert.com/v2/openapi.json` (or `/v2/schema`) and `git diff` it.
+2. **Diff it** — new/removed/renamed operations, new fields, new enum values.
+3. **Update the DERIVED layer to match the diff, and nothing else:**
+   - New/changed fields → update the relevant `model/*` class + its `from_hash`.
+   - New operation → add a method on the matching `resource/*` class (mirror the existing style).
+   - New input/output target types → extend `job_status.rb` / `input_type.rb`.
+4. **Do NOT change the hand-authored public API** (`convert`, `convert_async`, `download`, upload,
+   `wait`, webhook verification, error classes) unless `docs/SDK_CONTRACT.md` changes first. If a
+   real product change requires it, update the contract in the same change and bump the **major**
+   version.
+5. **Lint + test (the guardrail):**
+   ```console
+   bundle exec rake check   # rubocop + unit specs + security suite — all must pass
+   ```
+   Add or update a golden spec for any new behavior. Keep the live conformance spec runnable.
+6. **Record + version.** Add a `docs/CHANGELOG.md` entry and bump `Api2Convert::VERSION` per SemVer
+   (additive spec change → minor; breaking public-surface change → major). The five SDKs version
+   together against the shared contract.
+
+## Guarantees to uphold (don't break these)
+
+- **Never commit a real API key, token or secret** — not in source, specs, fixtures, examples, CI
+  files or commit messages. Keys come only from environment variables (`API2CONVERT_API_KEY`) or
+  masked/protected CI variables; specs use obvious fakes (`test-key`, `secret-key`, `whsec_test`).
+  The behat test keys live only in the `behat-api` repo's `behat.yml.dist_*` — supply one via the
+  env var when running `rake spec:live`, never paste it here. The SDK must never log or expose a
+  key/token in errors. Secret-scan before any release.
+- **The contract is law.** Public method names, signatures and semantics match `docs/SDK_CONTRACT.md`
+  across every SDK language. Adapt only to Ruby idiom (see divergences below).
+- **Upload uses the per-job `X-Oc-Token`, never the account key.** There is a spec for this.
+- **Secret-bearing requests never follow redirects.** The key/token/download-password ride in custom
+  `X-Oc-*` headers. `Net::HTTP` does not follow redirects by default — the SDK relies on that and
+  only opts the no-secret download path into following redirects. `spec/security` proves the
+  guarantee with real loopback servers.
+- **`convert` stays one call** for the common case (path/URL/IO → `to` → `save`).
+- **Transient failures retry; failures surface as typed exceptions.** Never leak a raw
+  `Net::HTTP`/socket error (wrap it in `NetworkError`). A non-idempotent `POST` is never blindly
+  retried.
+- **Ruby 3.1+, zero runtime dependencies, standard library only.** Don't add runtime deps.
+
+## Ruby-idiom divergences from the contract
+
+The contract fixes names and semantics; these are the _only_ places Ruby deviates, all for idiom:
+
+- **The client is `Api2Convert::Client`** (a module namespace can't be instantiated); the module-level
+  `Api2Convert.webhooks` mirrors the contract's client-less webhook verifier.
+- **Method and option names are `snake_case`** (`convert_async`, `add_input`, `download_password`,
+  `poll_interval`).
+- **The "extra" `convert` controls are Ruby keyword args** (`category:`, `timeout:`, `output_index:`,
+  `filename:`, `download_password:`), kept separate from the open-ended positional `options` Hash so
+  API option keys can never collide with SDK keys.
+- **Exceptions are named `...Error`** and extend `StandardError`; the poll timeout is
+  `ConversionTimeoutError` (not shadowing `Timeout::Error`).
+- **`Job` exposes predicates** `completed?` / `failed?` / `canceled?` / `terminal?` and keeps `raw`.
+- **Models are frozen value objects with `from_hash` factories**, hydrated defensively via
+  `Support::Data` (tolerate missing/extra fields — never raise on a surprising payload).
+- **The HTTP sender is a seam**: `Client.new(..., http_sender:, sleeper:, rng:)` injects a fake for
+  unit specs; the default is `Http::NetHttpSender`.
+
+## Conventions
+
+- Resource methods are thin: build the request, call `Transport`, hydrate a model.
+- Keep the README quickstart copy-pasteable; if you change the happy path, update the README example.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qaamgo Media GmbH
+
+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,164 @@
+# API2Convert Ruby SDK
+
+Official Ruby SDK for the [API2Convert](https://www.api2convert.com) file-conversion API.
+Convert, compress and transform images, documents, audio, video, ebooks, archives and CAD —
+and run operations like OCR, merge, thumbnail and website capture — in one line of code.
+
+Zero runtime dependencies: built entirely on the Ruby standard library.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "api2convert"
+```
+
+```console
+$ bundle install
+# or
+$ gem install api2convert
+```
+
+Requires Ruby 3.1+.
+
+## Quick start
+
+```ruby
+require "api2convert"
+
+client = Api2Convert::Client.new("YOUR_API_KEY")
+
+# 1) From a local file
+client.convert("photo.png", "jpg").save("photo.jpg")
+
+# 2) From a URL
+client.convert("https://example.com/photo.png", "jpg").save("photo.jpg")
+
+# 3) With conversion options (discover them via client.options)
+client.convert("photo.png", "jpg", { "quality" => 85, "width" => 1280, "height" => 720 })
+      .save("out/")
+```
+
+The API key falls back to the `API2CONVERT_API_KEY` environment variable when you
+construct the client without one.
+
+## Working with the result
+
+```ruby
+result = client.convert("report.docx", "pdf")
+
+result.save("report.pdf")   # stream to a file path
+result.save("downloads/")   # ...or a directory (keeps the API filename)
+bytes = result.contents     # the raw bytes
+url   = result.url          # just the (self-contained) download URL
+```
+
+## Password-protected output
+
+```ruby
+result = client.convert("statement.docx", "pdf", download_password: "hunter2")
+result.save("statement.pdf")   # the password is remembered and applied automatically
+
+# Or when you hold an OutputFile from elsewhere:
+client.download(output, "hunter2").save("out/")
+```
+
+## Async + webhooks
+
+```ruby
+job = client.convert_async("movie.mov", "mp4",
+                           callback: "https://your-app.example.com/webhooks/api2convert")
+
+# In your webhook handler (Rack-style):
+payload   = request.body.read
+signature = request.get_header("HTTP_X_OC_SIGNATURE")
+
+begin
+  event = Api2Convert.webhooks.construct_event(payload, signature, "YOUR_WEBHOOK_SECRET")
+  job   = event.job
+  # react to job.status.code
+rescue Api2Convert::SignatureVerificationError
+  # reject the request (400)
+end
+```
+
+## Error handling
+
+```ruby
+begin
+  client.convert("photo.png", "jpg").save("photo.jpg")
+rescue Api2Convert::ValidationError    # bad target / option
+rescue Api2Convert::AuthenticationError # bad or missing API key
+rescue Api2Convert::RateLimitError => e # too many requests — retry after e.retry_after
+rescue Api2Convert::ConversionFailedError => e # the job failed — inspect e.errors
+end
+```
+
+Transient failures (429 / 5xx / network) are retried automatically with capped,
+jittered exponential backoff; a non-idempotent `POST` is never blindly replayed.
+
+## Power user: the full job API
+
+```ruby
+job = client.jobs.create(
+  "process"    => false,
+  "conversion" => [{ "target" => "pdf", "options" => { "pdf_a" => true } }]
+)
+
+client.jobs.upload(job, "contract.docx")                              # local file
+client.jobs.add_input(job.id, "type" => "remote",
+                              "source" => "https://example.com/appendix.docx") # or URL
+
+client.jobs.start(job.id)
+done = client.jobs.wait(job.id, 120)
+
+done.output.each { |output| client.download(output).save("out/") }
+```
+
+## Discover options
+
+```ruby
+client.options("jpg") # => { "quality" => {...}, "width" => {...}, ... }
+```
+
+## Configuration
+
+```ruby
+client = Api2Convert::Client.new(
+  "YOUR_API_KEY",
+  base_url:          "https://api.api2convert.com/v2", # custom API host
+  timeout:           30,   # per-request network timeout (seconds)
+  max_retries:       2,    # automatic retries for transient failures
+  poll_interval:     1.0,  # first poll interval (seconds)
+  poll_max_interval: 5.0,  # backoff cap (seconds)
+  poll_timeout:      300   # give up waiting after this many seconds
+)
+```
+
+## Development
+
+```console
+$ bundle install
+$ bundle exec rake spec           # offline unit suite
+$ bundle exec rake spec:security  # independent security suite (real loopback servers)
+$ bundle exec rake check          # rubocop + unit + security — the guardrail
+```
+
+Live conformance tests hit the real API and are skipped unless a key is present:
+
+```console
+$ API2CONVERT_API_KEY=<your key> bundle exec rake spec:live
+```
+
+If your machine's Ruby is older than the gem targets, run the guardrail on a
+supported Ruby with the bundled `Dockerfile`:
+
+```console
+$ docker build -t api2convert-ruby .
+$ docker run --rm api2convert-ruby                        # rake check on Ruby 3.x
+$ docker build --build-arg RUBY_VERSION=3.4 -t a2c:3.4 .  # pin a specific version
+```
+
+## License
+
+MIT © Qaamgo Media GmbH

data/docs/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to the API2Convert Ruby SDK are documented here. The five
+official SDKs (PHP, Python, Java, Node.js, Ruby) version together against the
+shared [`SDK_CONTRACT.md`](SDK_CONTRACT.md).
+
+## [Unreleased]
+
+- Initial development; not yet publicly released.

data/docs/SDK_CONTRACT.md

@@ -0,0 +1,99 @@
+# API2Convert SDK contract
+
+The **language-agnostic** behavior contract every official API2Convert SDK implements. It is the
+source of truth for the public surface and its semantics, and the spec that future ports
+(TypeScript, Python, …) follow so the SDKs stay equivalent.
+
+Two layers make up an SDK:
+
+- **Derived layer** — typed models and one method per API operation. Tracks the OpenAPI spec
+  (`openapi/api2convert.openapi.json`); an AI update may freely change it to match the spec.
+- **Hand-authored layer** — the ergonomics below (`convert`, upload, polling, download, webhook
+  verification). These flows are **not** in the spec. Their **public signatures and semantics are
+  fixed**: change them only when this document changes, and bump the major version when you do.
+
+> When the two disagree, this contract wins for the hand-authored layer; the spec wins for the
+> derived layer.
+
+## Protocol facts (the API the SDK speaks)
+
+- Base URL `https://api.api2convert.com/v2`. Auth header `X-Oc-Api-Key: <key>` on account requests.
+- **Create job** `POST /jobs` `{ conversion:[{category?,target,options?}], input?:[…], process:bool,
+  callback?, notify_status?, download_passwords?:[…] }` → response includes `id`, per-job `token`,
+  per-job upload `server`, and `status.code`. `download_passwords` protects every output of the job;
+  any password in the list then unlocks its downloads. The API never returns the plaintext back.
+- **Upload** (not in the spec): `POST {server}/upload-file/{job_id}`, `multipart/form-data` field
+  `file`, authenticated with the per-job **`X-Oc-Token`** header — never the account key.
+- **Add remote input**: `POST /jobs/{id}/input` `{ type:'remote', source:'https://…' }`.
+- **Start**: `PATCH /jobs/{id}` `{ process:true }`.
+- **Poll**: `GET /jobs/{id}` → terminal when `status.code ∈ {completed, failed, canceled}`
+  (`failed`/`canceled` are unsuccessful terminals; non-terminal: `created`, `incomplete`,
+  `downloading`, `queued`, `processing`, and any unknown code). Poll with backoff; clamp the
+  interval to a floor (never busy-loop) and the total wait to a ceiling (never poll unbounded).
+- **Download**: `GET output.uri` — self-contained, no auth; `X-Oc-Download-Password` header if set.
+- **Discover options**: `GET /conversions?category=&target=`.
+- **Errors**: HTTP body `{ "message": "…" }`; job-level `errors[]` / `warnings[]` of
+  `{ source, id_source, code, message, details }`.
+
+## Public surface (every SDK must provide)
+
+### Client
+- Construct with an API key (falling back to the `API2CONVERT_API_KEY` env var) and options
+  (`baseUrl`, `timeout`, `maxRetries`, `pollInterval`, `pollMaxInterval`, `pollTimeout`).
+- `convert(input, to, options?, {category?, timeout?, outputIndex?, filename?, downloadPassword?}) →
+  ConversionResult` — create → (upload | remote input) → start → **poll to completion** → return.
+  `to` is the target format string; `options` is the conversion-options map (passed 1:1 to the API's
+  conversion `options`); the remaining controls are optional named/keyword arguments (never mixed
+  into the options map, so open-ended API options can't collide with SDK keys). `input` is a local
+  path, a URL (`^https?://`), or a stream. A URL is sent as a single started job with a `remote`
+  input; anything else is staged, uploaded, then started. `downloadPassword`, when given, is sent as
+  the job's `download_passwords` and **remembered on the returned result** so its downloads apply it
+  automatically (see below).
+- `convertAsync(input, to, options?, {callback?, category?, filename?, downloadPassword?}) → Job` —
+  same, but returns once started without polling; sets `notify_status: true` when a `callback` is
+  given. `downloadPassword` sets the job's `download_passwords` (a later download must supply it,
+  since the returned `Job` is not a result wrapper).
+- `download(output, downloadPassword?) → FileDownload`.
+- `options(target, category?) → map` — discover the valid conversion options for a target
+  (category optional). Sugar for `conversions().options(target, category?)`.
+- Resource accessors: `jobs()`, `conversions()`, `presets()`, `stats()`, `contracts()`.
+- `webhooks()` — usable without a configured client (static/standalone).
+
+### ConversionResult / FileDownload
+- `save(pathOrDir, downloadPassword?) → path` — streams to disk; a directory keeps the API filename.
+- `contents(downloadPassword?) → binary`, `url() → string`, `output()`, `outputs()`.
+- **Download-password transparency**: a password supplied at conversion time (`convert(...,
+  downloadPassword)`) or to `download(output, downloadPassword)` is remembered and sent as the
+  `X-Oc-Download-Password` header on every download from that result/handle — callers do not
+  re-supply it. An explicit `downloadPassword` argument to `save()` / `contents()` overrides the
+  remembered one for that call.
+
+### Jobs resource
+- `create(payload, idempotencyKey?)`, `get(id)`, `list(status?, page?)`, `update(id, payload)`,
+  `start(id)`, `cancel(id)`, `addInput(id, input)`, `upload(job, file, filename?)`, `outputs(id)`.
+- `wait(id, timeoutSeconds?, throwOnFailure=true)` — poll with backoff until terminal; raise
+  `ConversionFailedException` on `failed`/`canceled` (unless disabled), `TimeoutException` past the
+  deadline. Interval is floored and the total wait is capped, so no configuration can busy-loop or
+  poll unbounded.
+
+### Webhooks
+- `constructEvent(rawBody, signature, secret) → WebhookEvent` — verify HMAC-SHA256 (matching the
+  server's signed-webhooks scheme) then deserialize; raise `SignatureVerificationException` on a
+  missing/wrong signature. Empty secret skips verification.
+- `parse(rawBody) → WebhookEvent` — deserialize without verifying (pre-signed-webhooks).
+
+## Cross-cutting semantics
+- **Auth**: account key as `X-Oc-Api-Key`; uploads use the per-job token.
+- **Retries**: automatically retry with capped, jittered exponential backoff, honoring `Retry-After`
+  (delay-seconds or HTTP-date form, clamped to a ceiling). `429` is retried for every method; `5xx`
+  and network errors are retried only for idempotent methods (`GET`/`HEAD`/`PUT`/`DELETE`/`OPTIONS`/
+  `TRACE`) or a request carrying an `Idempotency-Key`, so a bare non-idempotent `POST` is never
+  blindly re-sent (no duplicate jobs). Only replayable (seekable/empty) bodies are retried at all.
+  Surface the failure as a typed exception once retries are exhausted.
+- **Forward-compat headers**: send an `Idempotency-Key` on create when supplied; read `Retry-After`
+  / `RateLimit-*`; capture `X-Request-Id` onto exceptions. All degrade gracefully if absent today.
+- **Errors** map by status: 400/422 → validation, 401/403 → auth, 402 → payment, 404 → not-found,
+  429 → rate-limit (with `retryAfter`), 5xx → server, other 4xx → generic API error. A failed job →
+  conversion-failed (carrying the job and its `errors`).
+- **Naming**: method names and option keys are identical across languages, adapted only to each
+  language's idiom (camelCase / snake_case).

data/examples/convert.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Minimal synchronous conversion example.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/convert.rb path/to/photo.png jpg out.jpg
+#
+# Falls back to converting a public sample image when no source is given.
+
+require "api2convert"
+
+source = ARGV[0] || "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
+target = ARGV[1] || "png"
+destination = ARGV[2] || "output.#{target}"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+result = client.convert(source, target)
+path = result.save(destination)
+
+puts "Converted #{source} -> #{path} (#{File.size(path)} bytes)"

data/examples/webhook.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# A tiny Rack app that verifies API2Convert webhook callbacks.
+#
+#   API2CONVERT_WEBHOOK_SECRET=<your secret> rackup -Ilib examples/webhook.rb
+#
+# Point your job's `callback` URL at this endpoint (see convert_async). Until
+# signed webhooks are enabled for your account no signature is sent — leave the
+# secret empty to skip verification, or use Api2Convert.webhooks.parse.
+
+require "api2convert"
+require "rack"
+
+SECRET = ENV.fetch("API2CONVERT_WEBHOOK_SECRET", "")
+
+app = lambda do |env|
+  request = Rack::Request.new(env)
+  payload = request.body.read
+  signature = env["HTTP_X_OC_SIGNATURE"]
+
+  begin
+    event = Api2Convert.webhooks.construct_event(payload, signature, SECRET)
+    job = event.job
+    warn "job #{job.id} is now #{job.status.code}"
+    [200, { "content-type" => "text/plain" }, ["ok"]]
+  rescue Api2Convert::SignatureVerificationError => e
+    warn "rejected webhook: #{e.message}"
+    [400, { "content-type" => "text/plain" }, ["invalid signature"]]
+  end
+end
+
+run app

data/lib/api2convert/client.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # The API2Convert client — convert, compress and transform files with one call.
+  #
+  # {#convert} hides the multi-step job lifecycle (create -> upload -> start ->
+  # poll -> download). For full control, use {#jobs} and the other resources.
+  #
+  # Quick start:
+  #
+  #   client = Api2Convert::Client.new("YOUR_API_KEY")
+  #   client.convert("invoice.docx", "pdf").save("invoice.pdf")
+  class Client
+    # Matches a source that is a public URL (sent as a `remote` input) rather than
+    # a local path. Anchored and linear — ReDoS-safe against a pathological input.
+    URL_RE = %r{\Ahttps?://}i
+
+    # Build the client. +api_key+ falls back to the `API2CONVERT_API_KEY`
+    # environment variable when empty.
+    #
+    # Options: +base_url+, +timeout+, +max_retries+, +poll_interval+,
+    # +poll_max_interval+, +poll_timeout+. For testing, inject +http_sender+ (an
+    # object responding to `call(request)`), +sleeper+ (a proc) and +rng+ (a proc).
+    def initialize(api_key = "", base_url: nil, timeout: nil, max_retries: nil,
+                   poll_interval: nil, poll_max_interval: nil, poll_timeout: nil,
+                   http_sender: nil, sleeper: nil, rng: nil)
+      api_key = api_key.to_s
+      api_key = ENV["API2CONVERT_API_KEY"].to_s if api_key.empty?
+      if api_key.empty?
+        raise ArgumentError,
+              "No API key provided. Pass it to the constructor or set the " \
+              "API2CONVERT_API_KEY environment variable."
+      end
+
+      config = Config.create(
+        api_key,
+        base_url: base_url, timeout: timeout, max_retries: max_retries,
+        poll_interval: poll_interval, poll_max_interval: poll_max_interval,
+        poll_timeout: poll_timeout
+      )
+      sender = http_sender || Http::NetHttpSender.new(timeout: config.timeout)
+      @transport = Http::Transport.new(sender, config, sleeper: sleeper, rng: rng)
+
+      uploader = Upload::FileUploader.new(@transport)
+      @jobs = Resource::Jobs.new(@transport, uploader)
+      @conversions = Resource::Conversions.new(@transport)
+      @presets = Resource::Presets.new(@transport)
+      @stats = Resource::Stats.new(@transport)
+      @contracts = Resource::Contracts.new(@transport)
+    end
+
+    # Convert a file and wait for the result.
+    #
+    # Hand it a local path, a public URL, or an open IO, name the target format,
+    # and get back a result you can `save`. +options+ are the target-specific
+    # conversion options (discover them via {#options}). A +download_password+ is
+    # remembered and applied automatically on download.
+    #
+    # @return [Result::ConversionResult]
+    def convert(source, to, options = nil, category: nil, timeout: nil,
+                output_index: nil, filename: nil, download_password: nil)
+      job = start_conversion(source, to, options, category, nil, filename, download_password)
+      done = @jobs.wait(job.id, timeout)
+      Result::ConversionResult.new(done, @transport, output_index.nil? ? 0 : output_index, download_password)
+    end
+
+    # Start a conversion without waiting.
+    #
+    # Pass a +callback+ URL to be notified (sets `notify_status`), or poll later
+    # with `client.jobs.get(job.id)` / `client.jobs.wait(job.id)`.
+    #
+    # @return [Model::Job]
+    def convert_async(source, to, options = nil, callback: nil, category: nil,
+                      filename: nil, download_password: nil)
+      start_conversion(source, to, options, category, callback, filename, download_password)
+    end
+
+    # A {Result::FileDownload} for an output file. A +download_password+ is
+    # remembered and sent automatically on download (overridable per call).
+    def download(output, download_password = nil)
+      Result::FileDownload.new(@transport, output, download_password)
+    end
+
+    # Discover the valid options (type / enum / default / range) for a target.
+    def options(target, category = nil)
+      @conversions.options(target, category)
+    end
+
+    attr_reader :jobs, :conversions, :presets, :stats, :contracts
+
+    # Webhook verifier — usable without a configured client.
+    def self.webhooks
+      Webhook::Verifier.new
+    end
+
+    # No persistent connection is held (the transport opens per request), so this
+    # is a no-op provided for symmetry with the sibling SDKs.
+    def close
+      nil
+    end
+
+    # Redacted representation. The default `#inspect` would recurse into the
+    # transport and its config and dump the API key in cleartext, so it is
+    # overridden to surface only the (non-secret) base URL.
+    def inspect
+      "#<#{self.class.name} base_url=#{@transport.config.base_url.inspect}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    private
+
+    def start_conversion(source, to, options, category, callback, filename, download_password)
+      conversion = { "target" => to }
+      conversion["category"] = category unless category.nil?
+      conversion["options"] = options if !options.nil? && !options.empty?
+
+      payload = { "conversion" => [conversion] }
+      unless callback.nil?
+        payload["callback"] = callback
+        payload["notify_status"] = true
+      end
+      payload["download_passwords"] = [download_password] unless download_password.nil?
+
+      if source.is_a?(String) && source =~ URL_RE
+        payload["process"] = true
+        payload["input"] = [{ "type" => "remote", "source" => source }]
+        return @jobs.create(payload)
+      end
+
+      payload["process"] = false
+      created = @jobs.create(payload)
+      @jobs.upload(created, source, filename)
+      @jobs.start(created.id)
+    end
+  end
+end

data/lib/api2convert/config.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # Immutable client configuration.
+  #
+  # Build via {Config.create}, which clamps every knob so a caller value can
+  # neither busy-loop the poll (interval floor) nor poll unbounded (timeout
+  # ceiling).
+  class Config
+    # Default API base URL — includes the `/v2` path segment, no trailing slash.
+    DEFAULT_BASE_URL = "https://api.api2convert.com/v2"
+
+    # Hard floor for the job-poll interval (seconds); prevents a busy-spin self-DDOS.
+    MIN_POLL_INTERVAL = 0.5
+
+    # Hard ceiling for the total job-poll timeout (4 hours); bounds an unbounded poll.
+    MAX_POLL_TIMEOUT = 14_400
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries,
+                :poll_interval, :poll_max_interval, :poll_timeout
+
+    # The constructor does not clamp — use {create} (the single entry point the
+    # client uses) so a caller value can never busy-loop or poll unbounded.
+    def initialize(api_key:, base_url:, timeout:, max_retries:,
+                   poll_interval:, poll_max_interval:, poll_timeout:)
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @max_retries = max_retries
+      @poll_interval = poll_interval
+      @poll_max_interval = poll_max_interval
+      @poll_timeout = poll_timeout
+      freeze
+    end
+
+    def self.create(api_key, base_url: nil, timeout: nil, max_retries: nil,
+                    poll_interval: nil, poll_max_interval: nil, poll_timeout: nil)
+      interval = [MIN_POLL_INTERVAL, (poll_interval.nil? ? 1.0 : poll_interval).to_f].max
+      max_interval = [interval, (poll_max_interval.nil? ? 5.0 : poll_max_interval).to_f].max
+      timeout_value = (poll_timeout.nil? ? 300 : poll_timeout).to_i.clamp(0, MAX_POLL_TIMEOUT)
+
+      new(
+        api_key: api_key,
+        base_url: (base_url.nil? ? DEFAULT_BASE_URL : base_url).sub(%r{/+\z}, ""),
+        timeout: [1, (timeout.nil? ? 30 : timeout).to_i].max,
+        max_retries: [0, (max_retries.nil? ? 2 : max_retries).to_i].max,
+        poll_interval: interval,
+        poll_max_interval: max_interval,
+        poll_timeout: timeout_value
+      )
+    end
+
+    # Redacted representation — the API key is masked so it can never be printed
+    # in cleartext by `p config`, a logger, or an object dumped in a backtrace.
+    def inspect
+      "#<#{self.class.name} api_key=#{Support::Secret.mask(@api_key)} " \
+        "base_url=#{@base_url.inspect} timeout=#{@timeout} max_retries=#{@max_retries} " \
+        "poll_interval=#{@poll_interval} poll_max_interval=#{@poll_max_interval} " \
+        "poll_timeout=#{@poll_timeout}>"
+    end
+
+    def to_s
+      inspect
+    end
+  end
+end