api2convert 10.2.1 → 10.3.1

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)

data/lib/api2convert/support/data.rb

@@ -36,10 +36,17 @@ module Api2Convert
         end
         if value.is_a?(String)
           begin
-            return Float(value).to_i
+            parsed = Float(value)
           rescue ArgumentError, TypeError
             return nil
           end
+          # A numeric string that overflows Float to +/-Infinity (e.g. "1e400")
+          # must fall back to nil, not raise: Float::INFINITY.to_i / NAN.to_i throw
+          # FloatDomainError, and this helper must NEVER raise on a hostile payload
+          # (mirrors the Float branch's finite? guard above).
+          return nil unless parsed.finite?
+
+          return parsed.to_i
         end
         nil
       end

data/lib/api2convert/support/redactor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Support
+    # Credential redaction for cloud connectors.
+    #
+    # Cloud `credentials` ride in the plaintext request body, so they must never
+    # surface where a value object or an SDK-emitted string could leak them. This
+    # helper centralizes the masks the contract mandates:
+    #
+    # - the **whole `credentials` object** collapses to {MARKER} on every
+    #   object-inspection path (`#inspect` / `#to_s`);
+    # - any `parameters` leaf whose key contains a sensitive token
+    #   ({SENSITIVE_SUBSTRINGS}, case-insensitive substring) collapses to {MARKER};
+    # - the decoded error body is deep-walked ({redact_body}) as belt-and-
+    #   suspenders — the API only ever echoes field *names*, never a credential
+    #   *value*, but a future server/proxy change must not be able to leak one.
+    #
+    # Internal helper, not part of the public API.
+    module Redactor
+      module_function
+
+      # The fixed, fleet-wide redaction marker (D9).
+      MARKER = "[REDACTED]"
+
+      # Case-insensitive substrings that mark a key as carrying a secret. A key
+      # containing any of these has its whole value masked.
+      SENSITIVE_SUBSTRINGS = %w[
+        token password passwd secret key keyfile
+        credential passphrase sas sig signature
+      ].freeze
+
+      # Precompiled union: a key is sensitive iff it *contains* any substring
+      # above. Equivalent to `SENSITIVE_SUBSTRINGS.any? { |s| key.include?(s) }`
+      # but written as a regex so Style/ArrayIntersect can't rewrite the
+      # String#include? substring test into Array#intersect? (which would need an
+      # array argument and change the semantics).
+      SENSITIVE_PATTERN = Regexp.union(SENSITIVE_SUBSTRINGS).freeze
+
+      # Whether a key name marks its value as sensitive (case-insensitive
+      # substring match). Accepts String or Symbol keys.
+      def sensitive_key?(key)
+        SENSITIVE_PATTERN.match?(key.to_s.downcase)
+      end
+
+      # Mask sensitive leaves of a `parameters` map: any key matching
+      # {sensitive_key?} has its value replaced by {MARKER}; nested Hashes are
+      # walked recursively. Non-secret keys (`bucket`, `host`, `file`,
+      # `container`, `projectid`, …) are left untouched.
+      def parameters(params)
+        return params unless params.is_a?(Hash)
+
+        params.each_with_object({}) do |(key, value), out|
+          out[key] =
+            if sensitive_key?(key)
+              MARKER
+            elsif value.is_a?(Hash)
+              parameters(value)
+            else
+              value
+            end
+        end
+      end
+
+      # Deep-walk a decoded error body and mask the value of every sensitive key
+      # (including a flattened/dotted key like
+      # `input.0.credentials.secretaccesskey`) to {MARKER}. Nested Hashes and
+      # Arrays are walked; scalars pass through.
+      def redact_body(body)
+        case body
+        when Hash
+          body.each_with_object({}) do |(key, value), out|
+            out[key] = sensitive_key?(key) ? MARKER : redact_body(value)
+          end
+        when Array
+          body.map { |value| redact_body(value) }
+        else
+          body
+        end
+      end
+    end
+  end
+end

data/lib/api2convert/upload/file_uploader.rb

@@ -10,7 +10,7 @@ module Api2Convert
     # This step is intentionally hand-written — it is NOT described by the OpenAPI
     # spec. It posts a `multipart/form-data` body (field `file`) to
     # `{job.server}/upload-file/{job.id}` and authenticates with the per-job
-    # `X-Oc-Token` header — never the account API key. The body is streamed, so
+    # `X-Api2convert-Token` header — never the account API key. The body is streamed, so
     # large files are not read into memory. Internal.
     class FileUploader
       def initialize(transport)
@@ -39,7 +39,7 @@ module Api2Convert
           @transport.build_request(
             "POST", url,
             headers: {
-              "X-Oc-Token" => token,
+              "X-Api2convert-Token" => token,
               "Content-Type" => "multipart/form-data; boundary=#{boundary}"
             },
             body_stream: body_stream,

data/lib/api2convert/version.rb

@@ -4,5 +4,5 @@ module Api2Convert
   # The SDK version. Kept in lock-step with the sibling SDKs (PHP, Python, Java,
   # Node.js): all official ports implement the same `docs/SDK_CONTRACT.md` and
   # version together.
-  VERSION = "10.2.1"
+  VERSION = "10.3.1"
 end

data/lib/api2convert.rb

@@ -21,10 +21,14 @@ require_relative "api2convert/errors"
 require_relative "api2convert/config"
 require_relative "api2convert/support/data"
 require_relative "api2convert/support/secret"
+require_relative "api2convert/support/redactor"
 require_relative "api2convert/job_status"
 require_relative "api2convert/input_type"
+require_relative "api2convert/cloud_provider"
 
 require_relative "api2convert/model/status"
+require_relative "api2convert/model/output_target"
+require_relative "api2convert/model/cloud_input"
 require_relative "api2convert/model/conversion"
 require_relative "api2convert/model/input_file"
 require_relative "api2convert/model/output_file"