api2convert 10.2.0

data/lib/api2convert/result.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Api2Convert
+  module Result
+    # A downloadable output file.
+    #
+    # Returned by `client.download(output)` and used internally by
+    # {ConversionResult}. A password supplied at conversion time (or to
+    # `client.download(output, password)`) is remembered and sent automatically on
+    # every download; an explicit password argument to {#save}/{#contents}
+    # overrides the remembered one for that call.
+    class FileDownload
+      def initialize(transport, output, download_password = nil)
+        @transport = transport
+        @output = output
+        @download_password = download_password
+      end
+
+      # The self-contained download URL (no auth required).
+      def url
+        @output.uri
+      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.
+      def save(path_or_dir, download_password = nil)
+        target = resolve_target(path_or_dir.to_s)
+        parent = File.dirname(target)
+        parent = "." if parent.empty?
+        begin
+          FileUtils.mkdir_p(parent)
+        rescue SystemCallError
+          raise Api2Convert::Error, "Could not create directory: #{parent}"
+        end
+
+        stream_to_file(target, resolve_password(download_password))
+        target
+      end
+
+      # Download the file and return its contents. This buffers the whole body in
+      # memory by design — use {#save} for a large file to stream it to disk.
+      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).
+        @transport.download(@output.uri, headers(password), follow_redirects: password.nil?)
+      end
+
+      # Redacted representation — the remembered download password is masked.
+      def inspect
+        "#<#{self.class.name} url=#{@output.uri.inspect} " \
+          "download_password=#{Support::Secret.mask(@download_password)}>"
+      end
+
+      def to_s
+        inspect
+      end
+
+      private
+
+      def stream_to_file(target, password)
+        success = 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}"
+        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
+        end
+      end
+
+      def resolve_password(download_password)
+        download_password.nil? ? @download_password : download_password
+      end
+
+      def headers(password)
+        password.nil? ? {} : { "X-Oc-Download-Password" => password }
+      end
+
+      def resolve_target(path_or_dir)
+        looks_like_dir = File.directory?(path_or_dir) ||
+                         path_or_dir.end_with?("/") ||
+                         path_or_dir.end_with?(File::SEPARATOR)
+        if looks_like_dir
+          name = safe_name(@output.filename) || safe_name(@output.id) || "output"
+          return File.join(path_or_dir.sub(%r{[/\\]+\z}, ""), name)
+        end
+        path_or_dir
+      end
+
+      # Reduce an API-supplied name to a bare filename safe to append to a dir.
+      # `output.filename` / `output.id` come straight from the API JSON, so a value
+      # like `../../etc/cron.d/evil` (or one with separators or a NUL byte) must
+      # never escape the caller's chosen directory. Returns nil when nothing usable
+      # remains, so the caller can fall back.
+      def safe_name(name)
+        return nil if name.nil?
+
+        base = File.basename(name.delete("\x00").tr("\\", "/")).strip
+        # Reject a name that reduces to nothing usable. Note Ruby's File.basename("/")
+        # is "/" (unlike POSIX basename -> ""), so a pure-separator name must be
+        # caught here too, matching the sibling SDKs' fallback behavior.
+        return nil if base == "." || base == ".." || base.delete("/").empty?
+
+        base
+      end
+    end
+
+    # The result of a completed conversion.
+    #
+    # The common case is one output: `result.save("out.pdf")`. Jobs that produce
+    # several files expose them via {#outputs} and {#download}.
+    class ConversionResult
+      # @return [Model::Job] the completed job.
+      attr_reader :job
+
+      def initialize(job, transport, index = 0, download_password = nil)
+        @job = job
+        @transport = transport
+        @index = index
+        @download_password = download_password
+      end
+
+      # The selected output file (the first one by default).
+      def output
+        # Any index not present — including a negative one — raises rather than
+        # wrapping around.
+        if @index.negative? || @index >= @job.output.length
+          raise Api2Convert::Error, "The job produced no output files."
+        end
+
+        @job.output[@index]
+      end
+
+      # All output files produced by the job.
+      def outputs
+        @job.output
+      end
+
+      # The download URL of the selected output (self-contained, no auth).
+      def url
+        output.uri
+      end
+
+      # Download the selected output to disk. Returns the path written to.
+      def save(path_or_dir, download_password = nil)
+        download.save(path_or_dir, download_password)
+      end
+
+      # Download the selected output and return its contents.
+      def contents(download_password = nil)
+        download.contents(download_password)
+      end
+
+      # A {FileDownload} for a specific output (defaults to the selected one).
+      def download(output_file = nil)
+        FileDownload.new(@transport, output_file.nil? ? output : output_file, @download_password)
+      end
+
+      # Redacted representation — the remembered download password is masked.
+      def inspect
+        "#<#{self.class.name} job=#{@job.id.inspect} outputs=#{@job.output.length} " \
+          "download_password=#{Support::Secret.mask(@download_password)}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/api2convert/support/data.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Support
+    # Typed, null-safe accessors over decoded JSON.
+    #
+    # Mirrors the PHP SDK's `Support\Data` helper: model hydration stays free of
+    # scattered casts and, crucially, **never raises** on a surprising payload — a
+    # missing or wrong-typed field falls back to a sensible default. Internal
+    # helper, not part of the public API.
+    module Data
+      module_function
+
+      # Return +value+ when it is a real String, else +default+. Does not
+      # stringify ints/floats/bools — only genuine strings pass through.
+      def as_str(value, default = "")
+        value.is_a?(String) ? value : default
+      end
+
+      def nullable_str(value)
+        value.is_a?(String) ? value : nil
+      end
+
+      # Coerce numeric values to Integer (truncating toward zero), else nil.
+      #
+      # +true+/+false+ are rejected (they must not become 1/0). Numeric strings
+      # and floats are truncated ("3.9" -> 3), matching PHP's (int) cast.
+      def nullable_int(value)
+        return nil if [true, false].include?(value)
+        return value if value.is_a?(Integer)
+
+        if value.is_a?(Float)
+          return nil unless value.finite?
+
+          return value.to_i
+        end
+        if value.is_a?(String)
+          begin
+            return Float(value).to_i
+          rescue ArgumentError, TypeError
+            return nil
+          end
+        end
+        nil
+      end
+
+      def as_bool(value, default = false)
+        [true, false].include?(value) ? value : default
+      end
+
+      # Return +value+ when it is a Hash (a JSON object), else an empty Hash.
+      def as_object(value)
+        value.is_a?(Hash) ? value : {}
+      end
+
+      # Return a list of values: an Array passes through; a Hash is reduced to its
+      # values (mirrors PHP `array_values`); anything else yields [].
+      def as_list(value)
+        return value if value.is_a?(Array)
+        return value.values if value.is_a?(Hash)
+
+        []
+      end
+
+      # Build a model from each Hash element of +value+; skip non-Hash elements.
+      def map_objects(value)
+        as_list(value).each_with_object([]) do |item, acc|
+          acc << yield(item) if item.is_a?(Hash)
+        end
+      end
+
+      def str_list(value)
+        as_list(value).grep(String)
+      end
+
+      # Percent-encode a value for use as a single URL path segment.
+      #
+      # A job/preset id or a stats date/filter is interpolated into the request
+      # path; a value carrying `/`, `?`, `#`, a space or any other reserved
+      # character (e.g. `all/../contracts`) must be encoded so it can never break
+      # out of its segment or forge a different path. Only the RFC 3986 unreserved
+      # set survives; everything else becomes `%XX` over the UTF-8 bytes (mirrors
+      # Node's `encodeURIComponent` / Go's `url.PathEscape`).
+      def encode_segment(value)
+        value.to_s.b.gsub(/[^A-Za-z0-9\-_.~]/n) { |byte| format("%%%02X", byte.ord) }
+      end
+    end
+  end
+end

data/lib/api2convert/support/secret.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Support
+    # Redaction helpers for `#inspect` / `#to_s`.
+    #
+    # Without these, `p client`, a `config.inspect` in a log line, or an object
+    # dumped in a backtrace would print `@api_key` / `@download_password` in
+    # cleartext. Every object that holds a secret overrides `#inspect` to route the
+    # secret through {mask}. Internal helper, not part of the public API.
+    module Secret
+      module_function
+
+      # Mask a secret for display. A `nil` renders as `nil`; a sufficiently long
+      # value keeps only its last 4 characters (so it stays recognizable in a log)
+      # with the rest hidden; a short value collapses to `[FILTERED]`.
+      def mask(value)
+        return "nil" if value.nil?
+
+        str = value.to_s
+        return "[FILTERED]" if str.length < 8
+
+        "[FILTERED:...#{str[-4..-1]}]"
+      end
+    end
+  end
+end

data/lib/api2convert/upload/file_uploader.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "securerandom"
+
+module Api2Convert
+  module Upload
+    # Uploads a local file to a job's per-job upload server.
+    #
+    # 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
+    # large files are not read into memory. Internal.
+    class FileUploader
+      def initialize(transport)
+        @transport = transport
+      end
+
+      # @param job [Model::Job] a staged job (created with `process: false`).
+      # @param file [String, Pathname, IO] a path, or an IO/StringIO of bytes.
+      # @return [Model::InputFile]
+      def upload(job, file, filename = nil)
+        if job.server.nil? || job.server.empty? || job.token.nil?
+          raise Api2Convert::Error,
+                "Cannot upload: the job has no upload server/token. " \
+                "Create the job with process=false and upload before starting it."
+        end
+
+        io, resolved_name, opened = resolve(file, filename)
+        seekable = io.respond_to?(:rewind)
+        url = "#{job.server.sub(%r{/+\z}, "")}/upload-file/#{job.id}"
+        token = job.token
+        boundary = "----Api2Convert#{SecureRandom.hex(16)}"
+
+        build = lambda do
+          io.rewind if seekable
+          body_stream, length = MultipartStream.build(boundary, "file", resolved_name, io)
+          @transport.build_request(
+            "POST", url,
+            headers: {
+              "X-Oc-Token" => token,
+              "Content-Type" => "multipart/form-data; boundary=#{boundary}"
+            },
+            body_stream: body_stream,
+            content_length: length
+          )
+        end
+
+        begin
+          response = @transport.send_request(build, replayable: seekable)
+          Model::InputFile.from_hash(@transport.interpret(response))
+        ensure
+          opened&.close
+        end
+      end
+
+      private
+
+      # Returns `[io, filename, opened]` where +opened+ is the handle to close
+      # afterwards (nil when the caller owns the IO). A path/Pathname is opened in
+      # binary mode; any other IO without a known byte size is buffered so the
+      # multipart Content-Length can be computed.
+      def resolve(file, filename)
+        if file.is_a?(String) || file.respond_to?(:to_path)
+          raw_path = file.respond_to?(:to_path) ? file.to_path : file
+          path = File.realpath(raw_path)
+          raise Api2Convert::Error, "Input file not found: #{file}" unless File.file?(path)
+
+          # Opened without a block on purpose: the handle is streamed by the
+          # transport and closed in upload's ensure clause.
+          handle = File.open(path, "rb") # rubocop:disable Style/FileOpen
+          # Mirror the null-coalesce: only nil falls back to the default, so an
+          # explicit "" filename is preserved as given.
+          name = filename.nil? ? File.basename(path) : filename
+          return [handle, name, handle]
+        end
+
+        io = file
+        io = StringIO.new(io.read) unless io.respond_to?(:size) && io.respond_to?(:rewind)
+        [io, filename.nil? ? "file" : filename, nil]
+      rescue Errno::ENOENT
+        raise Api2Convert::Error, "Input file not found: #{file}"
+      end
+    end
+  end
+end

data/lib/api2convert/upload/multipart_stream.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Api2Convert
+  module Upload
+    # A read-only IO that concatenates a multipart preamble, the file body IO, and
+    # the trailing boundary — so the body is streamed to the socket rather than
+    # loaded into memory. `Net::HTTP#body_stream=` reads it via `#read(len)`.
+    class MultipartStream
+      # Build the streamed body for a single `file` field. Returns
+      # `[stream, content_length]`; the caller sets `Content-Length` from the
+      # length so `Net::HTTP` does not fall back to chunked encoding.
+      #
+      # +io+ must be positioned at the start and expose a byte {#size} (a File or
+      # a StringIO both do — the uploader coerces anything else into a StringIO).
+      def self.build(boundary, field, filename, io)
+        disposition = %(form-data; name="#{escape(field)}"; filename="#{escape(filename)}")
+        preamble = [
+          "--#{boundary}",
+          "Content-Disposition: #{disposition}",
+          "Content-Type: application/octet-stream",
+          "",
+          ""
+        ].join("\r\n").b
+        epilogue = "\r\n--#{boundary}--\r\n".b
+
+        body_size = io.size - (io.respond_to?(:pos) ? io.pos : 0)
+        length = preamble.bytesize + body_size + epilogue.bytesize
+        [new(preamble, io, epilogue), length]
+      end
+
+      # Strip quotes and CR/LF from a header parameter so it can't break out of
+      # the multipart header (header-injection defense).
+      def self.escape(value)
+        value.to_s.gsub('"', "%22").gsub(/[\r\n]/, "")
+      end
+
+      def initialize(preamble, io, epilogue)
+        @parts = [StringIO.new(preamble), io, StringIO.new(epilogue)]
+        @index = 0
+      end
+
+      # Read up to +length+ bytes across the parts. With no length, reads all that
+      # remains. Returns nil at end of stream (the contract `Net::HTTP` expects).
+      def read(length = nil, outbuf = nil)
+        buffer = outbuf || "".b
+        buffer.clear
+
+        if length.nil?
+          while @index < @parts.length
+            chunk = @parts[@index].read
+            buffer << chunk unless chunk.nil?
+            @index += 1
+          end
+          return buffer
+        end
+
+        while buffer.bytesize < length && @index < @parts.length
+          chunk = @parts[@index].read(length - buffer.bytesize)
+          if chunk.nil?
+            @index += 1
+          else
+            buffer << chunk
+          end
+        end
+
+        return nil if buffer.empty? && @index >= @parts.length
+
+        buffer
+      end
+    end
+  end
+end

data/lib/api2convert/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+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.0"
+end

data/lib/api2convert/webhook/event.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Webhook
+    # A verified webhook callback. The API posts the job whose status changed.
+    class Event
+      # @return [Model::Job] the job whose status changed.
+      attr_reader :job
+      # @return [Hash] the full decoded callback body.
+      attr_reader :payload
+
+      def initialize(job, payload)
+        @job = job
+        @payload = payload
+        freeze
+      end
+
+      def self.from_hash(payload)
+        new(Model::Job.from_hash(payload), payload)
+      end
+    end
+  end
+end

data/lib/api2convert/webhook/verifier.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Api2Convert
+  module Webhook
+    # Webhook callback verification and parsing.
+    #
+    # Pass the **raw** request body (the exact string received) so signature
+    # verification is byte-exact. Verification uses HMAC-SHA256 and matches the
+    # server's signed-webhooks scheme; until signed webhooks are enabled on your
+    # account no signature is sent — use {#parse} then, or call {#construct_event}
+    # with an empty secret to skip verification.
+    class Verifier
+      # Verify the signature (when a secret is given) and return the typed event.
+      #
+      # +payload+ must be the raw request body. +signature+ is the value of the
+      # signature header (`X-Oc-Signature`). Pass an empty +secret+ to skip
+      # verification. Raises {SignatureVerificationError} when the signature is
+      # missing or does not match.
+      def construct_event(payload, signature, secret)
+        unless secret.nil? || secret == ""
+          if signature.nil? || signature == ""
+            raise SignatureVerificationError, "Missing webhook signature header."
+          end
+
+          expected = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, to_bytes(payload))
+          unless secure_compare(expected, signature)
+            raise SignatureVerificationError, "Webhook signature verification failed."
+          end
+        end
+
+        parse(payload)
+      end
+
+      # Parse a callback body into a typed event WITHOUT verifying a signature.
+      # Only use this when signed webhooks are not yet enabled for your account.
+      def parse(payload)
+        begin
+          decoded = JSON.parse(to_bytes(payload))
+        rescue JSON::ParserError => e
+          raise SignatureVerificationError, "Webhook payload is not valid JSON: #{e.message}"
+        end
+        raise SignatureVerificationError, "Webhook payload is not a JSON object." unless decoded.is_a?(Hash)
+
+        Event.from_hash(decoded)
+      end
+
+      private
+
+      def to_bytes(payload)
+        payload.is_a?(String) ? payload : payload.to_s
+      end
+
+      # Constant-time comparison, guarding the length check first. Uses OpenSSL's
+      # fixed-length compare when available (Ruby 2.6+); otherwise a portable
+      # branch-free fallback so old Rubies stay constant-time too.
+      def secure_compare(expected, actual)
+        a = expected.to_s.b
+        b = actual.to_s.b
+        return false unless a.bytesize == b.bytesize
+
+        if OpenSSL.respond_to?(:fixed_length_secure_compare)
+          OpenSSL.fixed_length_secure_compare(a, b)
+        else
+          result = 0
+          a.bytesize.times { |i| result |= a.getbyte(i) ^ b.getbyte(i) }
+          result.zero?
+        end
+      end
+    end
+  end
+end

data/lib/api2convert.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for the API2Convert 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:
+#
+#   require "api2convert"
+#
+#   client = Api2Convert::Client.new("YOUR_API_KEY")
+#   client.convert("invoice.docx", "pdf").save("invoice.pdf")
+#
+# 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`.
+module Api2Convert
+end
+
+require_relative "api2convert/version"
+require_relative "api2convert/errors"
+require_relative "api2convert/config"
+require_relative "api2convert/support/data"
+require_relative "api2convert/support/secret"
+require_relative "api2convert/job_status"
+require_relative "api2convert/input_type"
+
+require_relative "api2convert/model/status"
+require_relative "api2convert/model/conversion"
+require_relative "api2convert/model/input_file"
+require_relative "api2convert/model/output_file"
+require_relative "api2convert/model/job_message"
+require_relative "api2convert/model/preset"
+require_relative "api2convert/model/job"
+
+require_relative "api2convert/http/request"
+require_relative "api2convert/http/response"
+require_relative "api2convert/http/net_http_sender"
+require_relative "api2convert/http/transport"
+
+require_relative "api2convert/upload/multipart_stream"
+require_relative "api2convert/upload/file_uploader"
+
+require_relative "api2convert/resource/jobs"
+require_relative "api2convert/resource/conversions"
+require_relative "api2convert/resource/presets"
+require_relative "api2convert/resource/stats"
+require_relative "api2convert/resource/contracts"
+
+require_relative "api2convert/webhook/event"
+require_relative "api2convert/webhook/verifier"
+
+require_relative "api2convert/result"
+require_relative "api2convert/client"
+
+module Api2Convert
+  # Webhook verifier — usable without a configured client.
+  #
+  #   event = Api2Convert.webhooks.construct_event(raw_body, signature, secret)
+  def self.webhooks
+    Webhook::Verifier.new
+  end
+end