payment_kit 1.0.0

data/README.md

@@ -0,0 +1,1008 @@
+# PaymentKit
+
+Ruby HTTP client for the [PaymentKit](https://docs.paymentkit.com) REST API.
+
+This gem is a thin SDK: it authenticates requests, encodes JSON, follows redirects,
+retries transient failures, maps API errors, and exposes resource methods that
+return parsed JSON hashes.
+
+## Requirements
+
+- Ruby `>= 3.2`
+- `activesupport >= 6.1` (powers the webhook event bus)
+- Transport uses only stdlib (`net/http`, `json`, `openssl`); Rails is optional
+  and needed only for the mountable webhook engine
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "payment_kit"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install payment_kit
+```
+
+## Quick start
+
+```ruby
+require "payment_kit"
+
+PaymentKit.configure do |config|
+  config.secret_key = ENV.fetch("PAYMENT_KIT_SECRET_KEY") # st_prod_...
+  config.account_id = ENV.fetch("PAYMENT_KIT_ACCOUNT_ID") # acc_prod_...
+end
+
+client = PaymentKit::Client.new
+
+customer = client.create_customer(
+  email: "customer@example.com",
+  first_name: "Jane",
+  last_name: "Smith",
+  business_name: "Acme Inc"
+)
+
+puts customer["id"] # => "cus_prod_..."
+```
+
+## Configuration
+
+### Global configuration
+
+```ruby
+PaymentKit.configure do |config|
+  config.secret_key      = ENV.fetch("PAYMENT_KIT_SECRET_KEY")
+  config.account_id      = ENV.fetch("PAYMENT_KIT_ACCOUNT_ID")
+  config.signing_secret  = ENV["PAYMENT_KIT_SIGNING_SECRET"] # optional, for webhooks
+  config.api_host        = "https://app.paymentkit.com/api"  # default
+  config.open_timeout    = 10                                # seconds, default
+  config.read_timeout    = 30                                # seconds, default
+  config.max_retries     = 2                                 # default
+end
+```
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `secret_key` | Yes* | — | Server secret token (`st_prod_...`). Never expose in browsers. |
+| `account_id` | Yes* | — | Account external id (`acc_prod_...`) used in the API path. |
+| `api_host` | No | `https://app.paymentkit.com/api` | API host root (without account id). |
+| `base_url` | No | — | Full base URL override (`https://host/api/{account_id}`). Skips `account_id` when set. |
+| `open_timeout` | No | `10` | TCP open timeout (seconds). |
+| `read_timeout` | No | `30` | Response read timeout (seconds). |
+| `max_retries` | No | `2` | Retries for transient HTTP statuses. |
+| `signing_secret` | No | — | Webhook signing secret (`whsec_...`). |
+
+\*Required unless you pass them (or `base_url`) when constructing `Client`.
+
+Reset configuration in tests:
+
+```ruby
+PaymentKit.reset_configuration!
+```
+
+### Base URL resolution
+
+Requests are sent to:
+
+```text
+{base_url}{path}
+```
+
+Where `base_url` is resolved as:
+
+1. Explicit `base_url` if set (trailing slash removed), or
+2. `{api_host}/{account_id}`
+
+Examples:
+
+```ruby
+# Production-style
+PaymentKit.configure do |c|
+  c.secret_key = "st_prod_..."
+  c.account_id = "acc_prod_abc"
+end
+# => https://app.paymentkit.com/api/acc_prod_abc
+
+# Custom host
+PaymentKit.configure do |c|
+  c.secret_key = "st_prod_..."
+  c.account_id = "acc_prod_abc"
+  c.api_host   = "https://app.paymentkit.com/api"
+end
+
+# Full override (useful in tests)
+client = PaymentKit::Client.new(
+  secret_key: "st_test",
+  base_url: "https://api.test/acc"
+)
+```
+
+### Per-client configuration (recommended for multi-account)
+
+Prefer explicit credentials on the client when serving multiple accounts:
+
+```ruby
+client = PaymentKit::Client.new(
+  secret_key: ENV.fetch("PAYMENT_KIT_SECRET_KEY"),
+  account_id: ENV.fetch("PAYMENT_KIT_ACCOUNT_ID"),
+  open_timeout: 5,
+  read_timeout: 20,
+  max_retries: 3
+)
+
+client.base_url
+# => "https://app.paymentkit.com/api/acc_prod_..."
+```
+
+Keyword arguments override the global `PaymentKit.configuration` for that instance only.
+
+### Rails initializer example
+
+```ruby
+# config/initializers/payment_kit.rb
+PaymentKit.configure do |config|
+  config.secret_key     = Rails.application.credentials.dig(:payment_kit, :secret_key)
+  config.account_id     = Rails.application.credentials.dig(:payment_kit, :account_id)
+  config.signing_secret = Rails.application.credentials.dig(:payment_kit, :signing_secret)
+end
+```
+
+## Client overview
+
+`PaymentKit::Client` is the only network entry point.
+
+- Auth: `Authorization: Bearer {secret_key}`
+- Bodies: JSON (`Content-Type: application/json`)
+- Responses: parsed JSON `Hash` (or `Array` for auto-paginated lists)
+- Writes: `POST`, `PUT` and `PATCH` send an automatic `Idempotency-Key` (UUID)
+  unless you pass one
+- Redirects: follows HTTP `307` / `308` (PaymentKit path canonicalization)
+- Retries: `408`, `429` and `5xx` with exponential backoff; `409` only when
+  PaymentKit marks it retryable
+- Escape hatch: `raw_request` for endpoints the gem does not wrap
+
+```ruby
+client = PaymentKit::Client.new
+```
+
+## Resource API
+
+All methods return parsed JSON. Pass request bodies and query params as hashes
+(symbol or string keys are fine). Every write method also accepts an
+`idempotency_key:` — see [Idempotency](#idempotency).
+
+Paths below are relative to the account base URL
+(`{api_host}/{account_id}`), matching the
+[PaymentKit API reference](https://docs.paymentkit.com/api-reference/introduction).
+
+### Method index
+
+| Method | HTTP | Path |
+|--------|------|------|
+| `create_customer` | `POST` | `/customers/` |
+| `retrieve_customer` | `GET` | `/customers/{id}` |
+| `update_customer` | `PUT` | `/customers/{id}` |
+| `list_customers` | `GET` | `/customers/` |
+| `set_credit_balance` | `PATCH` | `/customers/{id}/credit-balance` |
+| `create_balance_transaction` *(deprecated)* | `PATCH` | `/customers/{id}/credit-balance` |
+| `create_credit_note` | `POST` | `/customers/{id}/credit-notes` |
+| `list_credit_notes` | `GET` | `/customers/{id}/credit-notes` |
+| `create_subscription` | `POST` | `/subscriptions` |
+| `retrieve_subscription` | `GET` | `/subscriptions/{id}` |
+| `list_subscriptions` | `GET` | `/subscriptions` |
+| `update_subscription` | `PATCH` | `/subscriptions/{id}` |
+| `update_subscription_items` | `PATCH` | `/subscriptions/{id}/items` |
+| `cancel_subscription` | `POST` | `/subscriptions/{id}/cancel` |
+| `schedule_cancellation` | `POST` | `/subscriptions/{id}/schedule-cancellation` |
+| `cancel_scheduled_cancellation` | `DELETE` | `/subscriptions/{id}/scheduled-cancellation` |
+| `pause_subscription` | `POST` | `/subscriptions/{id}/pause` |
+| `cancel_scheduled_pause` | `DELETE` | `/subscriptions/{id}/scheduled-pause` |
+| `resume_subscription` | `POST` | `/subscriptions/{id}/resume` |
+| `reschedule_billing` | `POST` | `/subscriptions/{id}/reschedule-billing` |
+| `renew_subscription` | `POST` | `/subscriptions/{id}/renew` |
+| `cancel_pending_change` | `DELETE` | `/subscriptions/{id}/pending-change` |
+| `change_plan` *(deprecated)* | `POST` | `/subscriptions/{id}/change-plan` |
+| `create_change_request` | `POST` | `/subscriptions/{id}/change-requests` |
+| `retrieve_change_request` | `GET` | `/subscriptions/{id}/change-requests/{request_id}` |
+| `active_change_request` | `GET` | `/subscriptions/{id}/change-requests/active` |
+| `add_change_request_changes` | `PATCH` | `/subscriptions/{id}/change-requests/{request_id}` |
+| `preview_change_request` | `POST` | `/subscriptions/{id}/change-requests/{request_id}/preview` |
+| `apply_change_request` | `POST` | `/subscriptions/{id}/change-requests/{request_id}/apply` |
+| `cancel_change_request` | `DELETE` | `/subscriptions/{id}/change-requests/{request_id}` |
+| `apply_subscription_changes` | `POST` | `/subscriptions/{id}/change-requests/apply` |
+| `create_invoice` | `POST` | `/invoices/` |
+| `retrieve_invoice` | `GET` | `/invoices/{id}` |
+| `list_invoices` | `GET` | `/invoices/` |
+| `retrieve_invoice_pdf` | `GET` | `/invoices/{id}/pdf` |
+| `finalize_invoice` | `POST` | `/invoices/{id}/finalize` |
+| `pay_invoice` | `POST` | `/invoices/{id}/collect` |
+| `void_invoice` | `POST` | `/invoices/{id}/void` |
+| `mark_invoice_uncollectible` | `POST` | `/invoices/{id}/mark-uncollectible` |
+| `bill_pending_items` | `POST` | `/invoices/bill-pending-items` |
+| `create_invoice_item` | `POST` | `/invoice-items/` |
+| `retrieve_invoice_item` | `GET` | `/invoice-items/{id}` |
+| `list_invoice_items` | `GET` | `/invoice-items/` |
+| `update_invoice_item` | `PATCH` | `/invoice-items/{id}` |
+| `create_payment_intent` | `POST` | `/payments/intents/` |
+| `retrieve_payment_intent` | `GET` | `/payments/intents/{id}` |
+| `list_payment_intents` | `GET` | `/payments/intents/` |
+| `list_refunds_by_intent` | `GET` | `/payments/refunds/by_intent/{id}` |
+| `list_attempts_by_intent` | `GET` | `/payments/processor_attempts/by_intent/{id}` |
+| `create_payment_method` | `POST` | `/payments/payment_methods/` |
+| `retrieve_payment_method` | `GET` | `/payments/payment_methods/{id}` |
+| `update_payment_method` | `PUT` | `/payments/payment_methods/{id}` |
+| `deactivate_payment_method` | `PUT` | `/payments/payment_methods/{id}` |
+| `detach_payment_method` | `DELETE` | `/payments/payment_methods/{id}` |
+| `create_checkout_session` | `POST` | `/checkout-sessions` |
+| `retrieve_checkout_session` | `GET` | `/checkout-sessions/{id}` |
+| `list_products` | `GET` | `/products/` |
+| `retrieve_product` | `GET` | `/products/{id}` |
+| `create_product` | `POST` | `/products/` |
+| `update_product` | `PATCH` | `/products/{id}` |
+| `list_product_prices` | `GET` | `/products/{id}/prices` |
+| `list_prices` | `GET` | `/prices/` |
+| `retrieve_price` | `GET` | `/prices/{id}` |
+| `create_price` | `POST` | `/prices/` |
+
+### Customers
+
+```ruby
+customer = client.create_customer(
+  email: "customer@example.com",
+  first_name: "Jane",
+  last_name: "Smith",
+  business_name: "Acme Inc",
+  phone: "+15550100",
+  billing_email: "ap@acme.test",
+  currency: "USD",
+  language: "en",
+  address: { line1: "1 Market St", city: "San Francisco", country: "US", postal_code: "94105" },
+  tax_ids: ["EU372009832"],
+  metadata: { plan_tier: "enterprise" }
+)
+
+customer = client.retrieve_customer("cus_123")
+
+# PUT — only the fields you send are changed
+customer = client.update_customer("cus_123",
+  email: "new@example.com",
+  metadata: { plan_tier: "pro" }
+)
+
+customers = client.list_customers(limit: 50)  # auto-paginated Array
+```
+
+### Customer credit
+
+`set_credit_balance` sets an **absolute target** balance for one currency —
+PaymentKit issues or voids credit to reach it. It is not a delta. Balances are
+tracked independently per currency, and `amount_atom` is in the smallest
+currency unit.
+
+```ruby
+# Make the customer's USD balance exactly 5000 atoms ($50.00)
+balance = client.set_credit_balance("cus_123", amount_atom: 5000, currency: "USD")
+# => { "amount_atom" => 5000, "currency" => "USD" }
+```
+
+To *add* credit incrementally, append a credit note. `reason` is required and
+must be one of `proration_excess`, `manual_adjustment`, `auto_apply` or
+`debit_settlement`. Always pass a stable idempotency key: a double submit issues
+two notes.
+
+```ruby
+note = client.create_credit_note(
+  "cus_123",
+  {
+    amount_atom: 2500,
+    currency: "USD",
+    reason: "manual_adjustment",
+    memo: "Goodwill credit for billing error",
+    invoice_id: "inv_123"   # optional; otherwise a paid companion invoice is created
+  },
+  idempotency_key: "credit-overcharge-918"
+)
+
+notes = client.list_credit_notes("cus_123", currency: "USD")
+```
+
+PaymentKit draws credit down automatically when an invoice is collected; you do
+not apply it manually.
+
+`create_balance_transaction` is deprecated. It hits the same endpoint, forwards
+to `set_credit_balance` and warns — the old name implied delta semantics, but the
+endpoint sets an absolute target balance:
+
+```ruby
+# Deprecated; identical to set_credit_balance("cus_123", ...)
+client.create_balance_transaction("cus_123", amount_atom: 5000, currency: "USD")
+```
+
+### Subscriptions
+
+`customer_id`, `currency`, `billing_interval`, `billing_interval_count`,
+`period_start` and `collection_method` are required. Each entry in `items` is a
+`price_id` plus `quantity`.
+
+```ruby
+subscription = client.create_subscription(
+  customer_id: "cus_123",
+  currency: "USD",
+  billing_interval: "month",          # day | week | month | year
+  billing_interval_count: 1,
+  period_start: "2026-02-01T00:00:00Z",
+  collection_method: "charge_automatically",  # or send_invoice
+  processor_id: "proc_live_abc",      # falls back to the account default
+  items: [
+    { price_id: "price_monthly_pro", quantity: 1 },
+    { price_id: "price_addon_seats", quantity: 5 }
+  ],
+  trial_start: "2026-02-01T00:00:00Z",
+  trial_end: "2026-02-15T00:00:00Z",
+  net_d: 30,                          # payment terms in days
+  coupon_id: "coup_welcome20",
+  total_billing_cycles: 12            # auto-cancel after N cycles
+)
+
+subscription  = client.retrieve_subscription("sub_123")
+subscriptions = client.list_subscriptions(customer_id: "cus_123")
+
+# Cancel at period end (and undo it) via the base update endpoint
+client.update_subscription("sub_123", cancel_at_period_end: true)
+client.update_subscription("sub_123", cancel_at_period_end: false)
+```
+
+Line-item changes go through the dedicated items endpoint, where
+`proration_behavior` is **required** (`always_invoice`, `create_prorations` or
+`none`). This is charge-first, so pass a stable idempotency key.
+
+```ruby
+client.update_subscription_items("sub_123",
+  {
+    proration_behavior: "always_invoice",
+    items: [
+      { id: "si_plan", price_id: "price_monthly_pro", quantity: 2 }
+    ]
+  },
+  idempotency_key: "seat-change-42-v3"
+)
+```
+
+#### Cancelling, pausing and rescheduling
+
+```ruby
+# Immediate cancel. refund_option: none | full | prorated | cancel_unpaid
+client.cancel_subscription("sub_123", refund_option: "prorated")
+
+# Calculate the refund without executing
+preview = client.cancel_subscription("sub_123", refund_option: "prorated", is_preview: true)
+
+# Cancel on a specific date instead, then undo it
+client.schedule_cancellation("sub_123", cancel_at: "2026-06-01T00:00:00Z", refund_option: "none")
+client.cancel_scheduled_cancellation("sub_123")
+
+# Pause now, or at period end. pause_for_cycles and resumption_date are
+# mutually exclusive ways to schedule the auto-resume.
+client.pause_subscription("sub_123", pause_behavior: "pause_immediately", pause_for_cycles: 2)
+client.pause_subscription("sub_123", pause_behavior: "pause_at_end")
+client.cancel_scheduled_pause("sub_123")   # removes a pending pause_at_end
+
+client.resume_subscription("sub_123")
+client.renew_subscription("sub_123")
+
+client.reschedule_billing("sub_123",
+  next_billing_date: "2026-03-15T00:00:00Z",
+  create_proration: true,
+  is_preview: false
+)
+
+# Cancels a scheduled (period-end) plan change before it executes
+client.cancel_pending_change("sub_123")
+```
+
+#### Change requests (recommended for plan changes)
+
+A create → add changes → preview → apply workflow that shows exact proration
+before committing, and collects payment before modifying the subscription. Only
+one active (`draft`/`ready`) request may exist per subscription; creating a
+second raises `PaymentKit::ConflictError`.
+
+```ruby
+request = client.create_change_request("sub_123",
+  reason: "Upgrade to annual plan",
+  expires_in_hours: 24
+)
+
+# Append item, coupon and balance changes. Callable repeatedly; each call
+# appends. Doing this on a `ready` request reverts it to `draft`.
+client.add_change_request_changes("sub_123", request["id"],
+  item_changes: [
+    { action: "update", item_id: "si_monthly_plan", price_id: "price_annual_plan" },
+    { action: "add", price_id: "price_addon_support", quantity: 1, apply_at_end: false },
+    { action: "drop", item_id: "si_legacy_addon" }
+  ],
+  coupon_changes: [
+    { action: "add", coupon_id: "coup_welcome20" }
+  ],
+  trial_behavior: "preserve"   # or end_now
+)
+
+# Pure computation: returns proration amounts and the execution plan, → ready
+preview = client.preview_change_request("sub_123", request["id"])
+preview["preview"]["invoice_total_atom"]
+
+# Charge-first execution. A decline raises PaymentKit::CardError (402).
+client.apply_change_request("sub_123", request["id"],
+  idempotency_key: "cr-#{request["id"]}"
+)
+
+request = client.retrieve_change_request("sub_123", request["id"])
+active  = client.active_change_request("sub_123")   # nil when none is pending
+client.cancel_change_request("sub_123", request["id"])
+```
+
+One-step shortcut — create, add changes, preview and apply in a single call:
+
+```ruby
+client.apply_subscription_changes("sub_123",
+  {
+    item_changes: [
+      { action: "update", item_id: "si_monthly_plan", price_id: "price_annual_plan" }
+    ],
+    reason: "Upgrade to annual plan",
+    payment_method_id: "pm_123"
+  },
+  idempotency_key: "upgrade-#{user_id}-v1"
+)
+```
+
+#### Legacy plan change (deprecated)
+
+PaymentKit documents `change-plan` as the legacy single-call endpoint, planned
+for deprecation. Prefer the change-request workflow above, or
+`apply_subscription_changes`. Kept for existing integrations:
+
+```ruby
+client.change_plan("sub_123",
+  reason: "Billing interval change to year",
+  proration_behavior: "always_invoice",
+  effective_at: "immediate",
+  items: [
+    { action: "update", subscription_item_id: "si_plan",
+      new_price_id: "price_annual_plan", quantity: 1 }
+  ]
+)
+```
+
+### Invoices
+
+Invoices are created in `draft`. Each line item takes either an `amount`, a
+`unit_amount` × `quantity`, or a catalog `price_id`.
+
+```ruby
+invoice = client.create_invoice(
+  customer_id: "cus_123",
+  currency: "USD",
+  issued_at: "2026-02-01T00:00:00Z",
+  description: "Setup fee — Enterprise onboarding",
+  collection_method: "charge_automatically",
+  items: [
+    { description: "Enterprise onboarding", quantity: 1, amount: 500.00 },
+    { description: "Custom integration", quantity: 4, unit_amount: 150.00 },
+    { price_id: "price_support_plan", quantity: 1 }
+  ]
+)
+
+# Draft → Open: locks amounts, optionally generates the PDF and emails it
+invoice = client.finalize_invoice(invoice["id"])
+
+# Attempts collection; finalizes the invoice first when still draft.
+# A decline raises PaymentKit::CardError and leaves the invoice payable.
+result = client.pay_invoice(invoice["id"], payment_method_id: "pm_123")
+result["invoice_status"] # => "paid"
+
+invoice  = client.retrieve_invoice("inv_123", expand: "custom_fields")
+invoices = client.list_invoices(customer_id: "cus_123", status: "open")
+
+# Poll while status is "generating"
+pdf = client.retrieve_invoice_pdf("inv_123")
+pdf["pdf_url"] if pdf["status"] == "available"
+
+client.void_invoice("inv_123")
+
+# Only permitted from OPEN or PAST_DUE; other states return 422
+client.mark_invoice_uncollectible("inv_123")
+```
+
+Sweep floating (pending) items into standalone invoices — one per currency —
+finalize them and attempt collection immediately, without waiting for renewal.
+Duplicate requests create duplicate invoices, so a stable key is essential.
+
+```ruby
+result = client.bill_pending_items(
+  {
+    customer_id: "cus_123",       # required
+    subscription_id: "sub_123",   # optional narrowing
+    currency: "USD",
+    collection_method: "charge_automatically",
+    description: "July usage",
+    tax_amount_atom: 0
+  },
+  idempotency_key: "bill-cus_123-2026-07"
+)
+
+result["invoices"].each { |inv| puts "#{inv["currency"]}: #{inv["items_swept"]} items" }
+```
+
+A renewal running concurrently raises `PaymentKit::ConflictError` (409).
+
+### Invoice items
+
+Floating items attach to a subscription and are collected at the next renewal
+(or on demand via `bill_pending_items`). The subscription must be `active` or
+`trialing`, and the `customer_id` must match it.
+
+```ruby
+# With a catalog price
+item = client.create_invoice_item(
+  customer_id: "cus_123",
+  subscription_id: "sub_123",
+  price_id: "price_sms_usage",
+  quantity: 150,
+  description: "SMS charges — July 2026 (150 messages)"
+)
+
+# With a custom amount
+item = client.create_invoice_item(
+  customer_id: "cus_123",
+  subscription_id: "sub_123",
+  amount: 75.00,
+  description: "Custom setup fee"
+)
+
+item  = client.retrieve_invoice_item(item["id"])
+item  = client.update_invoice_item(item["id"], quantity: 200, description: "SMS charges — revised")
+items = client.list_invoice_items(subscription_id: "sub_123", status: "floating")
+```
+
+### Payment intents
+
+Low-level charge control. Amounts are in atomic units.
+
+```ruby
+intent = client.create_payment_intent(
+  customer_id: "cus_123",
+  amount_atom: 2500,
+  currency: "USD",
+  payment_method_id: "pm_123",
+  processor_id: "proc_live_abc",
+  metadata: { order_id: "ord_9" }
+)
+
+intent  = client.retrieve_payment_intent("pi_123", expand: "checkout_attempt")
+intents = client.list_payment_intents(customer_id: "cus_123", limit: 50)
+
+refunds  = client.list_refunds_by_intent("pi_123")
+attempts = client.list_attempts_by_intent("pi_123")
+```
+
+### Payment methods
+
+```ruby
+pm = client.create_payment_method(customer_id: "cus_123", provider_type: "card")
+pm = client.retrieve_payment_method("pm_123")
+pm = client.update_payment_method("pm_123", metadata: { label: "primary" })
+
+# Documented way to take a card out of use (PUT is_active: false)
+client.deactivate_payment_method("pm_123")
+
+# Outright delete. PaymentKit documents deletion only on the customer-portal
+# surface, so if your account returns 404/405 use deactivate_payment_method.
+client.detach_payment_method("pm_123")
+```
+
+### Checkout sessions
+
+Hosted collection. The response carries the `secure_token` used to initialise
+PaymentKit.js or redirect to the hosted page.
+
+```ruby
+session = client.create_checkout_session(
+  customer_id: "cus_123",                       # optional; pre-fills the customer
+  line_items: [{ price_id: "price_123", quantity: 1 }],
+  success_url: "https://example.com/success",
+  return_url: "https://example.com/cancel",
+  expires_in_hours: 24,
+  promotion_code: "LAUNCH20",
+  custom_fields: { internal_ref: "ord_9" }
+)
+
+session["secure_token"]
+
+session = client.retrieve_checkout_session(session["id"])
+```
+
+### Catalog
+
+```ruby
+product  = client.create_product(
+  name: "Pro plan",
+  description: "Everything in Starter, plus priority support",
+  is_active: true,
+  metadata: { tier: "pro" }
+)
+
+product  = client.retrieve_product("prod_123")
+product  = client.update_product("prod_123", is_active: false, default_price_id: "price_123")
+products = client.list_products(limit: 50)
+prices   = client.list_product_prices("prod_123")
+```
+
+```ruby
+price = client.create_price(
+  product_id: "prod_123",
+  currency: "USD",
+  unit_amount_atom: 2500,
+  pricing_type: "recurring",
+  billing_scheme: "per_unit",
+  recurring_interval: "month",
+  recurring_interval_count: 1,
+  trial_days: 14
+)
+
+price  = client.retrieve_price("price_123")
+prices = client.list_prices(limit: 50)
+```
+
+## List pagination
+
+Every `list_*` helper auto-paginates PaymentKit’s offset/limit envelope:
+
+```json
+{ "items": [...], "total": 150, "has_more": true }
+```
+
+and return a flat Ruby `Array` of item hashes. PaymentKit defaults `limit` to 50
+and caps it at 100; the helpers keep requesting pages until `has_more` is false.
+
+```ruby
+products = client.list_products(limit: 50)
+products.each { |product| puts product["id"] }
+
+# Filters are forwarded as query params
+invoices = client.list_invoices(customer_id: "cus_123", status: "open")
+```
+
+Use `raw_request` when you need a single page rather than the whole collection.
+
+## Webhooks and event bus
+
+Inbound webhooks are verified, then fanned out synchronously via
+`ActiveSupport::Notifications`. The gem does **not** persist events, enqueue jobs,
+or retry deliveries — those remain host responsibilities. Deduplication is a host
+responsibility too, but the gem provides the `event_retriever` hook for it
+(see [Deduplicating redeliveries](#deduplicating-redeliveries)).
+
+Multiple signing secrets are supported and tried in order, which is what
+PaymentKit's `roll-secret` grace period requires: during rotation both the old
+and new secret are live.
+
+### Configure signing secrets
+
+```ruby
+PaymentKit.configure do |config|
+  config.signing_secret = ENV.fetch("PAYMENT_KIT_SIGNING_SECRET") # whsec_...
+  # or multiple secrets (tried in order):
+  # config.signing_secrets = [ENV["PAYMENT_KIT_SIGNING_SECRET"], ENV["PAYMENT_KIT_SIGNING_SECRET_OLD"]]
+end
+
+# Module-level accessors also work:
+PaymentKit.signing_secret  = ENV.fetch("PAYMENT_KIT_SIGNING_SECRET")
+PaymentKit.signing_secrets = [ENV["PAYMENT_KIT_SIGNING_SECRET"], ENV["PAYMENT_KIT_SIGNING_SECRET_OLD"]]
+```
+
+### Subscribe to events
+
+```ruby
+PaymentKit.subscribe "invoice.paid" do |event|
+  # event is a Hash, e.g. { "id" => "evt_...", "type" => "invoice.paid", ... }
+  # Prefer enqueueing work here; slow handlers delay the webhook HTTP response.
+end
+
+PaymentKit.subscribe "invoice.", InvoiceHandler.new  # prefix match; #call(event)
+PaymentKit.all { |event| Rails.logger.info(event["type"]) }
+
+PaymentKit.event_filter = lambda do |event|
+  # return event to dispatch, or nil to ignore (still a successful verify path)
+  event["type"] == "ping" ? nil : event
+end
+```
+
+`configure` accepts two block shapes. A block that takes an argument receives the
+configuration object; a block that takes none is evaluated against the module,
+which reads better for registering subscribers in an initializer:
+
+```ruby
+PaymentKit.configure do |config|          # settings
+  config.secret_key = ENV.fetch("PAYMENT_KIT_SECRET_KEY")
+end
+
+PaymentKit.configure do                   # subscriber DSL
+  subscribe("invoice.paid") { |event| InvoicePaidJob.perform_later(event["id"]) }
+  all { |event| Rails.logger.info(event["type"]) }
+end
+```
+
+### Process a webhook (non-Rails or custom controller)
+
+```ruby
+payload   = request.body.read
+signature = request.headers["X-Webhook-Signature"]
+
+begin
+  event = PaymentKit.process_webhook(payload, signature)
+  # verified + instrumented; subscribers already ran
+rescue PaymentKit::SignatureVerificationError
+  head :unauthorized  # signature missing or invalid
+rescue PaymentKit::InvalidRequestError
+  head :bad_request   # verified, but the body is not JSON
+end
+```
+
+Low-level verify without dispatch (existing Client API, preserved):
+
+```ruby
+event = client.verify_webhook(payload, signature)
+# or:
+event = PaymentKit::Webhook.construct_event(payload, signature, PaymentKit.signing_secrets)
+PaymentKit.instrument(event)
+```
+
+### Rails Engine (optional)
+
+When Rails is loaded, mount the engine to get `POST /` → verify → instrument → `200`:
+
+```ruby
+# config/routes.rb
+mount PaymentKit::Engine, at: "/payment_kit"
+```
+
+Point PaymentKit’s webhook URL at `https://your.app/payment_kit`.
+
+PaymentKit treats `4xx` as a permanent failure and retries `5xx`/timeouts five
+times over roughly 27 hours, so the controller maps failures deliberately:
+
+| Outcome | Status | Retried by PaymentKit |
+|---------|--------|-----------------------|
+| Bad or missing signature | `401` | No |
+| Verified but unparseable body | `400` | No |
+| Subscriber raised, no `error_handler` | `500` | Yes |
+| Subscriber raised, `error_handler` set | `200` | No |
+
+Endpoints must respond within 30 seconds, so subscribers should enqueue work
+rather than perform it inline.
+
+### Deduplicating redeliveries
+
+`event_retriever` runs after verification and before dispatch. Return the event
+to continue, or `nil` to drop it. PaymentKit redelivers on retry, so dedupe here
+on the event id — the same value it sends in the `X-Webhook-Event-Id` header:
+
+```ruby
+PaymentKit.event_retriever = lambda do |event|
+  key = "payment_kit:webhook:#{event["id"]}"
+  Sidekiq.redis { |r| r.set(key, "1", nx: true, ex: 3.days.to_i) } ? event : nil
+end
+```
+
+`process_webhook` returns `nil` when the retriever drops a delivery.
+
+### Reporting subscriber failures
+
+Without an `error_handler`, a raising subscriber returns `500` and PaymentKit
+retries. Set one to report the exception and answer `200` instead, which is the
+right choice when subscribers only enqueue background work:
+
+```ruby
+PaymentKit.error_handler = ->(exception, _request) { Sentry.capture_exception(exception) }
+```
+
+`error_handler` is request-scoped: it fires once, after the fan-out has already
+failed. For per-subscriber isolation use `subscriber_error_handler`, which wraps
+each subscriber individually:
+
+```ruby
+PaymentKit.subscriber_error_handler = lambda do |exception, event|
+  Sentry.capture_exception(exception, extra: { event_id: event["id"] })
+end
+```
+
+This matters because `ActiveSupport::Notifications` runs the remaining
+subscribers when one raises but still re-raises afterwards (aggregating into
+`ActiveSupport::Notifications::InstrumentationSubscriberError` when several
+fail). Without a handler the delivery fails and PaymentKit redelivers the whole
+event, re-running the subscribers that already succeeded. With one set, the
+failure is reported and the delivery is acknowledged.
+
+## Error handling
+
+All errors inherit from `PaymentKit::Error` and may expose:
+
+- `status` — HTTP status
+- `body` — raw response body
+- `request_id` — from the RFC 7807 payload, falling back to the `Request-Id` header
+- `error_code` / `retryable?` — set on transient failures such as `invoice_locked`
+- `problem` and `error["..."]` — any RFC 7807 extension member (`invoice_id`,
+  `subscription_id`, …)
+
+| Exception | Typical cause |
+|-----------|----------------|
+| `PaymentKit::AuthenticationError` | Missing/invalid key, HTTP 401 |
+| `PaymentKit::PermissionError` | HTTP 403 — valid key, but not allowed on this resource |
+| `PaymentKit::SignatureVerificationError` | Webhook signature missing or invalid |
+| `PaymentKit::InvalidRequestError` | Missing `account_id`, HTTP 400/404/422, unparseable webhook body |
+| `PaymentKit::CardError` | HTTP 402 — payment declined; the invoice stays payable |
+| `PaymentKit::ConflictError` | HTTP 409 — clashes with current resource state |
+| `PaymentKit::RateLimitError` | HTTP 429 |
+| `PaymentKit::APIError` | Other HTTP errors (including exhausted 5xx retries) |
+| `PaymentKit::APIConnectionError` | Timeouts, connection refused/reset, DNS failures |
+
+```ruby
+begin
+  client.create_subscription(params)
+rescue PaymentKit::ConflictError => e
+  retry if e.retryable? # e.g. error_code == "invoice_locked"
+  warn "Conflict on invoice #{e.invoice_id}: #{e.message}"
+rescue PaymentKit::CardError => e
+  warn "Declined: #{e.message}"
+rescue PaymentKit::InvalidRequestError => e
+  warn "Bad request (#{e.status}): #{e.message} request_id=#{e.request_id}"
+rescue PaymentKit::APIConnectionError => e
+  warn "Network problem: #{e.message}"
+rescue PaymentKit::Error => e
+  warn "PaymentKit error: #{e.message}"
+end
+```
+
+`PermissionError` and `SignatureVerificationError` both subclass
+`AuthenticationError`, so existing `rescue PaymentKit::AuthenticationError`
+blocks keep catching them.
+
+API errors follow [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem
+details (`title`, `detail`, `request_id`). Validation `detail` arrays are flattened
+into readable field messages.
+
+For compatibility with applications written against a nested error namespace,
+`PaymentKit::Client::AuthenticationError` and friends resolve to the same classes.
+
+## Idempotency
+
+- `POST`, `PUT` and `PATCH` automatically send an `Idempotency-Key` header
+  (random UUID), and the same key is reused across the gem's internal retries so
+  a retried write cannot double-charge.
+- A random key only protects a single call. For operations that must not
+  double-bill across *process-level* retries — `bill_pending_items`,
+  `create_credit_note`, charge-first `update_subscription_items` and
+  `apply_change_request` — pass your own stable key:
+
+```ruby
+client.bill_pending_items(params, idempotency_key: "dispatch-#{user_id}-#{timestamp}")
+client.update_subscription_items("sub_1", { items: [...], proration_behavior: "always_invoice" },
+                                 idempotency_key: "plan-change-#{user_id}-#{version}")
+```
+
+Every write method accepts the body positionally or as keywords, with an optional
+`idempotency_key:` alongside:
+
+```ruby
+client.create_customer(email: "a@b.com")
+client.create_customer({ email: "a@b.com" }, idempotency_key: "signup-42")
+client.create_customer(email: "a@b.com", idempotency_key: "signup-42")
+```
+
+### Retries
+
+`408`, `429` and `5xx` are always retried with exponential backoff. `409` is
+retried **only** when PaymentKit flags it (`retryable: true`, or a known
+side-effect-free `error_code` such as `invoice_locked`) — other conflicts, like
+creating a second active change request, fail immediately.
+
+A numeric `Retry-After` response header takes precedence over the backoff curve,
+capped at `PaymentKit::Client::MAX_RETRY_DELAY` (32s) so a bad header cannot park
+a request indefinitely.
+
+## Instrumentation
+
+`request_begin` and `request_end` hooks wrap every outbound API call. They are
+deliberately separate from the webhook event bus, so API traffic is never
+delivered to `PaymentKit.all` subscribers:
+
+```ruby
+PaymentKit::Instrumentation.subscribe(:request_end) do |event|
+  StatsD.timing(
+    "payment_kit.request",
+    event.duration * 1000,
+    tags: ["method:#{event.method}", "path:#{event.path}", "status:#{event.status}"]
+  )
+  Rails.logger.warn("PaymentKit retried #{event.path} #{event.num_retries}x") if event.num_retries.positive?
+end
+```
+
+`request_end` fires once per logical call — after retries, on both the success
+and failure paths — and carries `method`, `path`, `status`, `duration`,
+`num_retries` and `request_id`. A raising subscriber warns on stderr and never
+breaks the API call. `subscribe` returns a name you can pass to `unsubscribe`.
+
+## Calling unwrapped endpoints
+
+`raw_request` reaches any PaymentKit endpoint this gem does not wrap yet, reusing
+the same auth, retry, idempotency and error mapping:
+
+```ruby
+client.raw_request(:get, "/payment-links", params: { limit: 10 })
+client.raw_request(:post, "/webhook-endpoints/we_1/roll-secret",
+                   params: { ttl_seconds: 3600 }, idempotency_key: "roll-1")
+```
+
+Paths are account-scoped by default. Surfaces that sit outside the account
+prefix — such as the customer portal — opt out:
+
+```ruby
+client.raw_request(:get, "/billing-portal/token/#{token}/payment-methods",
+                   account_scoped: false)
+```
+
+It returns the parsed JSON body as a `Hash`; unlike `list_*` helpers it does not
+auto-paginate.
+
+## Testing
+
+Point the client at a stub base URL and stub `transport` (or use WebMock against
+the resolved host):
+
+```ruby
+client = PaymentKit::Client.new(
+  secret_key: "st_test",
+  base_url: "https://api.test/acc"
+)
+
+# Example: inject responses by stubbing the private transport seam in unit tests
+allow(client).to receive(:transport).and_return(fake_response)
+```
+
+In RSpec suites, call `PaymentKit.reset_configuration!` between examples that
+mutate global config.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake       # spec + rubocop
+```
+
+Interactive console:
+
+```bash
+bin/console
+```
+
+## Documentation
+
+- API & guides: https://docs.paymentkit.com
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).