@openrails/billing-ui 0.0.0-stage → 0.230.0

package/CHANGELOG.md

@@ -0,0 +1,257 @@
+# Changelog
+
+## Hosted checkout sessions (openrails#1124)
+
+- OpenRails serves the checkout session; hosts no longer write
+  `/api/v1/checkout/sessions` routes. `client.createCheckoutSession()` mints
+  one for the signed-in customer (`priceKey` or `priceId`, `successUrl`) and
+  `client.checkoutSource(id)` reads and pays it with the id alone (no bearer).
+  A refusal the buyer can act on resolves as a `failed`, `blocked` or
+  `expired` result. A `card` rail pays through the shared page too.
+- `<CheckoutFrame url onComplete theme>` frames the shared payment page and
+  `<CheckoutPage>` is that page; they speak an origin-checked frame protocol
+  (`ready`, `resize`, `complete`, `redirect`; `init {theme}`).
+- `<Checkout onRedirect>` replaces the top-window navigation of redirect rails.
+- The session document gains `embed_origin`.
+
+## Server card entry (openrails#1129)
+
+- Driver `card` (a PSP declared `card_entry: server`, flow `card`): `<Checkout>`
+  and `SavePaymentMethod` render plain card inputs with the Collect.js form's
+  layout and field errors, load no gateway script, and send
+  `card: {number, exp_month, exp_year, cvc}`. Inside a `BillingProvider` the
+  card is saved first (`addPaymentMethod({ provider, card })`) and charged by
+  id; a page without one sends `card` in `PayRequest`. The inputs are cleared
+  once the card is sent.
+- `cardSetupDriver` may return `"card"`; `NewCard` takes `payment_token` or
+  `card`, never both.
+
+## Catalog and plan-change client (openrails#1128)
+
+- `@openrails/billing-ui/client` gains the public catalog (`listProducts`,
+  `listPrices`, `listCurrencies`), plan change (`previewTierChange`,
+  `changeTier`) and Solana (`getSolanaConfig`, `listSolanaTokens`,
+  `prepareSolanaTierChange`, `confirmSolanaTierChange`) calls, with the types
+  `Product`, `Price`, `Currency`, `TierChangePreview`, `TierChange`,
+  `SolanaConfig`, `SolanaToken`, `SolanaTierChangeTx` and `SolanaTierChange`.
+  `changeTier` requires an `idempotencyKey`; reuse it until the change
+  resolves.
+- React: `useProducts`, and `useSubscriptions().changeTier` (per-row `pending`
+  `"change_tier"`, `onChange` `subscription.tier_changed`), which resolves to
+  the `TierChange` or a `BillingError`.
+
+## Explicit payment method, fail-fast errors (openrails#1087, #1088)
+
+- The checkout pre-selects the customer's default card (`PaymentMethod.default`,
+  `SavedPaymentMethod.default`) and always sends the chosen card's id.
+  OpenRails refuses a charge that names no method with
+  `payment_method_required` (400).
+- A server error (5xx) from `pay` is shown at once and the panel returns to
+  ready; hosts keep their idempotency key so paying again replays. A host
+  source signals it by throwing an error with a numeric `status`
+  (`CheckoutSourceError`, or any error carrying `status`).
+- The client never retries a write. A GET retries once, only on a network
+  error or 502/503/504 (429/503 with `Retry-After`), within `RETRY_BUDGET_MS`
+  (2 s). New `isServerError`; a 5xx without an error envelope has code
+  `server_error`.
+
+## One-click card subscriptions (openrails#1085)
+
+- A checkout host relays a card subscription's pay request with OpenRails'
+  `CreateCheckoutSessionRequest.Confirm`; a new Collect.js token subscribes in
+  one call. No package API change.
+
+## Advertised checkout rails (openrails#1078)
+
+- Breaking: `checkoutRails(offers)` takes OpenRails' checkout options alone.
+  Each option carries the `driver` and `public_config` OpenRails derived from
+  the armed PSP (Solana: `token_symbol`, `token_name`, `network`); the package
+  no longer derives drivers from `psps`. `CheckoutRailOffer` gains `selector`,
+  `driver` and `public_config`.
+
+## Moved into OpenRails
+
+The package now lives in `open-rails/openrails` under `sdk/billing-ui` and
+takes the OpenRails version: each OpenRails release `vX.Y.Z` attaches
+`openrails-billing-ui-X.Y.Z.tgz`. The e2e server and generated contract build
+the OpenRails at the same commit. `OPENRAILS_VERSION` is gone from the
+generated contract.
+
+## 0.9.0
+
+One embedded card panel for one-time purchases and subscriptions, on every
+card PSP (openrails#1064). Requires OpenRails v0.164.0.
+
+- Stripe Elements checkout rail (`driver: "stripe_elements"`, from a PSP with
+  `flow: "elements"`): saved Stripe cards or a new card in the page, 3-D
+  Secure via `authenticatePayment`; no redirect to hosted Checkout. The
+  Payment Element is cards only (no Link bank tab or wallets).
+- One screen: saved cards (brand •••• last4 · MM/YY, most recent first),
+  inline "Use a new card", one "Pay $X" / "Subscribe for $X every <period>"
+  button with the agreement line. No provider chooser for a single rail.
+- New cards are always saved to the account (no consent checkbox) before
+  paying by id; Collect.js display metadata (`last_four`, `card_type`,
+  `expiry_date`) is sent with every token.
+- Declines stay on the panel: `PayResult.failure` / `CheckoutSession.failure`
+  (`{ reason, message, field }`) render next to the card field; retry with
+  another card. `requires_action` + `operation_id` authenticates in the page.
+- Collect.js `validationCallback`: inline number/expiry/CVC errors; the
+  button waits for three valid fields. Stripe Elements and Collect.js fields
+  are themed from the page tokens.
+- `defaultCountry` on Checkout / SavePaymentMethod / AccountBilling /
+  TokenizedCardForm; fallback: the browser locale's region
+  (`initialCountry`, `browserCountry`).
+- `PspConfig.checkout`; `checkoutPsps(psps)` — only checkout PSPs take new
+  cards. `isCardRail`, `useOptionalBillingContext`.
+- `CheckoutModal`: always closable; `gate` renders host content (sign-in)
+  in place of the checkout.
+- Account: card labels read "Visa •••• 4242 · 12/30"; failed payments show
+  `payment.failure.message`.
+- Breaking: `paymentMethods.consent`/`enterCard` messages are replaced by
+  `paymentMethods.saveNotice`; `cardLabel` is "{brand} •••• {last4}".
+
+## 0.8.0
+
+Provider-neutral hosts: a host passes OpenRails's browser PSP configs through
+and never branches on Stripe, NMI or any other provider.
+
+- `checkoutRails(offers, psps)` / `savedMethodsFor(methods, rails)` derive the
+  checkout rails and chargeable saved cards from each PSP's `flow` and public
+  config.
+- `SavePaymentMethod`: consented in-page card saving with any PSP — Collect.js
+  tokenization or Stripe Elements card setup (Stripe.js is loaded on first
+  use). `canSavePaymentMethod`, `cardSetupDriver`.
+- `authenticatePayment(client, operationId, psp)`: 3-D Secure for a pending
+  payment operation. `canAuthenticatePayment`.
+- Client: `createCardSetup`, `getCardSetup`, `confirmCardSetup`,
+  `getPaymentAuthentication`, `confirmPaymentAuthentication`.
+- Breaking: `AccountBilling`/`PaymentMethodsPanel` take `psps` (and optional
+  `cardSetupReturnURL`) instead of `cardSetup`; `CardSetupConfig` is removed.
+  Stripe card setup needs OpenRails serving Stripe's `publishable_key`
+  (openrails#1062).
+
+## 0.7.0
+
+- Periods are exact. OpenRails windows are hours, so a 720h price reads
+  "every 30 days" (was "every month") and 8760h "every 365 days"; only exact
+  weeks, days or hours are named, in the account panels and the checkout
+  summary, in all six locales.
+- Plural messages: `interval.every|per|access.<hour|day|week>` are CLDR plural
+  nodes (`{ one, other }`, exact `"1"` for 毎日-style forms) chosen by the
+  provider's `locale`; `Translator.plural(key, count)`. Breaking for hosts
+  overriding the removed `interval.day|week|month|year|days|hours` keys.
+- Payment history names what was bought: the product's `display_name` from
+  OpenRails (`payment.product`, OpenRails after v0.160.0) and the renewal
+  period; older servers fall back to "Subscription"/"Purchase".
+- Checkout summary copy ("Renews {period}") is a message: `checkout.renews`.
+- The e2e harness and route contract pin OpenRails master `78039ea` (first
+  commit serving `payment.product`; untagged, after v0.160.0).
+
+## 0.6.0
+
+- "Add card" works against real OpenRails, which requires the PSP that
+  tokenized the card: `CardSetupConfig.provider` (the PSP key, e.g. `"nmi"`)
+  is required and sent as `NewCard.provider`. Before, every add was refused
+  with 400 `provider is required`.
+
+## 0.5.2
+
+- `renderSubscriptionFooter` (on `SubscriptionsPanel` and `AccountBilling`)
+  renders host content under a subscription row, e.g. a plan-change control.
+- `useBillingRefresh()` (from `./react`) refetches every hook after a
+  host-side change such as a plan switch.
+- The cancel and change-card dialogs use the panel's `appearance`; they read
+  only the provider's, so `AccountBilling appearance` missed them.
+
+## 0.5.1
+
+- `appearance.theme: "inherit"`: no bundled palette; components use the host
+  page's shadcn tokens and follow its `.dark` class.
+- `SubscriptionsPanel`: "Change card" switches the saved card an active NMI
+  subscription renews on (`useSubscriptions().setPaymentMethod`), which now
+  notifies `subscription.payment_method_changed`.
+
+## 0.5.0
+
+Account billing, alongside checkout. No change to checkout's API.
+
+- `@openrails/billing-ui/client`: `createBillingClient` for the OpenRails
+  customer surface (`/billing/v1/me/*`): subscriptions (list, get, cancel with
+  feedback, resume, payment method, Solana on-chain cancel), payment methods
+  (list, add tokenized card, remove, per-currency default), payments, invoices,
+  status. zod-validated responses, `BillingError` from the error envelope, the
+  pinned currency registry for exact money.
+- `@openrails/billing-ui/react`: `BillingProvider` (`onChange` for host cache
+  invalidation), `useSubscriptions`, `usePaymentMethods`, `usePayments`.
+- Styled: `AccountBilling`, `SubscriptionsPanel` with cancel/resume dialog and
+  provider-portal links, `PaymentMethodsPanel` (adding a card uses
+  `TokenizedCardForm`), `PaymentHistory`, `BillingStatusBadge`,
+  `BillingUiProvider`, `BillingUiRoot`.
+- Messages: typed bundles with `en de es ja ko zh` under `./locales/*`.
+- `formatAmount` takes an optional locale.
+- The route contract and e2e suite run against real OpenRails v0.159.0.
+
+## 0.4.2
+
+No API or visual change.
+
+- Components import `cn` from the [`cn`](https://github.com/shadcn-ui/cn)
+  package (pinned `0.4.0`), replacing `clsx` and `tailwind-merge`.
+
+## 0.4.1
+
+Visual only; no API change.
+
+- UI primitives regenerated as shadcn `base-vega` on a zinc palette.
+- Theme tokens now map to Tailwind colors, so token utilities (`bg-primary`,
+  `text-muted-foreground`, `border-input`, …) render; in 0.4.0 they emitted no
+  CSS, leaving the pay button and selected radios unstyled.
+- `dark:` variants follow `appearance.theme` instead of the OS alone.
+- `CheckoutModal` now paints its popover panel; buttons inside `.orck` drop the
+  UA button face.
+
+## 0.4.0
+
+Breaking: the package is renamed `openrails-checkout` → `@openrails/billing-ui`.
+
+- Import from `@openrails/billing-ui` and `@openrails/billing-ui/styles.css`.
+- The injected stylesheet is `<style id="billing-ui-styles" data-billing-ui>`.
+- Releases attach the packed tarball to the GitHub release instead of
+  publishing to npm:
+  `https://github.com/open-rails/billing-ui/releases/download/v0.4.0/openrails-billing-ui-0.4.0.tgz`.
+
+## 0.3.0
+
+Breaking: the session document carries exact money.
+
+- Accepted `processing` outcomes poll the same source without repeating payment
+  or tokenization. Ambiguous pay errors retain that pending attempt; local expiry
+  cannot turn it into a failure. Pending sessions may omit/null `expires_at`.
+- Export `TokenizedCardForm` for separately consented NMI card setup, reusing the
+  existing hosted fields without presenting setup as a payment.
+- Source changes fence late payment callbacks from the previous checkout.
+
+- `plan.unit_amount`, `line_items[].amount`, `tax` and `due_today` are int64
+  decimal strings of `plan.currency`'s native unit; `plan.unit_decimals` (the
+  currency's registered scale) is required. Numeric amounts are refused as an
+  unavailable session. Replaces `unit_amount_micros`, `amount_micros`,
+  `tax_micros` and `due_today_micros`, which were JSON numbers at an assumed
+  six decimals.
+- Rendering never passes money through a JS number (`BigInt` scaling, exact
+  Intl decimal formatting, refusal instead of rounding). `formatAmount`,
+  `amountToDecimal`, `addAmounts`, `isAmount`, `amountSchema` and
+  `unitDecimalsSchema` are exported.
+- Hosts build the plan with `openrails.NewHostedCheckoutPlan` (OpenRails
+  `HostedCheckoutSession` types); the package decodes OpenRails' canonical
+  `hosted_checkout_session.json` fixture.
+
+## 0.2.5
+
+- A Solana option is named after the host-bound token and network; the former
+  `USDC` default is removed.
+- Releases publish to npm through the GitHub release workflow.
+
+## 0.2.4
+
+- Hosts must accept `name_on_card` on the pay endpoint; `first_name` and
+  `last_name` are no longer emitted.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenRails and Paul Fidika
+
+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.

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# @openrails/billing-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Embeddable OpenRails billing UI: the checkout flow and the customer's account
+billing (subscriptions, saved cards, payment history).
+
+| Import                            | Contents                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `@openrails/billing-ui/client`    | Framework-free typed client for `/billing/v1/me/*` and the catalog, `BillingError` |
+| `@openrails/billing-ui/react`     | `BillingProvider` and headless hooks                                               |
+| `@openrails/billing-ui`           | Styled checkout and account components, `BillingUiProvider`, i18n                  |
+| `@openrails/billing-ui/locales/*` | `en de es ja ko zh` message bundles                                                |
+
+The checkout owns the browser payment flow. OpenRails holds the checkout
+session: the signed-in customer mints one for a price, and its `ocs_` id alone
+reads and pays it. Card data is tokenized in NMI-hosted Collect.js iframes and
+never enters the host application, unless the PSP takes cards on OpenRails
+itself (`card_entry: server`, driver `card`).
+
+See [Payment form contract](docs/payment-form-contract.md) for the exact-money
+session document, billing fields, browser-autofill behavior, and the checkout
+request schema.
+
+The package lives in the OpenRails repository and shares its version: each
+OpenRails release `vX.Y.Z` attaches `openrails-billing-ui-X.Y.Z.tgz`.
+
+```sh
+pnpm add https://github.com/open-rails/openrails/releases/download/vX.Y.Z/openrails-billing-ui-X.Y.Z.tgz
+```
+
+## Checkout
+
+```tsx
+import { createBillingClient } from "@openrails/billing-ui/client"
+import { Checkout, CheckoutFrame } from "@openrails/billing-ui"
+import "@openrails/billing-ui/styles.css"
+
+const billing = createBillingClient({ fetch: auth.authFetch })
+const session = await billing.createCheckoutSession({ priceKey: "pro-monthly" })
+
+// A shared payment page (Config.HTTP.Checkout.PageURL) answers with a url:
+<CheckoutFrame url={session.url} theme="dark" onComplete={() => refetchAccess()} />
+// Without one, the app renders the checkout itself:
+<Checkout source={billing.checkoutSource(session.id)} onComplete={() => refetchAccess()} />
+```
+
+`onComplete` is a hint: confirm access from your own authenticated API before
+granting anything. Pass `successUrl` to return the buyer from a redirect rail
+(CCBill, Stripe hosted); it must be on one of your app's return origins.
+
+The payment host serves `<CheckoutPage>` from one HTML entry at `PageURL`,
+behind its adapter's `CheckoutFramePolicy` (only the sites in
+`Config.HTTP.Checkout.EmbedOrigins` may frame it):
+
+```tsx
+import { BillingUiProvider, CheckoutPage } from "@openrails/billing-ui"
+
+createRoot(root).render(
+  <BillingUiProvider>
+    <CheckoutPage appearance={{ variables: brand }} />
+  </BillingUiProvider>
+)
+```
+
+The page reads the session id from its URL fragment and talks to its frame
+with `postMessage`, origin-checked both ways: page to app `ready`,
+`resize {height}`, `complete {status}` and `redirect {url}` (a nested frame
+cannot navigate the top window, so the app does); app to page
+`init {theme}`. The page messages only the app origin recorded on its session.
+
+## Account billing
+
+```tsx
+import { createBillingClient } from "@openrails/billing-ui/client"
+import { BillingProvider } from "@openrails/billing-ui/react"
+import { AccountBilling, BillingUiProvider } from "@openrails/billing-ui"
+import { de } from "@openrails/billing-ui/locales/de"
+
+// auth-ui's authFetch attaches the bearer and retries once after a refresh;
+// `getToken: () => token` works for any other auth.
+const billing = createBillingClient({ baseUrl: "/billing/v1", fetch: auth.authFetch })
+
+<BillingUiProvider appearance={{ theme: "auto" }} messages={de} locale="de" navigate={navigate}>
+  <BillingProvider client={billing} onChange={() => queryClient.invalidateQueries({ queryKey: ["billing"] })}>
+    <AccountBilling
+      plansHref="/plans"
+      psps={checkoutConfig.psps} // OpenRails checkout config; enables "Add card"
+      defaultCurrency="USD" // enables "Make default"
+      sendSolanaTransaction={(tx) => wallet.signAndSend(tx)} // Solana-rail cancel
+    />
+  </BillingProvider>
+</BillingUiProvider>
+```
+
+## Catalog and plan changes
+
+The client also reads the public catalog and changes a subscription's plan.
+No UI ships for these; hosts render their own. The catalog, currency and
+Solana reads are public routes, served only when the host mounts OpenRails'
+checkout routes.
+
+| Call                                                                                                | Route                                                           |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `listProducts()`, `listPrices({ currency, product, type })`                                         | `GET /products`, `GET /prices`                                  |
+| `listCurrencies()` (`client.currencies` is the pinned copy)                                         | `GET /currencies`                                               |
+| `previewTierChange(id, priceId)`                                                                    | `POST /me/subscriptions/{id}/change-tier/preview`               |
+| `changeTier(id, { priceId, idempotencyKey })`                                                       | `POST /me/subscriptions/{id}/change-tier`                       |
+| `getSolanaConfig()`, `listSolanaTokens({ priceId, wallet })`                                        | `GET /solana/config`, `GET /solana/tokens`                      |
+| `prepareSolanaTierChange(id, newPriceId)`, `confirmSolanaTierChange(id, { signature, newPriceId })` | `POST /me/subscriptions/{id}/solana-tier-change`, `.../confirm` |
+
+```ts
+const preview = await billing.previewTierChange(sub.id, price.id) // amount_due_now, effective
+const change = await billing.changeTier(sub.id, {
+  priceId: price.id,
+  idempotencyKey,
+})
+```
+
+- `changeTier` is a money write. Mint one `idempotencyKey` per attempt and
+  reuse it until the change resolves (`status: "processing"`, a
+  `tier_change_in_flight` refusal naming `metadata.operation_id`, a 5xx or a
+  lost response), so OpenRails replays the stored result instead of charging
+  twice. `requires_action` carries `operation_id` for `authenticatePayment`;
+  replay the same key afterwards.
+- Solana rail: the wallet signs and sends `prepareSolanaTierChange`'s
+  `transaction`; pass its signature to `confirmSolanaTierChange`. Keep the
+  signature until the confirm succeeds; confirming again replays the result.
+
+## Provider-neutral flows
+
+Hosts pass OpenRails's browser PSP configs (`GET /checkout-config`, `psps`)
+through unchanged; the PSP's `flow` and public `config` pick the browser flow
+(Collect.js, native card inputs, Stripe Elements, redirect, wallet). Hosts never branch on a
+provider:
+
+- `checkoutRails(offers)` and `savedMethodsFor(methods, rails)` build a
+  `CheckoutSource`'s `rails` and `saved_methods` (the default card first, pre-selected; paying sends
+  the chosen card's id explicitly).
+  `offers` is OpenRails' `ListCheckoutRailOptions` result, passed through: it
+  lists exactly the armed PSPs whose rail can make this sale (Solana when it is
+  configured, never CCBill for a new subscription), each with its `driver` and
+  `public_config`. An offer without a driver is not rendered.
+  Card rails (`collect_js`, `card`, `stripe_elements`) render one panel: saved cards,
+  an inline new card and one Pay/Subscribe button, which is the payer's
+  confirmation of the displayed terms. No provider chooser with one rail.
+- Inside a `BillingProvider`, a new card is always saved to the account first
+  and the source is paid with `payment_method_id`; `requires_action` results
+  carrying `operation_id` run 3-D Secure in the page. A `failed` result stays
+  on the panel with `failure.message` next to its `field`, so the buyer can
+  pick another card; the host gives each new attempt a new idempotency key.
+- Only PSPs with `checkout !== false` (`checkoutPsps`) take new cards; others
+  stay listed so existing cards and subscriptions keep working.
+- `<SavePaymentMethod psp={psp} onSaved={(id) => ...} />` saves a card in the
+  page (needs `BillingProvider`); `canSavePaymentMethod(psp)` filters PSPs
+  that support it. After an off-page verification the provider returns to
+  `returnURL(setupId)`; confirm with `client.confirmCardSetup(id)`.
+- `authenticatePayment(client, operationId, psp)` completes a pending
+  payment's 3-D Secure challenge when `canAuthenticatePayment(psp)`.
+- `defaultCountry` (Checkout, SavePaymentMethod, AccountBilling) preselects
+  the billing country, else the browser locale's region.
+- `CheckoutModal gate={<SignIn />}` renders host content (e.g. sign-in) in
+  the modal instead of the checkout until cleared.
+
+- Panels: `SubscriptionsPanel` (cancel, resume, change card),
+  `PaymentMethodsPanel`, `PaymentHistory`, `BillingStatusBadge`,
+  `CancelSubscriptionDialog`; `AccountBilling` stacks them.
+- `renderSubscriptionFooter={(s) => ...}` adds host content under a
+  subscription row; `useBillingRefresh()` refetches after host-side changes.
+- Hooks: `useSubscriptions` (`cancel`, `cancelOnChain`, `resume`,
+  `setPaymentMethod`, `changeTier`, per-row `pending`), `usePaymentMethods`
+  (`add`, `remove`, `setDefault`), `usePayments` (offset pages), `useProducts`
+  (the catalog). Actions resolve to `null` or a `BillingError`; they never
+  throw. `changeTier` resolves to the `TierChange` instead of `null`. Cancel
+  and resume are queued by OpenRails (202); hooks re-read the subscription
+  until the change shows.
+- Money is exact: `/me` amounts are int64 native-unit strings, scaled by the
+  OpenRails currency registry (`currencies` option to extend it).
+- Messages: English is complete and the fallback; `messages` layers bundles,
+  `t` lets the host's i18n win. `useMessages().error(err)` maps error codes.
+  Count-dependent messages are CLDR plural nodes (`{ one, other }`, plus an
+  exact `"1"` like ICU `=1`), selected with `locale`.
+- Periods are exact: OpenRails windows are hours, so 720h reads "every 30
+  days", never "monthly"; only exact weeks, days or hours are named.
+- Styles are scoped under `.orck`; `appearance.theme` is `light`, `dark`,
+  `auto` or `inherit`. `inherit` bundles no palette: the host page's shadcn
+  tokens (`--background`, `--primary`, ...) and its `.dark` class apply.
+
+## UI primitives
+
+`src/components/ui/*` is shadcn (`base-vega`, zinc; see `components.json`),
+managed with `pnpm dlx shadcn@4.21.0 add <name> --overwrite`, importing `cn`
+from the [`cn`](https://github.com/shadcn-ui/cn) package.
+
+## E2E against real OpenRails
+
+`e2e/server` is a Go module that builds the OpenRails at this commit (`replace`
+to the repository root) with AuthKit. It serves the
+embedded `/billing/v1` API and `/auth/v1` on a throwaway `postgres:18-alpine`
+container (Docker and Go required), with test-only `POST /__test/users` (user +
+access token) and `POST /__test/users/{id}/billing` (imported subscription,
+sale and saved card on a credential-less NMI PSP).
+
+```sh
+pnpm test:e2e        # Playwright against the real server
+pnpm contract        # regenerate src/client/generated from the in-repo OpenRails
+pnpm contract:check  # fail if the generated contract is stale
+```
+
+`e2e/openrails/account.spec.ts` drives the packaged `AccountBilling` (built from
+`dist/`) through list, cancel, resume, the in-use card refusal and history. Set
+`BILLING_UI_SCREENSHOTS=<dir>` to capture light, dark and mobile screenshots.
+Card deletion calls NMI, which the harness has no credentials for; jsdom tests
+cover it.

package/dist/account/account-billing.d.ts

@@ -0,0 +1,19 @@
+import { CheckoutAppearance } from '../appearance';
+import { SendSolanaTransaction } from '../client/client';
+import { PaymentMethodsPanelProps } from './payment-methods-panel';
+import { SubscriptionsPanelProps } from './subscriptions-panel';
+export interface AccountBillingProps {
+    psps?: PaymentMethodsPanelProps["psps"];
+    cardSetupReturnURL?: PaymentMethodsPanelProps["cardSetupReturnURL"];
+    defaultCurrency?: string;
+    /** Billing country to preselect when adding a card. */
+    defaultCountry?: string;
+    sendSolanaTransaction?: SendSolanaTransaction;
+    plansHref?: string;
+    renderSubscriptionFooter?: SubscriptionsPanelProps["renderSubscriptionFooter"];
+    historyPageSize?: number;
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+/** Subscriptions, payment methods and history in one column. */
+export declare function AccountBilling({ psps, cardSetupReturnURL, defaultCurrency, defaultCountry, sendSolanaTransaction, plansHref, renderSubscriptionFooter, historyPageSize, appearance, className, }: AccountBillingProps): import("react").JSX.Element;

package/dist/account/cancel-dialog.d.ts

@@ -0,0 +1,18 @@
+import { CheckoutAppearance } from '../appearance';
+import { BillingError } from '../client/errors';
+import { SubscriptionAction } from '../react/hooks';
+import * as React from "react";
+export interface CancelSubscriptionDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Subscription display name. */
+    name: string;
+    /** On-chain (Solana) cancel: no feedback, the wallet signs. */
+    onChain?: boolean;
+    /** In-flight stage, when cancelling. */
+    pending?: SubscriptionAction;
+    /** Resolves null on success; the dialog then closes. */
+    onConfirm: (feedback: string) => Promise<BillingError | null>;
+    appearance?: CheckoutAppearance;
+}
+export declare function CancelSubscriptionDialog({ open, onOpenChange, name, onChain, pending, onConfirm, appearance, }: CancelSubscriptionDialogProps): React.JSX.Element;

package/dist/account/change-card-dialog.d.ts

@@ -0,0 +1,14 @@
+import { CheckoutAppearance } from '../appearance';
+import { BillingError } from '../client/errors';
+import { Subscription } from '../client/types';
+import * as React from "react";
+export interface ChangeCardDialogProps {
+    subscription: Subscription | null;
+    name: string;
+    onOpenChange: (open: boolean) => void;
+    pending: boolean;
+    /** Resolves null on success; the dialog then closes. */
+    onConfirm: (paymentMethodId: string) => Promise<BillingError | null>;
+    appearance?: CheckoutAppearance;
+}
+export declare function ChangeCardDialog({ subscription, name, onOpenChange, pending, onConfirm, appearance, }: ChangeCardDialogProps): React.JSX.Element;

package/dist/account/format.d.ts

@@ -0,0 +1,25 @@
+import { CardSummary, CurrencyScales, Payment, Subscription, SubscriptionPrice } from '../client/types';
+import { Translator } from '../i18n/messages';
+export declare function formatDate(value: string | null | undefined, locale?: string): string | null;
+/** Exact money, or null while the currency's scale is unknown. */
+export declare function formatMoney(amount: string | null | undefined, currency: string, scales: CurrencyScales, locale?: string): string | null;
+/** "every 30 days", "30 days of access" or "one-time". */
+export declare function intervalLabel(price: SubscriptionPrice | null | undefined, m: Translator): string | null;
+export declare function subscriptionName(s: Subscription, { t }: Translator): string;
+/** What a payment bought: the product's name, else its kind, plus its cadence. */
+export declare function paymentItem(p: Payment, m: Translator): {
+    name: string;
+    detail: string | null;
+};
+export declare function brandName(brand: string | null | undefined, fallback: string): string;
+/** "Visa •••• 4242 · 12/30"; the brand alone when no digits are known. */
+export declare function cardText(card: CardSummary | null | undefined, m: Translator): string;
+export declare function expiry(card: CardSummary | null | undefined): string | null;
+export declare const LIVE_STATUSES: Set<string>;
+/** Still grants access: live, or cancelled with the paid period running. */
+export declare const isLive: (s: Subscription) => boolean;
+/** Access ends at period end and nothing renews it. */
+export declare const isEnding: (s: Subscription) => boolean;
+export type StatusTone = "success" | "warning" | "destructive" | "neutral";
+export declare const statusTone: (status: string) => StatusTone;
+export declare const RESET = "[&_h2]:m-0 [&_p]:m-0 [&_ul]:m-0 [&_ul]:list-none [&_ul]:p-0 [&_table]:border-spacing-0";

package/dist/account/notice.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+/** Polite confirmation line that clears itself. */
+export declare function useNotice(): [React.ReactNode, (text: string) => void];

package/dist/account/payment-history.d.ts

@@ -0,0 +1,8 @@
+import { CheckoutAppearance } from '../appearance';
+import { PaymentsOptions } from '../react/hooks';
+import * as React from "react";
+export interface PaymentHistoryProps extends PaymentsOptions {
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+export declare function PaymentHistory({ appearance, className, ...options }: PaymentHistoryProps): React.JSX.Element;

package/dist/account/payment-methods-panel.d.ts

@@ -0,0 +1,19 @@
+import { CheckoutAppearance } from '../appearance';
+import { PspConfig } from '../psp';
+import * as React from "react";
+export interface PaymentMethodsPanelProps {
+    /**
+     * OpenRails's browser PSP configs (checkout config). "Add card" offers
+     * each one a card can be saved with in the page.
+     */
+    psps?: readonly PspConfig[];
+    /** Return target after off-page card verification; see `SavePaymentMethod`. */
+    cardSetupReturnURL?: (setupId: string) => string;
+    /** Enables "Make default" for this currency's invoice collection. */
+    defaultCurrency?: string;
+    /** Billing country to preselect when adding a card. */
+    defaultCountry?: string;
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+export declare function PaymentMethodsPanel({ psps, cardSetupReturnURL, defaultCurrency, defaultCountry, appearance, className, }: PaymentMethodsPanelProps): React.JSX.Element;

package/dist/account/section.d.ts

@@ -0,0 +1,25 @@
+import { CheckoutAppearance } from '../appearance';
+import { BillingError } from '../client/errors';
+import * as React from "react";
+export interface SectionProps {
+    title: string;
+    description?: string;
+    action?: React.ReactNode;
+    appearance?: CheckoutAppearance;
+    className?: string;
+    children?: React.ReactNode;
+    "data-testid"?: string;
+}
+export declare function Section({ title, description, action, appearance, className, children, ...rest }: SectionProps): React.JSX.Element;
+export declare function ListSkeleton({ rows }: {
+    rows?: number;
+}): React.JSX.Element;
+export declare function EmptyState({ title, description, action, }: {
+    title: string;
+    description?: string;
+    action?: React.ReactNode;
+}): React.JSX.Element;
+export declare function ErrorState({ error, onRetry, }: {
+    error: BillingError;
+    onRetry: () => void;
+}): React.JSX.Element;

package/dist/account/status-badge.d.ts

@@ -0,0 +1,8 @@
+export interface BillingStatusBadgeProps {
+    /** Subscription, payment or card-health status. */
+    status: string;
+    /** Overrides the translated label. */
+    label?: string;
+    className?: string;
+}
+export declare function BillingStatusBadge({ status, label, className, }: BillingStatusBadgeProps): import("react").JSX.Element;