poli-page 0.9.0

data/lib/poli_page/render_to_file.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module PoliPage
+  class Client
+    # Render a PDF and stream the bytes straight to `path`. Built on
+    # `render.pdf_stream`, so memory usage stays bounded regardless of
+    # document size. Creates parent directories if missing. Overwrites
+    # existing files. On render error the partial file is removed before
+    # the error is re-raised.
+    #
+    # @param path   [String, Pathname]
+    # @param kwargs forwarded to `Resources::Render#pdf_stream`
+    # @return       [nil]
+    # @raise        [PoliPage::InvalidOptionsError] on filesystem failure
+    # @raise        any error raised by `Resources::Render#pdf_stream`
+    #
+    # @example Write a PDF to disk
+    #   client.render_to_file(
+    #     "out/welcome.pdf",
+    #     project:  "getting-started",
+    #     template: "welcome",
+    #     version:  "1.0.0",
+    #     data:     { name: "World" }
+    #   )
+    def render_to_file(path, **kwargs)
+      pathname = Pathname(path)
+      FileUtils.mkdir_p(pathname.dirname) unless pathname.dirname.directory?
+
+      stream_to_path(pathname, kwargs)
+      nil
+    rescue Errno::EACCES, Errno::ENOSPC, Errno::EISDIR, Errno::ENOENT, Errno::EROFS => e
+      raise PoliPage::InvalidOptionsError,
+            "failed to write to #{pathname}: #{e.class}: #{e.message}"
+    end
+
+    private
+
+    def stream_to_path(pathname, kwargs)
+      File.open(pathname, "wb") do |io|
+        render.pdf_stream(**kwargs) { |chunk| io.write(chunk) }
+      end
+    rescue StandardError
+      # Clean up the partial / empty file so the caller can see the failure
+      # cleanly. Mirrors Node `fs.createWriteStream` cleanup behaviour.
+      FileUtils.rm_f(pathname)
+      raise
+    end
+  end
+end

data/lib/poli_page/request_event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Event payload for the `on_request` constructor hook. Fired immediately
+  # before each HTTP attempt — including the first one and every retry.
+  # Parity with sdk-node `RequestEvent` (src/types.ts:171-175).
+  #
+  # - `method`  [String]  uppercase HTTP verb ("GET" / "POST" / "DELETE").
+  # - `url`     [String]  fully-resolved request URL (base_url + path).
+  # - `attempt` [Integer] 1-based attempt counter — first send is `1`, the
+  #                       first retry is `2`, etc.
+  #
+  # Naming `:method` shadows `Object#method`, but the field name is fixed by
+  # Node-SDK parity (`RequestEvent.method` is the public payload shape).
+  # Callers won't reach for `event.method(:foo)` on a value-typed event.
+  RequestEvent = Data.define(:method, :url, :attempt) # rubocop:disable Lint/DataDefineOverride
+end

data/lib/poli_page/response_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Event payload for the `on_response` constructor hook. Fired immediately
+  # after a 2xx response is received from the transport (NOT fired on
+  # non-2xx — those go through `on_retry` / `on_error` instead).
+  # Parity with sdk-node `ResponseEvent` (src/types.ts:177-181).
+  #
+  # - `status`      [Integer]      HTTP status code (always 200-299).
+  # - `request_id`  [String, nil]  value of the `x-request-id` response
+  #                                header, or nil if the server didn't send one.
+  # - `duration_ms` [Integer]      wall-clock duration of the HTTP attempt,
+  #                                measured around `@transport.execute`.
+  ResponseEvent = Data.define(:status, :request_id, :duration_ms)
+end

data/lib/poli_page/retry_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PoliPage
+  # Event payload for the `on_retry` constructor hook (sdk-ruby-plan.md §10.2).
+  #
+  # - `attempt`  [Integer]         1-based — the attempt about to be made.
+  # - `delay_ms` [Integer]         sleep duration in milliseconds before this
+  #                                attempt. Canonical units across the SDK fleet
+  #                                (Plan 0 / roadmap D3).
+  # - `reason`   [PoliPage::Error] error that triggered the retry.
+  RetryEvent = Data.define(:attempt, :delay_ms, :reason)
+end

data/lib/poli_page/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PoliPage
+  VERSION = "0.9.0"
+end

data/lib/poli_page.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "poli_page/version"
+require_relative "poli_page/errors"
+require_relative "poli_page/internal/constants"
+require_relative "poli_page/internal/http"
+require_relative "poli_page/internal/uuid"
+require_relative "poli_page/internal/wire"
+require_relative "poli_page/internal/transport"
+require_relative "poli_page/models/page_format"
+require_relative "poli_page/models/orientation"
+require_relative "poli_page/models/preview_result"
+require_relative "poli_page/models/document_descriptor"
+require_relative "poli_page/models/document_preview_result"
+require_relative "poli_page/models/thumbnail"
+require_relative "poli_page/inputs/project_mode_input"
+require_relative "poli_page/inputs/inline_mode_input"
+require_relative "poli_page/inputs/thumbnail_options"
+require_relative "poli_page/retry_event"
+require_relative "poli_page/request_event"
+require_relative "poli_page/response_event"
+require_relative "poli_page/render"
+require_relative "poli_page/documents"
+require_relative "poli_page/client"
+require_relative "poli_page/render_to_file"
+
+module PoliPage
+end

data/sig/poli_page/client.rbs

@@ -0,0 +1,46 @@
+module PoliPage
+  type request_hook = ^(PoliPage::RequestEvent) -> void
+  type response_hook = ^(PoliPage::ResponseEvent) -> void
+  type retry_hook = ^(PoliPage::RetryEvent) -> void
+  type error_hook = ^(PoliPage::Error) -> void
+
+  class Client
+    attr_reader base_url: String
+    attr_reader max_retries: Integer
+    attr_reader retry_delay: Numeric
+    attr_reader timeout: Numeric
+    attr_reader render: PoliPage::Resources::Render
+    attr_reader documents: PoliPage::Resources::Documents
+
+    def initialize: (api_key: String, ?base_url: String, ?max_retries: Integer,
+                     ?retry_delay: Numeric, ?timeout: Numeric,
+                     ?logger: untyped?, ?on_request: request_hook?,
+                     ?on_response: response_hook?,
+                     ?on_retry: retry_hook?,
+                     ?on_error: error_hook?,
+                     ?proxy: String?, ?ca_file: String?, ?ca_path: String?) -> void
+
+    def inspect: () -> String
+    def to_s: () -> String
+
+    # @api private
+    def execute_post: (String path, body: Hash[untyped, untyped], ?idempotency_key: String?) -> Hash[Symbol, untyped]
+
+    # @api private
+    def execute_get: (String path) -> Hash[Symbol, untyped]
+
+    # @api private
+    def execute_delete: (String path) -> untyped
+
+    # @api private
+    def execute_get_raw: (String path) -> untyped
+
+    # @api private — from PresignedFetch mixin
+    def fetch_bytes: (String url) -> String
+
+    # @api private — from PresignedFetch mixin
+    def stream_bytes: (String url) { (String) -> void } -> void
+
+    def render_to_file: (String | Pathname path, **untyped kwargs) -> nil
+  end
+end

data/sig/poli_page/documents.rbs

@@ -0,0 +1,12 @@
+module PoliPage
+  module Resources
+    class Documents
+      def initialize: (PoliPage::Client client) -> void
+
+      def get: (String id) -> PoliPage::DocumentDescriptor
+      def preview: (String id) -> PoliPage::DocumentPreviewResult
+      def thumbnails: (String id, **untyped options) -> Array[PoliPage::Thumbnail]
+      def delete: (String id) -> nil
+    end
+  end
+end

data/sig/poli_page/errors.rbs

@@ -0,0 +1,84 @@
+module PoliPage
+  class Error < StandardError
+    attr_reader code: String
+    attr_reader status: Integer?
+    attr_reader request_id: String?
+
+    def initialize: (?String? message, code: String, ?status: Integer?, ?request_id: String?) -> void
+
+    def auth_error?: () -> bool
+    def rate_limit_error?: () -> bool
+    def validation_error?: () -> bool
+    def network_error?: () -> bool
+    def retryable?: () -> bool
+  end
+
+  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
+
+  class InvalidOptionsError < Error
+    def initialize: (String message, ?code: String) -> void
+  end
+
+  class ConnectionError < Error
+    attr_reader cause: Exception?
+
+    def initialize: (message: String, ?cause: Exception?) -> void
+  end
+
+  class TimeoutError < Error
+    attr_reader timeout: Numeric
+
+    def initialize: (timeout: Numeric) -> void
+  end
+
+  class DownloadError < Error
+    def initialize: (message: String, ?status: Integer?) -> void
+  end
+
+  class InternalError < Error
+    def initialize: (String message, ?status: Integer?) -> void
+  end
+
+  module ErrorCodes
+    MISSING_API_KEY: String
+    INVALID_API_KEY: String
+    PAYMENT_REQUIRED: String
+    FORBIDDEN: String
+    ORGANIZATION_CANCELLED: String
+    ORGANIZATION_PURGED: String
+    NOT_FOUND: String
+    VERSION_NOT_FOUND: String
+    DOCUMENT_NOT_FOUND: String
+    GONE: String
+    VALIDATION_ERROR: String
+    MISSING_DATA: String
+    MISSING_PROJECT_OR_TEMPLATE: String
+    MISSING_TEMPLATE_SLUG: String
+    PROJECT_REQUIRED_FOR_DOCUMENT: String
+    INVALID_VERSION_FORMAT: String
+    VERSION_REQUIRED: String
+    INVALID_VERSION_FOR_KEY_ENV: String
+    QUOTA_EXCEEDED: String
+    OVERAGE_CAP_EXCEEDED: String
+    INTERNAL_ERROR: String
+  end
+end

data/sig/poli_page/models.rbs

@@ -0,0 +1,106 @@
+module PoliPage
+  module PageFormat
+    FORMATS: Set[String]
+
+    def self?.valid?: (untyped value) -> bool
+  end
+
+  module Orientation
+    ORIENTATIONS: Set[String]
+
+    def self?.valid?: (untyped value) -> bool
+  end
+
+  class PreviewResult < Data
+    attr_reader html: String
+    attr_reader total_pages: Integer
+    attr_reader environment: String
+
+    def self.new: (html: String, total_pages: Integer, environment: String) -> PreviewResult
+  end
+
+  class DocumentPreviewResult < Data
+    attr_reader html: String
+    attr_reader page_count: Integer
+
+    def self.new: (html: String, page_count: Integer) -> DocumentPreviewResult
+  end
+
+  class Thumbnail < Data
+    attr_reader page: Integer
+    attr_reader width: Integer
+    attr_reader height: Integer
+    attr_reader content_type: String
+    attr_reader data: String
+
+    def self.new: (page: Integer, width: Integer, height: Integer, content_type: String, data: String) -> Thumbnail
+  end
+
+  class DocumentDescriptor < Data
+    attr_reader document_id: String
+    attr_reader organization_id: String
+    attr_reader project_id: String?
+    attr_reader project_slug: String
+    attr_reader template_id: String
+    attr_reader template_slug: String?
+    attr_reader version: String
+    attr_reader environment: String
+    attr_reader api_key_id: String?
+    attr_reader format: String
+    attr_reader orientation: String?
+    attr_reader locale: String?
+    attr_reader page_count: Integer
+    attr_reader size_bytes: Integer
+    attr_reader created_at: String
+    attr_reader metadata: Hash[untyped, untyped]
+    attr_reader presigned_pdf_url: String
+    attr_reader expires_at: String
+    attr_reader _client: PoliPage::Client?
+
+    def self.new: (**untyped) -> DocumentDescriptor
+
+    def download_pdf: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+    def inspect: () -> String
+  end
+
+  class ProjectModeInput < Data
+    attr_reader project: String
+    attr_reader template: String
+    attr_reader data: Hash[untyped, untyped]
+    attr_reader version: String?
+    attr_reader format: String?
+    attr_reader orientation: String?
+    attr_reader locale: String?
+    attr_reader metadata: Hash[untyped, untyped]?
+
+    def self.new: (project: String, template: String, data: Hash[untyped, untyped],
+                   ?version: String?, ?format: String?, ?orientation: String?,
+                   ?locale: String?, ?metadata: Hash[untyped, untyped]?) -> ProjectModeInput
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class InlineModeInput < Data
+    attr_reader template: String
+    attr_reader data: Hash[untyped, untyped]
+    attr_reader format: String?
+    attr_reader orientation: String?
+    attr_reader locale: String?
+    attr_reader metadata: Hash[untyped, untyped]?
+
+    def self.new: (template: String, data: Hash[untyped, untyped],
+                   ?format: String?, ?orientation: String?,
+                   ?locale: String?, ?metadata: Hash[untyped, untyped]?) -> InlineModeInput
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class ThumbnailOptions < Data
+    attr_reader width: Integer
+    attr_reader format: String?
+    attr_reader quality: Integer?
+    attr_reader pages: Array[Integer]?
+
+    def self.new: (width: Integer, ?format: String?, ?quality: Integer?, ?pages: Array[Integer]?) -> ThumbnailOptions
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/poli_page/render.rbs

@@ -0,0 +1,32 @@
+module PoliPage
+  module Resources
+    class Render
+      def initialize: (PoliPage::Client client) -> void
+
+      def preview: (template: String, data: Hash[untyped, untyped],
+                    ?project: String?, ?version: String?, ?format: String?,
+                    ?orientation: String?, ?locale: String?,
+                    ?metadata: Hash[untyped, untyped]?,
+                    ?idempotency_key: String?) -> PoliPage::PreviewResult
+
+      def document: (project: String, template: String, data: Hash[untyped, untyped],
+                     ?version: String?, ?format: String?, ?orientation: String?,
+                     ?locale: String?, ?metadata: Hash[untyped, untyped]?,
+                     ?idempotency_key: String?) -> PoliPage::DocumentDescriptor
+
+      def pdf: (project: String, template: String, data: Hash[untyped, untyped],
+               ?version: String?, ?format: String?, ?orientation: String?,
+               ?locale: String?, ?metadata: Hash[untyped, untyped]?,
+               ?idempotency_key: String?) -> String
+
+      def pdf_stream: (project: String, template: String, data: Hash[untyped, untyped],
+                       ?version: String?, ?format: String?, ?orientation: String?,
+                       ?locale: String?, ?metadata: Hash[untyped, untyped]?,
+                       ?idempotency_key: String?) { (String) -> void } -> void
+                    | (project: String, template: String, data: Hash[untyped, untyped],
+                       ?version: String?, ?format: String?, ?orientation: String?,
+                       ?locale: String?, ?metadata: Hash[untyped, untyped]?,
+                       ?idempotency_key: String?) -> Enumerator[String, void]
+    end
+  end
+end

data/sig/poli_page/request_event.rbs

@@ -0,0 +1,9 @@
+module PoliPage
+  class RequestEvent < Data
+    attr_reader method: String
+    attr_reader url: String
+    attr_reader attempt: Integer
+
+    def self.new: (method: String, url: String, attempt: Integer) -> RequestEvent
+  end
+end

data/sig/poli_page/response_event.rbs

@@ -0,0 +1,9 @@
+module PoliPage
+  class ResponseEvent < Data
+    attr_reader status: Integer
+    attr_reader request_id: String?
+    attr_reader duration_ms: Integer
+
+    def self.new: (status: Integer, request_id: String?, duration_ms: Integer) -> ResponseEvent
+  end
+end

data/sig/poli_page/retry_event.rbs

@@ -0,0 +1,9 @@
+module PoliPage
+  class RetryEvent < Data
+    attr_reader attempt: Integer
+    attr_reader delay_ms: Integer
+    attr_reader reason: PoliPage::Error
+
+    def self.new: (attempt: Integer, delay_ms: Integer, reason: PoliPage::Error) -> RetryEvent
+  end
+end

data/sig/poli_page.rbs

@@ -0,0 +1,3 @@
+module PoliPage
+  VERSION: String
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: poli-page
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Poli Page
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby client for Poli Page. Renders PDFs, previews, and thumbnails
+  via api.poli.page.
+email: support@poli.page
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- MIGRATION.md
+- README.md
+- SECURITY.md
+- lib/poli_page.rb
+- lib/poli_page/client.rb
+- lib/poli_page/documents.rb
+- lib/poli_page/errors.rb
+- lib/poli_page/inputs/inline_mode_input.rb
+- lib/poli_page/inputs/project_mode_input.rb
+- lib/poli_page/inputs/thumbnail_options.rb
+- lib/poli_page/internal/constants.rb
+- lib/poli_page/internal/http.rb
+- lib/poli_page/internal/presigned_fetch.rb
+- lib/poli_page/internal/transport.rb
+- lib/poli_page/internal/uuid.rb
+- lib/poli_page/internal/wire.rb
+- lib/poli_page/models/document_descriptor.rb
+- lib/poli_page/models/document_preview_result.rb
+- lib/poli_page/models/orientation.rb
+- lib/poli_page/models/page_format.rb
+- lib/poli_page/models/preview_result.rb
+- lib/poli_page/models/thumbnail.rb
+- lib/poli_page/render.rb
+- lib/poli_page/render_to_file.rb
+- lib/poli_page/request_event.rb
+- lib/poli_page/response_event.rb
+- lib/poli_page/retry_event.rb
+- lib/poli_page/version.rb
+- sig/poli_page.rbs
+- sig/poli_page/client.rbs
+- sig/poli_page/documents.rbs
+- sig/poli_page/errors.rbs
+- sig/poli_page/models.rbs
+- sig/poli_page/render.rbs
+- sig/poli_page/request_event.rbs
+- sig/poli_page/response_event.rbs
+- sig/poli_page/retry_event.rbs
+homepage: https://poli.page
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://poli.page
+  source_code_uri: https://github.com/poli-page/sdk-ruby
+  changelog_uri: https://github.com/poli-page/sdk-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://poli-page.github.io/sdk-ruby/
+  bug_tracker_uri: https://github.com/poli-page/sdk-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Poli Page SDK for Ruby — render PDFs from HTML templates via the Poli Page
+  API
+test_files: []