poli-page 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da205dffa69777d3da13ab521d2390d2dd1e06474ce6851f99d806524f7efd19
+  data.tar.gz: bdbfb7093b0c615e2ba62910e8acd8a5fbf269d303b725ee92d35e01ac1d32d5
+SHA512:
+  metadata.gz: 79325da9ac0918bab1e86de4daf459493c1bc5897fc63413905688f01c6c3d130891af2682746a138414591bbf4dcda3e4ef241ba478383f01b13063c02d5075
+  data.tar.gz: 8c7c5d9389e5facab3da4552256d3a6b7206687d9811cc321a37f45d434c4c2ae4fc73570b3055554cc43ae49403d691d50059e6b50d8c6606dcef18928e582a

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `poli-page` (the Poli Page SDK for Ruby) are documented
+here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Breaking changes between major versions are summarized in
+[MIGRATION.md](MIGRATION.md).
+
+## [Unreleased]
+
+## [0.9.0] - 2026-06-18
+
+### Added — first release
+
+- **`PoliPage::Client`** with `render` and `documents` namespaces, sync
+  retry loop, hook firing, and thread-safe accessors.
+- **`render.pdf`**, **`render.pdf_stream`** (block + Enumerator forms),
+  **`render.preview`**, **`render.document`**.
+- **`documents.get`**, **`documents.preview`**, **`documents.thumbnails`**,
+  **`documents.delete`**.
+- **`Client#render_to_file`** — streams the PDF straight to disk with
+  bounded memory.
+- **`DocumentDescriptor#download_pdf`** — fluent helper that fetches the
+  PDF bytes from the descriptor's presigned URL.
+- **Class hierarchy errors** rooted at `PoliPage::Error < StandardError`:
+  `ValidationError` (400), `AuthenticationError` (401),
+  `PermissionDeniedError` (403), `NotFoundError` (404), `GoneError` (410),
+  `RateLimitError` (429), `APIError` (other 4xx/5xx),
+  `InvalidOptionsError`, `ConnectionError`, `TimeoutError`,
+  `DownloadError`, `InternalError`. Predicate helpers
+  (`auth_error?`/`rate_limit_error?`/`validation_error?`/
+  `network_error?`/`retryable?`) for users who prefer a single
+  `rescue PoliPage::Error => e` clause.
+- **`PoliPage::ErrorCodes`** module with the 21 known API code constants.
+- **Auto retry** on 5xx, 429, network errors, and timeouts. Exponential
+  backoff with jitter in `[0.5, 1.5)`; honours `Retry-After` (integer
+  seconds or HTTP-date), capped at 30 s.
+- **Auto-generated `Idempotency-Key`** (UUID v4) on every POST; override
+  via per-call `idempotency_key:` kwarg.
+- **Observability hooks**: `on_retry:` (receives `PoliPage::RetryEvent`)
+  and `on_error:` (receives the `PoliPage::Error` directly). Hook
+  exceptions never break the request.
+- **Frozen `Data.define` value objects** for inputs and responses:
+  `PreviewResult`, `DocumentDescriptor`, `DocumentPreviewResult`,
+  `Thumbnail`, `ProjectModeInput`, `InlineModeInput`, `ThumbnailOptions`,
+  `RetryEvent`.
+- **`PageFormat::FORMATS`** and **`Orientation::ORIENTATIONS`** — frozen
+  `Set`s of valid strings with `.valid?` predicates.
+- **Zero runtime dependencies** — stdlib `Net::HTTP`, `JSON`, `URI`,
+  `SecureRandom`, `Logger` only.
+- **RBS signatures** under `sig/` for the public surface; checked via
+  `bundle exec steep check` and `bundle exec rbs validate`.
+- **YARD `@example` blocks** on every public method.
+- **CI matrix**: Ruby 3.2 / 3.3 / 3.4 on Ubuntu, plus one job each on
+  macOS and Windows with 3.4. RuboCop + Steep + RSpec + bundler-audit
+  + gem build + install smoke.
+
+### Requirements
+
+Ruby >= 3.2.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Code of Conduct
+
+This project adopts the **Contributor Covenant, version 2.1**, in full and
+without modification. The canonical text lives at:
+
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+By participating in this project — opening issues, submitting pull
+requests, reviewing changes, or interacting in any project venue — you
+agree to abide by it.
+
+## Scope
+
+The Code of Conduct applies to all project spaces, including this
+repository's issues, pull requests, and discussions, as well as any
+public space where an individual is representing the project or its
+community.
+
+## Reporting
+
+Report any violation to **conduct@poli.page**. Reports are reviewed by
+the project maintainers; reporter identity is kept confidential.
+Vulnerability reports go to a different address — see
+[`SECURITY.md`](SECURITY.md).
+
+## Enforcement
+
+Maintainers follow the **Enforcement Guidelines** documented in section 5
+of the canonical Code of Conduct (linked above). Outcomes range from a
+private warning to a permanent ban, scaled to the impact of the
+violation.
+
+## Attribution
+
+This Code of Conduct is the
+[Contributor Covenant, v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html),
+authored by Coraline Ada Ehmke and contributors, released under the
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poli Page
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/MIGRATION.md

@@ -0,0 +1,68 @@
+# Migration Guide
+
+This file documents breaking changes between major versions of `poli-page`
+(the Poli Page SDK for Ruby). The SDK follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html): breaking changes
+only ship in major version bumps and always come with an entry here.
+
+## 1.0
+
+The first stable release. No prior versions of `poli-page` were published to
+RubyGems — treat `1.0.0` as the starting point.
+
+### Surface
+
+```ruby
+require "poli_page"
+
+client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))
+
+# Render namespace
+# render.pdf, render.pdf_stream, render.document → project mode only
+# render.preview → accepts both project mode and inline HTML
+client.render.pdf(project:, template:, version:, data:, ...)       # → String of bytes
+client.render.pdf_stream(project:, template:, ...) { |chunk| ... } # → block or Enumerator
+client.render.preview(template:, data:, ...)                       # → PreviewResult
+client.render.document(project:, template:, ...)                   # → DocumentDescriptor
+
+# Documents namespace
+client.documents.get(id)                  # → DocumentDescriptor
+client.documents.preview(id)              # → DocumentPreviewResult { html, page_count }
+client.documents.thumbnails(id, **opts)   # → Array<Thumbnail>
+client.documents.delete(id)               # → nil
+
+# File helper (instance method on Client)
+client.render_to_file(path, project:, template:, version:, data:, ...) # → nil
+```
+
+### Method casing
+
+All SDK methods are snake_case (`render.pdf_stream`, `documents.thumbnails`).
+Wire JSON uses camelCase; the SDK translates at the transport seam via
+`PoliPage::Internal::Wire.to_wire` / `from_wire`. Callers always pass and
+receive snake_case kwargs / `Data.define` accessors.
+
+### Errors
+
+Errors are dispatched by class:
+
+```ruby
+begin
+  client.render.pdf(...)
+rescue PoliPage::AuthenticationError, PoliPage::PermissionDeniedError => e
+  refresh_credentials(e)
+rescue PoliPage::RateLimitError => e
+  queue_for_later(e.request_id)
+rescue PoliPage::Error => e
+  raise
+end
+```
+
+Predicate methods (`auth_error?`, `rate_limit_error?`, `validation_error?`,
+`network_error?`, `retryable?`) are available on the base class for callers
+who prefer `rescue PoliPage::Error => e` with branching.
+
+### MSRV
+
+`required_ruby_version = ">= 3.2"`. Bumps to the MSRV are MINOR-version
+releases with a note in this file.

data/README.md

@@ -0,0 +1,376 @@
+# Poli Page SDK for Ruby
+
+[![Gem](https://img.shields.io/gem/v/poli-page?style=flat&logo=ruby&logoColor=ffffff&label=Gem)](https://rubygems.org/gems/poli-page)
+[![Downloads](https://img.shields.io/gem/dt/poli-page?style=flat&logo=ruby&logoColor=ffffff&label=Downloads)](https://rubygems.org/gems/poli-page)
+[![Ci](https://img.shields.io/github/actions/workflow/status/poli-page/sdk-ruby/ci.yml?branch=main&style=flat&logo=githubactions&logoColor=ffffff&label=Ci)](https://github.com/poli-page/sdk-ruby/actions/workflows/ci.yml)
+[![Codeql](https://img.shields.io/github/actions/workflow/status/poli-page/sdk-ruby/codeql.yml?branch=main&style=flat&logo=github&logoColor=ffffff&label=Codeql)](https://github.com/poli-page/sdk-ruby/actions/workflows/codeql.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/poli-page/sdk-ruby?style=flat&logo=codecov&logoColor=ffffff&label=Coverage)](https://codecov.io/gh/poli-page/sdk-ruby)
+[![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-blue?style=flat&logo=ruby&logoColor=ffffff)](https://github.com/poli-page/sdk-ruby/blob/main/.github/workflows/ci.yml)
+[![Types](https://img.shields.io/badge/Types-RBS-blue?style=flat&logo=ruby&logoColor=ffffff)](https://github.com/poli-page/sdk-ruby/tree/main/sig)
+[![Style](https://img.shields.io/badge/Style-Rubocop-blue?style=flat&logo=ruby&logoColor=ffffff)](https://github.com/rubocop/rubocop)
+[![Deps](https://img.shields.io/badge/Deps-up%20to%20date-brightgreen?style=flat&logo=ruby&logoColor=ffffff)](https://github.com/poli-page/sdk-ruby/network/dependencies)
+[![Docs](https://img.shields.io/badge/Docs-online-brightgreen?style=flat&logo=readthedocs&logoColor=ffffff)](https://poli-page.github.io/sdk-ruby/)
+[![License](https://img.shields.io/github/license/poli-page/sdk-ruby?style=flat&logo=gnu&logoColor=ffffff&label=License)](LICENSE)
+
+Official Ruby SDK for [Poli Page](https://poli.page) — render polished PDFs
+from HTML templates via the Poli Page API.
+
+→ **Documentation**: <https://poli-page.github.io/sdk-ruby/>
+
+## Install
+
+```ruby
+# Gemfile
+gem "poli-page"
+```
+
+```sh
+bundle install
+# or
+gem install poli-page
+```
+
+Requires Ruby **>= 3.2**.
+
+The gem has **zero runtime dependencies** — only the stdlib (`net/http`,
+`json`, `uri`, `securerandom`, `logger`, `openssl`).
+
+## Quick start
+
+### Project mode — render a published template by slug
+
+```ruby
+require "poli_page"
+
+client = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY"))
+
+pdf = client.render.pdf(
+  project:  "getting-started",
+  template: "welcome",
+  version:  "1.0.0",
+  data:     { name: "World" }
+)
+# pdf is a binary-encoded String
+```
+
+Every Poli Page org comes pre-provisioned with a `getting-started/welcome`
+template, so the snippet above runs as-is the moment you have an API key —
+no project setup needed. For your own templates, swap the slugs once
+you've pushed a version with the `poli` CLI:
+
+```ruby
+pdf = client.render.pdf(
+  project:  "billing",
+  template: "invoice",
+  version:  "1.0.0",
+  data:     { invoice_number: "INV-001", total: 1280 }
+)
+```
+
+### Preview inline HTML
+
+`render.preview` accepts raw HTML for live editing and visual inspection
+without producing a stored document. Use this for editor previews or
+layout tests.
+
+```ruby
+result = client.render.preview(
+  template: "<h1>Hello {{ name }}</h1>",
+  data:     { name: "World" }
+)
+puts "Rendered #{result.total_pages} page(s) in #{result.environment} mode"
+```
+
+`render.pdf`, `render.pdf_stream`, and `render.document` **require project
+mode** — `project` + `template`, optionally pinned to a specific
+`version` (omit to render the current draft). Inline HTML is only
+accepted by `render.preview`.
+
+### Write a PDF to disk
+
+```ruby
+client.render_to_file(
+  "./welcome.pdf",
+  project: "getting-started", template: "welcome", version: "1.0.0",
+  data:    { name: "World" }
+)
+```
+
+`render_to_file` streams the response bytes directly to disk via
+`render.pdf_stream` — bounded memory regardless of PDF size. Parent
+directories are created on the fly.
+
+### Try it locally — runnable demo
+
+```sh
+ruby examples/demo.rb
+```
+
+The demo walks every public method end-to-end and writes the results to
+`examples/output/`. First run prompts for a `pp_test_*` key and saves it
+to `.env` at the project root. Subsequent runs are silent. The `POLI_PAGE_API_KEY`
+env var wins over the file when set.
+
+### Stream — for large PDFs or piping to S3 / HTTP responses
+
+```ruby
+File.open("invoice.pdf", "wb") do |io|
+  client.render.pdf_stream(
+    project: "billing", template: "invoice", version: "1.0.0",
+    data:    { invoice_number: "INV-001" }
+  ) do |chunk|
+    io.write(chunk)
+  end
+end
+```
+
+Without a block, `pdf_stream` returns an `Enumerator` that composes with
+`Enumerable`:
+
+```ruby
+enum = client.render.pdf_stream(project: "billing", template: "invoice", version: "1.0.0", data: data)
+enum.each { |chunk| s3.upload_part(part_number: n += 1, body: chunk) }
+```
+
+## Working with stored documents
+
+Every render produces a stored document, accessible via `document_id` for
+later download or thumbnails. `render.pdf` and `render.pdf_stream` are
+conveniences that chain a presigned-URL fetch internally to return bytes;
+`render.document` returns just the descriptor (skip the auto-download
+when you'll fetch the bytes later).
+
+```ruby
+# 1. Render and store
+doc = client.render.document(
+  project:  "billing",
+  template: "invoice",
+  version:  "1.0.0",
+  data:     { invoice_number: "INV-001" },
+  metadata: { customer_id: "cust_123" }   # your own audit data
+)
+# doc.document_id, doc.page_count, doc.size_bytes, doc.presigned_pdf_url, doc.metadata, ...
+
+# 2. Persist doc.document_id in your database
+db.invoices.update(id: "INV-001", document_id: doc.document_id)
+
+# 3. Later, fetch a fresh presigned URL + download
+fresh = client.documents.get(doc.document_id)
+pdf   = fresh.download_pdf
+
+# 4. Generate thumbnails (Starter+ tier)
+thumbs = client.documents.thumbnails(doc.document_id, width: 320, format: "png")
+
+# 5. When done, soft-delete
+client.documents.delete(doc.document_id)
+```
+
+The presigned URL has a 15-minute TTL. If `download_pdf` raises
+`PoliPage::DownloadError` with `status: 403` from S3, call
+`documents.get(id)` to refresh and retry.
+
+## Authentication & environments
+
+The mode is determined by the API key prefix:
+
+- `pp_test_…` → sandbox mode (not billed, generous rate limits)
+- `pp_live_…` → live mode (billed, production rate limits)
+- `pp_sa_…`   → service-account keys; environment matches the SA's
+                configuration (sandbox or live)
+
+All prefixes hit the same endpoint (`https://api.poli.page`). The SDK
+passes the key through as a `Bearer` token and never inspects the prefix —
+pick whichever fits your deploy model.
+
+## Methods
+
+| Method                                          | Returns                            | Description                                         |
+| ----------------------------------------------- | ---------------------------------- | --------------------------------------------------- |
+| `client.render.pdf(**input)`                    | `String` (binary bytes)            | Render a PDF, return bytes                          |
+| `client.render.pdf_stream(**input) { \|c\| … }` | `Enumerator` or yields chunks      | Render and stream the response                      |
+| `client.render.preview(**input)`                | `PoliPage::PreviewResult`          | Paginated HTML preview                              |
+| `client.render.document(**input)`               | `PoliPage::DocumentDescriptor`     | Render and return descriptor (skip auto-download)   |
+| `client.documents.get(id)`                      | `PoliPage::DocumentDescriptor`     | Retrieve a stored document                          |
+| `client.documents.preview(id)`                  | `PoliPage::DocumentPreviewResult`  | Stored document's paginated HTML                    |
+| `client.documents.thumbnails(id, **opts)`       | `Array<PoliPage::Thumbnail>`       | Page thumbnails (PNG/JPEG, base64)                  |
+| `client.documents.delete(id)`                   | `nil`                              | Soft-delete a stored document                       |
+| `client.render_to_file(path, **input)`          | `nil`                              | Render and stream to disk                           |
+
+## Configuration
+
+| Option        | Type                       | Default                    | Description                                  |
+| ------------- | -------------------------- | -------------------------- | -------------------------------------------- |
+| `api_key:`    | `String`                   | (required)                 | `pp_test_*` or `pp_live_*` API key           |
+| `base_url:`   | `String`                   | `"https://api.poli.page"`  | API base URL                                 |
+| `max_retries:`| `Integer`                  | `2`                        | Max retry attempts on retryable errors       |
+| `retry_delay:`| `Numeric` (seconds)        | `0.5`                      | Base delay before the first retry            |
+| `timeout:`    | `Numeric` (seconds)        | `60`                       | Per-request timeout                          |
+| `logger:`     | `Logger` (any duck type)   | `nil`                      | Hook errors and DEBUG events here            |
+| `on_retry:`   | `#call(PoliPage::RetryEvent)`| `nil`                    | Called when a retry is scheduled             |
+| `on_error:`   | `#call(PoliPage::Error)`   | `nil`                      | Called when a call terminates in error       |
+| `proxy:`      | `String` (URL)             | `nil` (uses env)           | Override HTTP proxy; e.g. `"http://u:p@host:8080"` |
+| `ca_file:`    | `String` (path)            | `nil`                      | Custom CA bundle (corp MITM, private PKI)    |
+| `ca_path:`    | `String` (path)            | `nil`                      | Custom CA directory (hashed cert dir)        |
+
+`http_proxy`, `https_proxy`, and `no_proxy` environment variables are
+honored automatically by `Net::HTTP`'s `:ENV` proxy resolution — no
+configuration needed in the common case. Pass `proxy:` to override.
+For TLS verification against a private CA (e.g. behind a corporate
+MITM-terminating proxy), point `ca_file:` at a PEM bundle.
+
+## Error handling
+
+Errors are dispatched by class — the rescue-friendly path:
+
+```ruby
+require "poli_page"
+
+begin
+  client.render.pdf(project: "billing", template: "invoice", version: "1.0.0", data: data)
+rescue PoliPage::AuthenticationError, PoliPage::PermissionDeniedError => e
+  refresh_credentials(e)
+rescue PoliPage::RateLimitError => e
+  queue_for_later(e.request_id)
+rescue PoliPage::ValidationError => e
+  logger.error("Bad input: #{e.message}")
+rescue PoliPage::GoneError => e
+  mark_document_gone(e.code)
+rescue PoliPage::Error => e
+  raise
+end
+```
+
+Predicate helpers on the base class are kept for callers who prefer a
+single `rescue PoliPage::Error => e` clause:
+
+```ruby
+rescue PoliPage::Error => e
+  return refresh_credentials       if e.auth_error?
+  return queue_for_later           if e.rate_limit_error?
+  logger.error(e.code, e.status, e.request_id)
+  raise unless e.retryable?        # SDK already retried up to max_retries
+end
+```
+
+For lifecycle and billing failures, route the user to actionable messages
+rather than treating them as opaque:
+
+```ruby
+rescue PoliPage::Error => e
+  case e.code
+  when "PAYMENT_REQUIRED"       then show_banner("Subscription has unpaid invoices.")
+  when "ORGANIZATION_CANCELLED" then show_banner("Subscription cancelled — service is read-only.")
+  when "ORGANIZATION_PURGED"    then show_banner("Organization has been purged.")
+  when "DOCUMENT_NOT_FOUND"     then render_404
+  when "GONE"                   then render_410   # document was soft-deleted
+  else
+    raise
+  end
+end
+```
+
+The full list of known API codes lives in `PoliPage::ErrorCodes` (see
+`lib/poli_page/errors.rb`).
+
+→ Full error reference: <https://poli-page.github.io/sdk-ruby/reference/errors/>
+
+## Cancellation
+
+Ruby has no async cancellation primitive comparable to `AbortSignal`.
+Three mechanisms are available:
+
+- **Per-request timeout** via the constructor's `timeout:` option — the
+  most common case.
+- **`Timeout.timeout` wrapping** for caller-side deadlines:
+  ```ruby
+  begin
+    pdf = Timeout.timeout(10) { client.render.pdf(...) }
+  rescue Timeout::Error
+    # ... handle the deadline; the SDK does NOT translate this into PoliPage::TimeoutError
+  end
+  ```
+- **`Thread#raise`** from a sibling thread for advanced cases; the SDK's
+  blocking `sleep` between retries honours the interrupt.
+
+For streaming methods, the block is the cancellation point: `break` or
+`raise` out of the block to stop reading mid-stream.
+
+## Observability
+
+Two hooks fire at well-defined points. They're synchronous, optional, and
+never break the request:
+
+```ruby
+client = PoliPage::Client.new(
+  api_key:  ENV.fetch("POLI_PAGE_API_KEY"),
+  logger:   Logger.new($stdout),
+  on_retry: ->(event) { Statsd.increment("polipage.retry", tags: ["code:#{event.reason.code}"]) },
+  on_error: ->(err)   { Sentry.capture_exception(err) }
+)
+```
+
+Hook exceptions are swallowed — a broken metrics path never crashes a
+render. The injected `logger:` works with any `Logger`-compatible object
+(`lograge`, `ougai`, `semantic_logger`, etc.).
+
+## Retries & idempotency
+
+The SDK retries on **5xx**, **429**, **network errors**, and **timeouts**.
+Backoff is exponential (`retry_delay * 2**(attempt - 1)`) with jitter in
+`[0.5, 1.5)`, capped by `Retry-After` when the server provides it
+(integer seconds or HTTP-date; capped at 30 s).
+
+Every POST sends an auto-generated `Idempotency-Key` (UUID v4); pass
+`idempotency_key:` to override.
+
+```ruby
+client.render.pdf(project: "billing", template: "invoice", version: "1.0.0",
+                  data: data, idempotency_key: "render-INV-001-2026-05")
+```
+
+## Type system
+
+The gem ships RBS signatures under `sig/`. Steep checks them against the
+implementation in CI. Consumers can opt into project-mode validation via
+required kwargs at runtime — `Client#render.pdf` raises `ArgumentError`
+immediately if `project:`, `template:`, or `data:` are omitted.
+
+For Sorbet users: `.rbi` shipping is a post-1.0 enhancement.
+
+## Concurrency & thread-safety
+
+A single `PoliPage::Client` instance is safe to share across threads.
+Configuration is immutable after `#initialize`; each request opens its
+own `Net::HTTP` connection.
+
+```ruby
+CLIENT = PoliPage::Client.new(api_key: ENV.fetch("POLI_PAGE_API_KEY")).freeze
+
+pdfs = ids.map do |id|
+  Thread.new { CLIENT.render.pdf(project: "billing", template: "invoice", version: "1.0.0", data: { invoice_number: id }) }
+end.map(&:value)
+```
+
+Build the client once at boot. Don't construct a new client per request.
+
+## Runtime support
+
+- Ruby 3.1+ (CRuby/MRI). Latest two minor releases tested in CI.
+- JRuby 9.4+ on a best-effort basis.
+- Linux and macOS in CI. Windows is supported but not exercised in CI.
+
+## Requirements
+
+Ruby **>= 3.2**. Tested in CI against 3.2, 3.3, and 3.4 on Ubuntu, plus
+one job each on macOS and Windows with 3.4.
+
+## Documentation & support
+
+- Platform docs: [docs.poli.page](https://docs.poli.page)
+- SDK documentation: [poli-page.github.io/sdk-ruby](https://poli-page.github.io/sdk-ruby/)
+- Sign up & generate API keys: [app.poli.page](https://app.poli.page)
+- Issues: [github.com/poli-page/sdk-ruby/issues](https://github.com/poli-page/sdk-ruby/issues)
+
+## License
+
+[MIT](LICENSE) © Poli Page

data/SECURITY.md

@@ -0,0 +1,100 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Report suspected vulnerabilities **privately** to **security@poli.page**.
+
+Please do **not** file a public GitHub issue, open a pull request that
+demonstrates the flaw on `main`, or discuss the issue in public channels
+until a fix has shipped.
+
+Useful information to include:
+
+- A short description of the issue and its impact.
+- Affected versions (run `bundle info poli-page` or check `Gemfile.lock`).
+- Reproduction steps or a proof-of-concept (minimal Ruby script
+  preferred).
+- Suggested remediation, if you have one.
+
+GitHub's **private vulnerability reporting** is also enabled on this
+repository — see
+[Report a vulnerability](https://github.com/poli-page/sdk-ruby/security/advisories/new).
+Either channel reaches the same maintainers.
+
+## Response Timeline
+
+| Stage                 | Target                                        |
+| --------------------- | --------------------------------------------- |
+| Acknowledgement       | within **2 business days** of the report      |
+| Triage decision       | within **5 business days**                    |
+| Fix released          | typically within **30 days** of triage        |
+| Public advisory       | published alongside the fix release           |
+| Coordinated disclosure| up to **90 days** by default; negotiable      |
+
+We will keep the reporter informed at each stage and credit them in the
+published advisory unless they prefer to remain anonymous.
+
+## Supported Versions
+
+Only the **latest minor version** of `poli-page` receives security
+updates. Older minors do not receive backports — please upgrade.
+
+| Version       | Supported          |
+| ------------- | ------------------ |
+| `1.x` (latest)| Yes                |
+| `< 1.x`       | No                 |
+
+## Scope
+
+**In scope** — issues in code shipped by this gem:
+
+- Credential leakage through logs, exceptions, or `#inspect` output.
+- Request-forgery via SDK-constructed URLs, headers, or bodies.
+- TLS / certificate validation defects in the transport layer.
+- Retry / idempotency invariants that could cause unintended side effects.
+- Denial-of-service via malformed API responses or unbounded resource use.
+- Supply-chain integrity issues in the published `.gem` artifact.
+
+**Out of scope:**
+
+- Vulnerabilities in the deployed Poli Page API (`api.poli.page`) —
+  report those at <https://poli.page/security>.
+- Issues that require running the SDK against an untrusted Poli Page
+  base URL (`base_url:` is a trust boundary; pointing the client at a
+  malicious host is the caller's call).
+- Issues in development-only dependencies (Gemfile group `:development,
+  :test`) that do not ship in the published `.gem`.
+- Findings from automated scanners without a demonstrated impact.
+
+## Hardening This Project Applies
+
+- **Zero runtime dependencies** — the SDK uses only the Ruby stdlib for
+  HTTP, JSON, randomness, and TLS. The runtime attack surface is what
+  ships with Ruby itself.
+- **Lockfile committed and frozen in CI** — `Gemfile.lock` is checked
+  in, and CI installs run with `bundle config set --local frozen true`.
+- **Advisory scan in CI** — `bundle-audit check --update` runs on every
+  push and PR.
+- **CodeQL "security-and-quality" suite** — runs on push, PR, and
+  weekly schedule.
+- **GitHub Actions pinned to commit SHAs** — every third-party Action
+  is pinned to a 40-character SHA, not a floating tag.
+- **Dependabot** — weekly updates for `bundler` and `github-actions`.
+- **MFA-required publishing** — the gemspec declares
+  `rubygems_mfa_required: "true"`; the per-gem RubyGems API key is
+  scoped to `poli-page` only.
+- **Restricted workflow permissions** — every workflow declares the
+  minimum `permissions:` block (most are `contents: read`).
+
+## Verifying a Published Release
+
+```sh
+gem fetch poli-page -v <version>
+gem unpack poli-page-<version>.gem
+gem spec poli-page-<version>.gem
+```
+
+The unpacked `.gem` contains the full source — diff it against the
+matching git tag on
+[`github.com/poli-page/sdk-ruby`](https://github.com/poli-page/sdk-ruby)
+to verify the published artifact matches the public history.