api2convert 10.2.0

data/lib/api2convert/model/conversion.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+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
+
+      def initialize(target: "", id: nil, category: nil, options: {}, metadata: {})
+        @target = target
+        @id = id
+        @category = category
+        @options = options
+        @metadata = metadata
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          target: Support::Data.as_str(d["target"]),
+          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"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/model/input_file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # An input file attached to a job.
+    class InputFile
+      attr_reader :id, :type, :source, :status, :filename, :size, :content_type, :options
+
+      def initialize(id: nil, type: "", source: nil, status: nil, filename: nil,
+                     size: nil, content_type: nil, options: {})
+        @id = id
+        @type = type
+        @source = source
+        @status = status
+        @filename = filename
+        @size = size
+        @content_type = content_type
+        @options = options
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          id: Support::Data.nullable_str(d["id"]),
+          type: Support::Data.as_str(d["type"]),
+          source: Support::Data.nullable_str(d["source"]),
+          status: Support::Data.nullable_str(d["status"]),
+          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"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/model/job.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A conversion job — the central API2Convert resource.
+    #
+    # {#server} and {#token} are needed to upload local files; {#output} holds the
+    # produced files once {#completed?}. {#raw} keeps the full decoded response for
+    # fields not surfaced as typed attributes.
+    class Job
+      attr_reader :id, :status, :token, :server, :callback,
+                  :conversion, :input, :output, :errors, :warnings, :raw
+
+      def initialize(id:, status:, token:, server:, callback:,
+                     conversion:, input:, output:, errors:, warnings:, raw:)
+        @id = id
+        @status = status
+        @token = token
+        @server = server
+        @callback = callback
+        @conversion = conversion
+        @input = input
+        @output = output
+        @errors = errors
+        @warnings = warnings
+        @raw = raw
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          id: Support::Data.as_str(d["id"]),
+          status: Status.from_hash(d["status"]),
+          token: Support::Data.nullable_str(d["token"]),
+          server: Support::Data.nullable_str(d["server"]),
+          callback: Support::Data.nullable_str(d["callback"]),
+          conversion: Support::Data.map_objects(d["conversion"]) { |x| Conversion.from_hash(x) },
+          input: Support::Data.map_objects(d["input"]) { |x| InputFile.from_hash(x) },
+          output: Support::Data.map_objects(d["output"]) { |x| OutputFile.from_hash(x) },
+          errors: Support::Data.map_objects(d["errors"]) { |x| JobMessage.from_hash(x) },
+          warnings: Support::Data.map_objects(d["warnings"]) { |x| JobMessage.from_hash(x) },
+          raw: d
+        )
+      end
+
+      def completed?
+        @status.code == JobStatus::COMPLETED
+      end
+
+      def failed?
+        @status.code == JobStatus::FAILED
+      end
+
+      # The job was canceled server-side — terminal, and produced no output.
+      def canceled?
+        @status.code == JobStatus::CANCELED
+      end
+
+      # Finished (completed, failed or canceled) and will not change further.
+      def terminal?
+        JobStatus.terminal?(@status.code)
+      end
+    end
+  end
+end

data/lib/api2convert/model/job_message.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # An error or warning attached to a job (the `errors[]` / `warnings[]` entries).
+    class JobMessage
+      attr_reader :code, :message, :source, :id_source, :details
+
+      def initialize(code: nil, message: "", source: nil, id_source: nil, details: {})
+        @code = code
+        @message = message
+        @source = source
+        @id_source = id_source
+        @details = details
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          code: Support::Data.nullable_int(d["code"]),
+          message: Support::Data.as_str(d["message"]),
+          source: Support::Data.nullable_str(d["source"]),
+          id_source: Support::Data.nullable_str(d["id_source"]),
+          details: Support::Data.as_object(d["details"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/model/output_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A produced output file.
+    #
+    # {#uri} is a self-contained download URL (no auth), valid for a limited time
+    # (24h by default).
+    class OutputFile
+      attr_reader :id, :uri, :filename, :size, :status, :content_type, :checksum, :metadata
+
+      def initialize(id: nil, uri: "", filename: nil, size: nil, status: nil,
+                     content_type: nil, checksum: nil, metadata: {})
+        @id = id
+        @uri = uri
+        @filename = filename
+        @size = size
+        @status = status
+        @content_type = content_type
+        @checksum = checksum
+        @metadata = metadata
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          id: Support::Data.nullable_str(d["id"]),
+          uri: Support::Data.as_str(d["uri"]),
+          filename: Support::Data.nullable_str(d["filename"]),
+          size: Support::Data.nullable_int(d["size"]),
+          status: Support::Data.nullable_str(d["status"]),
+          content_type: Support::Data.nullable_str(d["content_type"]),
+          checksum: Support::Data.nullable_str(d["checksum"]),
+          metadata: Support::Data.as_object(d["metadata"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/model/preset.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A saved conversion preset (a reusable named set of target + options).
+    class Preset
+      attr_reader :id, :name, :target, :category, :scope, :options
+
+      def initialize(id: nil, name: "", target: nil, category: nil, scope: nil, options: {})
+        @id = id
+        @name = name
+        @target = target
+        @category = category
+        @scope = scope
+        @options = options
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          id: Support::Data.nullable_str(d["id"]),
+          name: Support::Data.as_str(d["name"]),
+          target: Support::Data.nullable_str(d["target"]),
+          category: Support::Data.nullable_str(d["category"]),
+          scope: Support::Data.nullable_str(d["scope"]),
+          options: Support::Data.as_object(d["options"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/model/status.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Model
+    # A job's status: a machine-readable {#code} plus optional human {#info}.
+    class Status
+      attr_reader :code, :info
+
+      def initialize(code: "", info: nil)
+        @code = code
+        @info = info
+        freeze
+      end
+
+      def self.from_hash(data)
+        d = Support::Data.as_object(data)
+        new(
+          code: Support::Data.as_str(d["code"]),
+          info: Support::Data.nullable_str(d["info"])
+        )
+      end
+    end
+  end
+end

data/lib/api2convert/resource/contracts.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Resource
+    # Information about the account's active contracts (free-form response).
+    class Contracts
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def get
+        @transport.request("GET", "/contracts")
+      end
+    end
+  end
+end

data/lib/api2convert/resource/conversions.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Resource
+    # The conversions catalog (`GET /conversions`).
+    #
+    # The source of truth for which targets exist and which options each accepts.
+    class Conversions
+      def initialize(transport)
+        @transport = transport
+      end
+
+      # List supported conversions, optionally filtered by category/target. Each
+      # entry: `{ id, category, target, options }`.
+      def list(category = nil, target = nil, page = 1)
+        query = { "page" => page.to_s }
+        query["category"] = category unless category.nil?
+        query["target"] = target unless target.nil?
+        rows = @transport.request("GET", "/conversions", nil, query)
+        Support::Data.as_list(rows).grep(Hash)
+      end
+
+      # The option schema (type / enum / default / range) for a single target.
+      # +category+ is optional — pass it only to disambiguate an ambiguous target.
+      def options(target, category = nil)
+        rows = list(category, target)
+        first = rows.first || {}
+        opts = first["options"]
+        opts.is_a?(Hash) ? opts : {}
+      end
+    end
+  end
+end

data/lib/api2convert/resource/jobs.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Resource
+    # Full control over the job lifecycle.
+    #
+    # Most users only need `client.convert`, which is built on top of these
+    # methods. Reach for this resource for compound jobs, merges, presets, custom
+    # polling or job chaining. Methods are thin: build the request, call the
+    # transport, hydrate a model.
+    class Jobs
+      def initialize(transport, uploader)
+        @transport = transport
+        @uploader = uploader
+      end
+
+      # Create a job. Pass `{ "process" => false }` to stage it for uploads, then
+      # call {#start} once inputs are attached. +idempotency_key+ makes the create
+      # retry-safe (sent as the `Idempotency-Key` header).
+      def create(payload, idempotency_key = nil)
+        headers = idempotency_key.nil? ? nil : { "Idempotency-Key" => idempotency_key }
+        Model::Job.from_hash(@transport.request("POST", "/jobs", payload, nil, headers))
+      end
+
+      def get(job_id)
+        Model::Job.from_hash(@transport.request("GET", "/jobs/#{Support::Data.encode_segment(job_id)}"))
+      end
+
+      # List the current key's jobs (paginated, 50 per page).
+      def list(status = nil, page = 1)
+        query = { "page" => page.to_s }
+        query["status"] = status unless status.nil?
+        rows = @transport.request("GET", "/jobs", nil, query)
+        hashes(rows).map { |row| Model::Job.from_hash(row) }
+      end
+
+      def update(job_id, payload)
+        Model::Job.from_hash(
+          @transport.request("PATCH", "/jobs/#{Support::Data.encode_segment(job_id)}", payload)
+        )
+      end
+
+      # Start processing a staged job (`process => true`).
+      def start(job_id)
+        update(job_id, { "process" => true })
+      end
+
+      # Cancel a job (whether staged or processing).
+      def cancel(job_id)
+        @transport.request("DELETE", "/jobs/#{Support::Data.encode_segment(job_id)}")
+        nil
+      end
+
+      # Attach an input by descriptor, e.g. a remote URL:
+      # `add_input(job_id, { "type" => "remote", "source" => "https://..." })`.
+      def add_input(job_id, descriptor)
+        Model::InputFile.from_hash(
+          @transport.request("POST", "/jobs/#{Support::Data.encode_segment(job_id)}/input", descriptor)
+        )
+      end
+
+      # Upload a local file (path or IO) to the job's upload server.
+      def upload(job, file, filename = nil)
+        @uploader.upload(job, file, filename)
+      end
+
+      # Block until the job reaches a terminal status, polling with backoff.
+      #
+      # Raises {ConversionFailedError} on a failed/canceled job (unless
+      # +throw_on_failure+ is false) and {ConversionTimeoutError} past the
+      # deadline. The interval is floored and the total wait capped, so no
+      # configuration can busy-loop or poll unbounded.
+      def wait(job_id, timeout_seconds = nil, throw_on_failure = true)
+        config = @transport.config
+        # Clamp again here (Config.create already clamps) so a directly-built
+        # Config or a per-call override can never busy-loop or poll unbounded.
+        requested = timeout_seconds.nil? ? config.poll_timeout : timeout_seconds
+        timeout = requested.clamp(0, Config::MAX_POLL_TIMEOUT)
+        max_interval = [Config::MIN_POLL_INTERVAL, config.poll_max_interval].max
+        interval = [Config::MIN_POLL_INTERVAL, config.poll_interval].max
+        deadline = monotonic + timeout
+
+        loop do
+          job = get(job_id)
+
+          raise ConversionFailedError.new(job) if (job.failed? || job.canceled?) && throw_on_failure
+          return job if job.terminal?
+          raise ConversionTimeoutError.new(job, timeout) if monotonic >= deadline
+
+          @transport.pause(interval)
+          interval = [max_interval, interval * 1.5].min
+        end
+      end
+
+      # Outputs produced by the job (use {#get} or {#wait} first).
+      def outputs(job_id)
+        rows = @transport.request("GET", "/jobs/#{Support::Data.encode_segment(job_id)}/output")
+        hashes(rows).map { |row| Model::OutputFile.from_hash(row) }
+      end
+
+      private
+
+      def hashes(rows)
+        Support::Data.as_list(rows).grep(Hash)
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/api2convert/resource/presets.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Resource
+    # Saved conversion presets (reusable named target + options).
+    class Presets
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def list(category: nil, target: nil, filter: nil)
+        query = {}
+        query["category"] = category unless category.nil?
+        query["target"] = target unless target.nil?
+        query["filter"] = filter unless filter.nil?
+        rows = @transport.request("GET", "/presets", nil, query)
+        Support::Data.as_list(rows).grep(Hash).map { |row| Model::Preset.from_hash(row) }
+      end
+
+      # Create a preset from `{ name, target, options, scope?, category? }`.
+      def create(payload)
+        Model::Preset.from_hash(@transport.request("POST", "/presets", payload))
+      end
+
+      def get(preset_id)
+        Model::Preset.from_hash(
+          @transport.request("GET", "/presets/#{Support::Data.encode_segment(preset_id)}")
+        )
+      end
+
+      def update(preset_id, payload)
+        Model::Preset.from_hash(
+          @transport.request("PATCH", "/presets/#{Support::Data.encode_segment(preset_id)}", payload)
+        )
+      end
+
+      def delete(preset_id)
+        @transport.request("DELETE", "/presets/#{Support::Data.encode_segment(preset_id)}")
+        nil
+      end
+    end
+  end
+end

data/lib/api2convert/resource/stats.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+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"`.
+    class Stats
+      def initialize(transport)
+        @transport = transport
+      end
+
+      # +day+ format `yyyy-mm-dd`.
+      def day(day, filter = "all")
+        @transport.request("GET", "/stats/day/#{seg(day)}/#{seg(filter)}")
+      end
+
+      # +month+ format `yyyy-mm`.
+      def month(month, filter = "all")
+        @transport.request("GET", "/stats/month/#{seg(month)}/#{seg(filter)}")
+      end
+
+      # +year+ format `yyyy`.
+      def year(year, filter = "all")
+        @transport.request("GET", "/stats/year/#{seg(year)}/#{seg(filter)}")
+      end
+
+      private
+
+      def seg(value)
+        Support::Data.encode_segment(value)
+      end
+    end
+  end
+end