poli-page 0.9.0

data/lib/poli_page/internal/http.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "constants"
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # Pure transport helpers — no I/O, no socket access. Mirrors
+    # `sdk-node/src/internal/http.ts` (sdk-ruby-plan.md §13 Phase 1).
+    module HTTP
+      module_function
+
+      # @param base [String] e.g. "https://api.poli.page"
+      # @param path [String] e.g. "/v1/render"
+      # @return [String] the joined URL with exactly one slash between the two
+      def build_url(base, path)
+        "#{base.chomp("/")}/#{path.sub(%r{\A/}, "")}"
+      end
+
+      # @param method         [Symbol] :get, :post, or :delete
+      # @param api_key        [String]
+      # @param idempotency_key [String, nil] only used on POST
+      # @param user_agent     [String]
+      # @return [Hash{String=>String}]
+      def build_headers(method:, api_key:, idempotency_key:, user_agent:)
+        headers = {
+          Constants::HEADER_ACCEPT        => "application/json",
+          Constants::HEADER_AUTHORIZATION => "Bearer #{api_key}",
+          Constants::HEADER_USER_AGENT    => user_agent
+        }
+        if method == :post
+          headers[Constants::HEADER_CONTENT_TYPE] = "application/json"
+          headers[Constants::HEADER_IDEMPOTENCY_KEY] = idempotency_key if idempotency_key
+        end
+        headers
+      end
+
+      # Parse a non-2xx response body into a `[code, message]` pair. Falls
+      # back to `INTERNAL_ERROR` when the body is not parseable JSON. The
+      # fallback chain (`code → message → error → 'unknown_error'`) is
+      # ported verbatim from Node `parseErrorBody` (sdk-ruby-plan.md §7.3).
+      #
+      # @param body   [String]
+      # @param status [Integer]
+      # @return       [Array(String, String)] `[code, message]`
+      def parse_error_body(body, status)
+        parsed = parse_json_or_nil(body)
+        unless parsed.is_a?(Hash)
+          return ["INTERNAL_ERROR",
+                  "HTTP #{status}: response body was not valid JSON"]
+        end
+
+        # RFC 7807: prefer `detail` (specific reason) over `title` (generic name)
+        # over the legacy `message` field; fall back to a canned status string.
+        # Code is verbatim from the API — never inferred from message.
+        code = parsed.values_at("code", "error").compact.first || "unknown_error"
+        message = parsed.values_at("detail", "title", "message").compact.first || "HTTP #{status}"
+        [code, message]
+      end
+
+      def parse_json_or_nil(body)
+        JSON.parse(body)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      # Parse the `Retry-After` response header. Accepts an integer number
+      # of seconds or an HTTP-date. Returns the delay in **seconds** (Ruby's
+      # `Kernel#sleep` and `Net::HTTP#*_timeout` units), capped at
+      # `RETRY_AFTER_CAP` (30 s). Returns `nil` when the header is missing or
+      # unparseable. Mirrors Node `parseRetryAfter` modulo unit (ms → s).
+      def parse_retry_after(header_value)
+        return nil if header_value.nil? || header_value.empty?
+
+        return header_value.to_i.clamp(0, Constants::RETRY_AFTER_CAP) if /\A\d+\z/.match?(header_value)
+
+        begin
+          target = Time.httpdate(header_value)
+        rescue ArgumentError
+          return nil
+        end
+        (target - Time.now).floor.clamp(0, Constants::RETRY_AFTER_CAP)
+      end
+
+      # Compute the delay (in seconds) before the next retry attempt. When
+      # `retry_after` is non-nil, it is returned as-is (server-explicit, no
+      # jitter). Otherwise: `base_delay * 2**(attempt-1) * (0.5 + rand)`.
+      # `attempt` is 1-based: 1 means the first retry.
+      def compute_backoff(attempt:, base_delay:, retry_after: nil)
+        return retry_after unless retry_after.nil?
+
+        exp = base_delay * (2**(attempt - 1))
+        exp * (0.5 + rand)
+      end
+
+      # Map an API response (status + parsed code/message) to the most
+      # specific `PoliPage::Error` subclass (sdk-ruby-plan.md §7).
+      #
+      # @param status     [Integer]
+      # @param code       [String]
+      # @param message    [String]
+      # @param request_id [String, nil]
+      # @return           [PoliPage::Error]
+      def classify(status:, code:, message:, request_id:)
+        klass = STATUS_MAP.fetch(status, PoliPage::APIError)
+        klass.new(message, code: code, status: status, request_id: request_id)
+      end
+
+      STATUS_MAP = {
+        400 => PoliPage::ValidationError,
+        401 => PoliPage::AuthenticationError,
+        403 => PoliPage::PermissionDeniedError,
+        404 => PoliPage::NotFoundError,
+        410 => PoliPage::GoneError,
+        429 => PoliPage::RateLimitError
+      }.freeze
+    end
+  end
+end

data/lib/poli_page/internal/presigned_fetch.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # Mixin used by `PoliPage::Client` for the unauthenticated presigned-URL
+    # second hop (DocumentDescriptor#download_pdf, render.pdf, pdf_stream).
+    # The presigned URL is signed by S3 and MUST NOT be retried by the SDK
+    # (sdk-ruby-plan.md §5.5).
+    #
+    # Honors the same proxy/CA configuration as {PoliPage::Internal::Transport}
+    # — reads `@proxy`, `@ca_file`, `@ca_path`, `@timeout` from the including
+    # `Client` instance.
+    module PresignedFetch
+      # Fetch the entire body of `url`. Returns the raw bytes; raises
+      # PoliPage::DownloadError on non-2xx or network failure.
+      def fetch_bytes(url)
+        uri = URI.parse(url)
+        response = start_presigned(uri) { |http| http.request(Net::HTTP::Get.new(uri.request_uri)) }
+        guard_presigned_status!(response)
+        response.body
+      rescue *PRESIGNED_NETWORK_ERRORS => e
+        raise PoliPage::DownloadError.new(message: e.message)
+      end
+
+      # Stream the body of `url` to the block. Raises PoliPage::DownloadError
+      # on non-2xx and PoliPage::InternalError on Content-Length: 0 (port of
+      # Node `render.ts:128-130` `!response.body` guard).
+      def stream_bytes(url, &block)
+        uri = URI.parse(url)
+        start_presigned(uri) do |http|
+          http.request_get(uri.request_uri) { |response| yield_stream_chunks(response, &block) }
+        end
+      rescue *PRESIGNED_NETWORK_ERRORS => e
+        raise PoliPage::DownloadError.new(message: e.message)
+      end
+
+      PRESIGNED_NETWORK_ERRORS = [
+        SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+        Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError
+      ].freeze
+      private_constant :PRESIGNED_NETWORK_ERRORS
+
+      private
+
+      def start_presigned(uri, &)
+        p_addr, p_port, p_user, p_pass = presigned_proxy_args
+        opts = {
+          use_ssl:      uri.scheme == "https",
+          open_timeout: @timeout,
+          read_timeout: @timeout
+        }
+        opts[:ca_file] = @ca_file if @ca_file
+        opts[:ca_path] = @ca_path if @ca_path
+        Net::HTTP.start(uri.host, uri.port, p_addr, p_port, p_user, p_pass, opts, &)
+      end
+
+      def presigned_proxy_args
+        return [:ENV, nil, nil, nil] if @proxy.nil?
+
+        pu = URI.parse(@proxy)
+        [pu.host, pu.port, pu.user, pu.password]
+      end
+
+      def guard_presigned_status!(response)
+        status = response.code.to_i
+        return if (200..299).cover?(status)
+
+        raise PoliPage::DownloadError.new(
+          message: "Failed to download: #{status} #{response.message}",
+          status:  status
+        )
+      end
+
+      def yield_stream_chunks(response, &)
+        guard_presigned_status!(response)
+        status = response.code.to_i
+        raise PoliPage::InternalError.new("response has no body", status: status) if response["Content-Length"] == "0"
+
+        response.read_body(&)
+      end
+    end
+  end
+end

data/lib/poli_page/internal/transport.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+require_relative "http"
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # Thin wrapper around `Net::HTTP`. The ONLY module that opens sockets
+    # (sdk-ruby-plan.md §3.2). Translates network-level exceptions into the
+    # `PoliPage::Error` hierarchy at the seam (§8 error mapping).
+    #
+    # Honors `http_proxy`, `https_proxy`, and `no_proxy` environment variables
+    # by default (via `Net::HTTP`'s `:ENV` proxy resolution). Pass `proxy:` to
+    # force an explicit proxy URL or `ca_file:` / `ca_path:` to point at a
+    # custom CA bundle (e.g., a corporate MITM TLS-terminating proxy).
+    class Transport
+      Response = Data.define(:status, :headers, :body)
+
+      VERBS = {
+        get:    Net::HTTP::Get,
+        post:   Net::HTTP::Post,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      def initialize(base_url:, timeout:, proxy: nil, ca_file: nil, ca_path: nil)
+        @base_url = base_url
+        @timeout  = timeout
+        @proxy    = proxy
+        @ca_file  = ca_file
+        @ca_path  = ca_path
+      end
+
+      # @param method  [Symbol]               :get, :post, or :delete
+      # @param path    [String]               e.g. "/v1/render"
+      # @param headers [Hash{String=>String}]
+      # @param body    [String, nil]          JSON-encoded body or nil
+      # @return        [Response]
+      # @raise         [PoliPage::TimeoutError, PoliPage::ConnectionError]
+      def execute(method:, path:, headers:, body: nil)
+        uri = URI.parse(HTTP.build_url(@base_url, path))
+        build_response(perform_request(uri, build_request(method, uri, headers, body)))
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+        raise PoliPage::TimeoutError.new(timeout: @timeout)
+      rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+             Errno::EHOSTUNREACH, Errno::ENETUNREACH, OpenSSL::SSL::SSLError => e
+        raise PoliPage::ConnectionError.new(message: e.message, cause: e)
+      end
+
+      private
+
+      def perform_request(uri, request)
+        p_addr, p_port, p_user, p_pass = proxy_args
+        opts = {
+          use_ssl:       uri.scheme == "https",
+          open_timeout:  @timeout,
+          read_timeout:  @timeout,
+          write_timeout: @timeout
+        }
+        opts[:ca_file] = @ca_file if @ca_file
+        opts[:ca_path] = @ca_path if @ca_path
+        Net::HTTP.start(uri.host, uri.port, p_addr, p_port, p_user, p_pass, opts) do |http|
+          http.request(request)
+        end
+      end
+
+      # Default `:ENV` lets `Net::HTTP` resolve `http_proxy` / `https_proxy` /
+      # `no_proxy` (via `URI#find_proxy`) per-request. Returning a tuple lets
+      # us pass positionally without keyword/positional ambiguity.
+      def proxy_args
+        return [:ENV, nil, nil, nil] if @proxy.nil?
+
+        pu = URI.parse(@proxy)
+        [pu.host, pu.port, pu.user, pu.password]
+      end
+
+      def build_response(response)
+        Response.new(
+          status:  response.code.to_i,
+          headers: response.to_hash.transform_values { |v| v.is_a?(Array) ? v.first : v },
+          body:    response.body
+        )
+      end
+
+      def build_request(method, uri, headers, body)
+        verb_class = VERBS.fetch(method) { raise ArgumentError, "unsupported method: #{method.inspect}" }
+        request = verb_class.new(uri.request_uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = body if body && method == :post
+        request
+      end
+    end
+  end
+end

data/lib/poli_page/internal/uuid.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # Thin wrapper over `SecureRandom.uuid`. Indirection exists so a future
+    # swap (e.g. UUIDv7 once the stdlib lands `SecureRandom.uuid_v7`) is a
+    # one-file change (sdk-ruby-plan.md §13 Phase 1).
+    module UUID
+      module_function
+
+      def generate
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/poli_page/internal/wire.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PoliPage
+  module Internal
+    # @api private
+    #
+    # snake_case ↔ camelCase translator (sdk-ruby-plan.md §5.4). Pure, no
+    # runtime dependency on metaprogramming DSLs. Outgoing: hash keys are
+    # stringified and camelized. Incoming: hash keys are snake_cased and
+    # symbolized.
+    module Wire
+      module_function
+
+      def to_wire(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), h|
+            h[snake_to_camel(k.to_s)] = to_wire(v)
+          end
+        when Array
+          value.map { |v| to_wire(v) }
+        else
+          value
+        end
+      end
+
+      def from_wire(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), h|
+            h[camel_to_snake(k.to_s).to_sym] = from_wire(v)
+          end
+        when Array
+          value.map { |v| from_wire(v) }
+        else
+          value
+        end
+      end
+
+      def snake_to_camel(str)
+        str.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+      end
+
+      def camel_to_snake(str)
+        str.gsub(/([A-Z])/, '_\1').downcase
+      end
+    end
+  end
+end

data/lib/poli_page/models/document_descriptor.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # The stored-document descriptor returned by `client.render.document` and
+  # the `client.documents.*` methods. Carries every wire field plus an
+  # SDK-attached `_client` back-reference used by `#download_pdf`.
+  #
+  # The `_client` field is hidden from `#to_h` and `#inspect` so it doesn't
+  # leak into logs or marshalled representations (sdk-ruby-plan.md §3.4).
+  DocumentDescriptor = Data.define(
+    :document_id,
+    :organization_id,
+    :project_id,         # nullable on the wire
+    :project_slug,
+    :template_id,
+    :template_slug,
+    :version,
+    :environment,        # "sandbox" or "live"
+    :api_key_id,
+    :format,
+    :orientation,        # nullable
+    :locale,             # nullable
+    :page_count,
+    :size_bytes,
+    :created_at,         # ISO 8601 String — not parsed (no extra deps)
+    :metadata,           # Hash; SDK normalises nil → {} after from_wire
+    :presigned_pdf_url,
+    :expires_at,         # ISO 8601 String
+    :_client             # SDK back-reference; not part of the wire shape
+  ) do
+    # Fetch the PDF bytes from `presigned_pdf_url`. The URL has a ~15-minute
+    # TTL — if it expired, call `client.documents.get(document_id)` to
+    # refresh and retry.
+    #
+    # @return [String] raw PDF bytes (binary-encoded)
+    # @raise  [PoliPage::DownloadError] on non-2xx or network failure
+    # @raise  [PoliPage::InternalError] if the descriptor lacks a client back-reference
+    def download_pdf
+      raise PoliPage::InternalError, "DocumentDescriptor missing client back-reference" if _client.nil?
+
+      _client.fetch_bytes(presigned_pdf_url)
+    end
+
+    def to_h
+      super.except(:_client)
+    end
+
+    def inspect
+      "#<PoliPage::DocumentDescriptor document_id=#{document_id.inspect} ...>"
+    end
+  end
+end

data/lib/poli_page/models/document_preview_result.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Return value of `client.documents.preview`. Distinct from
+  # `PoliPage::PreviewResult`: this carries `page_count` (NOT `total_pages`)
+  # because the documents.preview endpoint exposes the page count via the
+  # `X-Document-Page-Count` response header on a `text/html` body
+  # (sdk-ruby-plan.md §13 Phase 4; mirrors Node `documents.ts:75-77`).
+  DocumentPreviewResult = Data.define(:html, :page_count)
+end

data/lib/poli_page/models/orientation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Valid `orientation:` strings for the rendering endpoints
+  # (sdk-specification.md §4.1).
+  module Orientation
+    ORIENTATIONS = Set["portrait", "landscape"].freeze
+
+    module_function
+
+    def valid?(value)
+      ORIENTATIONS.include?(value)
+    end
+  end
+end

data/lib/poli_page/models/page_format.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Valid `format:` strings for the rendering endpoints (sdk-specification.md
+  # §4.1). Ruby has no native enum; a frozen Set of strings is the most
+  # idiomatic representation and matches the wire format directly. The set
+  # is used both for input validation (in resource methods) and for
+  # documentation.
+  module PageFormat
+    FORMATS = Set[
+      "A3", "A4", "A5", "A6",
+      "Letter", "Legal", "Tabloid",
+      "Executive", "B4", "B5",
+      "Statement", "Folio"
+    ].freeze
+
+    module_function
+
+    def valid?(value)
+      FORMATS.include?(value)
+    end
+  end
+end

data/lib/poli_page/models/preview_result.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Return value of `client.render.preview`. The HTML is the rendered output;
+  # `total_pages` is the page count the rendering engine reports;
+  # `environment` is either `"sandbox"` or `"live"` and reflects the key the
+  # request was made with.
+  PreviewResult = Data.define(:html, :total_pages, :environment)
+end

data/lib/poli_page/models/thumbnail.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # A single page thumbnail returned by `client.documents.thumbnails`.
+  # `data` is base64-encoded image bytes; decode with `Base64.decode64(data)`
+  # (stdlib).
+  Thumbnail = Data.define(:page, :width, :height, :content_type, :data)
+end

data/lib/poli_page/render.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "models/preview_result"
+require_relative "models/document_descriptor"
+
+module PoliPage
+  module Resources
+    # `client.render` namespace. Each method captures a back-reference to the
+    # parent `PoliPage::Client` and delegates HTTP execution through it
+    # (sdk-ruby-plan.md §3.1).
+    class Render
+      def initialize(client)
+        @client = client
+      end
+
+      # POST /v1/render/preview — render and return the HTML, total page
+      # count, and the environment ("sandbox" / "live") inferred from the
+      # API key. Accepts both project mode and inline mode (the only render-*
+      # method that does).
+      #
+      # @param template        [String]  template slug (project mode) OR raw HTML (inline mode)
+      # @param data            [Hash]    template data
+      # @param project         [String, nil] project slug; required for project mode
+      # @param version         [String, nil] exact semver (e.g. "1.0.0") or "draft"
+      # @param format          [String, nil] one of `PoliPage::PageFormat::FORMATS`; default A4
+      # @param orientation     [String, nil] "portrait" or "landscape"; default portrait
+      # @param locale          [String, nil] BCP 47 (e.g. "en-US")
+      # @param metadata        [Hash, nil]   primitive-valued metadata echoed on render.document responses
+      # @param idempotency_key [String, nil] caller-supplied UUID; auto-generated if nil
+      # @return [PoliPage::PreviewResult]
+      # @raise  [PoliPage::ValidationError] on 400
+      # @raise  [PoliPage::AuthenticationError] on 401
+      #
+      # @example Project mode
+      #   result = client.render.preview(
+      #     project: "billing", template: "invoice", version: "1.0.0",
+      #     data:    { invoice_number: "INV-001" }
+      #   )
+      #   puts result.html
+      #   puts "#{result.total_pages} page(s) in #{result.environment} mode"
+      #
+      # @example Inline mode (raw HTML; only render.preview accepts this)
+      #   result = client.render.preview(
+      #     template: "<h1>Hello {{ name }}</h1>",
+      #     data:     { name: "World" }
+      #   )
+      def preview(template:, data:, project: nil, version: nil, format: nil,
+                  orientation: nil, locale: nil, metadata: nil,
+                  idempotency_key: nil)
+        validate_render_kwargs!(format: format, orientation: orientation)
+        body = { project: project, template: template, data: data, version: version,
+                 format: format, orientation: orientation, locale: locale, metadata: metadata }.compact
+        parsed = @client.execute_post(Internal::Constants::PATH_RENDER_PREVIEW,
+                                      body: body, idempotency_key: idempotency_key)
+        PoliPage::PreviewResult.new(**parsed)
+      end
+
+      # POST /v1/render — render and store the document, returning a
+      # `PoliPage::DocumentDescriptor` with the client back-reference attached
+      # so that `#download_pdf` works. Project mode only.
+      #
+      # @return [PoliPage::DocumentDescriptor]
+      #
+      # @example
+      #   doc = client.render.document(
+      #     project:  "billing",
+      #     template: "invoice",
+      #     version:  "1.0.0",
+      #     data:     { invoice_number: "INV-001" },
+      #     metadata: { customer_id: "cust_123" }   # echoed on the descriptor
+      #   )
+      #   db.invoices.update(id: "INV-001", document_id: doc.document_id)
+      #   pdf = doc.download_pdf
+      def document(project:, template:, data:, version: nil, format: nil,
+                   orientation: nil, locale: nil, metadata: nil,
+                   idempotency_key: nil)
+        validate_render_kwargs!(format: format, orientation: orientation)
+        body = { project: project, template: template, data: data, version: version,
+                 format: format, orientation: orientation, locale: locale, metadata: metadata }.compact
+        parsed = @client.execute_post(Internal::Constants::PATH_RENDER,
+                                      body: body, idempotency_key: idempotency_key)
+        parsed[:metadata] ||= {}
+        PoliPage::DocumentDescriptor.new(**parsed, _client: @client)
+      end
+
+      # Two-hop: render the document, then fetch the presigned PDF URL and
+      # return the raw bytes (binary-encoded String). The presigned fetch
+      # is unauthenticated and NOT subject to the retry policy.
+      #
+      # @return [String] raw PDF bytes
+      # @raise  [PoliPage::DownloadError] on second-hop failure
+      #
+      # @example
+      #   pdf = client.render.pdf(
+      #     project: "billing", template: "invoice", version: "1.0.0",
+      #     data:    { invoice_number: "INV-001" }
+      #   )
+      #   File.binwrite("invoice.pdf", pdf)
+      def pdf(project:, template:, data:, version: nil, format: nil,
+              orientation: nil, locale: nil, metadata: nil, idempotency_key: nil)
+        desc = document(project: project, template: template, data: data,
+                        version: version, format: format, orientation: orientation,
+                        locale: locale, metadata: metadata, idempotency_key: idempotency_key)
+        desc.download_pdf
+      end
+
+      # Streaming form of `#pdf`. With a block, yields raw chunks (binary
+      # bytes) as they arrive. Without a block, returns an `Enumerator` so
+      # the caller can `.each`, `.first(n)`, pipe into `Enumerable` chains,
+      # etc.
+      #
+      # @yieldparam chunk [String] raw bytes
+      # @return           [Enumerator, nil]
+      # @raise            [PoliPage::DownloadError]
+      #
+      # @example Block form — pipe straight to a file
+      #   File.open("invoice.pdf", "wb") do |io|
+      #     client.render.pdf_stream(
+      #       project: "billing", template: "invoice", version: "1.0.0", data: data
+      #     ) { |chunk| io.write(chunk) }
+      #   end
+      #
+      # @example Enumerator form
+      #   enum = client.render.pdf_stream(
+      #     project: "billing", template: "invoice", version: "1.0.0", data: data
+      #   )
+      #   total = enum.sum(&:bytesize)
+      def pdf_stream(project:, template:, data:, version: nil, format: nil,
+                     orientation: nil, locale: nil, metadata: nil, idempotency_key: nil, &block)
+        unless block
+          return Enumerator.new do |yielder|
+            pdf_stream(project: project, template: template, data: data,
+                       version: version, format: format, orientation: orientation,
+                       locale: locale, metadata: metadata,
+                       idempotency_key: idempotency_key) { |chunk| yielder << chunk }
+          end
+        end
+
+        desc = document(project: project, template: template, data: data,
+                        version: version, format: format, orientation: orientation,
+                        locale: locale, metadata: metadata, idempotency_key: idempotency_key)
+        @client.stream_bytes(desc.presigned_pdf_url, &block)
+      end
+
+      private
+
+      # Local arg validation — fail fast with a clear `InvalidOptionsError`
+      # before issuing the HTTP request. The deployed API rejects these too,
+      # but raising client-side saves a round-trip and surfaces a friendlier
+      # error message (sdk-ruby-plan.md §9.1).
+      def validate_render_kwargs!(format:, orientation:)
+        if format && !PoliPage::PageFormat.valid?(format)
+          raise PoliPage::InvalidOptionsError,
+                "invalid format: #{format.inspect}; expected one of #{PoliPage::PageFormat::FORMATS.to_a}"
+        end
+        return unless orientation && !PoliPage::Orientation.valid?(orientation)
+
+        raise PoliPage::InvalidOptionsError,
+              "invalid orientation: #{orientation.inspect}; expected 'portrait' or 'landscape'"
+      end
+    end
+  end
+end