poli-page 0.9.0

data/lib/poli_page/client.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "retry_event"
+require_relative "internal/constants"
+require_relative "internal/http"
+require_relative "internal/presigned_fetch"
+require_relative "internal/transport"
+require_relative "internal/uuid"
+require_relative "internal/wire"
+require_relative "render"
+require_relative "documents"
+
+module PoliPage
+  # Main entry point — orchestrates retries, fires hooks, and delegates HTTP
+  # execution to `PoliPage::Internal::Transport`. The `render` and `documents`
+  # resource namespaces hold a reference to this client and delegate request
+  # execution back through it.
+  #
+  # Thread-safety: configuration is immutable after `#initialize`; each
+  # request opens its own `Net::HTTP` connection. A single `Client` may be
+  # safely shared across threads — build one at boot and reuse it.
+  #
+  # @example Construct with defaults
+  #   client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))
+  #
+  # @example Construct with full configuration
+  #   client = PoliPage::Client.new(
+  #     api_key:     ENV.fetch("POLI_PAGE_API_KEY"),
+  #     base_url:    "https://api.example.com",
+  #     max_retries: 3,
+  #     retry_delay: 0.5,                            # seconds
+  #     timeout:     30,                             # seconds
+  #     logger:      Logger.new($stdout),
+  #     on_retry:    ->(e) { metrics.increment("polipage.retry") },
+  #     on_error:    ->(err) { Sentry.capture_exception(err) },
+  #     proxy:       "http://user:pass@proxy.example.com:8080",
+  #     ca_file:     "/etc/ssl/corp-mitm-ca.pem"
+  #   )
+  #
+  # @example Behind a corporate egress proxy (env-detected)
+  #   # `http_proxy` / `https_proxy` / `no_proxy` env vars are honoured
+  #   # automatically — no `proxy:` kwarg needed.
+  #   client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))
+  class Client
+    include Internal::PresignedFetch
+
+    attr_reader :base_url, :max_retries, :retry_delay, :timeout, :render, :documents
+
+    def initialize(api_key:, base_url: Internal::Constants::DEFAULT_BASE_URL,
+                   max_retries: Internal::Constants::DEFAULT_MAX_RETRIES,
+                   retry_delay: Internal::Constants::DEFAULT_RETRY_DELAY,
+                   timeout: Internal::Constants::DEFAULT_TIMEOUT,
+                   logger: nil, on_request: nil, on_response: nil,
+                   on_retry: nil, on_error: nil,
+                   proxy: nil, ca_file: nil, ca_path: nil)
+      raise InvalidOptionsError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key     = api_key
+      @base_url    = base_url
+      @max_retries = max_retries
+      @retry_delay = retry_delay
+      @timeout     = timeout
+      @logger      = logger
+      @on_request  = on_request
+      @on_response = on_response
+      @on_retry    = on_retry
+      @on_error    = on_error
+      @proxy       = proxy
+      @ca_file     = ca_file
+      @ca_path     = ca_path
+      init_collaborators
+    end
+
+    # Redacted `#inspect`. Ruby's default would dump `@api_key` into any
+    # `puts client` or exception backtrace — that's how secrets end up in
+    # logs (sdk-ruby-plan.md §10.1 redaction rule).
+    def inspect
+      "#<PoliPage::Client base_url=#{@base_url.inspect} timeout=#{@timeout} max_retries=#{@max_retries}>"
+    end
+    alias to_s inspect
+
+    # Execute a POST request against `path` with `body` (snake_case hash;
+    # caller's responsibility to compact nils). Returns the parsed
+    # snake_case-symbol-keyed Hash on 2xx, or raises a `PoliPage::Error`.
+    #
+    # @api private
+    def execute_post(path, body:, idempotency_key: nil)
+      wire_body = JSON.generate(Internal::Wire.to_wire(body))
+      response = run_with_retry(method: :post, path: path, body: wire_body,
+                                idempotency_key: idempotency_key || Internal::UUID.generate)
+      parse_json_response(response)
+    end
+
+    # Execute a GET request against `path`. Returns the parsed
+    # snake_case-symbol-keyed Hash on 2xx, or raises a `PoliPage::Error`.
+    #
+    # @api private
+    def execute_get(path)
+      response = run_with_retry(method: :get, path: path, body: nil, idempotency_key: nil)
+      parse_json_response(response)
+    end
+
+    # Execute a DELETE request against `path`. Returns nil on 2xx; the
+    # response body is ignored. Raises `PoliPage::Error` on non-2xx.
+    #
+    # @api private
+    def execute_delete(path)
+      run_with_retry(method: :delete, path: path, body: nil, idempotency_key: nil)
+      nil
+    end
+
+    # Execute a GET request and return the raw `Internal::Transport::Response`
+    # (body + headers) without JSON parsing. Used by `documents.preview` which
+    # gets `text/html` directly plus the page count via the
+    # `X-Document-Page-Count` response header.
+    #
+    # @api private
+    def execute_get_raw(path)
+      run_with_retry(method: :get, path: path, body: nil, idempotency_key: nil)
+    end
+
+    private
+
+    def init_collaborators
+      @transport = Internal::Transport.new(base_url: @base_url, timeout: @timeout,
+                                           proxy: @proxy, ca_file: @ca_file, ca_path: @ca_path)
+      @render = Resources::Render.new(self)
+      @documents = Resources::Documents.new(self)
+    end
+
+    def run_with_retry(method:, path:, body:, idempotency_key:)
+      state = { last_error: nil, next_retry_after: nil }
+
+      (0..@max_retries).each do |attempt|
+        sleep_before_retry(attempt, state) if attempt.positive?
+        result = send_once(method: method, path: path, body: body,
+                           idempotency_key: idempotency_key, attempt: attempt + 1)
+        return result[:response] if result[:ok]
+
+        record_failure(state, result)
+        raise_terminal(state[:last_error]) unless result[:retryable]
+      end
+
+      raise_terminal(state[:last_error])
+    end
+
+    def record_failure(state, result)
+      state[:last_error] = result[:error]
+      state[:next_retry_after] = result[:retry_after]
+    end
+
+    def sleep_before_retry(attempt, state)
+      delay = Internal::HTTP.compute_backoff(attempt: attempt, base_delay: @retry_delay,
+                                             retry_after: state[:next_retry_after])
+      fire_hook(@on_retry,
+                RetryEvent.new(attempt: attempt + 1, delay_ms: (delay * 1000).round,
+                               reason: state[:last_error]))
+      sleep(delay)
+    end
+
+    def raise_terminal(error)
+      fire_hook(@on_error, error)
+      raise error
+    end
+
+    def send_once(method:, path:, body:, idempotency_key:, attempt:)
+      headers = build_request_headers(method, idempotency_key)
+      url = Internal::HTTP.build_url(@base_url, path)
+      fire_hook(@on_request,
+                RequestEvent.new(method: method.to_s.upcase, url: url, attempt: attempt))
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = @transport.execute(method: method, path: path, headers: headers, body: body)
+      return success_result(response, started_at) if (200..299).cover?(response.status)
+
+      build_error_result(response)
+    rescue PoliPage::TimeoutError, PoliPage::ConnectionError => e
+      { ok: false, error: e, retry_after: nil, retryable: true }
+    end
+
+    def build_request_headers(method, idempotency_key)
+      Internal::HTTP.build_headers(
+        method: method, api_key: @api_key,
+        idempotency_key: idempotency_key,
+        user_agent: "poli-page-sdk-ruby/#{PoliPage::VERSION}"
+      )
+    end
+
+    def success_result(response, started_at)
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+      fire_hook(@on_response,
+                ResponseEvent.new(
+                  status: response.status,
+                  request_id: response.headers[Internal::Constants::HEADER_REQUEST_ID],
+                  duration_ms: duration_ms
+                ))
+      { ok: true, response: response }
+    end
+
+    def build_error_result(response)
+      status = response.status
+      request_id = response.headers[Internal::Constants::HEADER_REQUEST_ID]
+      code, message = Internal::HTTP.parse_error_body(response.body.to_s, status)
+      error = Internal::HTTP.classify(status: status, code: code, message: message, request_id: request_id)
+      retryable = status >= 500 || status == 429
+      retry_after_header = response.headers[Internal::Constants::HEADER_RETRY_AFTER]
+      retry_after = retryable ? Internal::HTTP.parse_retry_after(retry_after_header) : nil
+      { ok: false, error: error, retry_after: retry_after, retryable: retryable }
+    end
+
+    def parse_json_response(response)
+      parsed = JSON.parse(response.body)
+      Internal::Wire.from_wire(parsed)
+    rescue JSON::ParserError => e
+      raise PoliPage::InternalError.new("response body was not valid JSON: #{e.message}", status: response.status)
+    end
+
+    def fire_hook(hook, event)
+      return unless hook
+
+      hook.call(event)
+    rescue StandardError => e
+      @logger&.warn("polipage hook raised: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/poli_page/documents.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "models/document_descriptor"
+require_relative "models/document_preview_result"
+require_relative "models/thumbnail"
+
+module PoliPage
+  module Resources
+    # `client.documents` namespace (sdk-ruby-plan.md §13 Phase 4, port of
+    # sdk-node/src/documents.ts).
+    class Documents
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /v1/documents/:id — returns a `DocumentDescriptor` with the
+      # client back-reference attached so `#download_pdf` works.
+      #
+      # @param id [String] the document id (e.g. `"doc_abc123"`)
+      # @return [PoliPage::DocumentDescriptor]
+      # @raise  [PoliPage::NotFoundError] on 404
+      # @raise  [PoliPage::GoneError]     on 410 (soft-deleted)
+      #
+      # @example Re-fetch a stored document and download its PDF
+      #   doc = client.documents.get("doc_abc123")
+      #   File.binwrite("invoice.pdf", doc.download_pdf)
+      def get(id)
+        parsed = @client.execute_get(path_for(id))
+        parsed[:metadata] ||= {}
+        PoliPage::DocumentDescriptor.new(**parsed, _client: @client)
+      end
+
+      # GET /v1/documents/:id/preview — returns the stored paginated HTML
+      # plus the page count carried by the `X-Document-Page-Count` response
+      # header. The body is `text/html`, NOT a JSON envelope. No engine work
+      # — this is a snapshot read of the stored document.
+      #
+      # @param id [String]
+      # @return   [PoliPage::DocumentPreviewResult] `{ html:, page_count: }`
+      #
+      # @example
+      #   stored = client.documents.preview("doc_abc123")
+      #   File.write("preview.html", stored.html)
+      #   puts "#{stored.page_count} pages"
+      def preview(id)
+        response = @client.execute_get_raw("#{path_for(id)}/preview")
+        page_count_header = response.headers[Internal::Constants::HEADER_DOCUMENT_PAGE_COUNT]
+        page_count = page_count_header.to_s.match?(/\A\d+\z/) ? page_count_header.to_i : 0
+        PoliPage::DocumentPreviewResult.new(html: response.body.to_s, page_count: page_count)
+      end
+
+      # POST /v1/documents/:id/thumbnails — the deployed API expects the
+      # options nested under a `thumbnails` key. The response envelope
+      # `{ thumbnails: [...] }` is unwrapped here. Returns an Array of
+      # `PoliPage::Thumbnail`; each carries base64-encoded image bytes in
+      # `data` (decode with `Base64.decode64(thumb.data)`).
+      #
+      # @param id      [String]
+      # @param options [Hash] Forwarded to the wire under `thumbnails:`.
+      #   - `width:` [Integer] (required)
+      #   - `format:` ["png" | "jpeg"]
+      #   - `quality:` [Integer] JPEG quality 1-100 (jpeg only)
+      #   - `pages:` [Array<Integer>] 1-based page indices; default all pages
+      # @return [Array<PoliPage::Thumbnail>]
+      #
+      # @example
+      #   thumbs = client.documents.thumbnails("doc_abc123", width: 320, format: "png", pages: [1])
+      #   File.binwrite("page1.png", Base64.decode64(thumbs.first.data))
+      def thumbnails(id, **options)
+        validate_thumbnail_options!(options)
+        body = { thumbnails: options.compact }
+        parsed = @client.execute_post("#{path_for(id)}/thumbnails", body: body)
+        parsed[:thumbnails].map { |t| PoliPage::Thumbnail.new(**t) }
+      end
+
+      # DELETE /v1/documents/:id — returns nil. Re-deleting an
+      # already-deleted document surfaces as `PoliPage::GoneError` (HTTP
+      # 410) — no special handling here.
+      #
+      # @param id [String]
+      # @return   [nil]
+      # @raise    [PoliPage::GoneError] if already deleted
+      #
+      # @example
+      #   client.documents.delete("doc_abc123")
+      def delete(id)
+        @client.execute_delete(path_for(id))
+        nil
+      end
+
+      private
+
+      # Ruby 3.2+ `URI.encode_uri_component` matches JS `encodeURIComponent`
+      # (used by sdk-node). `CGI.escape` would form-encode spaces as `+`,
+      # which the deployed API rejects in path segments.
+      def path_for(id)
+        "#{Internal::Constants::PATH_DOCUMENTS}/#{URI.encode_uri_component(id)}"
+      end
+
+      # Local arg validation — fail fast with a clear `InvalidOptionsError`
+      # before issuing the HTTP request. Mirrors the server's invariants for
+      # `documents.thumbnails` (sdk-specification.md / Node SDK).
+      def validate_thumbnail_options!(options)
+        validate_thumbnail_width!(options[:width])
+        validate_thumbnail_format!(options[:format])
+        validate_thumbnail_quality!(options[:quality], options[:format])
+        validate_thumbnail_pages!(options[:pages])
+      end
+
+      def validate_thumbnail_width!(width)
+        return if width.is_a?(Integer) && width.positive?
+
+        raise PoliPage::InvalidOptionsError,
+              "thumbnails: width is required and must be a positive Integer (got #{width.inspect})"
+      end
+
+      def validate_thumbnail_format!(format)
+        return if format.nil? || %w[png jpeg].include?(format)
+
+        raise PoliPage::InvalidOptionsError,
+              "thumbnails: format must be 'png' or 'jpeg' (got #{format.inspect})"
+      end
+
+      def validate_thumbnail_quality!(quality, format)
+        return if quality.nil?
+
+        unless format == "jpeg"
+          raise PoliPage::InvalidOptionsError,
+                "thumbnails: quality is only valid with format: 'jpeg'"
+        end
+        return if quality.is_a?(Integer) && (1..100).cover?(quality)
+
+        raise PoliPage::InvalidOptionsError,
+              "thumbnails: quality must be an Integer between 1 and 100 (got #{quality.inspect})"
+      end
+
+      def validate_thumbnail_pages!(pages)
+        return if pages.nil?
+        return if pages.is_a?(Array) && pages.all? { |p| p.is_a?(Integer) && p.positive? }
+
+        raise PoliPage::InvalidOptionsError,
+              "thumbnails: pages must be an Array of positive Integers (got #{pages.inspect})"
+      end
+    end
+  end
+end

data/lib/poli_page/errors.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Base for all SDK-raised errors. Inherits from `StandardError` so that
+  # `rescue => e` catches it (whereas inheriting from `Exception` would
+  # bypass the default rescue and surprise callers).
+  #
+  # The rescue-friendly path is the class hierarchy
+  # (`rescue PoliPage::AuthenticationError`); the predicate methods below are
+  # kept for spec parity with the Node SDK and for callers who want a single
+  # rescue clause backed by introspection.
+  class Error < StandardError
+    attr_reader :code, :status, :request_id
+
+    def initialize(message = nil, code:, status: nil, request_id: nil)
+      super(message)
+      @code       = code
+      @status     = status
+      @request_id = request_id
+    end
+
+    def auth_error?
+      is_a?(AuthenticationError) || is_a?(PermissionDeniedError)
+    end
+
+    def rate_limit_error?
+      is_a?(RateLimitError)
+    end
+
+    def validation_error?
+      is_a?(ValidationError)
+    end
+
+    def network_error?
+      is_a?(ConnectionError) || is_a?(TimeoutError)
+    end
+
+    def retryable?
+      return true if network_error?
+      return true if status && (status >= 500 || status == 429)
+
+      false
+    end
+
+    # Canonical wire payload for framework integrations:
+    # `{code:, message:, status:, request_id:}`. `status` surfaces 503 for
+    # connection failures, 504 for timeouts, the API HTTP status for
+    # status-bearing errors. The {#status} reader itself stays nil for
+    # transport-error instances — only the payload surfaces 503/504.
+    def to_payload
+      {
+        code: @code,
+        message: message,
+        status: payload_status,
+        request_id: @request_id
+      }
+    end
+
+    def payload_status
+      @status
+    end
+  end
+
+  # API status errors. `status` carries the HTTP status; `code` is the
+  # machine-readable string from the response body. The subclass picked for a
+  # given status is decided by `PoliPage::Internal::HTTP.classify`.
+  #
+  #   400 → ValidationError
+  #   401 → AuthenticationError
+  #   403 → PermissionDeniedError
+  #   404 → NotFoundError
+  #   410 → GoneError
+  #   429 → RateLimitError
+  #   other 4xx / 5xx → APIError
+  class ValidationError       < Error; end
+  class AuthenticationError   < Error; end
+  class PermissionDeniedError < Error; end
+  class NotFoundError         < Error; end
+  class GoneError             < Error; end
+  class RateLimitError        < Error; end
+  class APIError              < Error; end
+
+  # --- SDK-internal errors. `status` is nil except where the SDK observed a
+  # status from a non-API hop (e.g., the S3 second-hop for DownloadError). ---
+
+  class InvalidOptionsError < Error
+    def initialize(message, code: "invalid_options")
+      super(message, code: code, status: nil, request_id: nil)
+    end
+  end
+
+  class ConnectionError < Error
+    attr_reader :cause
+
+    def initialize(message:, cause: nil)
+      super(message, code: "network_error", status: nil, request_id: nil)
+      @cause = cause
+    end
+
+    def payload_status
+      503
+    end
+  end
+
+  class TimeoutError < Error
+    attr_reader :timeout
+
+    def initialize(timeout:)
+      super("request timed out after #{timeout}s",
+            code: "timeout", status: nil, request_id: nil)
+      @timeout = timeout
+    end
+
+    def payload_status
+      504
+    end
+  end
+
+  class DownloadError < Error
+    def initialize(message:, status: nil)
+      super(message, code: "DOWNLOAD_FAILED", status: status, request_id: nil)
+    end
+  end
+
+  class InternalError < Error
+    def initialize(message, status: nil)
+      super(message, code: "INTERNAL_ERROR", status: status, request_id: nil)
+    end
+  end
+
+  # Known API codes (sdk-ruby-plan.md §7.4). The SDK passes through whatever
+  # the API returns — callers may still see codes not in this list. Note:
+  # `STORAGE_REQUIRED` was retired from the deployed API and is NOT exported.
+  module ErrorCodes
+    MISSING_API_KEY               = "MISSING_API_KEY"
+    INVALID_API_KEY               = "INVALID_API_KEY"
+    PAYMENT_REQUIRED              = "PAYMENT_REQUIRED"
+    FORBIDDEN                     = "FORBIDDEN"
+    ORGANIZATION_CANCELLED        = "ORGANIZATION_CANCELLED"
+    ORGANIZATION_PURGED           = "ORGANIZATION_PURGED"
+    NOT_FOUND                     = "NOT_FOUND"
+    VERSION_NOT_FOUND             = "VERSION_NOT_FOUND"
+    DOCUMENT_NOT_FOUND            = "DOCUMENT_NOT_FOUND"
+    GONE                          = "GONE"
+    VALIDATION_ERROR              = "VALIDATION_ERROR"
+    MISSING_DATA                  = "MISSING_DATA"
+    MISSING_PROJECT_OR_TEMPLATE   = "MISSING_PROJECT_OR_TEMPLATE"
+    MISSING_TEMPLATE_SLUG         = "MISSING_TEMPLATE_SLUG"
+    PROJECT_REQUIRED_FOR_DOCUMENT = "PROJECT_REQUIRED_FOR_DOCUMENT"
+    INVALID_VERSION_FORMAT        = "INVALID_VERSION_FORMAT"
+    VERSION_REQUIRED              = "VERSION_REQUIRED"
+    INVALID_VERSION_FOR_KEY_ENV   = "INVALID_VERSION_FOR_KEY_ENV"
+    QUOTA_EXCEEDED                = "QUOTA_EXCEEDED"
+    OVERAGE_CAP_EXCEEDED          = "OVERAGE_CAP_EXCEEDED"
+    INTERNAL_ERROR                = "INTERNAL_ERROR"
+  end
+end

data/lib/poli_page/inputs/inline_mode_input.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Convenience value-object form of the inline-mode render input. Inline
+  # mode is only accepted by `client.render.preview` (sdk-ruby-plan.md §13
+  # Phase 2); the render-to-document methods require project mode.
+  InlineModeInput = Data.define(
+    :template,
+    :data,
+    :format,
+    :orientation,
+    :locale,
+    :metadata,
+    :idempotency_key
+  ) do
+    def to_h
+      super.compact
+    end
+  end
+
+  class << InlineModeInput
+    alias _strict_new new
+
+    def new(template:, data:, format: nil, orientation: nil, locale: nil,
+            metadata: nil, idempotency_key: nil)
+      _strict_new(template: template, data: data, format: format,
+                  orientation: orientation, locale: locale, metadata: metadata,
+                  idempotency_key: idempotency_key)
+    end
+  end
+end

data/lib/poli_page/inputs/project_mode_input.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Convenience value-object form of the project-mode render input. Methods
+  # accept bare kwargs directly; this wrapper is for callers who want
+  # `Data.define`'s equality, frozen-by-default semantics, and a single
+  # marshallable type to thread through their own code.
+  ProjectModeInput = Data.define(
+    :project,
+    :template,
+    :data,
+    :version,
+    :format,
+    :orientation,
+    :locale,
+    :metadata,
+    :idempotency_key
+  ) do
+    # @return [Hash] kwargs ready to splat into the matching `client.render.*` method
+    def to_h
+      super.compact
+    end
+  end
+
+  # Allow positional-as-keyword construction with optional fields defaulted to nil
+  # — Data.define is strict by default. We re-open the class only to add a
+  # forgiving constructor that lets callers omit the optional knobs.
+  class << ProjectModeInput
+    alias _strict_new new
+
+    def new(project:, template:, data:, version: nil, format: nil,
+            orientation: nil, locale: nil, metadata: nil, idempotency_key: nil)
+      _strict_new(project: project, template: template, data: data,
+                  version: version, format: format, orientation: orientation,
+                  locale: locale, metadata: metadata, idempotency_key: idempotency_key)
+    end
+  end
+end

data/lib/poli_page/inputs/thumbnail_options.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Convenience value-object form of the `client.documents.thumbnails`
+  # options hash. Methods accept bare kwargs directly; this wrapper is for
+  # callers who want `Data.define`'s equality + frozen-by-default semantics.
+  #
+  # - `width`   [Integer]                   thumbnail width in pixels (required)
+  # - `format`  ["png", "jpeg", nil]        output format; default "png"
+  # - `quality` [Integer, nil]              JPEG quality 1-100; only valid when format is "jpeg"
+  # - `pages`   [Array<Integer>, nil]       1-based page indices to render; nil means all pages
+  ThumbnailOptions = Data.define(:width, :format, :quality, :pages) do
+    def to_h
+      super.compact
+    end
+  end
+
+  class << ThumbnailOptions
+    alias _strict_new new
+
+    def new(width:, format: nil, quality: nil, pages: nil)
+      _strict_new(width: width, format: format, quality: quality, pages: pages)
+    end
+  end
+end

data/lib/poli_page/internal/constants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # Internal constants. Convention-private; do not depend on these from
+    # outside the gem (no semver protection).
+    module Constants
+      # API paths (relative to the configured base URL).
+      PATH_RENDER          = "/v1/render"
+      PATH_RENDER_PREVIEW  = "/v1/render/preview"
+      PATH_DOCUMENTS       = "/v1/documents"
+
+      # Defaults (in seconds where applicable — Ruby's `Kernel#sleep`,
+      # `Net::HTTP#open_timeout`, etc. all use seconds).
+      DEFAULT_BASE_URL     = "https://api.poli.page"
+      DEFAULT_MAX_RETRIES  = 2
+      DEFAULT_RETRY_DELAY  = 0.5      # Node: 500 ms.
+      DEFAULT_TIMEOUT      = 60       # Node: 60_000 ms.
+      RETRY_AFTER_CAP      = 30       # Node: 30_000 ms.
+
+      # Header names (lowercase form — Net::HTTP normalises to lowercase on
+      # the way back; matches the Node `x-request-id` convention).
+      HEADER_AUTHORIZATION   = "Authorization"
+      HEADER_ACCEPT          = "Accept"
+      HEADER_CONTENT_TYPE    = "Content-Type"
+      HEADER_USER_AGENT      = "User-Agent"
+      HEADER_IDEMPOTENCY_KEY = "Idempotency-Key"
+      HEADER_REQUEST_ID      = "x-request-id"
+      HEADER_RETRY_AFTER     = "retry-after"
+
+      # Document-preview response header carrying the page count
+      # (mirrors Node `documents.ts:75-77`).
+      HEADER_DOCUMENT_PAGE_COUNT = "x-document-page-count"
+    end
+  end
+end