api2convert 10.2.1 → 10.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39056074d7f58decce593b6b8baae8d93bf51f1b5e8bc28d4f803febccedd74a
-  data.tar.gz: 268f0497c655e8cbe40aef88b56642b803f7def33d6dbf06495979977d94967e
+  metadata.gz: ab0c201184fae5e154e8eb8dda08b1dd523f6721b8c0ea63882f36b0d08d69a8
+  data.tar.gz: 51d41801caf9b731b48b2f988b2f76605638b455b90a337c4ce6ce2acbfda4d6
 SHA512:
-  metadata.gz: 107965e469189bae258af1ec97409a89db7a0b1b898295a1322b0701d0c49e2544850ca439caa3459d46637eff51e1b4cc926f5d21dfdea5aa8235596a353242
-  data.tar.gz: 446402026e834fcb47a077a64db9f5cee4442e07056700b5770bfe98332c7560799228d25fb88a633f919c2fdb12965fba1423fd4b24a2e208476ad8ad8d258a
+  metadata.gz: e1a07542793b7fe4f016907ba28b6e25bc6d887bf0549714b3233350994f561534604a79f1488df8c69efc7cd40f76340a73486938fa5c82fb9424a8f63417d6
+  data.tar.gz: bd3a8cdc13f9d5092a54f91d7e6ef3caa5e7627b2bee607e8203afda5a7991d5356749ce35da48afcd0ae8420e3e43cf6b52f359b37bdfc6feba030111fefb24

data/AGENTS.md

@@ -63,7 +63,7 @@ junior-friendly surface — one-call `convert` — and use AI to keep it current
   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.
+- **Upload uses the per-job `X-Api2convert-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

data/README.md

@@ -1,5 +1,10 @@
 # API2Convert Ruby SDK
 
+[![CI](https://github.com/QaamGo/api2convert-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/QaamGo/api2convert-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/api2convert)](https://rubygems.org/gems/api2convert)
+![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.1-red)
+![License](https://img.shields.io/badge/license-MIT-green)
+
 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.

data/docs/SDK_CONTRACT.md

@@ -10,27 +10,40 @@ Two layers make up an SDK:
   (`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.
+  fixed**: change them only when this document changes. Adding a new **optional** parameter or
+  options-bag field that preserves every existing call site and behavior is an additive **minor**;
+  changing or removing an existing parameter, return type, or documented semantic is a **major**.
 
 > 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.
+- Base URL `https://api.api2convert.com/v2`. Auth header `X-Api2convert-Api-Key: <key>` on account requests (canonical `X-Api2convert-*` names; the legacy `X-Oc-*` headers remain accepted by the API as permanent aliases).
 - **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.
+  `file`, authenticated with the per-job **`X-Api2convert-Token`** header — never the account key.
 - **Add remote input**: `POST /jobs/{id}/input` `{ type:'remote', source:'https://…' }`.
+- **Cloud input** (import from customer storage): `POST /jobs/{id}/input` (or inline in `create`)
+  `{ type:'cloud', source:<provider>, parameters:{…}, credentials:{…} }`, `<provider> ∈ {amazons3,
+  azure, ftp, googlecloud}`; plus `{ type:'gdrive_picker', source:<drive-file-id>,
+  credentials:{token}, content_type? }` for Google Drive. The API validates a cloud descriptor
+  **asynchronously** — it accepts any descriptor on create (`201`) and later fails a bad one on the
+  input (`status:failed`, generic `code 99`); it never echoes a credential value.
+- **Cloud output** (deliver to customer storage): a `conversion[]` may carry
+  `output_target:[{ type:<provider>, parameters:{…}, credentials:{…} }]`, `<provider> ∈ {amazons3,
+  googlecloud, azure, ftp, youtube, gdrive}`. `status` (`waiting|uploading|completed|failed`) is
+  server-set and read-only — never sent on create. The job reaches `completed` only after the upload
+  succeeds (a failed upload → `failed`); an output-target conversion produces **no** local output.
 - **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.
+- **Download**: `GET output.uri` — self-contained, no auth; `X-Api2convert-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 }`.
@@ -64,7 +77,7 @@ Two layers make up an SDK:
 - `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
+  `X-Api2convert-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.
 
@@ -82,8 +95,39 @@ Two layers make up an SDK:
   missing/wrong signature. Empty secret skips verification.
 - `parse(rawBody) → WebhookEvent` — deserialize without verifying (pre-signed-webhooks).
 
+## Cloud storage connectors
+
+The API imports inputs from and delivers outputs to customer-owned cloud storage. The SDK models the
+wire descriptors above; per-provider keys are **not** validated synchronously server-side, so the
+typed surface is the client's only pre-flight structure.
+
+- **Provider vocabulary** — one shared `CloudProvider` concept (per-language spelling): `amazons3,
+  azure, ftp, gdrive, googlecloud, youtube`. It is **build-side vocabulary only** — read models keep
+  `source`/`type`/`status` as raw strings, and an unknown provider from the server round-trips
+  untyped (never throws).
+- **Cloud input** — a `CloudInput` builder emits `{ type:cloud, source, parameters, credentials }`
+  and hands off to `addInput` / the create path. It ships per-provider named constructors whose
+  signatures carry each provider's required keys **verbatim** (flat/lowercase, as the API expects):
+  `amazonS3(bucket, file, accesskeyid, secretaccesskey)`,
+  `azure(container, file, accountname, accountkey)`, `ftp(host, file, username, password)`,
+  `googleCloud(projectid, bucket, file, keyfile)`. The required keys are **constructor arguments**,
+  not a runtime gate — the builder never rejects a descriptor the permissive server would accept, and
+  a generic `parameters`/`credentials` map stays reachable for optional/forward-compat keys. Google
+  Drive input uses `type:gdrive_picker` (`source` = the Drive file id, token in `credentials.token`),
+  carried by the generic `addInput` raw-map path this wave (no typed builder yet). `gdrive` and
+  `youtube` are **output-only** — they validate as an input `source` but have no downloader.
+- **Cloud output** — an `OutputTarget` model (`type` = a `CloudProvider` + free-form
+  `parameters`/`credentials`) attaches to a conversion, both via `convert`/`convertAsync` (a new
+  optional `outputTargets` control, never merged into the options map) and the raw `jobs().create`
+  conversion map. It serializes `{ type, parameters, credentials }` and **omits `status`** on create.
+  Per-provider output factories are **not** in this wave (their keys live in a separate service and
+  diverge per provider). When any output target is set, `convert` returns the completed `Job` and
+  does **not** download — the conversion has no local output.
+- **Read semantics** — `parameters` and the per-target `status` round-trip on read; `credentials`
+  are **never** surfaced (the API returns them empty; the SDK does not hydrate them).
+
 ## Cross-cutting semantics
-- **Auth**: account key as `X-Oc-Api-Key`; uploads use the per-job token.
+- **Auth**: account key as `X-Api2convert-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`/
@@ -97,3 +141,10 @@ Two layers make up an SDK:
   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).
+- **Credential redaction**: cloud `credentials` travel in the request body — never derive error text
+  from the request body, and mask the **whole `credentials` object** to `[REDACTED]` wherever a value
+  object could surface it: object inspection (`toString`/`repr`/`Debug`/`inspect`), any SDK-emitted
+  request log, and the decoded error body (belt-and-suspenders — the API does not echo credential
+  values). Also mask any `parameters` leaf whose key contains a sensitive token (`token, password,
+  passwd, secret, key, keyfile, credential, passphrase, sas, sig, signature`, case-insensitive).
+  Credentials ride in the plaintext body — user-attached request logging must redact its own.

data/lib/api2convert/client.rb

@@ -57,9 +57,18 @@ module Api2Convert
     # remembered and applied automatically on download.
     #
     # @return [Result::ConversionResult]
+    # A {Model::CloudInput} imports the source straight from customer storage (a
+    # started job, like a remote URL). Pass +output_targets+ (a list of
+    # {Model::OutputTarget}) to deliver the output(s) to customer storage instead
+    # of producing a downloadable file — the job then completes with **no** local
+    # output and the returned result is not downloaded (calling `output`/`save`
+    # on it would have nothing to fetch). Output targets are attached to the
+    # conversion's `output_target` and never merged into +options+.
     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)
+                output_index: nil, filename: nil, download_password: nil,
+                output_targets: nil)
+      job = start_conversion(source, to, options, category, nil, filename,
+                             download_password, output_targets)
       done = @jobs.wait(job.id, timeout)
       Result::ConversionResult.new(done, @transport, output_index.nil? ? 0 : output_index, download_password)
     end
@@ -71,8 +80,9 @@ module Api2Convert
     #
     # @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)
+                      filename: nil, download_password: nil, output_targets: nil)
+      start_conversion(source, to, options, category, callback, filename,
+                       download_password, output_targets)
     end
 
     # A {Result::FileDownload} for an output file. A +download_password+ is
@@ -112,10 +122,16 @@ module Api2Convert
 
     private
 
-    def start_conversion(source, to, options, category, callback, filename, download_password)
+    def start_conversion(source, to, options, category, callback, filename,
+                         download_password, output_targets = nil)
       conversion = { "target" => to }
       conversion["category"] = category unless category.nil?
       conversion["options"] = options if !options.nil? && !options.empty?
+      # Cloud delivery targets attach to the conversion's `output_target` — never
+      # merged into the options map.
+      unless output_targets.nil? || output_targets.empty?
+        conversion["output_target"] = Array(output_targets).map(&:to_h)
+      end
 
       payload = { "conversion" => [conversion] }
       unless callback.nil?
@@ -124,6 +140,14 @@ module Api2Convert
       end
       payload["download_passwords"] = [download_password] unless download_password.nil?
 
+      # A cloud input imports from customer storage — a started job with the
+      # descriptor inline, exactly like a remote URL (never staged/uploaded).
+      if source.is_a?(Model::CloudInput)
+        payload["process"] = true
+        payload["input"] = [source.to_h]
+        return @jobs.create(payload)
+      end
+
       if source.is_a?(String) && source =~ URL_RE
         payload["process"] = true
         payload["input"] = [{ "type" => "remote", "source" => source }]

data/lib/api2convert/cloud_provider.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  # The cloud storage providers the API can import inputs from and deliver
+  # outputs to — the values of a cloud descriptor's `source` (input) / `type`
+  # (output) field.
+  #
+  # This is **build-side vocabulary only**: it types the input builder
+  # ({Model::CloudInput}) and output-target serialization ({Model::OutputTarget}).
+  # Read models keep `source`/`type`/`status` as raw strings, so an unknown
+  # provider string returned by the server round-trips untyped and never raises —
+  # there is deliberately no strict parse.
+  #
+  # Import support (a {Model::CloudInput} factory) exists for {AMAZON_S3},
+  # {AZURE}, {FTP} and {GOOGLE_CLOUD}. {GDRIVE} and {YOUTUBE} are **output-only**
+  # (they validate as an output `type` but have no downloader); Google Drive
+  # *input* uses the separate `gdrive_picker` input type.
+  module CloudProvider
+    AMAZON_S3 = "amazons3"
+    AZURE = "azure"
+    FTP = "ftp"
+    GDRIVE = "gdrive"
+    GOOGLE_CLOUD = "googlecloud"
+    YOUTUBE = "youtube"
+
+    # The full provider vocabulary, in canonical order.
+    ALL = [AMAZON_S3, AZURE, FTP, GDRIVE, GOOGLE_CLOUD, YOUTUBE].freeze
+  end
+end

data/lib/api2convert/http/net_http_sender.rb

@@ -13,7 +13,7 @@ module Api2Convert
     # `Net::HTTP` does not follow redirects on its own — this SDK relies on that.
     # A request only follows a 3xx when {Request#follow_redirects} is true (the
     # no-secret download path); a redirect is then re-issued as a bare GET carrying
-    # only `Accept`/`User-Agent`, so a custom `X-Oc-*` secret header can never be
+    # only `Accept`/`User-Agent`, so a custom `X-Api2convert-*` secret header can never be
     # forwarded to the redirect target.
     #
     # An {HttpSender} is any object responding to `call(request) -> Response`. Unit
@@ -23,6 +23,15 @@ module Api2Convert
       MAX_REDIRECTS = 5
       REDIRECT_CODES = [301, 302, 303, 307, 308].freeze
 
+      # Caps how much of a control-plane (API / error) JSON body the SDK buffers
+      # into memory, so a hostile or buggy server cannot force an unbounded read
+      # (OOM) on that path. Mirrors the shipped Go SDK's `maxResponseBytes = 16 <<
+      # 20` (transport.go), whose readAllAndClose reads through an
+      # io.LimitReader(rc, maxResponseBytes). File downloads are streamed straight
+      # to the sink (never buffered) and bounded separately, so this cap covers the
+      # buffered control-plane path only.
+      MAX_RESPONSE_BYTES = 16 * 1024 * 1024 # 16 MiB
+
       # Errors worth surfacing when they strike mid-stream (after bytes have
       # already reached the sink). They are re-raised as {NetworkError} so the
       # transport does NOT retry — replaying would re-stream the whole body and
@@ -83,13 +92,13 @@ module Api2Convert
               stream_body(res, sink)
               result = to_response(res, "")
             else
-              result = to_response(res, res.body || "")
+              result = to_response(res, read_capped_body(res))
             end
           end
         end
 
         if redirect_to
-          # Re-issue as a bare GET carrying only non-secret headers, so no X-Oc-*
+          # Re-issue as a bare GET carrying only non-secret headers, so no X-Api2convert-*
           # secret header is ever forwarded to the redirect target.
           safe = {}
           %w[Accept User-Agent].each { |k| safe[k] = headers[k] unless headers[k].nil? }
@@ -100,6 +109,25 @@ module Api2Convert
         result
       end
 
+      # Buffer a control-plane (API / error) response body into memory, bounded by
+      # {MAX_RESPONSE_BYTES}. Because `Net::HTTP` is used in block form the body is
+      # not read until this runs, so — unlike an SDK-side cap applied after a whole
+      # `res.body` — we accumulate chunk-by-chunk and abort the instant the total
+      # crosses the cap, before an over-cap body is ever fully resident. Mirrors the
+      # Go SDK's io.LimitReader-wrapped read. Only the cap is raised here; genuine
+      # transport errors propagate exactly as `res.body` would, so the retry loop
+      # still classifies them.
+      def read_capped_body(res)
+        buffer = +""
+        res.read_body do |chunk|
+          buffer << chunk
+          next unless buffer.bytesize > MAX_RESPONSE_BYTES
+
+          raise Api2Convert::NetworkError, "API response body exceeds 16 MiB"
+        end
+        buffer
+      end
+
       def stream_body(res, sink)
         res.read_body { |chunk| sink.write(chunk) }
       rescue *STREAM_ERRORS => e

data/lib/api2convert/http/request.rb

@@ -11,7 +11,7 @@ module Api2Convert
     class Request
       attr_reader :method, :url, :headers, :body, :body_stream, :content_length, :response_sink
       # Whether the sender may follow a 3xx redirect. Set by the transport per
-      # request: authenticated requests carry a secret in a custom `X-Oc-*` header,
+      # request: authenticated requests carry a secret in a custom `X-Api2convert-*` header,
       # so they must NOT follow redirects (the header could leak to another host).
       attr_accessor :follow_redirects
 
@@ -29,12 +29,14 @@ module Api2Convert
         @response_sink = response_sink
       end
 
-      # Redacted representation — {#headers} carries the raw `X-Oc-Api-Key` /
-      # `X-Oc-Download-Password` secrets, so the default `#inspect` would print
-      # them in cleartext in a log line or a backtrace. Mask every `X-Oc-*` value.
+      # Redacted representation — {#headers} carries the raw `X-Api2convert-Api-Key` /
+      # `X-Api2convert-Download-Password` secrets, so the default `#inspect` would print
+      # them in cleartext in a log line or a backtrace. Mask every `X-Api2convert-*` value
+      # (and the legacy `X-Oc-*` prefix, so a redaction gap can never open up).
       def inspect
         safe = @headers.to_h do |key, value|
-          [key, key.to_s.downcase.start_with?("x-oc-") ? Support::Secret.mask(value) : value]
+          secret = key.to_s.downcase.start_with?("x-api2convert-", "x-oc-")
+          [key, secret ? Support::Secret.mask(value) : value]
         end
         "#<#{self.class.name} method=#{@method.inspect} url=#{@url.inspect} headers=#{safe.inspect}>"
       end

data/lib/api2convert/http/transport.rb

@@ -61,7 +61,7 @@ module Api2Convert
 
       # Perform an authenticated JSON request and return the decoded body.
       def request(method, path, body = nil, query = nil, headers = nil)
-        request_headers = { "X-Oc-Api-Key" => @config.api_key }
+        request_headers = { "X-Api2convert-Api-Key" => @config.api_key }
         request_headers.merge!(headers) unless headers.nil?
         content = nil
         unless body.nil?
@@ -83,7 +83,7 @@ module Api2Convert
       # a non-seekable body so it is sent once.
       #
       # +follow_redirects+ defaults to false: authenticated requests carry a secret
-      # in a custom `X-Oc-*` header, which a redirect could leak to another host.
+      # in a custom `X-Api2convert-*` header, which a redirect could leak to another host.
       # Only the self-contained download path (no account key) opts in.
       def send_request(build, replayable: true, follow_redirects: false)
         attempt = 0
@@ -125,6 +125,15 @@ module Api2Convert
       def interpret(response)
         ensure_successful(response)
 
+        # Every API request rides the no-follow path (secrets travel in X-Api2convert-* headers), so a 3xx
+        # passes ensure_successful (status < 400) but was deliberately not followed; decoding its
+        # body would yield an empty model. Surface it as a typed error instead.
+        status = response.status
+        if status >= 300 && status < 400
+          raise NetworkError, "API2Convert returned an unexpected redirect (HTTP #{status}); " \
+                              "the request was not followed."
+        end
+
         raw = response.body
         return {} if raw.nil? || raw.empty?
 
@@ -143,7 +152,13 @@ module Api2Convert
         status = response.status
         return if status < 400
 
-        body = decode_safe(response)
+        # Belt-and-suspenders: deep-redact the decoded error body before it lands
+        # on the exception. Cloud credentials ride in the plaintext request body;
+        # the API only ever echoes field *names* (never a value), but a future
+        # server/proxy change must not be able to surface a secret through
+        # `error.body`. The `message` is server-provided text, never derived from
+        # the request body.
+        body = Support::Redactor.redact_body(decode_safe(response))
         api_message = body["message"]
         message = api_message.is_a?(String) ? api_message : fallback_message(response)
         request_id = response.header("x-request-id")

data/lib/api2convert/model/cloud_input.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A cloud-storage input descriptor:
+    # `{ type:"cloud", source:<provider>, parameters, credentials }`.
+    #
+    # Hand it to `client.convert` / `convert_async` as the input, or to
+    # `client.jobs.add_input(job_id, cloud_input)`; either way it emits the wire
+    # descriptor via {#to_h}. Like a remote URL, a cloud input is a **started**
+    # job (`process => true`), not a staged upload.
+    #
+    # The per-provider factories carry each provider's required keys **verbatim**
+    # — flat and lowercase, exactly as the API expects (`accesskeyid`, not
+    # `access_key_id`). The required keys are constructor arguments (structural
+    # correctness), **not** a runtime gate: the builder never rejects a descriptor
+    # the permissive, asynchronously-validating server would accept. Optional and
+    # forward-compat keys go through the trailing +parameters+ / +credentials+
+    # maps, or the generic {.of} escape hatch.
+    #
+    # Google Drive *input* uses the `gdrive_picker` input type (the generic
+    # `add_input` raw-map path this wave); `gdrive`/`youtube` are output-only.
+    #
+    # `credentials` ride in the plaintext body, so {#inspect} masks the **whole**
+    # credentials object to `[REDACTED]` and any sensitive `parameters` leaf.
+    class CloudInput
+      attr_reader :source, :parameters, :credentials
+
+      # +source+ is the provider string; +parameters+ are non-secret locator keys
+      # (`bucket`, `file`, `host`, …); +credentials+ are secret keys.
+      def initialize(source:, parameters: {}, credentials: {})
+        @source = source
+        @parameters = parameters
+        @credentials = credentials
+        freeze
+      end
+
+      # Generic escape hatch: any provider (a {CloudProvider} constant or a
+      # forward-compat string) with free-form maps.
+      def self.of(source, parameters: {}, credentials: {})
+        new(source: source.to_s, parameters: parameters, credentials: credentials)
+      end
+
+      # Import from Amazon S3. Extra/forward-compat keys merge into
+      # +parameters+ / +credentials+.
+      def self.amazon_s3(bucket:, file:, accesskeyid:, secretaccesskey:,
+                         parameters: {}, credentials: {})
+        new(
+          source: CloudProvider::AMAZON_S3,
+          parameters: { "bucket" => bucket, "file" => file }.merge(parameters),
+          credentials: { "accesskeyid" => accesskeyid, "secretaccesskey" => secretaccesskey }
+            .merge(credentials)
+        )
+      end
+
+      # Import from Azure Blob Storage.
+      def self.azure(container:, file:, accountname:, accountkey:,
+                     parameters: {}, credentials: {})
+        new(
+          source: CloudProvider::AZURE,
+          parameters: { "container" => container, "file" => file }.merge(parameters),
+          credentials: { "accountname" => accountname, "accountkey" => accountkey }.merge(credentials)
+        )
+      end
+
+      # Import from an FTP server.
+      def self.ftp(host:, file:, username:, password:, parameters: {}, credentials: {})
+        new(
+          source: CloudProvider::FTP,
+          parameters: { "host" => host, "file" => file }.merge(parameters),
+          credentials: { "username" => username, "password" => password }.merge(credentials)
+        )
+      end
+
+      # Import from Google Cloud Storage.
+      def self.google_cloud(projectid:, bucket:, file:, keyfile:, parameters: {}, credentials: {})
+        new(
+          source: CloudProvider::GOOGLE_CLOUD,
+          parameters: { "projectid" => projectid, "bucket" => bucket, "file" => file }.merge(parameters),
+          credentials: { "keyfile" => keyfile }.merge(credentials)
+        )
+      end
+
+      # The wire descriptor sent to `POST /jobs` (inline `input`) or
+      # `POST /jobs/{id}/input`.
+      def to_h
+        {
+          "type" => InputType::CLOUD,
+          "source" => @source,
+          "parameters" => @parameters,
+          "credentials" => @credentials
+        }
+      end
+
+      # Redacted representation — the whole `credentials` object renders as
+      # `[REDACTED]`; sensitive `parameters` leaves are masked too. Safe to log.
+      def inspect
+        "#<#{self.class.name} type=cloud source=#{@source.inspect} " \
+          "parameters=#{Support::Redactor.parameters(@parameters).inspect} " \
+          "credentials=#{Support::Redactor::MARKER}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/api2convert/model/conversion.rb

@@ -4,14 +4,17 @@ module Api2Convert
   module Model
     # A single conversion within a job: the target format plus its options.
     class Conversion
-      attr_reader :target, :id, :category, :options, :metadata
+      attr_reader :target, :id, :category, :options, :metadata, :output_targets
 
-      def initialize(target: "", id: nil, category: nil, options: {}, metadata: {})
+      def initialize(target: "", id: nil, category: nil, options: {}, metadata: {},
+                     output_targets: [])
         @target = target
         @id = id
         @category = category
         @options = options
         @metadata = metadata
+        # Cloud delivery targets for this conversion's output, if any.
+        @output_targets = output_targets
         freeze
       end
 
@@ -22,7 +25,8 @@ module Api2Convert
           id: Support::Data.nullable_str(d["id"]),
           category: Support::Data.nullable_str(d["category"]),
           options: Support::Data.as_object(d["options"]),
-          metadata: Support::Data.as_object(d["metadata"])
+          metadata: Support::Data.as_object(d["metadata"]),
+          output_targets: Support::Data.map_objects(d["output_target"]) { |x| OutputTarget.from_hash(x) }
         )
       end
     end

data/lib/api2convert/model/input_file.rb

@@ -4,10 +4,11 @@ module Api2Convert
   module Model
     # An input file attached to a job.
     class InputFile
-      attr_reader :id, :type, :source, :status, :filename, :size, :content_type, :options
+      attr_reader :id, :type, :source, :status, :filename, :size, :content_type, :options,
+                  :parameters
 
       def initialize(id: nil, type: "", source: nil, status: nil, filename: nil,
-                     size: nil, content_type: nil, options: {})
+                     size: nil, content_type: nil, options: {}, parameters: {})
         @id = id
         @type = type
         @source = source
@@ -16,6 +17,9 @@ module Api2Convert
         @size = size
         @content_type = content_type
         @options = options
+        # Cloud-input locator keys (`bucket`, `file`, `host`, …); empty for
+        # non-cloud inputs. Credentials are never surfaced on read.
+        @parameters = parameters
         freeze
       end
 
@@ -29,7 +33,8 @@ module Api2Convert
           filename: Support::Data.nullable_str(d["filename"]),
           size: Support::Data.nullable_int(d["size"]),
           content_type: Support::Data.nullable_str(d["content_type"]),
-          options: Support::Data.as_object(d["options"])
+          options: Support::Data.as_object(d["options"]),
+          parameters: Support::Data.as_object(d["parameters"])
         )
       end
     end

data/lib/api2convert/model/output_target.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A cloud-storage delivery target for a conversion's output:
+    # `{ type:<provider>, parameters, credentials }`.
+    #
+    # Attach one (or more) to a conversion via
+    # `client.convert(..., output_targets: [...])` / `convert_async(...)`, or
+    # inline in a raw `jobs.create` conversion map. When any output target is set
+    # the conversion delivers straight to your storage and produces **no** local
+    # output — so `convert` returns the completed job without downloading.
+    #
+    # This wave ships the **generic** shape only (`type` + free-form
+    # `parameters`/`credentials`); the per-provider output keys live in a separate
+    # service and diverge per provider, so there are no per-provider output
+    # factories yet.
+    #
+    # Serialization ({#to_h}) emits `{ type, parameters, credentials }` and
+    # **omits `status`** (server-set, read-only). On read ({.from_hash}) `type`,
+    # `parameters` and `status` round-trip as raw values; `credentials` are
+    # **never** surfaced (the API returns them empty). `credentials` ride in the
+    # plaintext body, so {#inspect} masks the whole object to `[REDACTED]`.
+    class OutputTarget
+      attr_reader :type, :parameters, :credentials, :status
+
+      # +status+ is server-set on read (`waiting|uploading|completed|failed`) and
+      # never sent on create.
+      def initialize(type:, parameters: {}, credentials: {}, status: nil)
+        @type = type
+        @parameters = parameters
+        @credentials = credentials
+        @status = status
+        freeze
+      end
+
+      # Generic constructor accepting a {CloudProvider} constant or a
+      # forward-compat string.
+      def self.of(type, parameters: {}, credentials: {})
+        new(type: type.to_s, parameters: parameters, credentials: credentials)
+      end
+
+      # The wire descriptor sent on create — `{ type, parameters, credentials }`,
+      # with `status` omitted (server-set, read-only).
+      def to_h
+        {
+          "type" => @type,
+          "parameters" => @parameters,
+          "credentials" => @credentials
+        }
+      end
+
+      # Hydrate from a `GET /jobs/{id}` `output_target[]` element. `type`/`status`
+      # stay raw strings (an unknown provider round-trips untyped); `credentials`
+      # are deliberately not surfaced.
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          type: Support::Data.as_str(d["type"]),
+          parameters: Support::Data.as_object(d["parameters"]),
+          credentials: {},
+          status: Support::Data.nullable_str(d["status"])
+        )
+      end
+
+      # Redacted representation — credentials masked. Safe to log.
+      def inspect
+        "#<#{self.class.name} type=#{@type.inspect} " \
+          "parameters=#{Support::Redactor.parameters(@parameters).inspect} " \
+          "credentials=#{Support::Redactor::MARKER} status=#{@status.inspect}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/api2convert/resource/jobs.rb

@@ -52,10 +52,14 @@ module Api2Convert
       end
 
       # Attach an input by descriptor, e.g. a remote URL:
-      # `add_input(job_id, { "type" => "remote", "source" => "https://..." })`.
+      # `add_input(job_id, { "type" => "remote", "source" => "https://..." })`,
+      # a Google Drive picker
+      # (`{ "type" => "gdrive_picker", "source" => file_id, "credentials" => { "token" => ... } }`),
+      # or a {Model::CloudInput} builder.
       def add_input(job_id, descriptor)
+        payload = descriptor.is_a?(Model::CloudInput) ? descriptor.to_h : descriptor
         Model::InputFile.from_hash(
-          @transport.request("POST", "/jobs/#{Support::Data.encode_segment(job_id)}/input", descriptor)
+          @transport.request("POST", "/jobs/#{Support::Data.encode_segment(job_id)}/input", payload)
         )
       end