@openrails/billing-ui 0.234.0 → 0.236.0

package/CHANGELOG.md

@@ -1,9 +1,134 @@
 # Changelog
 
+## Apple Pay and Google Pay
+
+- `<OrderCheckout wallets>` offers Apple Pay and Google Pay through a Stripe
+  PSP's Express Checkout Element, above the saved and new cards. Off by
+  default: the page's host must be a payment-method domain registered on that
+  Stripe account.
+
+## Renewals are orders
+
+- `Order` gains `renewal` (a subscription renewal's period and `due_at`) and
+  `voided_at`; `expires_at` is null on a renewal; `status` may be `void`.
+- `PaymentRecovery` gains `order_id`: an engine-owned subscription's unpaid
+  renewal, paid through `<OrderCheckout>`.
+- `<OrderCheckout>` offers new card entry only where the order takes one (a
+  renewal takes saved cards), and lets the customer authenticate a payment
+  their bank challenged while they were away.
+
+## Hosted checkout
+
+- `getConfig()` returns `merchant` (`PublicMerchant`: `display_name`, and
+  `logo_url` and `support_url` when they are https), null when the request
+  resolves no merchant.
+- `Order` carries `checkout` (its hosted checkout: `expires_at`,
+  `success_url`, `cancel_url`, `saved_payment_methods`; `url` only on the
+  answer that made it), null without one.
+
+## Orders take Solana and hosted pages
+
+- `<OrderCheckout>` offers an order's Solana option: one button per token,
+  then the Solana Pay QR of the order's `solana_pay` next action, confirmed
+  until the transfer lands.
+- A PSP with no fields in the page (Stripe without a publishable key) takes
+  the order on its hosted page: `<OrderCheckout>` sends the customer there and
+  back to `returnUrl` (default: the current page).
+- `OrderPaymentInput` gains `{ token_symbol, psp_id? }` and
+  `{ return_url, psp_id? }`.
+
+## OrderCheckout pays an order
+
+- `<OrderCheckout orderId>` shows an order and pays it with a saved card or a
+  new card in the PSP's fields, running any `next_action` and `confirm`. It
+  takes an optional `client` and offers only cards kept for one-click buys
+  (`PaymentMethod.reusable`).
+- The client gains `getOrder`, and `payOrder` and `confirmOrder`, which answer
+  `{ order, error? }`: a declined payment (402) is the order with
+  `payment.last_payment_error`, not a throw. `BillingError` carries `order`.
+- `StripeCardEntry`'s handle gains `tokenize()` and `handleNextAction()`.
+
+## A card is saved in one call
+
+- `addPaymentMethod` takes `token` (was `payment_token`). A Stripe card is a
+  `pm_` from Stripe's fields, saved by the same call; a card the bank wants to
+  authenticate answers `status: "requires_action"` with `next_action`, and
+  `confirmPaymentMethod(id)` finishes it after Stripe.js `handleNextAction`.
+  `StripeCardEntry` and `SavePaymentMethod` do this themselves.
+- `createCardSetup`, `getCardSetup`, `confirmCardSetup`, the `CardSetup` type
+  and the `returnURL` / `cardSetupReturnURL` props are gone: 3-D Secure runs in
+  the page.
+
+## Offers sell products by key
+
+- The public catalog is a lookup by product key: `listProducts({ keys })` and
+  `useProducts({ keys })` take the keys alone (1 to 100) and read one page;
+  `entitlements`, `limit` and `cursor` are gone, and so is
+  `ProductsState.nextCursor`. No keys fetch nothing.
+- `<Offers keys>` replaces `<Offers entitlements>`: your server names the
+  products, with the Go `Client.ListOffers` when it finds them by
+  entitlement.
+
+## Apps buy through BuyButton and Offers
+
+- `Checkout` and `CheckoutModal` (and their props), the fixture sources and
+  the `CheckoutSource` type are no longer exported; the client no longer has
+  `createCheckoutSession` or `checkoutSource`. Buy with `<BuyButton>` (it takes
+  `amount`, `autoRenew` and `successUrl`) or `<Offers>`. `CheckoutPage` and
+  `CheckoutFrame` stay, for the shared payment page.
+- The main entry also exports `createBillingClient` (with `BillingClient`,
+  `BillingClientOptions` and `ProductListOptions`) beside `formatAmount`, so a
+  React app imports from `@openrails/billing-ui` alone; `./client` and
+  `./react` are unchanged.
+
+## One provider
+
+- `BillingProvider` takes what `BillingUiProvider` took (`appearance`,
+  `messages`, `t`, `locale`, `navigate`) beside `client` and `onChange`, and
+  `BillingUiProvider` is gone. The main entry exports it; `./react` exports the
+  same component for hook-only apps, without the stylesheet. `client` is
+  optional: leave it out where no customer signs in, such as `CheckoutPage`.
+- Inside a provider with a client, the checkout saves a new card to the
+  customer first and pays on the customer surface.
+
+## Offers sell an entitlement
+
+- `<BuyButton product price onPaid onSignInRequired>` buys one price, labelled
+  from the catalog unless given `label`. The app never touches a checkout
+  session: when orders take a new card (#1168) it creates an order instead.
+- `<Offers entitlements onPaid onSignInRequired>` lists every product on sale
+  granting any of the entitlements, a `BuyButton` per price; `products` feeds
+  it from the host's server instead.
+- `listProducts({ entitlements, keys })` and `useProducts({ entitlements, keys })`
+  filter the public catalog. One of them is required: OpenRails no longer
+  lists the whole catalog publicly.
+
+## Checkout saves a new card under its PSP
+
+- Inside a `BillingProvider`, `Checkout` saved a new card with the session
+  option's id as `psp_id`, which `POST /me/payment-methods` refuses
+  (`invalid_param`); it now sends the option's `psp_id`.
+
+## A default card per currency
+
+- `setDefaultPaymentMethod({currency, paymentMethodId})` (`PUT
+  /me/default-payment-methods/{currency}`) replaces
+  `setCollectionPaymentMethod`: the default card pays the currency's invoices
+  and every subscription in it without its own card. `usePaymentMethods()`
+  has `setDefault` for `setCollection`, `PaymentMethod.default_currencies`
+  replaces `collection_currencies`, and the `payment_method.default_changed`
+  change replaces `payment_method.collection_changed`.
+- `AccountBilling` and `PaymentMethodsPanel` take `defaultCurrency` (was
+  `collectionCurrency`) and offer "Make default".
+- `setSubscriptionPaymentMethod(id, null)` and `setPaymentMethod(id, null)`
+  make a subscription follow the default card; `Subscription.payment_method_id`
+  is its own card, null when it follows. The change-card dialog offers "Your
+  default card" and opens on any card subscription (`collection_policy`).
+
 ## The customer's summary
 
-- `getAccount()` reads `GET /me`: the balance per currency, the card that
-  pays each currency, and the unread notice count.
+- `getAccount()` reads `GET /me`: the balance per currency, the default card
+  of each currency, and the unread notice count.
 - `Invoice.delinquent`: overdue past grace; new usage in its currency is
   refused until it is paid.
 
@@ -14,6 +139,21 @@
   final retry, and whether it waits for a new card. Null unless the
   subscription is `past_due` or `awaiting_method`.
 
+## Subscription changes and seats
+
+- `changeTier` and `previewTierChange` are `changeSubscription(id,
+  { priceId?, quantity?, idempotencyKey, signature? })` and
+  `previewSubscriptionChange(id, { priceId?, quantity? })`, on
+  `POST /me/subscriptions/{id}/change[/preview]`. `TierChange` and
+  `TierChangePreview` are `SubscriptionChange` and `SubscriptionChangePreview`:
+  no `action`, a `quantity`. `useSubscriptions().changeTier` is
+  `changeSubscription`, its pending state `change`, and its host event
+  `subscription.changed`.
+- `Subscription` has `quantity`: the seats of a per-seat price, null
+  otherwise; `scheduled_change.quantity` is the seats the next renewal bills. The `tier_change_*` codes are
+  `subscription_change_*`, and `quantity_not_allowed` refuses seats on a price
+  without them.
+
 ## The public catalog is under /catalog
 
 - `listProducts()` reads `GET /catalog/products` (was `GET /products`).

package/README.md

@@ -6,13 +6,13 @@ 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/react`     | `BillingProvider` and headless hooks, without styles                               |
+| `@openrails/billing-ui`           | `BillingProvider`, styled checkout and account components, 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
+The checkout owns the browser payment flow, behind `<BuyButton>` and
+`<Offers>`. 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`).
 
@@ -21,41 +21,65 @@ 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`.
+OpenRails release `vX.Y.Z` publishes `@openrails/billing-ui@X.Y.Z` to npm, with
+provenance.
 
 ```sh
-pnpm add https://github.com/open-rails/openrails/releases/download/vX.Y.Z/openrails-billing-ui-X.Y.Z.tgz
+pnpm add @openrails/billing-ui@X.Y.Z
 ```
 
-## Checkout
+## Buying
+
+A React app imports from one place:
 
 ```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({
-  productKey: "pro",
-  priceKey: "monthly",
-})
+import { BillingProvider, BuyButton, Offers, createBillingClient, formatAmount } from "@openrails/billing-ui"
 
-// A shared payment page (Config.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()} />
+// 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 })
+
+<BillingProvider client={billing} appearance={{ theme: "auto" }}>
+  <App />
+</BillingProvider>
 ```
 
-`onComplete` is a hint: confirm access from your own authenticated API before
-granting anything. Pass `successUrl` to return the buyer from a redirect step
-(Stripe's hosted page); it must be on one of your app's return origins. A
-server that starts checkout itself mints the session with the Go
-`Client.CreateCheckoutSession` and hands the browser its `id` and `url`.
+`<BuyButton>` buys one price, `<Offers>` the products your server names by
+key (a course, its bundle and the membership that also unlocks it; the Go
+`Client.ListOffers` finds the products granting an entitlement): a
+`BuyButton` per price ("$4.99", "Rent for 3 days, $1.99",
+"$10.00 every 30 days"). The purchase is theirs from start to payment, so the
+app never handles a checkout session: today a button opens one in a checkout
+dialog; when orders take a new card it will create an order instead,
+and apps won't change. Signing in is the host's: with `signedIn={false}`, or
+when OpenRails answers 401, they call `onSignInRequired` instead. `onPaid`
+follows a successful payment only; it is a hint, so confirm access from your
+own API (your gate) before granting anything.
 
-For prepaid credits, a fixed pack is another product/price selection. A
-`customer_amount` price also accepts `amount` when minting. Collect the amount
-on your product page before opening checkout; the resulting session shows and
-charges that exact amount, and its payment form cannot change it:
+```tsx
+<BuyButton
+  product="course-101"
+  price="rent" // labelled from the catalog unless you pass label
+  signedIn={signedIn}
+  onSignInRequired={() => openSignIn()}
+  onPaid={() => navigate("/courses/css-101")} // your gate now admits them
+/>
+
+<Offers
+  keys={["course-101", "course-bundle", "channel-membership"]} // from your server, or products={...} from its Client.ListOffers
+  signedIn={signedIn}
+  onSignInRequired={() => openSignIn()}
+  onPaid={() => navigate("/courses/css-101")}
+/>
+```
+
+`successUrl` returns the buyer from a redirect step (Stripe's hosted page); it
+must be on one of your app's return origins. `autoRenew={false}` buys a
+recurring price's first term only.
+
+For prepaid credits, a fixed pack is another product/price. A
+`customer_amount` price takes the buyer's `amount`: collect it on your product
+page, and the checkout charges exactly that:
 
 ```tsx
 import { decimalToAmount } from "@openrails/billing-ui/client"
@@ -64,42 +88,46 @@ import { decimalToAmount } from "@openrails/billing-ui/client"
 // `enteredAmount` is the text from an <input inputMode="decimal">, e.g. "100".
 const amount = decimalToAmount(enteredAmount, currency.decimals)
 const bounds = depositPrice.customer_amount
-if (
-  !amount ||
-  !bounds ||
-  BigInt(amount) < BigInt(bounds.min_amount) ||
-  BigInt(amount) > BigInt(bounds.max_amount)
-) {
-  throw new Error("Choose an amount within the deposit limits")
-}
-const session = await billing.createCheckoutSession({
-  priceId: depositPrice.id,
-  amount, // USD 100 becomes "100000000"; no floating-point conversion
-})
+const valid = amount && bounds && BigInt(amount) >= BigInt(bounds.min_amount) && BigInt(amount) <= BigInt(bounds.max_amount)
+
+<BuyButton product="api-credits" price="deposit" amount={valid ? amount : undefined} label="Add credits" {...handlers} />
 ```
 
 OpenRails validates the bounds and whole currency minor units before accepting
 payment. Fixed prices reject `amount`; their pack benefit can be greater than
 the purchase price for a bulk discount. Customer-selected deposits currently
-use NMI or Stripe. Changing the selected amount requires minting a new session.
+use NMI or Stripe.
 
 A rail's own step is the pay result's `next_action`: `redirect_to_url` (an
 https page, opened in the top window) or `solana_pay` (a `solana:` link shown
 as a QR code). A card challenge is its `operation`, authenticated in the page.
-Stripe Elements needs the buyer's billing client (`<Checkout>` inside a
-`BillingProvider`): the shared payment page offers token rails only.
+
+### A shared payment page
+
+Several sites selling for one merchant can share one payment page
+(`Config.Checkout.PageURL`). A server mints the session with the Go
+`Client.CreateCheckoutSession` and hands the browser its `url`, which the site
+frames:
+
+```tsx
+<CheckoutFrame url={session.url} theme="dark" onComplete={() => refetchAccess()} />
+```
+
+Stripe Elements needs the buyer's own client, so the shared page offers token
+rails only.
 
 The payment host serves `<CheckoutPage>` from one HTML entry at `PageURL`,
 behind its adapter's `CheckoutFramePolicy` (only the sites in
-`Config.Checkout.EmbedOrigins` may frame it):
+`Config.Checkout.EmbedOrigins` may frame it). No customer signs in there, so
+its `BillingProvider` has no client:
 
 ```tsx
-import { BillingUiProvider, CheckoutPage } from "@openrails/billing-ui"
+import { BillingProvider, CheckoutPage } from "@openrails/billing-ui"
 
 createRoot(root).render(
-  <BillingUiProvider>
+  <BillingProvider>
     <CheckoutPage appearance={{ variables: brand }} />
-  </BillingUiProvider>
+  </BillingProvider>
 )
 ```
 
@@ -111,25 +139,30 @@ cannot navigate the top window, so the app does); app to page
 
 ## Account billing
 
+One `BillingProvider`, usually at the app's root, gives every component the
+client, the appearance and the words. `@openrails/billing-ui/react` exports the
+same provider for an app that uses only the hooks; it loads no stylesheet.
+
 ```tsx
-import { createBillingClient } from "@openrails/billing-ui/client"
-import { BillingProvider } from "@openrails/billing-ui/react"
-import { AccountBilling, BillingUiProvider } from "@openrails/billing-ui"
+import { AccountBilling, BillingProvider, createBillingClient } 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"
-      collectionCurrency="USD" // offers "Use for invoices"
-      sendSolanaTransaction={(tx) => wallet.signAndSend(tx)} // signs a Solana cancel
-    />
-  </BillingProvider>
-</BillingUiProvider>
+<BillingProvider
+  client={billing}
+  appearance={{ theme: "auto" }}
+  messages={de}
+  locale="de"
+  navigate={navigate}
+  onChange={() => queryClient.invalidateQueries({ queryKey: ["billing"] })}
+>
+  <AccountBilling
+    plansHref="/plans"
+    defaultCurrency="USD" // offers "Make default"
+    sendSolanaTransaction={(tx) => wallet.signAndSend(tx)} // signs a Solana cancel
+  />
+</BillingProvider>
 ```
 
 The panels read OpenRails' public configuration (`GET /config`) themselves,
@@ -142,36 +175,38 @@ for host components.
 ## 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 and Solana reads
-are public routes, served only when the host mounts OpenRails' checkout
-routes; `GET /config` is always served.
+The catalog and Solana reads are public routes, served only when the host
+mounts OpenRails' checkout routes; `GET /config` is always served.
 
 | Call                                                                                                | Route                                                           |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `listProducts()` (each product embeds its prices on sale)                                           | `GET /catalog/products`                                         |
+| `listProducts({ keys })`: the products on sale named by `keys` (1 to 100 product keys), each with its prices, in one page; `useProducts` reads the same | `GET /catalog/products` |
 | `getConfig()` (capabilities, `currencies`, `payment` with PSPs, `solana.network` and tokens; `client.currencies` is the pinned registry) | `GET /config` |
-| `previewTierChange(id, priceId)`                                                                    | `POST /me/subscriptions/{id}/change-tier/preview`               |
-| `changeTier(id, { priceId, idempotencyKey, signature? })`                                         | `POST /me/subscriptions/{id}/change-tier`                       |
+| `previewSubscriptionChange(id, { priceId?, quantity? })`                                            | `POST /me/subscriptions/{id}/change/preview`                    |
+| `changeSubscription(id, { priceId?, quantity?, idempotencyKey, signature? })`                       | `POST /me/subscriptions/{id}/change`                            |
 | `listSolanaTokens({ priceId, wallet })`                                                             | `GET /solana/tokens`                                            |
 
 ```ts
-const preview = await billing.previewTierChange(sub.id, price.id) // amount_due_now, effective
-const change = await billing.changeTier(sub.id, {
-  priceId: price.id,
+const preview = await billing.previewSubscriptionChange(sub.id, { quantity: 5 }) // amount_due_now, effective
+const change = await billing.changeSubscription(sub.id, {
+  quantity: 5,
   idempotencyKey,
 })
 ```
 
-- `changeTier` is a money write. Mint one `idempotencyKey` per attempt and
+- A change moves to another price of the tier group (`priceId`), to other
+  seats of a per-seat price (`quantity`), or both. More seats and an upgrade
+  charge now; fewer seats and a downgrade apply at the next renewal.
+- `changeSubscription` 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
+  `subscription_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.
 - A rail that needs the customer's own step answers `requires_action` with a
   `next_action`. Solana's is `solana_sign_transactions`:
   `signWalletAction(change.next_action, send)` signs and sends its
-  transactions and returns the signature; repeat `changeTier` with the same
+  transactions and returns the signature; repeat `changeSubscription` with the same
   key and `signature`. `cancelSubscription(id, { reason, signature? })` works
   the same way: its answer is the subscription, unchanged and carrying
   `next_action` until the signed cancel lands. The hooks run this when given
@@ -191,8 +226,9 @@ provider:
   Card rails (`collect_js`, `card`, `stripe_elements`) render one panel: saved cards,
   an inline new card and one Pay/Subscribe button, which is the customer'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
+- Inside a `BillingProvider` with a client, a new card is always saved to the
+  account first and the session is paid with `payment_method_id` on the
+  customer surface; `requires_action` results
   carrying an `operation` 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.
@@ -204,10 +240,8 @@ provider:
   `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.
+- `defaultCountry` (CheckoutPage, SavePaymentMethod, AccountBilling)
+  preselects the billing country, else the browser locale's region.
 
 - Panels: `SubscriptionsPanel` (cancel, resume, change card),
   `PaymentMethodsPanel`, `PaymentHistory`, `BillingStatusBadge`,
@@ -215,11 +249,11 @@ provider:
 - `renderSubscriptionFooter={(s) => ...}` adds host content under a
   subscription row; `useBillingRefresh()` refetches after host-side changes.
 - Hooks: `useSubscriptions` (`cancel`, `resume`, `setPaymentMethod`,
-  `changeTier`, per-row `pending`, `nextCursor`), `usePaymentMethods` (`add`,
-  `remove`, `setCollection`), `usePayments` (cursor pages), `useProducts` (the
-  catalog).
+  `changeSubscription`, per-row `pending`, `nextCursor`), `usePaymentMethods` (`add`,
+  `remove`, `setDefault`), `usePayments` (cursor pages), `useProducts` (a
+  catalog lookup by product key).
   Actions resolve to `null` or a `BillingError`; they never throw.
-  `changeTier` resolves to the `TierChange` instead of `null`. Cancel, resume
+  `changeSubscription` resolves to the `SubscriptionChange` instead of `null`. Cancel, resume
   and the card change answer the subscription, which replaces the row.
 - Money is exact: `/me` amounts are int64 native-unit strings, scaled by the
   OpenRails currency registry (`currencies` option to extend it).

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

@@ -1,11 +1,12 @@
 import { CheckoutAppearance } from '../appearance';
 import { SendSolanaTransaction } from '../client/client';
-import { PaymentMethodsPanelProps } from './payment-methods-panel';
 import { SubscriptionsPanelProps } from './subscriptions-panel';
 export interface AccountBillingProps {
-    cardSetupReturnURL?: PaymentMethodsPanelProps["cardSetupReturnURL"];
-    /** Offers to make a card the one that collects this currency's invoices. */
-    collectionCurrency?: string;
+    /**
+     * Offers to make a card the default for this currency: it pays the
+     * currency's invoices and every subscription in it without its own card.
+     */
+    defaultCurrency?: string;
     /** Billing country to preselect when adding a card. */
     defaultCountry?: string;
     sendSolanaTransaction?: SendSolanaTransaction;
@@ -16,4 +17,4 @@ export interface AccountBillingProps {
     className?: string;
 }
 /** Subscriptions, payment methods and history in one column. */
-export declare function AccountBilling({ cardSetupReturnURL, collectionCurrency, defaultCountry, sendSolanaTransaction, plansHref, renderSubscriptionFooter, historyPageSize, appearance, className, }: AccountBillingProps): import("react").JSX.Element;
+export declare function AccountBilling({ defaultCurrency, defaultCountry, sendSolanaTransaction, plansHref, renderSubscriptionFooter, historyPageSize, appearance, className, }: AccountBillingProps): import("react").JSX.Element;

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

@@ -7,8 +7,11 @@ export interface ChangeCardDialogProps {
     name: string;
     onOpenChange: (open: boolean) => void;
     pending: boolean;
-    /** Resolves null on success; the dialog then closes. */
-    onConfirm: (paymentMethodId: string) => Promise<BillingError | null>;
+    /**
+     * The subscription's own card, or null to follow the default card. Resolves
+     * null on success; the dialog then closes.
+     */
+    onConfirm: (paymentMethodId: string | null) => Promise<BillingError | null>;
     appearance?: CheckoutAppearance;
 }
 export declare function ChangeCardDialog({ subscription, name, onOpenChange, pending, onConfirm, appearance, }: ChangeCardDialogProps): React.JSX.Element;

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

@@ -1,10 +1,11 @@
 import { CheckoutAppearance } from '../appearance';
 import * as React from "react";
 export interface PaymentMethodsPanelProps {
-    /** Return target after off-page card verification; see `SavePaymentMethod`. */
-    cardSetupReturnURL?: (setupId: string) => string;
-    /** Offers to make a card the one that collects this currency's invoices. */
-    collectionCurrency?: string;
+    /**
+     * Offers to make a card the default for this currency: it pays the
+     * currency's invoices and every subscription in it without its own card.
+     */
+    defaultCurrency?: string;
     /** Billing country to preselect when adding a card. */
     defaultCountry?: string;
     appearance?: CheckoutAppearance;
@@ -14,4 +15,4 @@ export interface PaymentMethodsPanelProps {
  * The customer's saved cards. "Add card" offers each PSP of the merchant's
  * payment setup (`GET /config`) that saves a card in the page.
  */
-export declare function PaymentMethodsPanel({ cardSetupReturnURL, collectionCurrency, defaultCountry, appearance, className, }: PaymentMethodsPanelProps): React.JSX.Element;
+export declare function PaymentMethodsPanel({ defaultCurrency, defaultCountry, appearance, className, }: PaymentMethodsPanelProps): React.JSX.Element;

package/dist/buy-button.d.ts

@@ -0,0 +1,35 @@
+import { CheckoutAppearance } from './appearance';
+import { PayResult } from './types';
+import * as React from "react";
+export interface BuyButtonProps {
+    /** The product's catalog key. */
+    product: string;
+    /** The price's key within the product. */
+    price: string;
+    /** The button's text; by default the price's amount and terms, from the catalog. */
+    label?: string;
+    /**
+     * A customer-chosen deposit, in the price currency's native units, for a
+     * price with `customer_amount`; the checkout charges exactly this.
+     */
+    amount?: string;
+    /** false buys a recurring price's first term only; default: renews. */
+    autoRenew?: boolean;
+    /** Where a redirect rail (Stripe's hosted page) returns the buyer: one of the app's return origins. */
+    successUrl?: string;
+    /**
+     * The purchase succeeded. A hint: the host's own gate decides access, so
+     * send the buyer to the content it guards.
+     */
+    onPaid: (result: PayResult) => void;
+    /**
+     * Buying needs a signed-in customer: called instead of the checkout when
+     * `signedIn` is false or OpenRails answers 401.
+     */
+    onSignInRequired: () => void;
+    /** false when the host knows the visitor is signed out. */
+    signedIn?: boolean;
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+export declare function BuyButton(props: BuyButtonProps): React.JSX.Element;

package/dist/cart.d.ts

@@ -0,0 +1,18 @@
+import { CheckoutAppearance } from './appearance';
+import { BillingClient } from './client/client';
+import { Order } from './client/types';
+import * as React from "react";
+export interface CartProps {
+    /** The client to read and buy through; default: the provider's. */
+    client?: BillingClient;
+    /**
+     * The order made from the cart. Default: pay it here with OrderCheckout.
+     */
+    onOrder?: (order: Order) => void;
+    /** Passed to OrderCheckout: the order is complete, or processing. */
+    onSettled?: (order: Order) => void;
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+/** The customer's cart. Requires `BillingProvider`. */
+export declare function Cart({ client: given, onOrder, onSettled, appearance, className, }: CartProps): React.JSX.Element;

package/dist/checkout.d.ts

@@ -9,8 +9,6 @@ export interface CheckoutProps {
     layout?: CheckoutLayout;
     /** Billing country to preselect; default: the browser locale's region. */
     defaultCountry?: string;
-    /** Return target after an off-page card verification (Stripe setup). */
-    cardSetupReturnURL?: (setupId: string) => string;
     onComplete?: (result: PayResult) => void;
     /**
      * Leaves for a redirect rail's page. Default: navigate the top window,
@@ -21,4 +19,4 @@ export interface CheckoutProps {
     completionMode?: "embedded" | "redirect";
     className?: string;
 }
-export declare function Checkout({ source, appearance, layout, defaultCountry, cardSetupReturnURL, onComplete, onRedirect, onPhaseChange, completionMode, className, }: CheckoutProps): React.JSX.Element;
+export declare function Checkout({ source, appearance, layout, defaultCountry, onComplete, onRedirect, onPhaseChange, completionMode, className, }: CheckoutProps): React.JSX.Element;

package/dist/client/checkout.d.ts

@@ -0,0 +1,28 @@
+import { CheckoutSource } from '../source';
+import { CheckoutSessionLink } from './types';
+export interface CheckoutSourceOptions {
+    /**
+     * A customer surface's base: its `/me` prefix, such as `/billing/v1/me` or
+     * a host's own `/api/v1/merchants/acme/billing/me`. The session is read and
+     * paid there with this client's credential, which proves the session's
+     * customer, so its saved cards pay. Default: the session id alone, at
+     * `{baseUrl}/checkout-sessions`.
+     */
+    customerBase?: string;
+}
+export interface CheckoutCalls {
+    createCheckoutSession(input: {
+        priceKey?: string;
+        productKey?: string;
+        priceId?: string;
+        /** Customer-selected deposit in the price currency's native units. */
+        amount?: string;
+        /** Defaults to true for recurring prices; false buys the initial term only. */
+        autoRenew?: boolean;
+        successUrl?: string;
+    }): Promise<CheckoutSessionLink>;
+    checkoutSource(sessionId: string, opts?: CheckoutSourceOptions): CheckoutSource;
+}
+export declare function registerCheckout(client: object, checkout: CheckoutCalls): void;
+/** The checkout calls of a client from createBillingClient. */
+export declare function checkoutOf(client: object): CheckoutCalls;