enconvert 0.0.1

data/lib/enconvert/client.rb

@@ -0,0 +1,419 @@
+# 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

data/lib/enconvert/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Enconvert SDK exceptions.
+module Enconvert
+  # Base class for every error raised by this SDK (including client-side
+  # validation errors raised before any HTTP request is made).
+  class Error < StandardError; end
+
+  # Raised for any HTTP response with status >= 400 that isn't one of the
+  # more specific subclasses below. `status_code` carries the HTTP status.
+  class APIError < Error
+    attr_reader :status_code
+
+    def initialize(status_code, message)
+      @status_code = status_code
+      super("[#{status_code}] #{message}")
+    end
+  end
+
+  # HTTP 401 or 403 — invalid or missing API key.
+  class AuthenticationError < APIError
+    def initialize(message = "Invalid or missing API key")
+      super(401, message)
+    end
+  end
+
+  # HTTP 429 — too many requests.
+  class RateLimitError < APIError
+    def initialize(message = "Rate limit exceeded")
+      super(429, message)
+    end
+  end
+
+  # HTTP 402 — plan feature not enabled or monthly quota exhausted.
+  # V2 endpoints raise this for disabled/quota-gated features.
+  class QuotaError < APIError
+    def initialize(message = "Plan feature not enabled or quota exhausted")
+      super(402, message)
+    end
+  end
+end

data/lib/enconvert/formats.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Enconvert
+  # Format tables mirroring the gateway's CONVERTER_MAP (api/v1/convert.py).
+  #
+  # IMPLEMENTED_CONVERSIONS is the client-side gate: the gateway returns 503
+  # for any `{input}-to-{output}` endpoint not in its CONVERTER_MAP, so we
+  # reject unsupported pairs here with a useful message instead of paying a
+  # network round-trip for a guaranteed failure.
+  module Formats
+    # The 43 implemented `{input}-to-{output}` conversion endpoints.
+    IMPLEMENTED_CONVERSIONS = Set.new(
+      [
+        # Structured text (13)
+        "json-to-xml",
+        "xml-to-json",
+        "json-to-yaml",
+        "yaml-to-json",
+        "csv-to-json",
+        "json-to-csv",
+        "json-to-toml",
+        "toml-to-json",
+        "csv-to-xml",
+        "xml-to-csv",
+        "markdown-to-html",
+        "markdown-to-pdf",
+        "html-to-pdf",
+        # Documents (9) — EPUB→PDF now flows through anything-to-pdf, not a dedicated pair.
+        "doc-to-pdf",
+        "excel-to-pdf",
+        "ppt-to-pdf",
+        "odt-to-pdf",
+        "ods-to-pdf",
+        "odp-to-pdf",
+        "ots-to-pdf",
+        "pages-to-pdf",
+        "numbers-to-pdf",
+        # Images (21)
+        "jpeg-to-png",
+        "png-to-jpeg",
+        "jpeg-to-svg",
+        "svg-to-jpeg",
+        "jpeg-to-heic",
+        "heic-to-jpeg",
+        "jpeg-to-webp",
+        "webp-to-jpeg",
+        "png-to-svg",
+        "svg-to-png",
+        "png-to-heic",
+        "heic-to-png",
+        "png-to-webp",
+        "webp-to-png",
+        "svg-to-heic",
+        "heic-to-svg",
+        "svg-to-webp",
+        "webp-to-svg",
+        "heic-to-webp",
+        "webp-to-heic",
+        "pdf-to-jpeg"
+      ]
+    ).freeze
+
+    # Extension -> API format name (input side).
+    IMAGE_FORMATS = {
+      ".jpg" => "jpeg",
+      ".jpeg" => "jpeg",
+      ".png" => "png",
+      ".svg" => "svg",
+      ".heic" => "heic",
+      ".webp" => "webp",
+      # PDF is an image input solely for pdf-to-jpeg (rasterization).
+      ".pdf" => "pdf"
+    }.freeze
+
+    DOCUMENT_FORMATS = {
+      ".doc" => "doc",
+      ".docx" => "doc",
+      ".xls" => "excel",
+      ".xlsx" => "excel",
+      ".ppt" => "ppt",
+      ".pptx" => "ppt",
+      ".html" => "html",
+      ".htm" => "html",
+      ".odt" => "odt",
+      ".ods" => "ods",
+      ".odp" => "odp",
+      ".ots" => "ots",
+      ".pages" => "pages",
+      ".numbers" => "numbers",
+      # .epub has no dedicated document pair — use convert_to_pdf / convert_to_markdown.
+      ".md" => "markdown",
+      ".markdown" => "markdown",
+      ".csv" => "csv",
+      ".json" => "json",
+      ".xml" => "xml",
+      ".yaml" => "yaml",
+      ".yml" => "yaml",
+      ".toml" => "toml"
+    }.freeze
+
+    MIME_BY_EXT = {
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".png" => "image/png",
+      ".svg" => "image/svg+xml",
+      ".heic" => "image/heic",
+      ".webp" => "image/webp",
+      ".pdf" => "application/pdf",
+      ".doc" => "application/msword",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".xls" => "application/vnd.ms-excel",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      ".ppt" => "application/vnd.ms-powerpoint",
+      ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      ".html" => "text/html",
+      ".htm" => "text/html",
+      ".odt" => "application/vnd.oasis.opendocument.text",
+      ".ods" => "application/vnd.oasis.opendocument.spreadsheet",
+      ".odp" => "application/vnd.oasis.opendocument.presentation",
+      ".epub" => "application/epub+zip",
+      ".md" => "text/markdown",
+      ".markdown" => "text/markdown",
+      ".csv" => "text/csv",
+      ".json" => "application/json",
+      ".xml" => "application/xml",
+      ".yaml" => "application/x-yaml",
+      ".yml" => "application/x-yaml",
+      ".toml" => "application/toml"
+    }.freeze
+
+    # Common aliases users pass that differ from the API's canonical format names.
+    OUTPUT_FORMAT_ALIASES = {
+      "jpg" => "jpeg",
+      "yml" => "yaml",
+      "htm" => "html",
+      "md" => "markdown"
+    }.freeze
+
+    module_function
+
+    def ext_of(name)
+      s = name.to_s
+      i = s.rindex(".")
+      i.nil? ? "" : s[i..].downcase
+    end
+
+    def mime_for(name)
+      MIME_BY_EXT[ext_of(name)] || "application/octet-stream"
+    end
+
+    # Map a filename's extension to its API input format, or raise.
+    def resolve_input_format(name, map)
+      ext = ext_of(name)
+      fmt = map[ext]
+      if fmt.nil?
+        supported = map.keys.sort.join(", ")
+        raise Enconvert::Error, "Unsupported file extension '#{ext}'. Supported: #{supported}"
+      end
+      fmt
+    end
+
+    # Lowercase, strip a leading dot, and resolve aliases (jpg, yml, htm, md).
+    def normalize_output_format(fmt)
+      f = fmt.to_s.downcase.sub(/\A\./, "")
+      OUTPUT_FORMAT_ALIASES[f] || f
+    end
+
+    # List the output formats the API implements for a given input format.
+    def valid_outputs_for(input_format)
+      prefix = "#{input_format}-to-"
+      IMPLEMENTED_CONVERSIONS.to_a
+                             .select { |name| name.start_with?(prefix) }
+                             .map { |name| name[prefix.length..] }
+                             .sort
+    end
+
+    # Assert `{input}-to-{output}` is an implemented endpoint and return its
+    # name. Raises with the list of valid outputs for that input otherwise.
+    def assert_conversion_implemented(input_format, output_format)
+      endpoint = "#{input_format}-to-#{output_format}"
+      unless IMPLEMENTED_CONVERSIONS.include?(endpoint)
+        outputs = valid_outputs_for(input_format)
+        hint = if outputs.empty?
+                 "No conversions are available for input format '#{input_format}'"
+               else
+                 "Supported outputs for '#{input_format}': #{outputs.join(', ')}"
+               end
+        raise Enconvert::Error, "Conversion '#{input_format}' to '#{output_format}' is not supported. #{hint}."
+      end
+      endpoint
+    end
+  end
+end