enconvert 0.0.1 → 0.1.1

data/lib/enconvert/client.rb

@@ -1,419 +1,422 @@
-# frozen_string_literal: true
-
-require "json"
-require "securerandom"
-require "fileutils"
-require "net/http"
-require "uri"
-
-require_relative "internal"
-require_relative "errors"
-require_relative "formats"
-require_relative "results"
-require_relative "v2"
-
-module Enconvert
-  # Enconvert file conversion client.
-  #
-  # @example
-  #   client = Enconvert::Client.new(api_key: "sk_...")
-  #   result = client.convert_url_to_pdf("https://example.com")
-  #   puts result.presigned_url
-  class Client
-    include Internal
-
-    DEFAULT_BASE_URL = "https://api.enconvert.com"
-    DEFAULT_TIMEOUT = 300
-    DEFAULT_BATCH_POLL_INTERVAL = 5
-    DEFAULT_BATCH_TIMEOUT = 1_800
-
-    # V2 API namespace: perceive, discover, lookup, distill, ingest, watch.
-    # Requires a private API key; endpoints are plan-gated (QuotaError on 402).
-    attr_reader :v2
-
-    def initialize(api_key:, timeout: DEFAULT_TIMEOUT, base_url: DEFAULT_BASE_URL)
-      raise Enconvert::Error, "Enconvert: 'api_key' is required" if api_key.nil? || api_key.to_s.strip.empty?
-
-      @api_key = api_key
-      @base_url = base_url.to_s.sub(%r{/+\z}, "")
-      @timeout = timeout
-      @transport = Internal::Transport.new(api_key: @api_key, base_url: @base_url, timeout: @timeout)
-      @v2 = Enconvert::V2.new(@transport)
-    end
-
-    # ------------------------------------------------------------------
-    # URL conversions (single page)
-    # ------------------------------------------------------------------
-
-    # Convert a URL to PDF.
-    #
-    # opts accepts: viewport_width, viewport_height, load_media,
-    # enable_scroll, output_filename, auth, cookies, headers,
-    # plus save_to, single_page (default true), pdf_options.
-    def convert_url_to_pdf(url, save_to: nil, single_page: nil, pdf_options: nil, **opts)
-      body = build_url_body(url, opts)
-      body[:single_page] = single_page.nil? ? true : single_page
-      body[:pdf_options] = serialize_pdf_options(pdf_options) if pdf_options
-
-      data = post_json("/v1/convert/url-to-pdf", body)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # Convert a URL to a PNG screenshot.
-    def convert_url_to_screenshot(url, save_to: nil, **opts)
-      body = build_url_body(url, opts)
-
-      data = post_json("/v1/convert/url-to-screenshot", body)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # Convert a URL to clean GitHub-Flavored Markdown with YAML frontmatter
-    # (title, description, url, links, images). Strips nav/footer/ads/scripts
-    # and extracts the main article content.
-    def convert_url_to_markdown(url, save_to: nil, **opts)
-      body = build_url_body(url, opts)
-
-      data = post_json("/v1/convert/url-to-markdown", body)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # ------------------------------------------------------------------
-    # Website conversions (async batch, whole-site crawl)
-    # ------------------------------------------------------------------
-
-    # Convert every discovered page of a website to PDF. Async-only: pages
-    # are discovered via sitemap or full crawl (plan-dependent), converted
-    # in the background, and bundled into a single ZIP. Poll with
-    # get_batch_status or block with wait_for_batch. Requires a private API
-    # key with crawl access.
-    def convert_website_to_pdf(url, single_page: nil, pdf_options: nil, **opts)
-      body = build_website_body(url, opts)
-      body[:single_page] = single_page unless single_page.nil?
-      body[:pdf_options] = serialize_pdf_options(pdf_options) if pdf_options
-
-      # No job-polling fallback: website submissions have no per-job row, so
-      # a 5xx here means the submission itself failed and must surface directly.
-      data = post_json("/v1/convert/website-to-pdf", body, job_fallback: false)
-      to_batch_submission(data)
-    end
-
-    # Screenshot every discovered page of a website (PNG). Async-only,
-    # bundled into a single ZIP. Poll with get_batch_status or block with
-    # wait_for_batch. Requires a private API key with crawl access.
-    def convert_website_to_screenshot(url, **opts)
-      body = build_website_body(url, opts)
-
-      data = post_json("/v1/convert/website-to-screenshot", body, job_fallback: false)
-      to_batch_submission(data)
-    end
-
-    # ------------------------------------------------------------------
-    # File conversions
-    # ------------------------------------------------------------------
-
-    # Convert an image between formats (jpeg, png, svg, heic, webp), or
-    # rasterize a PDF to JPEG. Only pairs implemented by the API are
-    # accepted; unsupported pairs raise before any request is made.
-    def convert_image(file, output_format:, save_to: nil, output_filename: nil)
-      part = to_file_part(file)
-      input_format = Formats.resolve_input_format(part.filename, Formats::IMAGE_FORMATS)
-      output_fmt = Formats.normalize_output_format(output_format)
-      endpoint = "/v1/convert/#{Formats.assert_conversion_implemented(input_format, output_fmt)}"
-      data = post_file(endpoint, part, output_filename: output_filename)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # Convert a document (doc, excel, ppt, odt, ods, odp, ots, pages,
-    # numbers, html, markdown, csv, json, xml, yaml, toml). Output
-    # defaults to pdf. Only pairs implemented by the API are accepted;
-    # unsupported pairs raise before any request is made. (EPUB has no
-    # dedicated pair — use convert_to_pdf / convert_to_markdown.)
-    def convert_document(file, output_format: "pdf", save_to: nil, output_filename: nil, pdf_options: nil)
-      part = to_file_part(file)
-      input_format = Formats.resolve_input_format(part.filename, Formats::DOCUMENT_FORMATS)
-      output_fmt = Formats.normalize_output_format(output_format)
-      endpoint = "/v1/convert/#{Formats.assert_conversion_implemented(input_format, output_fmt)}"
-      data = post_file(endpoint, part, output_filename: output_filename, pdf_options: pdf_options)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # Convert an uploaded file of (almost) any document format to clean
-    # Markdown — PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT/MD, and
-    # legacy/ODF office. The format is auto-detected server-side; a
-    # RAG-ingestion building block. Images are not supported.
-    def convert_to_markdown(file, save_to: nil, output_filename: nil)
-      part = to_file_part(file)
-      data = post_file("/v1/convert/anything-to-markdown", part, output_filename: output_filename)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # Convert an uploaded file of (almost) any format to PDF —
-    # office/ODF/Pages/Numbers/RTF/CSV, HTML, Markdown, text, raster
-    # images, SVG, EPUB, or an existing PDF (passthrough/normalise). The
-    # format is auto-detected server-side. Only `pdf_options[:grayscale]`
-    # is honored on this endpoint.
-    def convert_to_pdf(file, save_to: nil, output_filename: nil, pdf_options: nil)
-      part = to_file_part(file)
-      data = post_file("/v1/convert/anything-to-pdf", part, output_filename: output_filename, pdf_options: pdf_options)
-      result = to_conversion_result(data)
-      download(result.presigned_url, save_to) if save_to
-      result
-    end
-
-    # ------------------------------------------------------------------
-    # Job + batch status
-    # ------------------------------------------------------------------
-
-    # Poll the status of an async conversion job.
-    def get_job_status(job_id)
-      resp = @transport.request(:get, "/v1/convert/status/#{job_id}")
-      raise_for_status(resp)
-      to_job_status(JSON.parse(resp.body))
-    end
-
-    # Get the status of an async batch (website conversion). Returns
-    # aggregate counts, per-URL statuses, and download URLs. Private API
-    # keys only.
-    def get_batch_status(batch_id)
-      resp = @transport.request(:get, "/v1/convert/batch/#{batch_id}")
-      raise_for_status(resp)
-      to_batch_status(JSON.parse(resp.body))
-    end
-
-    # Poll a batch until it leaves "processing", then return its final
-    # status. With save_to, downloads the batch ZIP once available.
-    # Raises APIError 504 on timeout.
-    def wait_for_batch(batch_id, interval: DEFAULT_BATCH_POLL_INTERVAL, timeout: DEFAULT_BATCH_TIMEOUT, save_to: nil)
-      deadline = Time.now + timeout
-
-      loop do
-        status = get_batch_status(batch_id)
-        if status.status != "processing"
-          if save_to
-            if status.zip_download_url.nil?
-              raise APIError.new(
-                500, "Batch #{batch_id} finished with status '#{status.status}' but no ZIP is available to save"
-              )
-            end
-            download(status.zip_download_url, save_to)
-          end
-          return status
-        end
-        raise APIError.new(504, "Batch #{batch_id} did not complete within #{timeout}s") if Time.now >= deadline
-
-        sleep(interval)
-      end
-    end
-
-    private
-
-    # ------------------------------------------------------------------
-    # Internal helpers (mirror of Node's postJson / postFile / pollJob /
-    # download / toFilePart / raiseForStatus)
-    # ------------------------------------------------------------------
-
-    # Request body shared by all single-URL conversions.
-    def build_url_body(url, opts)
-      body = {
-        url: url,
-        direct_download: false,
-        viewport_width: opts.key?(:viewport_width) ? opts[:viewport_width] : 1920,
-        viewport_height: opts.key?(:viewport_height) ? opts[:viewport_height] : 1080,
-        load_media: opts.key?(:load_media) ? opts[:load_media] : true,
-        enable_scroll: opts.key?(:enable_scroll) ? opts[:enable_scroll] : true
-      }
-      body[:output_filename] = opts[:output_filename] if opts[:output_filename]
-      append_browser_access(body, opts)
-      body
-    end
-
-    # Request body for website (whole-site) conversions. Render options are
-    # only sent when set — the gateway applies the same defaults per page.
-    def build_website_body(url, opts)
-      body = { url: url }
-      body[:crawl_mode] = opts[:crawl_mode] if opts[:crawl_mode]
-      body[:include_patterns] = opts[:include_patterns] if opts[:include_patterns]
-      body[:exclude_patterns] = opts[:exclude_patterns] if opts[:exclude_patterns]
-      body[:notification_email] = opts[:notification_email] if opts[:notification_email]
-      body[:callback_url] = opts[:callback_url] if opts[:callback_url]
-      body[:output_filename] = opts[:output_filename] if opts[:output_filename]
-      body[:viewport_width] = opts[:viewport_width] if opts.key?(:viewport_width)
-      body[:viewport_height] = opts[:viewport_height] if opts.key?(:viewport_height)
-      body[:load_media] = opts[:load_media] if opts.key?(:load_media)
-      body[:enable_scroll] = opts[:enable_scroll] if opts.key?(:enable_scroll)
-      append_browser_access(body, opts)
-      body
-    end
-
-    # Attach the plan-gated auth/cookies/headers fields when provided.
-    def append_browser_access(body, opts)
-      body[:auth] = opts[:auth] if opts[:auth]
-      body[:cookies] = opts[:cookies] if opts[:cookies]
-      body[:headers] = opts[:headers] if opts[:headers]
-    end
-
-    def post_json(endpoint, body, job_fallback: true)
-      job_id = job_fallback ? new_job_id : nil
-      body[:job_id] = job_id if job_id
-      begin
-        resp = @transport.request(
-          :post, endpoint,
-          headers: { "Content-Type" => "application/json" },
-          body: JSON.generate(body)
-        )
-        raise_for_status(resp)
-        data = JSON.parse(resp.body)
-        # Some success responses omit job_id (URL sync path); backfill the
-        # client-generated id so callers can still poll get_job_status with it.
-        job_id ? { "job_id" => job_id }.merge(data) : data
-      rescue APIError => e
-        raise unless job_id && e.status_code >= 500
-
-        poll_job(job_id)
-      end
-    end
-
-    def post_file(endpoint, part, output_filename: nil, pdf_options: nil)
-      job_id = new_job_id
-      fields = [
-        { name: "file", value: part.bytes, filename: part.filename, content_type: part.content_type },
-        { name: "direct_download", value: "false" },
-        { name: "job_id", value: job_id }
-      ]
-      fields << { name: "output_filename", value: output_filename } if output_filename
-      fields << { name: "pdf_options", value: JSON.generate(serialize_pdf_options(pdf_options)) } if pdf_options
-
-      body, boundary = build_multipart(fields)
-      begin
-        resp = @transport.request(
-          :post, endpoint,
-          headers: { "Content-Type" => "multipart/form-data; boundary=#{boundary}" },
-          body: body
-        )
-        raise_for_status(resp)
-        data = JSON.parse(resp.body)
-        { "job_id" => job_id }.merge(data)
-      rescue APIError => e
-        raise unless e.status_code >= 500
-
-        poll_job(job_id)
-      end
-    end
-
-    # Poll job status until success/failure. Used as fallback when the
-    # HTTP request fails.
-    def poll_job(job_id, max_wait: 300, interval: 3)
-      deadline = Time.now + max_wait
-      while Time.now < deadline
-        sleep(interval)
-        resp = @transport.request(:get, "/v1/convert/status/#{job_id}")
-        next if resp.code.to_i == 404
-
-        raise_for_status(resp)
-        data = JSON.parse(resp.body)
-        return data if data["status"] == "success"
-        raise APIError.new(500, data["error"] || "Conversion failed") if data["status"] == "failed"
-      end
-      raise APIError.new(504, "Conversion timed out")
-    end
-
-    # Save a presigned URL to a local file. Streams the response to disk.
-    # Deliberately bypasses @transport: this is a signed S3 URL and must
-    # NOT receive the X-API-Key header.
-    def download(url, dest)
-      uri = URI(url)
-      FileUtils.mkdir_p(File.dirname(dest))
-      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
-        req = Net::HTTP::Get.new(uri)
-        http.request(req) do |response|
-          unless response.is_a?(Net::HTTPSuccess)
-            raise APIError.new(response.code.to_i, "Failed to download: #{response.message}")
-          end
-
-          File.open(dest, "wb") do |file|
-            response.read_body { |chunk| file.write(chunk) }
-          end
-        end
-      end
-    end
-
-    # ------------------------------------------------------------------
-    # Response mappers
-    # ------------------------------------------------------------------
-
-    def to_conversion_result(data)
-      object_key = data["object_key"].is_a?(String) ? data["object_key"] : ""
-      # Job-status fallback responses omit `filename`; recover it from the
-      # object key so callers never see a nil/blank filename silently.
-      filename = data["filename"].is_a?(String) ? data["filename"] : basename_fallback(object_key)
-      ConversionResult.new(
-        presigned_url: data["presigned_url"].to_s,
-        object_key: object_key,
-        filename: filename,
-        file_size: data["file_size"].is_a?(Numeric) ? data["file_size"] : nil,
-        conversion_time_seconds: data["conversion_time_seconds"].is_a?(Numeric) ? data["conversion_time_seconds"] : nil,
-        job_id: data["job_id"].is_a?(String) ? data["job_id"] : nil
-      )
-    end
-
-    def basename_fallback(object_key)
-      parts = object_key.to_s.split("/")
-      parts.empty? ? "" : parts.last
-    end
-
-    def to_job_status(data)
-      JobStatus.new(
-        status: data["status"],
-        presigned_url: data["presigned_url"].is_a?(String) ? data["presigned_url"] : nil,
-        object_key: data["object_key"].is_a?(String) ? data["object_key"] : nil,
-        error: data["error"].is_a?(String) ? data["error"] : nil
-      )
-    end
-
-    def to_batch_submission(data)
-      BatchSubmission.new(
-        batch_id: data["batch_id"].to_s,
-        status: data["status"].is_a?(String) ? data["status"] : "processing",
-        url_count: data["url_count"].is_a?(Numeric) ? data["url_count"] : 0,
-        total_discovered: data["total_discovered"].is_a?(Numeric) ? data["total_discovered"] : nil,
-        discovery_method: data["discovery_method"].is_a?(String) ? data["discovery_method"] : nil,
-        output_format: data["output_format"].is_a?(String) ? data["output_format"] : nil
-      )
-    end
-
-    def to_batch_status(d)
-      raw_items = d["items"].is_a?(Array) ? d["items"] : []
-      BatchStatus.new(
-        batch_id: d["batch_id"].to_s,
-        status: d["status"],
-        total: d["total"].is_a?(Numeric) ? d["total"] : 0,
-        completed: d["completed"].is_a?(Numeric) ? d["completed"] : 0,
-        failed: d["failed"].is_a?(Numeric) ? d["failed"] : 0,
-        in_progress: d["in_progress"].is_a?(Numeric) ? d["in_progress"] : 0,
-        output_mode: d["output_mode"],
-        zip_download_url: d["zip_download_url"].is_a?(String) ? d["zip_download_url"] : nil,
-        items: raw_items.map do |item|
-          BatchItem.new(
-            source_url: item["source_url"].is_a?(String) ? item["source_url"] : "",
-            status: item["status"].is_a?(String) ? item["status"] : "",
-            download_url: item["download_url"].is_a?(String) ? item["download_url"] : nil,
-            output_file_size: item["output_file_size"].is_a?(Numeric) ? item["output_file_size"] : nil,
-            duration: item["duration"].is_a?(String) ? item["duration"] : nil
-          )
-        end
-      )
-    end
-  end
-end
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "fileutils"
+require "net/http"
+require "uri"
+
+require_relative "internal"
+require_relative "errors"
+require_relative "formats"
+require_relative "results"
+require_relative "v2"
+
+module Enconvert
+  # Enconvert file conversion client.
+  #
+  # @example
+  #   client = Enconvert::Client.new(api_key: "sk_...")
+  #   result = client.convert_url_to_pdf("https://example.com")
+  #   puts result.presigned_url
+  class Client
+    include Internal
+
+    DEFAULT_BASE_URL = "https://api.enconvert.com"
+    DEFAULT_TIMEOUT = 300
+    DEFAULT_BATCH_POLL_INTERVAL = 5
+    DEFAULT_BATCH_TIMEOUT = 1_800
+
+    # V2 API namespace: perceive, discover, lookup, distill, ingest, watch.
+    # Requires a private API key; endpoints are plan-gated (QuotaError on 402).
+    attr_reader :v2
+
+    # `user_agent` overrides the default "enconvert-sdk/<version> (ruby)"
+    # User-Agent sent on every gateway request.
+    def initialize(api_key:, timeout: DEFAULT_TIMEOUT, base_url: DEFAULT_BASE_URL, user_agent: nil)
+      raise Enconvert::Error, "Enconvert: 'api_key' is required" if api_key.nil? || api_key.to_s.strip.empty?
+
+      @api_key = api_key
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @transport = Internal::Transport.new(api_key: @api_key, base_url: @base_url, timeout: @timeout,
+                                           user_agent: user_agent)
+      @v2 = Enconvert::V2.new(@transport)
+    end
+
+    # ------------------------------------------------------------------
+    # URL conversions (single page)
+    # ------------------------------------------------------------------
+
+    # Convert a URL to PDF.
+    #
+    # opts accepts: viewport_width, viewport_height, load_media,
+    # enable_scroll, output_filename, auth, cookies, headers,
+    # plus save_to, single_page (default true), pdf_options.
+    def convert_url_to_pdf(url, save_to: nil, single_page: nil, pdf_options: nil, **opts)
+      body = build_url_body(url, opts)
+      body[:single_page] = single_page.nil? ? true : single_page
+      body[:pdf_options] = serialize_pdf_options(pdf_options) if pdf_options
+
+      data = post_json("/v1/convert/url-to-pdf", body)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # Convert a URL to a PNG screenshot.
+    def convert_url_to_screenshot(url, save_to: nil, **opts)
+      body = build_url_body(url, opts)
+
+      data = post_json("/v1/convert/url-to-screenshot", body)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # Convert a URL to clean GitHub-Flavored Markdown with YAML frontmatter
+    # (title, description, url, links, images). Strips nav/footer/ads/scripts
+    # and extracts the main article content.
+    def convert_url_to_markdown(url, save_to: nil, **opts)
+      body = build_url_body(url, opts)
+
+      data = post_json("/v1/convert/url-to-markdown", body)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # ------------------------------------------------------------------
+    # Website conversions (async batch, whole-site crawl)
+    # ------------------------------------------------------------------
+
+    # Convert every discovered page of a website to PDF. Async-only: pages
+    # are discovered via sitemap or full crawl (plan-dependent), converted
+    # in the background, and bundled into a single ZIP. Poll with
+    # get_batch_status or block with wait_for_batch. Requires a private API
+    # key with crawl access.
+    def convert_website_to_pdf(url, single_page: nil, pdf_options: nil, **opts)
+      body = build_website_body(url, opts)
+      body[:single_page] = single_page unless single_page.nil?
+      body[:pdf_options] = serialize_pdf_options(pdf_options) if pdf_options
+
+      # No job-polling fallback: website submissions have no per-job row, so
+      # a 5xx here means the submission itself failed and must surface directly.
+      data = post_json("/v1/convert/website-to-pdf", body, job_fallback: false)
+      to_batch_submission(data)
+    end
+
+    # Screenshot every discovered page of a website (PNG). Async-only,
+    # bundled into a single ZIP. Poll with get_batch_status or block with
+    # wait_for_batch. Requires a private API key with crawl access.
+    def convert_website_to_screenshot(url, **opts)
+      body = build_website_body(url, opts)
+
+      data = post_json("/v1/convert/website-to-screenshot", body, job_fallback: false)
+      to_batch_submission(data)
+    end
+
+    # ------------------------------------------------------------------
+    # File conversions
+    # ------------------------------------------------------------------
+
+    # Convert an image between formats (jpeg, png, svg, heic, webp), or
+    # rasterize a PDF to JPEG. Only pairs implemented by the API are
+    # accepted; unsupported pairs raise before any request is made.
+    def convert_image(file, output_format:, save_to: nil, output_filename: nil)
+      part = to_file_part(file)
+      input_format = Formats.resolve_input_format(part.filename, Formats::IMAGE_FORMATS)
+      output_fmt = Formats.normalize_output_format(output_format)
+      endpoint = "/v1/convert/#{Formats.assert_conversion_implemented(input_format, output_fmt)}"
+      data = post_file(endpoint, part, output_filename: output_filename)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # Convert a document (doc, excel, ppt, odt, ods, odp, ots, pages,
+    # numbers, html, markdown, csv, json, xml, yaml, toml). Output
+    # defaults to pdf. Only pairs implemented by the API are accepted;
+    # unsupported pairs raise before any request is made. (EPUB has no
+    # dedicated pair — use convert_to_pdf / convert_to_markdown.)
+    def convert_document(file, output_format: "pdf", save_to: nil, output_filename: nil, pdf_options: nil)
+      part = to_file_part(file)
+      input_format = Formats.resolve_input_format(part.filename, Formats::DOCUMENT_FORMATS)
+      output_fmt = Formats.normalize_output_format(output_format)
+      endpoint = "/v1/convert/#{Formats.assert_conversion_implemented(input_format, output_fmt)}"
+      data = post_file(endpoint, part, output_filename: output_filename, pdf_options: pdf_options)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # Convert an uploaded file of (almost) any document format to clean
+    # Markdown — PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT/MD, and
+    # legacy/ODF office. The format is auto-detected server-side; a
+    # RAG-ingestion building block. Images are not supported.
+    def convert_to_markdown(file, save_to: nil, output_filename: nil)
+      part = to_file_part(file)
+      data = post_file("/v1/convert/anything-to-markdown", part, output_filename: output_filename)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # Convert an uploaded file of (almost) any format to PDF —
+    # office/ODF/Pages/Numbers/RTF/CSV, HTML, Markdown, text, raster
+    # images, SVG, EPUB, or an existing PDF (passthrough/normalise). The
+    # format is auto-detected server-side. Only `pdf_options[:grayscale]`
+    # is honored on this endpoint.
+    def convert_to_pdf(file, save_to: nil, output_filename: nil, pdf_options: nil)
+      part = to_file_part(file)
+      data = post_file("/v1/convert/anything-to-pdf", part, output_filename: output_filename, pdf_options: pdf_options)
+      result = to_conversion_result(data)
+      download(result.presigned_url, save_to) if save_to
+      result
+    end
+
+    # ------------------------------------------------------------------
+    # Job + batch status
+    # ------------------------------------------------------------------
+
+    # Poll the status of an async conversion job.
+    def get_job_status(job_id)
+      resp = @transport.request(:get, "/v1/convert/status/#{job_id}")
+      raise_for_status(resp)
+      to_job_status(JSON.parse(resp.body))
+    end
+
+    # Get the status of an async batch (website conversion). Returns
+    # aggregate counts, per-URL statuses, and download URLs. Private API
+    # keys only.
+    def get_batch_status(batch_id)
+      resp = @transport.request(:get, "/v1/convert/batch/#{batch_id}")
+      raise_for_status(resp)
+      to_batch_status(JSON.parse(resp.body))
+    end
+
+    # Poll a batch until it leaves "processing", then return its final
+    # status. With save_to, downloads the batch ZIP once available.
+    # Raises APIError 504 on timeout.
+    def wait_for_batch(batch_id, interval: DEFAULT_BATCH_POLL_INTERVAL, timeout: DEFAULT_BATCH_TIMEOUT, save_to: nil)
+      deadline = Time.now + timeout
+
+      loop do
+        status = get_batch_status(batch_id)
+        if status.status != "processing"
+          if save_to
+            if status.zip_download_url.nil?
+              raise APIError.new(
+                500, "Batch #{batch_id} finished with status '#{status.status}' but no ZIP is available to save"
+              )
+            end
+            download(status.zip_download_url, save_to)
+          end
+          return status
+        end
+        raise APIError.new(504, "Batch #{batch_id} did not complete within #{timeout}s") if Time.now >= deadline
+
+        sleep(interval)
+      end
+    end
+
+    private
+
+    # ------------------------------------------------------------------
+    # Internal helpers (mirror of Node's postJson / postFile / pollJob /
+    # download / toFilePart / raiseForStatus)
+    # ------------------------------------------------------------------
+
+    # Request body shared by all single-URL conversions.
+    def build_url_body(url, opts)
+      body = {
+        url: url,
+        direct_download: false,
+        viewport_width: opts.key?(:viewport_width) ? opts[:viewport_width] : 1920,
+        viewport_height: opts.key?(:viewport_height) ? opts[:viewport_height] : 1080,
+        load_media: opts.key?(:load_media) ? opts[:load_media] : true,
+        enable_scroll: opts.key?(:enable_scroll) ? opts[:enable_scroll] : true
+      }
+      body[:output_filename] = opts[:output_filename] if opts[:output_filename]
+      append_browser_access(body, opts)
+      body
+    end
+
+    # Request body for website (whole-site) conversions. Render options are
+    # only sent when set — the gateway applies the same defaults per page.
+    def build_website_body(url, opts)
+      body = { url: url }
+      body[:crawl_mode] = opts[:crawl_mode] if opts[:crawl_mode]
+      body[:include_patterns] = opts[:include_patterns] if opts[:include_patterns]
+      body[:exclude_patterns] = opts[:exclude_patterns] if opts[:exclude_patterns]
+      body[:notification_email] = opts[:notification_email] if opts[:notification_email]
+      body[:callback_url] = opts[:callback_url] if opts[:callback_url]
+      body[:output_filename] = opts[:output_filename] if opts[:output_filename]
+      body[:viewport_width] = opts[:viewport_width] if opts.key?(:viewport_width)
+      body[:viewport_height] = opts[:viewport_height] if opts.key?(:viewport_height)
+      body[:load_media] = opts[:load_media] if opts.key?(:load_media)
+      body[:enable_scroll] = opts[:enable_scroll] if opts.key?(:enable_scroll)
+      append_browser_access(body, opts)
+      body
+    end
+
+    # Attach the plan-gated auth/cookies/headers fields when provided.
+    def append_browser_access(body, opts)
+      body[:auth] = opts[:auth] if opts[:auth]
+      body[:cookies] = opts[:cookies] if opts[:cookies]
+      body[:headers] = opts[:headers] if opts[:headers]
+    end
+
+    def post_json(endpoint, body, job_fallback: true)
+      job_id = job_fallback ? new_job_id : nil
+      body[:job_id] = job_id if job_id
+      begin
+        resp = @transport.request(
+          :post, endpoint,
+          headers: { "Content-Type" => "application/json" },
+          body: JSON.generate(body)
+        )
+        raise_for_status(resp)
+        data = JSON.parse(resp.body)
+        # Some success responses omit job_id (URL sync path); backfill the
+        # client-generated id so callers can still poll get_job_status with it.
+        job_id ? { "job_id" => job_id }.merge(data) : data
+      rescue APIError => e
+        raise unless job_id && e.status_code >= 500
+
+        poll_job(job_id)
+      end
+    end
+
+    def post_file(endpoint, part, output_filename: nil, pdf_options: nil)
+      job_id = new_job_id
+      fields = [
+        { name: "file", value: part.bytes, filename: part.filename, content_type: part.content_type },
+        { name: "direct_download", value: "false" },
+        { name: "job_id", value: job_id }
+      ]
+      fields << { name: "output_filename", value: output_filename } if output_filename
+      fields << { name: "pdf_options", value: JSON.generate(serialize_pdf_options(pdf_options)) } if pdf_options
+
+      body, boundary = build_multipart(fields)
+      begin
+        resp = @transport.request(
+          :post, endpoint,
+          headers: { "Content-Type" => "multipart/form-data; boundary=#{boundary}" },
+          body: body
+        )
+        raise_for_status(resp)
+        data = JSON.parse(resp.body)
+        { "job_id" => job_id }.merge(data)
+      rescue APIError => e
+        raise unless e.status_code >= 500
+
+        poll_job(job_id)
+      end
+    end
+
+    # Poll job status until success/failure. Used as fallback when the
+    # HTTP request fails.
+    def poll_job(job_id, max_wait: 300, interval: 3)
+      deadline = Time.now + max_wait
+      while Time.now < deadline
+        sleep(interval)
+        resp = @transport.request(:get, "/v1/convert/status/#{job_id}")
+        next if resp.code.to_i == 404
+
+        raise_for_status(resp)
+        data = JSON.parse(resp.body)
+        return data if data["status"] == "success"
+        raise APIError.new(500, data["error"] || "Conversion failed") if data["status"] == "failed"
+      end
+      raise APIError.new(504, "Conversion timed out")
+    end
+
+    # Save a presigned URL to a local file. Streams the response to disk.
+    # Deliberately bypasses @transport: this is a signed S3 URL and must
+    # NOT receive the X-API-Key header.
+    def download(url, dest)
+      uri = URI(url)
+      FileUtils.mkdir_p(File.dirname(dest))
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        req = Net::HTTP::Get.new(uri)
+        http.request(req) do |response|
+          unless response.is_a?(Net::HTTPSuccess)
+            raise APIError.new(response.code.to_i, "Failed to download: #{response.message}")
+          end
+
+          File.open(dest, "wb") do |file|
+            response.read_body { |chunk| file.write(chunk) }
+          end
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Response mappers
+    # ------------------------------------------------------------------
+
+    def to_conversion_result(data)
+      object_key = data["object_key"].is_a?(String) ? data["object_key"] : ""
+      # Job-status fallback responses omit `filename`; recover it from the
+      # object key so callers never see a nil/blank filename silently.
+      filename = data["filename"].is_a?(String) ? data["filename"] : basename_fallback(object_key)
+      ConversionResult.new(
+        presigned_url: data["presigned_url"].to_s,
+        object_key: object_key,
+        filename: filename,
+        file_size: data["file_size"].is_a?(Numeric) ? data["file_size"] : nil,
+        conversion_time_seconds: data["conversion_time_seconds"].is_a?(Numeric) ? data["conversion_time_seconds"] : nil,
+        job_id: data["job_id"].is_a?(String) ? data["job_id"] : nil
+      )
+    end
+
+    def basename_fallback(object_key)
+      parts = object_key.to_s.split("/")
+      parts.empty? ? "" : parts.last
+    end
+
+    def to_job_status(data)
+      JobStatus.new(
+        status: data["status"],
+        presigned_url: data["presigned_url"].is_a?(String) ? data["presigned_url"] : nil,
+        object_key: data["object_key"].is_a?(String) ? data["object_key"] : nil,
+        error: data["error"].is_a?(String) ? data["error"] : nil
+      )
+    end
+
+    def to_batch_submission(data)
+      BatchSubmission.new(
+        batch_id: data["batch_id"].to_s,
+        status: data["status"].is_a?(String) ? data["status"] : "processing",
+        url_count: data["url_count"].is_a?(Numeric) ? data["url_count"] : 0,
+        total_discovered: data["total_discovered"].is_a?(Numeric) ? data["total_discovered"] : nil,
+        discovery_method: data["discovery_method"].is_a?(String) ? data["discovery_method"] : nil,
+        output_format: data["output_format"].is_a?(String) ? data["output_format"] : nil
+      )
+    end
+
+    def to_batch_status(d)
+      raw_items = d["items"].is_a?(Array) ? d["items"] : []
+      BatchStatus.new(
+        batch_id: d["batch_id"].to_s,
+        status: d["status"],
+        total: d["total"].is_a?(Numeric) ? d["total"] : 0,
+        completed: d["completed"].is_a?(Numeric) ? d["completed"] : 0,
+        failed: d["failed"].is_a?(Numeric) ? d["failed"] : 0,
+        in_progress: d["in_progress"].is_a?(Numeric) ? d["in_progress"] : 0,
+        output_mode: d["output_mode"],
+        zip_download_url: d["zip_download_url"].is_a?(String) ? d["zip_download_url"] : nil,
+        items: raw_items.map do |item|
+          BatchItem.new(
+            source_url: item["source_url"].is_a?(String) ? item["source_url"] : "",
+            status: item["status"].is_a?(String) ? item["status"] : "",
+            download_url: item["download_url"].is_a?(String) ? item["download_url"] : nil,
+            output_file_size: item["output_file_size"].is_a?(Numeric) ? item["output_file_size"] : nil,
+            duration: item["duration"].is_a?(String) ? item["duration"] : nil
+          )
+        end
+      )
+    end
+  end
+end