api2convert 10.2.0 → 10.3.0

data/examples/webhooks.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Webhooks — start a conversion and be notified via a callback URL.
+#
+#   API2CONVERT_API_KEY=<your key> ruby -Ilib examples/webhooks.rb
+#
+# convert_async returns immediately with a started job; the API POSTs to your
+# callback when it finishes. See examples/webhook.rb for a receiver that verifies
+# the callback signature.
+
+require "api2convert"
+
+DOCX = "https://example-files.online-convert.com/document/docx/example.docx"
+
+client = Api2Convert::Client.new # reads API2CONVERT_API_KEY
+
+job = client.convert_async(
+  DOCX, "pdf",
+  callback: "https://your-app.example.com/api2convert/webhook",
+  category: "document"
+)
+
+puts "started job #{job.id} (#{job.status.code})"
+puts "the API will POST to the callback URL when it completes"

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
 

data/lib/api2convert/resource/stats.rb

@@ -4,7 +4,8 @@ module Api2Convert
   module Resource
     # API usage statistics. The response shape is free-form (returned as-is).
     #
-    # +filter+ is either an API key to scope to, or `"all"`.
+    # +filter+ is "single" (only the calling API key) or "all" (every key on the account, the default).
+    # The request is scoped by the X-Api2convert-Api-Key header, so never pass a key as +filter+.
     class Stats
       def initialize(transport)
         @transport = transport

data/lib/api2convert/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "tempfile"
 
 module Api2Convert
   module Result
@@ -24,11 +25,11 @@ module Api2Convert
       end
 
       # Stream the file to disk. +path_or_dir+ is a file path, or a directory (the
-      # API filename is used). The body is streamed straight to the file
-      # chunk-by-chunk (never buffered whole in memory), so an arbitrarily large
-      # output cannot exhaust memory. A mid-stream failure removes the partial file
-      # so a truncated download never masquerades as a complete result. Returns the
-      # path written to.
+      # API filename is used). The body is streamed chunk-by-chunk to a sibling temp
+      # file (never buffered whole in memory), then atomically renamed over the
+      # target only after a clean write+close — so an arbitrarily large output cannot
+      # exhaust memory and a mid-stream failure never truncates the target nor
+      # destroys a pre-existing complete file at that path. Returns the path written.
       def save(path_or_dir, download_password = nil)
         target = resolve_target(path_or_dir.to_s)
         parent = File.dirname(target)
@@ -48,7 +49,7 @@ module Api2Convert
       def contents(download_password = nil)
         password = resolve_password(download_password)
         # A passwordless download follows storage redirects; a password-protected
-        # one must not (the X-Oc-Download-Password header could leak on a redirect).
+        # one must not (the X-Api2convert-Download-Password header could leak on a redirect).
         @transport.download(@output.uri, headers(password), follow_redirects: password.nil?)
       end
 
@@ -65,30 +66,60 @@ module Api2Convert
       private
 
       def stream_to_file(target, password)
-        success = false
+        parent = File.dirname(target)
+        parent = "." if parent.empty?
+        # Stream to a sibling temp file and rename over the target only after a clean
+        # write+close. This never truncates the target up front and never destroys a
+        # pre-existing complete file on a mid-stream failure — a download either fully
+        # replaces the target or leaves it untouched.
+        temp = create_temp(parent, target)
+
+        committed = false
         begin
-          File.open(target, "wb") do |file|
-            @transport.download(
-              @output.uri, headers(password), follow_redirects: password.nil?, sink: file
-            )
-            success = true
-          end
-        rescue SystemCallError
-          raise Api2Convert::Error, "Could not open file for writing: #{target}"
+          @transport.download(
+            @output.uri, headers(password), follow_redirects: password.nil?, sink: temp
+          )
+          # Flush + close BEFORE the rename so a truncated-on-close write can never be
+          # committed as a complete file, and a close/flush fault surfaces here rather
+          # than being swallowed on the success path.
+          temp.close
+          File.rename(temp.path, target)
+          committed = true
+        rescue SystemCallError => e
+          # A network read failure mid-stream is already a (non-retryable) NetworkError
+          # raised by the sender, which is NOT a SystemCallError and so passes straight
+          # through; reaching this rescue means a write / flush / rename fault — a
+          # genuine filesystem error.
+          raise Api2Convert::Error, "Could not write file: #{target}: #{e.message}"
         ensure
-          # Any failure (open error, network break, a refused-redirect NetworkError,
-          # a mid-stream break) leaves a partial or empty file — remove it so a
-          # truncated download can never masquerade as a complete result.
-          FileUtils.rm_f(target) unless success
+          # On any failure (network break, refused-redirect NetworkError, write/close/
+          # rename fault) only the temp file is removed; the target is never touched
+          # unless the rename already committed a complete download.
+          unless committed
+            begin
+              temp.close unless temp.closed?
+            rescue SystemCallError
+              nil
+            end
+            FileUtils.rm_f(temp.path)
+          end
         end
       end
 
+      def create_temp(parent, target)
+        temp = Tempfile.create([".a2c-download-", ".part"], parent)
+        temp.binmode
+        temp
+      rescue SystemCallError
+        raise Api2Convert::Error, "Could not open file for writing: #{target}"
+      end
+
       def resolve_password(download_password)
         download_password.nil? ? @download_password : download_password
       end
 
       def headers(password)
-        password.nil? ? {} : { "X-Oc-Download-Password" => password }
+        password.nil? ? {} : { "X-Api2convert-Download-Password" => password }
       end
 
       def resolve_target(path_or_dir)