poli_page-rails 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc6c84ba2e602d0b343aab8a74fc7f1cd34b65d087891c7a74640c558ba70194
+  data.tar.gz: 7218a8e03696761feeba15cf51822bf669910997373a4a163e7a703036e1fd94
+SHA512:
+  metadata.gz: 823d3338569c4d2dc5d89ee67d4ce1018c8368f9cc4ffcb6f123ec05f6c21793f6b2a845fb945b6650b29a4a4add6be990deb437cdcf1894e70c7f15a7d69f47
+  data.tar.gz: 1dd17a7968b5e0bcb3fea62225e61bb594613380a921c2189304398c206c74f0326dc49d8242df24ee50da6f73277970cbe1a09044c1dc27a1713ae379bbae5e

data/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to `poli_page-rails` 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).
+
+## [Unreleased]
+
+## [0.13.0] - 2026-11-04
+
+First release on RubyGems. It requires the `poli-page` SDK 0.13
+(`~> 0.13.0`) and passes the Poli Page API contract v0.13.0. The gem shares
+its major.minor with the Poli Page API, so its first version is 0.13.0; a
+0.11.0 was prepared and never published, and neither was the 0.1.0
+development line. The Changed, Removed and Fixed entries below describe
+changes made during those lines.
+
+### Added
+
+- Rails engine + Railtie wrapping the official `poli-page` Ruby SDK.
+- `PoliPage.client` — lazy memoised class-level accessor (Monitor-guarded;
+  shared across threads per the SDK's thread-safety guarantee).
+  `PoliPage.reset_client!` clears the memo (test-only).
+- `Rails.application.config.poli_page` — `Configuration` object exposing every
+  SDK kwarg as an `attr_accessor` plus a `notifications` opt-out switch.
+  `to_client_kwargs.compact` lets the SDK's own defaults apply for `nil` keys.
+- `PoliPage::Rails::ConfigurationValidator` — validates `api_key` (see
+  Changed), `base_url` (http/https), `timeout`
+  (1..600), `max_retries` (0..10), `retry_delay` (0..30), `notifications`
+  (boolean), and `on_retry` / `on_error` (callable). Runs lazily on first
+  `PoliPage.client` call — keeps `assets:precompile` and `db:create` working
+  in containers without secrets at boot.
+- `PoliPage::Rails::Renderable` — controller concern providing `render_pdf`,
+  `render_preview`, `redirect_to_document`. Sets `Cache-Control: private,
+  no-store`, `X-Content-Type-Options: nosniff`, and an RFC 5987 / RFC 6266
+  `Content-Disposition` that handles ASCII + non-ASCII filenames (`résumé.pdf`,
+  `発票.pdf`, `🦀.pdf`).
+- `PoliPage::Rails::FilenameEncoder` — thin wrapper over
+  `ActionDispatch::Http::ContentDisposition.format`; single seam if Rails
+  changes the formatting API across versions.
+- `ActiveSupport::Notifications` bridge for the SDK's retry/error hooks
+  (`poli_page.retry`, `poli_page.error`). **Default-on**, opt-out via
+  `c.notifications = false`. Zero overhead with no subscribers.
+- `rails generate poli_page:install` — writes
+  `config/initializers/poli_page.rb` with a commented template documenting
+  every configuration key. Zero custom options to avoid Thor-reserved-name
+  shadowing (`--force`, `--skip`, `--pretend`, `--quiet`, etc.).
+- Example Rails 8 app at [`example-app/`](./example-app) with an interactive
+  single-page demo UI covering every SDK method (`render.pdf`,
+  `render.pdf_stream`, `render.document`, `documents.get`,
+  `documents.thumbnails`, `documents.preview`, `documents.delete`, an
+  error demo, and a `bin/rake demo:render_to_file` task for
+  `render_to_file`).
+- RBS signatures in `sig/` mirroring the public API surface.
+- A default error handler, on by default: `PoliPage::Rails::ErrorHandler` is
+  included into `ActionController::Base` and `ActionController::API` and
+  answers every unrescued `PoliPage::Error` with the SDK's `to_payload`, as is,
+  as JSON `{ "code", "message", "status", "requestId" }` and the payload's
+  status (`503` for `network_error`, `504` for `timeout`, `502` for
+  `invalid_response`), or `500` with `"status": null` when the status is
+  unknown (`invalid_options`, `io_error`), always as `application/json`. Set
+  `config.poli_page.error_handler = false` to leave it out. An error raised
+  after a response is committed (an `ActionController::Live` stream that wrote
+  its first chunk or was closed) is raised again, for Live to log and report;
+  close a Live stream only once it has written, or an error before the first
+  byte ends as an empty `200`.
+- The API contract's integration cases (`spec/contract`), run in CI against
+  the example app on every Ruby and Rails version of the matrix, with the
+  contract pinned to v0.13.0 by the `poli-page/api-contract` action, including
+  `impl.invalid-response`.
+- Release workflow: the tag's major.minor must be the pinned API contract's (a
+  stable contract tag on the pinned commit, not the comment next to it) and
+  the required `poli-page` SDK's (`~> X.Y.0` in the gemspec and the example
+  app), and the example app's lockfile must lock the tag's version
+  (`scripts/check-release-versions.sh`); the error names both versions.
+
+### Changed
+
+- Requires the `poli-page` SDK 0.13 (`~> 0.13.0`, that is `>= 0.13.0,
+  < 0.14`). With it, a 2xx from the API whose body is not JSON (usually from a
+  proxy) raises `PoliPage::InvalidResponseError`, code `invalid_response` (was
+  `INTERNAL_ERROR`), which the default error handler answers `502`; a
+  `render_to_file` that cannot write its file raises
+  `PoliPage::FileWriteError`, code `io_error` (was `invalid_options` or the
+  raw Ruby exception), answered `500` with `"status": null`; and the PDF
+  download is bounded by the `timeout` option (an idle timeout for
+  `render.pdf_stream` and `render_to_file`).
+- The default error handler forwards the SDK's `to_payload` as is: the SDK
+  0.13 names the request id `requestId` itself, so the gem's own renaming of
+  `request_id` and its `ErrorHandler::WIRE_KEYS` are gone.
+  `ErrorHandler.body` returns the payload's Symbol-keyed Hash.
+- Environment keys and no template versions, as in the SDK since 0.11:
+  render calls take no `version:`, a key belongs to one environment
+  (`pp_{environment}_{32 lowercase hex}`, for example `pp_sandbox_…`,
+  `pp_live_…`, `pp_staging_…`), and the key alone selects the environment and
+  so the published copy that renders.
+- `ConfigurationValidator` accepts any environment key. It raises
+  `ConfigurationError` only for a missing or empty `api_key`; a value that does
+  not match `pp_{environment}_{32 lowercase hex}` logs one warning through
+  `config.logger` that names the expected format and shows no part of the
+  key, not even its `pp_{environment}_` prefix, and the client starts anyway,
+  leaving the verdict to the API.
+  `API_KEY_PATTERN` is replaced by `API_KEY_FORMAT`.
+- `render_preview` now documents `DocumentPreviewResult` (`documents.preview`)
+  only.
+- Example app: the demo routes move from `/api/*` to the demo-contract
+  paths (`GET /render/pdf`, `GET /documents/:id`, `GET /errors/not-found`, …).
+  `GET /api/errors/bad-version` (`INVALID_VERSION_FORMAT`) is replaced by
+  `GET /errors/not-found`, which renders the template `does-not-exist` and,
+  through the default error handler, answers `404 TEMPLATE_NOT_FOUND` with the
+  error's code, message, status and request id. `GET /documents/:id/preview`
+  now goes through `render_preview`. `GET /documents/:id` still answers a
+  `302` to the presigned PDF URL.
+- Example app: `GET /render/stream` sets its PDF headers when the first chunk
+  arrives, after the render and the start of the download, so a render error
+  or a network error before that answers through the default error handler
+  (JSON, its own status) instead of a `200 application/pdf`.
+- The integration spec runs only with a `pp_sandbox_` key.
+- CI: the live API job runs on `main` (and on demand) against the production API with the sandbox key from the `POLI_PAGE_API_KEY` secret, and skips with a notice when the key is absent or not a `pp_sandbox_` key.
+- The live API CI job passes the optional `POLI_PAGE_BASE_URL` secret to the integration spec (unset: the SDK default), next to the `pp_sandbox_` key in `POLI_PAGE_API_KEY`. The spec sets `config.base_url` from `POLI_PAGE_BASE_URL` when it is set.
+
+### Removed
+
+- Example app: `GET /api/render/preview` (`render.preview`) and its "HTML
+  preview" button; the SDK no longer has `render.preview`.
+- Example app: `DocumentsController`'s own `rescue_from PoliPage::Error`; the
+  default error handler answers instead.
+
+### Fixed
+
+- `render_pdf` / `FilenameEncoder.disposition`: control characters (CR/LF, TAB,
+  DEL, C1) are now stripped from the `Content-Disposition` filename before
+  `ActionDispatch::Http::ContentDisposition` formats it, instead of surviving as
+  `%0D%0A`-style escapes that clients decode back into the saved filename.
+- Example app: the demo page's status row no longer shows the first 8
+  characters of `POLI_PAGE_API_KEY`; no part of the key is shown.
+
+[Unreleased]: https://github.com/poli-page/rubyonrails/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/poli-page/rubyonrails/releases/tag/v0.13.0

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/README.md

@@ -0,0 +1,254 @@
+# poli_page-rails
+
+> Render Poli Page documents from Rails controllers.
+
+## About
+
+This gem wires the official [`poli-page`](https://rubygems.org/gems/poli-page) Ruby SDK into a Rails app as an Engine. A Railtie installs a `Configuration` object on `Rails.application.config.poli_page`, `PoliPage.client` returns a lazy-memoised SDK client, and a `Renderable` controller concern turns SDK responses into PDF, HTML, or 302 responses with RFC 5987 `Content-Disposition` headers. Retry and terminal-error hooks on the SDK bridge into `ActiveSupport::Notifications` so subscribers like `lograge`, `appsignal`, or `scout_apm` pick them up without extra wiring.
+
+**When to use this:**
+
+- You render PDFs or HTML previews from a Rails controller and want `send_data`-shaped helpers that already set the right cache and content-disposition headers.
+- You want SDK retry and error events on the standard `ActiveSupport::Notifications` bus.
+- You want a generator that writes a fully commented `config/initializers/poli_page.rb`.
+
+**When not to:**
+
+- You are outside Rails — use the [`poli-page`](https://rubygems.org/gems/poli-page) SDK directly.
+- You need to reimplement HTTP transport, retry policy, idempotency, or error mapping. Those live in the SDK; this gem deliberately does not duplicate them.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Rails 7.0, 7.1, 7.2, or 8.0
+- `poli-page` SDK 0.13.x (`~> 0.13.0`); Bundler installs it with the gem
+
+## Install
+
+Add the gem to your `Gemfile`:
+
+```ruby
+# Gemfile
+gem "poli_page-rails", "~> 0.13.0"
+```
+
+Then run:
+
+```ruby
+# shell
+bundle install
+bin/rails generate poli_page:install
+```
+
+The generator writes `config/initializers/poli_page.rb` with a commented template. Set `POLI_PAGE_API_KEY` in your environment, then restart the app.
+
+### API keys
+
+A key belongs to exactly one environment of your organization and reads `pp_{environment}_{32 lowercase hex}`. The key alone selects the environment, and so the published copy of each project that renders.
+
+| Environment                           | Key            | Watermark | Counted |
+| ------------------------------------- | -------------- | --------- | ------- |
+| `sandbox` (every org)                 | `pp_sandbox_…` | yes       | no      |
+| `live` (every org, deletable on Pro+) | `pp_live_…`    | no        | yes     |
+| created on Pro+ (e.g. `staging`)      | `pp_staging_…` | no        | yes     |
+
+"Counted" means the render counts toward the organization's monthly PDF quota.
+
+The API is the only authority on keys. The gem raises `ConfigurationError` only when `api_key` is missing or empty. A value that does not match `pp_{environment}_{32 lowercase hex}` logs one warning through `config.logger` that names the expected format and shows no part of the key, then the client starts anyway and the API answers `401` if the key is wrong (`INVALID_API_KEY`, or `MISSING_API_KEY` for a value without `pp_`).
+
+## Quick start
+
+Return a generated PDF from any controller action.
+
+```ruby
+# app/controllers/invoices_controller.rb
+class InvoicesController < ApplicationController
+  include PoliPage::Rails::Renderable
+
+  def show
+    invoice = Invoice.find(params[:id])
+    bytes = PoliPage.client.render.pdf(
+      project:  "billing",
+      template: "invoice",
+      data:     invoice.to_template_data
+    )
+    render_pdf(bytes, filename: "#{invoice.number}.pdf", inline: false)
+  end
+end
+```
+
+`render_pdf` sets `Content-Type: application/pdf`, `Cache-Control: private, no-store`, `X-Content-Type-Options: nosniff`, and an RFC 5987 / RFC 6266 `Content-Disposition` that round-trips non-ASCII filenames.
+
+## Configuration
+
+Every key is optional except `api_key`. The SDK's own defaults apply when a value is left `nil`.
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | — | Required. A key for one environment: `pp_sandbox_…`, `pp_live_…`, or `pp_{environment}_…` (see [API keys](#api-keys)). |
+| `base_url` | `https://api.poli.page` | Override for the develop environment or a private proxy. |
+| `timeout` | SDK default | Request timeout in seconds. Must be in `1..600`. |
+| `max_retries` | SDK default | Retry attempts on retryable failures. Must be in `0..10`. |
+| `retry_delay` | SDK default | Base backoff delay in seconds. Must be in `0..30`. |
+| `logger` | `Rails.logger` | Any `Logger`-compatible instance. |
+| `proxy` | `nil` | HTTP proxy URL. Honoured by `Net::HTTP` via the SDK. |
+| `ca_file` | `nil` | Path to a CA bundle for corporate egress. |
+| `ca_path` | `nil` | Path to a CA directory. |
+| `notifications` | `true` | Set to `false` to disable the `ActiveSupport::Notifications` bridge. |
+| `on_retry` | bridge | Custom callable. Setting it replaces the notifications bridge. |
+| `on_error` | bridge | Custom callable. Setting it replaces the notifications bridge. |
+| `error_handler` | `true` | Set to `false` to leave out the default error handler (see [Default error handler](#default-error-handler)). |
+
+A minimal initializer:
+
+```ruby
+# config/initializers/poli_page.rb
+Rails.application.config.poli_page.tap do |c|
+  c.api_key = ENV.fetch("POLI_PAGE_API_KEY")
+end
+```
+
+Configuration is validated lazily on the first `PoliPage.client` call, so `assets:precompile` and `db:create` keep working in containers that have no secrets at boot.
+
+## API at a glance
+
+| Symbol | Purpose |
+|---|---|
+| `PoliPage.client` | Lazy-memoised, thread-safe SDK `PoliPage::Client`. |
+| `PoliPage::Rails::Renderable` | Controller concern exposing `render_pdf`, `render_preview`, `redirect_to_document`. |
+| `PoliPage::Rails::Configuration` | The object behind `Rails.application.config.poli_page`. |
+| `PoliPage::Rails::Engine` | Rails engine subclass auto-loaded from your `Gemfile`. |
+| `PoliPage::Rails::ErrorHandler` | Controller concern that answers a `PoliPage::Error` with JSON; included by default. |
+| `PoliPage::Rails::Railtie` | Installs the configuration, the logger default, the notifications bridge, and the error handler. |
+| `"poli_page.retry"` | `ActiveSupport::Notifications` event fired before each SDK retry. |
+| `"poli_page.error"` | `ActiveSupport::Notifications` event fired on terminal SDK failure. |
+| `rails generate poli_page:install` | Writes `config/initializers/poli_page.rb`. |
+
+Full reference: [docs/api.md](docs/api.md) (forthcoming).
+
+## Errors
+
+The SDK raises a fixed hierarchy under `PoliPage::Error`. The four categories you typically branch on:
+
+- **Auth** — `PoliPage::AuthenticationError`, `PoliPage::PermissionDeniedError`. Bad or revoked key, blocked organization.
+- **Rate limit** — `PoliPage::RateLimitError`. The API returned `429`; honour `Retry-After`.
+- **Request rejected** — `PoliPage::ValidationError`. The template, project, or `data` payload was rejected at `400`.
+- **Network / transport** — `PoliPage::ConnectionError`, `PoliPage::TimeoutError`. Network failure, DNS, TLS, or timeout.
+
+Two more come from outside the API: `PoliPage::InvalidResponseError` (`invalid_response`) when a 2xx answer's body is not JSON, usually from a proxy between your app and the API, and `PoliPage::FileWriteError` (`io_error`) when `render_to_file` cannot write its file.
+
+A `PoliPage::Error` you do not rescue reaches the [default error handler](#default-error-handler).
+
+This gem adds one Rails-specific error: `PoliPage::Rails::ConfigurationError`, raised by `ConfigurationValidator` on the first `PoliPage.client` call when the initializer is invalid. It inherits from `PoliPage::Error`, so a single `rescue PoliPage::Error` catches everything.
+
+```ruby
+# app/controllers/invoices_controller.rb
+def show
+  bytes = PoliPage.client.render.pdf(project: "billing", template: "invoice", data: invoice_data)
+  render_pdf(bytes, filename: "invoice.pdf")
+rescue PoliPage::ValidationError => e
+  Rails.logger.warn("PoliPage validation failed: #{e.message}")
+  head :unprocessable_entity
+rescue PoliPage::RateLimitError
+  head :too_many_requests
+rescue PoliPage::AuthenticationError, PoliPage::PermissionDeniedError
+  head :forbidden
+rescue PoliPage::ConnectionError, PoliPage::TimeoutError
+  head :bad_gateway
+end
+```
+
+### Default error handler
+
+The gem answers every `PoliPage::Error` a controller action raises without rescuing it. The Railtie includes `PoliPage::Rails::ErrorHandler` into `ActionController::Base` and `ActionController::API`, which `rescue_from PoliPage::Error` and render the SDK's `Error#to_payload` as JSON, as is:
+
+```json
+{ "code": "TEMPLATE_NOT_FOUND", "message": "Template 'does-not-exist' not found in project 'getting-started'.", "status": 404, "requestId": "req_…" }
+```
+
+- The HTTP status is the payload's `status`: the API's status for an API error, `503` for `network_error`, `504` for `timeout`, `502` for `invalid_response` (the 2xx a proxy sent never reaches your client). When the status is unknown (for example `configuration_error` or `io_error`), the answer is `500` and the body's `status` is `null`.
+- `requestId` is the API's `x-request-id`, or `null` when there is none.
+- The `Content-Type` is `application/json`, even when the action had set another one (a PDF route, say) before the error.
+- The keys are the SDK's, spelled the same by every Poli Page SDK: your app's inflections (an `ID` acronym, for example) do not change them.
+
+The handler cannot answer once a response is committed: an `ActionController::Live` stream is committed when it writes its first chunk or when it is closed. The handler then raises the error again, so Live logs it and calls the stream's `on_error`. After PDF bytes went out, the client gets a short `200` (the PDF cut where the error happened); compare the bytes received with the descriptor's `sizeBytes` if you need to detect it.
+
+So that an error before the first byte still gets the JSON answer, in a Live action:
+
+- set the PDF headers and write the first chunk only after the SDK call has started;
+- close the stream only once you have written to it (`ensure response.stream.close if started`). The usual unconditional `ensure response.stream.close` commits an empty `200` before the handler runs, and the error then ends as that empty `200`.
+
+The example app's `StreamsController` does both.
+
+A `rescue_from` in your own controllers (for `PoliPage::Error`, one of its subclasses, or `StandardError`) takes precedence, as usual in Rails. To leave the handler out entirely:
+
+```ruby
+# config/initializers/poli_page.rb
+Rails.application.config.poli_page.tap do |c|
+  c.error_handler = false
+end
+```
+
+The value must be `true` or `false`; the app refuses to boot with anything else.
+
+## Example app
+
+A runnable Rails 8 app lives in [`example-app/`](./example-app). It exercises every public SDK method behind a single-page UI and ships a `bin/rake demo:render_to_file` task for the `render_to_file` SDK path. It renders the `welcome` template of the `getting-started` project, which every organization has in its `sandbox` environment. Its routes follow the Poli Page demo contract: `GET /render/pdf` answers the PDF, `GET /documents/:id` redirects (`302`) to the document's presigned PDF URL, and `GET /errors/not-found` renders the template `does-not-exist`, so the default error handler answers `404` with the `TEMPLATE_NOT_FOUND` error's code, message, status and request id. If your organization renamed or removed `getting-started` from `sandbox`, the renders answer `404 PROJECT_NOT_FOUND` or `PROJECT_NOT_IN_ENVIRONMENT`: use a fresh organization.
+
+```ruby
+# shell
+cd example-app
+bundle install
+export POLI_PAGE_API_KEY=pp_sandbox_...           # a sandbox key
+# export POLI_PAGE_BASE_URL=https://api.poli.page  # optional
+bin/rails server
+```
+
+## Going further
+
+- ActiveSupport::Notifications — subscribe to `poli_page.retry` and `poli_page.error` for logging, metrics, and alerting (forthcoming `docs/notifications.md`).
+- Filename encoding — how `PoliPage::Rails::FilenameEncoder` produces RFC 5987 `Content-Disposition` values for non-ASCII names (forthcoming `docs/filenames.md`).
+- Background rendering — running renders through Active Job for slow templates (forthcoming `docs/active_job.md`).
+- Testing helpers — stubbing `PoliPage.client` in request specs and system tests (forthcoming `docs/testing.md`).
+
+## Compatibility
+
+| Gem | `poli-page` SDK | Rails | Ruby |
+|---|---|---|---|
+| 0.13.x | 0.13.x | 7.0 / 7.1 / 7.2 / 8.0 | 3.2 – 3.4 |
+
+The gem shares its major.minor with the Poli Page API and requires the SDK of the same minor (see [RELEASING.md](RELEASING.md#versions)).
+
+You receive fixes for the latest two Rails majors. Older majors receive security fixes for six months after their upstream EOL.
+
+## Contributing
+
+Run the lint and the specs for one Rails version with Appraisal:
+
+```sh
+bundle install
+bundle exec appraisal generate
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle install
+bundle exec rubocop
+bundle exec appraisal rails-8.0 rspec --exclude-pattern "spec/integration/**/*"
+```
+
+`spec/integration` renders against a real API and runs only with `POLI_PAGE_API_KEY` set to a `pp_sandbox_` key. It targets the SDK's default API, or the one in `POLI_PAGE_BASE_URL` when that is set. The live API CI job reads both from repository secrets: `POLI_PAGE_API_KEY` (a `pp_sandbox_` key) and the optional `POLI_PAGE_BASE_URL`.
+
+### Contract tests
+
+`spec/contract/impl_contract_spec.rb` runs the integration cases of the [Poli Page API contract](https://github.com/poli-page/api-contract) against the example app's controllers, routes and initializer, with the SDK pointed at a local mock server. CI runs them on every Ruby and Rails version of the matrix, against the contract version pinned in `.github/workflows/ci.yml`. Locally, download a `contract.json` and run:
+
+```sh
+POLI_CONTRACT=<path to contract.json> bundle exec rspec spec/contract
+```
+
+Without `POLI_CONTRACT` the cases are pending (and fail when `CI` is set). Cases allowed to fail are listed with a reason in `spec/contract-skip.json`.
+
+### Releasing
+
+Releases are published by pushing a `vX.Y.Z` tag; see [RELEASING.md](RELEASING.md).
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE).

data/lib/generators/poli_page/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module PoliPage
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Writes config/initializers/poli_page.rb with a commented template."
+
+      # NOTE: Zero custom options on this generator. Rails::Generators::Base
+      # inherits Thor-reserved flags (--force, --pretend, --quiet, --skip,
+      # --skip-namespace, --skip-collision-check). Defining a custom option
+      # with any of those names would silently shadow them and make the
+      # generator appear broken.
+
+      argument :initializer_path, type: :string, required: false,
+                                  default: "config/initializers/poli_page.rb",
+                                  banner: "PATH"
+
+      def copy_initializer
+        template "poli_page.rb.tt", initializer_path
+      end
+
+      def show_post_install_hint
+        say ""
+        say "Created #{initializer_path}.", :green
+        say "Set POLI_PAGE_API_KEY in your environment, then restart the app.", :green
+      end
+    end
+  end
+end

data/lib/generators/poli_page/install/templates/poli_page.rb.tt

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Configuration for the poli_page-rails gem (https://poli.page).
+#
+# Set POLI_PAGE_API_KEY in your environment, then customise below as needed.
+# Get a key at https://app.poli.page/settings/api-keys.
+
+Rails.application.config.poli_page.tap do |c|
+  c.api_key = ENV.fetch("POLI_PAGE_API_KEY")
+
+  # Optional — defaults to https://api.poli.page (the SDK applies its default
+  # when this is nil).
+  # c.base_url = ENV["POLI_PAGE_BASE_URL"]
+
+  # Optional — request timeout in seconds (Float). SDK default applies when nil.
+  # c.timeout = 30.0
+
+  # Optional — retry policy. SDK defaults apply when nil.
+  # c.max_retries = 3
+  # c.retry_delay = 0.5
+
+  # Optional — pass any Logger-compatible instance. Defaults to Rails.logger.
+  # c.logger = Rails.logger
+
+  # Optional — corporate-egress controls. Honoured by Net::HTTP via the SDK.
+  # c.proxy   = ENV["POLI_PAGE_HTTP_PROXY"]
+  # c.ca_file = ENV["POLI_PAGE_CA_FILE"]
+  # c.ca_path = ENV["POLI_PAGE_CA_PATH"]
+
+  # Optional — set to false to disable the ActiveSupport::Notifications bridge.
+  # The bridge is default-on; it costs nothing when no subscribers attach.
+  # c.notifications = false
+
+  # Optional — set to false to remove the default error handler. It answers
+  # every PoliPage::Error a controller raises with JSON
+  # { code, message, status, requestId } (the SDK's to_payload) and the
+  # payload's status, or 500 when the status is unknown.
+  # c.error_handler = false
+
+  # Optional — custom retry/error callables. Setting these REPLACES the
+  # ActiveSupport::Notifications bridge entirely (you opt out of the default
+  # bridge by providing your own callable). To preserve the bridge AND add
+  # custom behaviour, subscribe to AS::Notifications instead:
+  #
+  #   ActiveSupport::Notifications.subscribe("poli_page.retry") do |*args|
+  #     event = ActiveSupport::Notifications::Event.new(*args)
+  #     Rails.logger.warn("PoliPage retry: #{event.payload}")
+  #   end
+  #
+  # c.on_retry = ->(event) { Rails.logger.warn("retry: #{event.attempt}") }
+  # c.on_error = ->(err)   { Sentry.capture_exception(err) }
+end

data/lib/poli_page/rails/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "poli_page"
+
+require_relative "configuration_validator"
+
+module PoliPage
+  # Re-opened from the SDK. Adds the Rails-friendly lazy accessor.
+  class << self
+    def client
+      Rails::Client.instance
+    end
+
+    # Test-only: clear the memoised instance so the next #client call rebuilds.
+    # Marked private API; do NOT use in application code.
+    def reset_client!
+      Rails::Client.reset!
+    end
+  end
+
+  module Rails
+    # Holds the lazy memoised PoliPage::Client. Thread-safe via a Monitor.
+    # The SDK documents PoliPage::Client as thread-safe, so memoising a single
+    # instance and sharing it across threads is correct.
+    module Client
+      LOCK = Monitor.new
+      private_constant :LOCK
+
+      class << self
+        def instance
+          LOCK.synchronize do
+            @instance ||= build!
+          end
+        end
+
+        def reset!
+          LOCK.synchronize do
+            @instance = nil
+          end
+        end
+
+        private
+
+        def build!
+          config = ::Rails.application.config.poli_page
+          ConfigurationValidator.validate!(config)
+          PoliPage::Client.new(**config.to_client_kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/poli_page/rails/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PoliPage
+  module Rails
+    class Configuration
+      attr_accessor :api_key, :base_url, :timeout, :user_agent,
+                    :max_retries, :retry_delay,
+                    :logger, :on_retry, :on_error,
+                    :proxy, :ca_file, :ca_path,
+                    :notifications, :error_handler
+
+      def initialize
+        @api_key       = nil
+        @base_url      = nil
+        @timeout       = nil
+        @user_agent    = nil
+        @max_retries   = nil
+        @retry_delay   = nil
+        @logger        = nil
+        @on_retry      = nil
+        @on_error      = nil
+        @proxy         = nil
+        @ca_file       = nil
+        @ca_path       = nil
+        @notifications = true
+        @error_handler = true
+      end
+
+      # Single source of truth for SDK kwargs. Compact drops every nil entry,
+      # so the SDK's own defaults take over for every unset key. user_agent
+      # is intentionally NOT included — PoliPage::Client#initialize does not
+      # accept it (poli-page 0.11).
+      def to_client_kwargs
+        {
+          api_key:     api_key,
+          base_url:    base_url,
+          max_retries: max_retries,
+          retry_delay: retry_delay,
+          timeout:     timeout,
+          logger:      logger,
+          on_retry:    on_retry,
+          on_error:    on_error,
+          proxy:       proxy,
+          ca_file:     ca_file,
+          ca_path:     ca_path
+        }.compact
+      end
+    end
+  end
+end

data/lib/poli_page/rails/configuration_validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "errors"
+
+module PoliPage
+  module Rails
+    module ConfigurationValidator
+      module_function
+
+      # pp_{environment}_{32 lowercase hex}. Only drives a startup warning: the
+      # API is the authority on keys, so a mismatch never blocks the client.
+      API_KEY_FORMAT = /\App_(?=[a-z][a-z0-9-]{0,19}_)[a-z][a-z0-9]*(?:-[a-z0-9]+)*_[0-9a-f]{32}\z/
+
+      def validate!(config)
+        validate_api_key!(config.api_key, config.logger)
+        validate_base_url!(config.base_url)
+        validate_timeout!(config.timeout)
+        validate_max_retries!(config.max_retries)
+        validate_retry_delay!(config.retry_delay)
+        validate_notifications!(config.notifications)
+        validate_callable!(config.on_retry, "on_retry")
+        validate_callable!(config.on_error, "on_error")
+      end
+
+      def validate_api_key!(value, logger)
+        unless value.is_a?(String) && !value.empty?
+          raise ConfigurationError, "Poli Page api_key is required (a non-empty String). " \
+                                    "Get one at https://app.poli.page/settings/api-keys."
+        end
+        return if API_KEY_FORMAT.match?(value)
+
+        # No part of the key reaches the log: even a well-formed pp_{environment}_
+        # can be a pasted secret fragment.
+        logger&.warn("Poli Page api_key does not match the expected format " \
+                     "pp_{environment}_{32 lowercase hex characters}; starting anyway, " \
+                     "the API will reject it if it is not a valid key.")
+      end
+
+      def validate_base_url!(value)
+        return if value.nil?
+
+        uri = URI.parse(value.to_s)
+        return if uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+
+        raise ConfigurationError, "Poli Page base_url must be an http or https URL (got #{value.inspect})."
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "Poli Page base_url must be an http or https URL (got #{value.inspect})."
+      end
+
+      def validate_timeout!(value)
+        return if value.nil?
+
+        unless value.is_a?(Numeric) && value.positive?
+          raise ConfigurationError, "Poli Page timeout must be a positive number (got #{value.inspect})."
+        end
+
+        return if value <= 600
+
+        raise ConfigurationError, "Poli Page timeout must be <= 600 seconds (got #{value.inspect})."
+      end
+
+      def validate_max_retries!(value)
+        return if value.nil?
+        return if value.is_a?(Integer) && (0..10).cover?(value)
+
+        raise ConfigurationError,
+              "Poli Page max_retries must be an integer between 0 and 10 (got #{value.inspect})."
+      end
+
+      def validate_retry_delay!(value)
+        return if value.nil?
+        return if value.is_a?(Numeric) && (0..30).cover?(value)
+
+        raise ConfigurationError, "Poli Page retry_delay must be a number between 0 and 30 seconds " \
+                                  "(got #{value.inspect})."
+      end
+
+      def validate_notifications!(value)
+        return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+        raise ConfigurationError, "Poli Page notifications must be true or false (got #{value.inspect})."
+      end
+
+      # Checked at boot by the Railtie, when it decides whether to install the
+      # error handler (not in validate!, which runs when the client is built).
+      def validate_error_handler!(value)
+        return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+        raise ConfigurationError, "Poli Page error_handler must be true or false (got #{value.inspect})."
+      end
+
+      def validate_callable!(value, name)
+        return if value.nil?
+        return if value.respond_to?(:call) && !value.is_a?(String) && !value.is_a?(Symbol)
+
+        raise ConfigurationError, "Poli Page #{name} must respond to #call (got #{value.class})."
+      end
+    end
+  end
+end

data/lib/poli_page/rails/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module PoliPage
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace PoliPage::Rails
+
+      # config.poli_page is wired by the Railtie (Task 5). This Engine class
+      # exists primarily so future routes / generators / assets can ship as
+      # part of v0.2 without re-architecting.
+    end
+  end
+end

data/lib/poli_page/rails/error_handler.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/concern"
+
+module PoliPage
+  module Rails
+    # Turns every PoliPage::Error a controller action raises into a JSON answer:
+    #
+    #   status: the payload's status, or 500 when it is nil
+    #   body:   { "code", "message", "status", "requestId" }
+    #
+    # The body is the SDK's Error#to_payload as is: the SDK names its keys
+    # code, message, status and requestId, the same in every Poli Page SDK.
+    # The Content-Type is application/json even when the action had set
+    # another one before the error (a PDF route, for example). Its status is
+    # the API status, 503 for network_error, 504 for timeout, 502 for
+    # invalid_response, and null when unknown (io_error, for example); the
+    # HTTP status falls back to 500 only in that last case.
+    #
+    # The Railtie includes this concern into ActionController::Base and
+    # ActionController::API unless the app sets
+    # `config.poli_page.error_handler = false`. A rescue_from declared later in
+    # a controller (for PoliPage::Error, a subclass, or StandardError) takes
+    # precedence over this one, as usual in Rails.
+    module ErrorHandler
+      extend ::ActiveSupport::Concern
+
+      included do
+        rescue_from ::PoliPage::Error, with: :render_poli_page_error
+      end
+
+      # The JSON body for `error`: its to_payload, forwarded as is. JSON.generate
+      # writes the Symbol keys as they are spelled, so the host app's
+      # inflections (an "ID" acronym, say) cannot change them.
+      def self.body(error)
+        error.to_payload
+      end
+
+      # The HTTP status for `error`: the payload's status, or 500 when unknown.
+      def self.status(error)
+        error.to_payload[:status] || 500
+      end
+
+      private
+
+      # A response already committed (an ActionController::Live stream that
+      # sent its first chunk) cannot change its status or body: the error is
+      # raised again so Live logs it and calls the stream's on_error, instead
+      # of being reported as an answer that was never sent.
+      #
+      # Why JSON.generate: the body holds only strings, integers and nil, and
+      # it keeps the answer independent of ActiveSupport's JSON encoder (whose
+      # Rails 7.0, 7.1 and 8.0 releases pass an option the json 3 gem refuses).
+      def render_poli_page_error(error)
+        raise error if response.committed?
+
+        render json: JSON.generate(ErrorHandler.body(error)),
+               status: ErrorHandler.status(error),
+               content_type: "application/json"
+      end
+    end
+  end
+end

data/lib/poli_page/rails/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "poli_page/errors"
+
+module PoliPage
+  module Rails
+    # Raised by ConfigurationValidator when Rails.application.config.poli_page
+    # contains an invalid value. Inherits from PoliPage::Error so existing
+    # `rescue PoliPage::Error` clauses catch it.
+    class ConfigurationError < PoliPage::Error
+      def initialize(message)
+        super(message, code: "configuration_error", status: nil, request_id: nil)
+      end
+    end
+  end
+end

data/lib/poli_page/rails/filename_encoder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "action_dispatch/http/content_disposition"
+
+module PoliPage
+  module Rails
+    # Builds a Content-Disposition header value with RFC 5987 / RFC 6266
+    # encoding for non-ASCII filenames. Thin wrapper over Rails's own
+    # ActionDispatch::Http::ContentDisposition.format — what ActiveStorage
+    # uses to set the same header for downloaded blobs.
+    #
+    # Why a wrapper at all: single seam if Rails changes the formatting API
+    # across versions (stable since Rails 5.2; one place to patch if it
+    # changes).
+    #
+    # Control characters are stripped before formatting: ContentDisposition
+    # percent-escapes them (%0D%0A), which keeps the header intact but hands
+    # CR/LF/TAB back to any client that decodes filename*.
+    module FilenameEncoder
+      # C0 controls (incl. TAB, CR, LF), DEL and C1 controls.
+      CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/
+
+      module_function
+
+      def disposition(filename, inline:)
+        disposition_type = inline ? "inline" : "attachment"
+        ::ActionDispatch::Http::ContentDisposition.format(
+          disposition: disposition_type,
+          filename: filename.gsub(CONTROL_CHARS, "")
+        )
+      end
+    end
+  end
+end

data/lib/poli_page/rails/notifications.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module PoliPage
+  module Rails
+    # Bridges the SDK's on_retry / on_error Closure hooks into Rails-idiomatic
+    # ActiveSupport::Notifications events.
+    #
+    # Event names follow Rails conventions (sql.active_record, deliver.action_mailer):
+    #   - "poli_page.retry"  — fired before each retry attempt
+    #   - "poli_page.error"  — fired on terminal failure (post-retries)
+    #
+    # Default-on: the Railtie installs the bridges as the default on_retry /
+    # on_error config values, so retries and failures reach the usual Rails
+    # instrumentation subscribers without extra wiring. Users opt out via
+    # c.notifications = false in the initializer.
+    module Notifications
+      RETRY_EVENT_NAME = "poli_page.retry"
+      ERROR_EVENT_NAME = "poli_page.error"
+
+      def self.retry_bridge
+        @retry_bridge ||= lambda do |event|
+          ::ActiveSupport::Notifications.instrument(
+            RETRY_EVENT_NAME,
+            attempt:  event.attempt,
+            delay_ms: event.delay_ms,
+            reason:   event.reason
+          )
+        end
+      end
+
+      def self.error_bridge
+        @error_bridge ||= lambda do |error|
+          ::ActiveSupport::Notifications.instrument(
+            ERROR_EVENT_NAME,
+            error: error
+          )
+        end
+      end
+    end
+  end
+end

data/lib/poli_page/rails/railtie.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+require_relative "configuration_validator"
+require_relative "error_handler"
+require_relative "notifications"
+
+module PoliPage
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "poli_page.configure", before: :load_config_initializers do |app|
+        # Why: Rails::Application::Configuration#method_missing raises
+        # NoMethodError on read when the key has never been set, so the
+        # idiomatic `||=` expansion (which reads first) blows up at boot.
+        # Assign unconditionally — user code in config/initializers/poli_page.rb
+        # runs AFTER this (we use before: :load_config_initializers) and
+        # mutates the existing Configuration object, it never reassigns.
+        app.config.poli_page = Configuration.new
+      end
+
+      # Runs after config/initializers/*.rb, so `config.poli_page.error_handler
+      # = false` there turns it off. The on_load hook includes the concern into
+      # ActionController::Base and ActionController::API when they load, before
+      # any application controller inherits from them.
+      initializer "poli_page.error_handler", after: :load_config_initializers do |app|
+        enabled = app.config.poli_page.error_handler
+        ConfigurationValidator.validate_error_handler!(enabled)
+        next unless enabled
+
+        ::ActiveSupport.on_load(:action_controller) do
+          include PoliPage::Rails::ErrorHandler
+        end
+      end
+
+      config.after_initialize do |app|
+        c = app.config.poli_page
+        c.logger ||= ::Rails.logger
+
+        if c.notifications
+          c.on_retry ||= PoliPage::Rails::Notifications.retry_bridge
+          c.on_error ||= PoliPage::Rails::Notifications.error_bridge
+        end
+      end
+    end
+  end
+end

data/lib/poli_page/rails/renderable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+require_relative "filename_encoder"
+
+module PoliPage
+  module Rails
+    module Renderable
+      extend ::ActiveSupport::Concern
+
+      # Sends raw PDF bytes with PDF headers + RFC 5987 Content-Disposition.
+      #
+      # @param bytes    [String]  raw PDF bytes (binary-encoded)
+      # @param filename [String]  used in Content-Disposition; ASCII and
+      #                           non-ASCII both handled per RFC 5987 / RFC 6266
+      # @param inline   [Boolean] inline (browser viewer) vs attachment (download)
+      def render_pdf(bytes, filename: "document.pdf", inline: false)
+        send_data(
+          bytes,
+          type: "application/pdf",
+          disposition: inline ? "inline" : "attachment",
+          filename: filename
+        )
+        # Why: send_data sets Content-Disposition using Rails's plain ASCII
+        # formatting. Overwrite with our RFC 5987 encoder so non-ASCII filenames
+        # survive. Cache-Control + nosniff are independent additions.
+        response.headers["Content-Disposition"]    = FilenameEncoder.disposition(filename, inline: inline)
+        response.headers["Cache-Control"]          = "private, no-store"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+      end
+
+      # Renders the .html attribute of a DocumentPreviewResult (documents.preview).
+      # The HTML is a complete document from the Poli Page render pipeline; use
+      # render body: to skip template processing and layouts entirely — no
+      # html_safe needed (Rails only escapes inside templates, not for body:).
+      def render_preview(result)
+        html = result.respond_to?(:html) ? result.html : result.to_s
+        response.headers["Cache-Control"]          = "private, no-store"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        render body: html, content_type: "text/html; charset=utf-8"
+      end
+
+      # 302 to the descriptor's presigned URL. Adds Cache-Control so the
+      # redirect itself never gets intermediary-cached.
+      def redirect_to_document(descriptor, status: :found)
+        response.headers["Cache-Control"] = "private, no-store"
+        redirect_to descriptor.presigned_pdf_url, status: status, allow_other_host: true
+      end
+    end
+  end
+end

data/lib/poli_page/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PoliPage
+  module Rails
+    VERSION = "0.13.0"
+  end
+end

data/lib/poli_page-rails.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "poli_page"
+require_relative "poli_page/rails/version"
+require_relative "poli_page/rails/errors"
+require_relative "poli_page/rails/configuration"
+require_relative "poli_page/rails/configuration_validator"
+require_relative "poli_page/rails/client"
+require_relative "poli_page/rails/filename_encoder"
+require_relative "poli_page/rails/renderable"
+require_relative "poli_page/rails/error_handler"
+require_relative "poli_page/rails/notifications"
+require_relative "poli_page/rails/engine"
+require_relative "poli_page/rails/railtie"

data/sig/poli_page/rails/client.rbs

@@ -0,0 +1,11 @@
+module PoliPage
+  def self.client: () -> PoliPage::Client
+  def self.reset_client!: () -> void
+
+  module Rails
+    module Client
+      def self.instance: () -> PoliPage::Client
+      def self.reset!: () -> void
+    end
+  end
+end

data/sig/poli_page/rails/configuration.rbs

@@ -0,0 +1,37 @@
+module PoliPage
+  module Rails
+    class Configuration
+      attr_accessor api_key: String?
+      attr_accessor base_url: String?
+      attr_accessor timeout: Numeric?
+      attr_accessor user_agent: String?
+      attr_accessor max_retries: Integer?
+      attr_accessor retry_delay: Numeric?
+      attr_accessor logger: untyped
+      attr_accessor on_retry: (^(untyped) -> void)?
+      attr_accessor on_error: (^(untyped) -> void)?
+      attr_accessor proxy: String?
+      attr_accessor ca_file: String?
+      attr_accessor ca_path: String?
+      attr_accessor notifications: bool
+      attr_accessor error_handler: bool
+
+      def initialize: () -> void
+      def to_client_kwargs: () -> Hash[Symbol, untyped]
+    end
+
+    module ConfigurationValidator
+      API_KEY_FORMAT: Regexp
+
+      def self.validate!: (Configuration) -> void
+      def self.validate_api_key!: (untyped, untyped logger) -> void
+      def self.validate_base_url!: (untyped) -> void
+      def self.validate_timeout!: (untyped) -> void
+      def self.validate_max_retries!: (untyped) -> void
+      def self.validate_retry_delay!: (untyped) -> void
+      def self.validate_notifications!: (untyped) -> void
+      def self.validate_error_handler!: (untyped) -> void
+      def self.validate_callable!: (untyped, String) -> void
+    end
+  end
+end

data/sig/poli_page/rails/engine.rbs

@@ -0,0 +1,6 @@
+module PoliPage
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/sig/poli_page/rails/error_handler.rbs

@@ -0,0 +1,14 @@
+module PoliPage
+  module Rails
+    module ErrorHandler
+      extend ActiveSupport::Concern
+
+      def self.body: (PoliPage::Error error) -> { code: String, message: String, status: Integer?, requestId: String? }
+      def self.status: (PoliPage::Error error) -> Integer
+
+      private
+
+      def render_poli_page_error: (PoliPage::Error error) -> void
+    end
+  end
+end

data/sig/poli_page/rails/errors.rbs

@@ -0,0 +1,7 @@
+module PoliPage
+  module Rails
+    class ConfigurationError < PoliPage::Error
+      def initialize: (String message) -> void
+    end
+  end
+end

data/sig/poli_page/rails/filename_encoder.rbs

@@ -0,0 +1,9 @@
+module PoliPage
+  module Rails
+    module FilenameEncoder
+      CONTROL_CHARS: Regexp
+
+      def self.disposition: (String filename, inline: bool) -> String
+    end
+  end
+end

data/sig/poli_page/rails/notifications.rbs

@@ -0,0 +1,11 @@
+module PoliPage
+  module Rails
+    module Notifications
+      RETRY_EVENT_NAME: String
+      ERROR_EVENT_NAME: String
+
+      def self.retry_bridge: () -> ^(untyped) -> void
+      def self.error_bridge: () -> ^(untyped) -> void
+    end
+  end
+end

data/sig/poli_page/rails/railtie.rbs

@@ -0,0 +1,6 @@
+module PoliPage
+  module Rails
+    class Railtie < ::Rails::Railtie
+    end
+  end
+end

data/sig/poli_page/rails/renderable.rbs

@@ -0,0 +1,11 @@
+module PoliPage
+  module Rails
+    module Renderable
+      extend ActiveSupport::Concern
+
+      def render_pdf: (String bytes, ?filename: String, ?inline: bool) -> void
+      def render_preview: (untyped result) -> void
+      def redirect_to_document: (untyped descriptor, ?status: Symbol | Integer) -> void
+    end
+  end
+end

data/sig/poli_page/rails/version.rbs

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

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: poli_page-rails
+version: !ruby/object:Gem::Version
+  version: 0.13.0
+platform: ruby
+authors:
+- Poli Page
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: poli-page
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Rails engine + controller concern + ActiveSupport::Notifications bridge
+  over the official poli-page Ruby SDK. Lazy-memoised PoliPage.client, RFC 5987 Content-Disposition
+  handling, opt-out notifications instrumentation, and a rails generate poli_page:install
+  generator that writes config/initializers/poli_page.rb.
+email: support@poli.page
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/poli_page/install/install_generator.rb
+- lib/generators/poli_page/install/templates/poli_page.rb.tt
+- lib/poli_page-rails.rb
+- lib/poli_page/rails/client.rb
+- lib/poli_page/rails/configuration.rb
+- lib/poli_page/rails/configuration_validator.rb
+- lib/poli_page/rails/engine.rb
+- lib/poli_page/rails/error_handler.rb
+- lib/poli_page/rails/errors.rb
+- lib/poli_page/rails/filename_encoder.rb
+- lib/poli_page/rails/notifications.rb
+- lib/poli_page/rails/railtie.rb
+- lib/poli_page/rails/renderable.rb
+- lib/poli_page/rails/version.rb
+- sig/poli_page/rails/client.rbs
+- sig/poli_page/rails/configuration.rbs
+- sig/poli_page/rails/engine.rbs
+- sig/poli_page/rails/error_handler.rbs
+- sig/poli_page/rails/errors.rbs
+- sig/poli_page/rails/filename_encoder.rbs
+- sig/poli_page/rails/notifications.rbs
+- sig/poli_page/rails/railtie.rbs
+- sig/poli_page/rails/renderable.rbs
+- sig/poli_page/rails/version.rbs
+homepage: https://poli.page
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://poli.page
+  source_code_uri: https://github.com/poli-page/rubyonrails
+  changelog_uri: https://github.com/poli-page/rubyonrails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/poli-page/rubyonrails/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: Rails engine for the Poli Page PDF rendering API
+test_files: []