@openrails/billing-ui 0.236.0 → 0.238.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## Public reads name their merchant; token source
+
+- Breaking: `listProducts({ merchant, keys })`, `useProducts({ merchant, keys
+  })` and `<BuyButton merchant>` take the merchant's id, and `<Offers>` takes
+  it with `keys`: `GET /catalog/products?merchant=<id>&keys=…`. The read sends
+  no bearer, signed in or out.
+- Breaking: `getConfig()` and `useConfig()` are the deployment's part alone
+  (`capabilities`, `currencies`, `captcha`, `network`); `PublicConfig` loses
+  `payment` and `merchant`. `getCustomerConfig()` and `useCustomerConfig()`
+  read the customer's merchant (`GET /me/config`, `CustomerConfig`: `payment`
+  and `merchant`); `<OrderCheckout>`, `<AccountBilling>` and
+  `<PaymentMethodsPanel>` take their PSPs from it.
+- Breaking: `createConfigStore(read)` takes the read it shares, and
+  `ConfigStore` and `ConfigState` name what they hold (`ConfigStore<T>`).
+- `tokenSource({ fetchToken, skew = 60 })` is a `getToken` that keeps the
+  customer's access token in memory (never in browser storage), replaces it
+  `skew` seconds before it expires with one request in flight, and has
+  `invalidate()`. With one, the client sends a call answered 401
+  `credential_expired` once more with a new token.
+- `redeemAssertion({ tokenEndpoint, assertion, fetch })` redeems the
+  assertion a merchant's backend signed for its customer (RFC 7523,
+  `scope=openrails:self`) with the fetch it is given, so a DPoP fetch binds
+  the token to the browser's key.
+
+## Payment operations removed
+
+- Breaking: `getPaymentAuthentication`, `confirmPaymentAuthentication`,
+  `authenticatePayment`, `PaymentOperation` and `PaymentAuthentication` are
+  removed, with `operation_id` on `SubscriptionChange` and `operation` on
+  `PaymentRecovery`. A change the issuer challenges answers an `authenticate`
+  `next_action`; `authenticateChange(client, id, change, psp)` completes it
+  and confirms the change (`confirmSubscriptionChange`).
+- `NextAction` is one shape for orders, changes and subscriptions (`type`,
+  `url`, `psp_id`, `transactions`, `payload`); `OrderNextAction` is gone.
+
+## Running charges
+
+- `Balance` gains `accrued_amount`, `accrual_rate_per_hour`, `as_of` and
+  `depletes_at`: what the customer's running charges have charged and not yet
+  posted, the rate they draw the balance at, and when it runs out.
+  `available_amount` is net of the accrual.
+
+## Orders replace checkout sessions
+
+- Breaking: `<BuyButton>` and `<Offers>` create the customer's order and pay
+  it in `<OrderCheckout>`; `onPaid` receives the completed `Order`.
+  `returnUrl` replaces `successUrl`, and `autoRenew` is gone.
+- Breaking: `<CheckoutPage>`, `<CheckoutFrame>` and the shared payment page
+  are removed with checkout sessions; so are `CheckoutLayout`,
+  `CheckoutFrameTheme`, `CheckoutSession`, `CheckoutSessionStatus`,
+  `CheckoutPlan`, `CheckoutLineItem`, `CheckoutPhase`, `PaymentOption`,
+  `PayRequest`, `PayResult`, their schemas, `amountSchema`,
+  `unitDecimalsSchema`, `isCardRail`, `savedMethodsFor` and the client's
+  `CheckoutSessionLink`. `NextAction` and `PaymentFailure` are the order's,
+  from `@openrails/billing-ui/client`.
+- A page that paid a server-minted session pays the server's order instead:
+  the Go `Client.CreateOrder` creates it, and `<OrderCheckout orderId>` pays
+  it, a subscription line included.
+- `SavedPaymentMethod` names its `psp_id` (was `option_id`).
+
+## Usage orders
+
+- Breaking: `listInvoices`, `getInvoice` and `Invoice` are removed. Usage
+  billed in arrears is an order (`origin: usage`): `listOrders({ origin:
+  "usage" })` lists them, and `<OrderCheckout>` pays one with a saved card.
+- `Order` gains `usage` (its period, `due_at`, `amount_paid`, `amount_due`,
+  collection and `delinquent`) and `uncollectible_at`; `status` may be
+  `uncollectible`. A usage line names its `source`; its `price_id` and
+  `product_id` are null.
+- `Order.checkout.expires_at` is read again.
+
+## Embedded checkout
+
+- `<EmbeddedCheckout url onComplete?>` frames a merchant order's embedded
+  checkout (`checkout.ui_mode: embedded`): it follows the page's height and
+  hears its completion only from its own frame on the checkout host's origin;
+  without `onComplete` it goes to the checkout's `success_url`.
+- `Order.checkout.ui_mode`; `PublicMerchant.embed_origins`;
+  `PublicConfig.network` (the checkout page's sign-in to the customer network).
+- `createNetworkLinkChallenge()` and `createNetworkLink({challengeId, idToken})`
+  link the customer to a customer-network account.
+
+## No Solana token list
+
+- `listSolanaTokens` and `SolanaToken` are gone with `GET /v1/solana/tokens`:
+  the accepted tokens are `getConfig()`'s `payment.solana.tokens`.
+
 ## Apple Pay and Google Pay
 
 - `<OrderCheckout wallets>` offers Apple Pay and Google Pay through a Stripe
@@ -183,15 +270,6 @@
   product on sale with its current prices. Filter by currency, product or
   renewal in the browser.
 
-## Paying on a customer surface
-
-- `client.checkoutSource(id, { customerBase })` reads and pays a checkout
-  session as its signed-in customer at a customer surface's
-  `/checkout-sessions/{id}` (for example a host's
-  `/api/v1/merchants/acme/billing/me`), so its saved cards pay. Without
-  `customerBase` the session id alone pays at `/checkout-sessions/{id}` as
-  before. `<CheckoutPage customerBase>` passes it through.
-
 ## 1.0.0
 
 Ships with OpenRails v1.0.0; use the two at the same version. Everything a host

package/README.md

@@ -10,15 +10,13 @@ billing (subscriptions, saved cards, payment history).
 | `@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, 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`).
+The checkout owns the browser payment flow, behind `<BuyButton>`, `<Offers>`
+and `<OrderCheckout>`: the signed-in customer's order, read and paid with
+their own credential. Card data is tokenized in the PSP's own fields
+(Collect.js, Stripe Elements) and never enters the host application.
 
-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.
+See [Payment form contract](docs/payment-form-contract.md) for exact money,
+billing fields, browser-autofill behavior and the payment request.
 
 The package lives in the OpenRails repository and shares its version: each
 OpenRails release `vX.Y.Z` publishes `@openrails/billing-ui@X.Y.Z` to npm, with
@@ -44,20 +42,43 @@ const billing = createBillingClient({ baseUrl: "/billing/v1", fetch: auth.authFe
 </BillingProvider>
 ```
 
+Where your backend mints the customer's token, `tokenSource` keeps it: in
+memory only, replaced `skew` seconds (60) before it expires with one request
+however many calls wait, and once more when a call answers 401
+`credential_expired`.
+
+```ts
+import { createBillingClient, redeemAssertion, tokenSource } from "@openrails/billing-ui"
+
+const billing = createBillingClient({
+  baseUrl: "https://billing.example/v1",
+  getToken: tokenSource({
+    // { access_token, expires_in } from your backend, or its signed assertion redeemed here.
+    fetchToken: async () => {
+      const { assertion } = await (await fetch("/api/billing/assertion", { method: "POST" })).json()
+      return redeemAssertion({ tokenEndpoint: "https://billing.example/oauth2/token", assertion })
+    },
+  }),
+})
+```
+
 `<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.
+"$10.00 every 30 days"). Both look prices up in the public catalog of the
+merchant whose id you pass as `merchant`, signed in or out. The purchase is
+theirs from start to payment: a
+button creates the customer's order and pays it in a dialog
+(`<OrderCheckout>`); a second click before it is paid opens the same order.
+Signing in is the host's: with `signedIn={false}`, or when OpenRails answers
+401, they call `onSignInRequired` instead. `onPaid` receives the completed
+order; it is a hint, so confirm access from your own API (your gate) before
+granting anything.
 
 ```tsx
 <BuyButton
+  merchant={merchantId} // your merchant's id, from your server
   product="course-101"
   price="rent" // labelled from the catalog unless you pass label
   signedIn={signedIn}
@@ -66,6 +87,7 @@ own API (your gate) before granting anything.
 />
 
 <Offers
+  merchant={merchantId}
   keys={["course-101", "course-bundle", "channel-membership"]} // from your server, or products={...} from its Client.ListOffers
   signedIn={signedIn}
   onSignInRequired={() => openSignIn()}
@@ -73,9 +95,8 @@ own API (your gate) before granting anything.
 />
 ```
 
-`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.
+`returnUrl` returns the buyer from a redirect step (Stripe's hosted page); it
+must be on one of your app's return origins.
 
 For prepaid credits, a fixed pack is another product/price. A
 `customer_amount` price takes the buyer's `amount`: collect it on your product
@@ -90,7 +111,7 @@ const amount = decimalToAmount(enteredAmount, currency.decimals)
 const bounds = depositPrice.customer_amount
 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} />
+<BuyButton merchant={merchantId} product="api-credits" price="deposit" amount={valid ? amount : undefined} label="Add credits" {...handlers} />
 ```
 
 OpenRails validates the bounds and whole currency minor units before accepting
@@ -98,44 +119,22 @@ 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.
 
-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.
+A rail's own step is the order's `payment.next_action`: `redirect_to_url` (an
+https page, opened in the top window), `solana_pay` (a `solana:` link shown
+as a QR code) or `authenticate` (the bank's challenge, run in the page).
 
-### A shared payment page
+### An order your server creates
 
-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:
+A server that decides what its customer buys creates the order with the Go
+`Client.CreateOrder` (`POST /v1/app/orders`) and hands its id to the
+customer's browser, which pays it signed in:
 
 ```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). No customer signs in there, so
-its `BillingProvider` has no client:
-
-```tsx
-import { BillingProvider, CheckoutPage } from "@openrails/billing-ui"
-
-createRoot(root).render(
-  <BillingProvider>
-    <CheckoutPage appearance={{ variables: brand }} />
-  </BillingProvider>
-)
+<OrderCheckout orderId={orderId} returnUrl={returnUrl} onSettled={(order) => refetchAccess(order)} />
 ```
 
-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.
+`onSettled` follows a complete order, or one processing on an asynchronous
+rail. A subscription line names its subscription once paid.
 
 ## Account billing
 
@@ -165,26 +164,27 @@ const billing = createBillingClient({ baseUrl: "/billing/v1", fetch: auth.authFe
 </BillingProvider>
 ```
 
-The panels read OpenRails' public configuration (`GET /config`) themselves,
-once per `BillingProvider`: "Add card" offers each PSP of its `payment` that
-saves a card in the page, and says so while the configuration fails or its
-card PSPs are temporarily unavailable; amounts use its currency registry over
-the pinned copy. `useConfig()` and `useCurrencyScales()` read the same copy
-for host components.
+The panels read OpenRails' configuration themselves, once per
+`BillingProvider`: the customer's merchant's (`GET /me/config`), where "Add
+card" offers each PSP of its `payment` that saves a card in the page, and says
+so while the read fails or its card PSPs are temporarily unavailable; and the
+deployment's (`GET /config`), whose currency registry amounts use over the
+pinned copy. `useCustomerConfig()`, `useConfig()` and `useCurrencyScales()`
+read the same copies for host components.
 
 ## Catalog and plan changes
 
 The client also reads the public catalog and changes a subscription's plan.
-The catalog and Solana reads are public routes, served only when the host
-mounts OpenRails' checkout routes; `GET /config` is always served.
+The catalog read and `GET /config` are public routes: the client sends them
+no bearer.
 
 | Call                                                                                                | Route                                                           |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `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` |
+| `listProducts({ merchant, keys })`: the products `merchant` (its id) has 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`, `captcha`; `client.currencies` is the pinned registry) | `GET /config` |
+| `getCustomerConfig()` (the customer's merchant: `payment` with PSPs, `solana.network` and tokens, and `merchant`, its name) | `GET /me/config` |
 | `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.previewSubscriptionChange(sub.id, { quantity: 5 }) // amount_due_now, effective
@@ -199,10 +199,11 @@ const change = await billing.changeSubscription(sub.id, {
   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
-  `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.
+  `subscription_change_in_flight` refusal, a 5xx or a lost response), so
+  OpenRails replays the stored result instead of charging twice. A change the
+  card issuer challenges answers `requires_action` with an `authenticate`
+  `next_action`: `authenticateChange(client, id, change, psp)` runs it in the
+  page and confirms the change (`confirmSubscriptionChange`).
 - 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
@@ -214,33 +215,27 @@ const change = await billing.changeSubscription(sub.id, {
 
 ## Provider-neutral flows
 
-OpenRails's browser PSP configs (`GET /config`'s `payment.psps`) pick the
+OpenRails's browser PSP configs (`GET /me/config`'s `payment.psps`) pick the
 browser flow from each PSP's `flow` and public `config`
 (Collect.js, native card inputs, Stripe Elements, redirect, wallet). Hosts never branch on a
 provider:
 
-- A session's `options` are exactly the armed PSPs whose rail can make this
-  sale (Solana when it is configured, never CCBill),
-  each with its `driver` and `public_config`; `saved_methods` are the buyer's
-  cards on them, newest first (paying sends the chosen card's id explicitly).
-  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` 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.
+- An order's `payment_options` are exactly the armed PSPs whose rail can make
+  this sale (Solana for one-time lines when it is configured, never CCBill),
+  each with what it `accepts`. `OrderCheckout` renders one panel: the
+  customer's saved cards on them, newest first, an inline new card and one Pay
+  button. No provider chooser with one rail.
+- A new card is charged and saved in one pay; an `authenticate` next action
+  runs 3-D Secure in the page, then `confirm`. A decline stays on the panel
+  with its message, so the buyer can pick another card under 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` (CheckoutPage, SavePaymentMethod, AccountBilling)
+- `defaultCountry` (SavePaymentMethod, AccountBilling)
   preselects the billing country, else the browser locale's region.
 
 - Panels: `SubscriptionsPanel` (cancel, resume, change card),

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

@@ -4,7 +4,7 @@ import { SubscriptionsPanelProps } from './subscriptions-panel';
 export interface AccountBillingProps {
     /**
      * 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.
+     * currency's usage orders and every subscription in it without its own card.
      */
     defaultCurrency?: string;
     /** Billing country to preselect when adding a card. */

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

@@ -3,7 +3,7 @@ import * as React from "react";
 export interface PaymentMethodsPanelProps {
     /**
      * 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.
+     * currency's usage orders and every subscription in it without its own card.
      */
     defaultCurrency?: string;
     /** Billing country to preselect when adding a card. */
@@ -13,6 +13,6 @@ 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.
+ * payment setup (`GET /me/config`) that saves a card in the page.
  */
 export declare function PaymentMethodsPanel({ defaultCurrency, defaultCountry, appearance, className, }: PaymentMethodsPanelProps): React.JSX.Element;

package/dist/authenticate.d.ts

@@ -1,8 +1,9 @@
 import { BillingClient } from './client/client';
+import { SubscriptionChange } from './client/types';
 import { PspConfig } from './psp';
 /**
- * Completes the provider challenge (3-D Secure) a pending payment operation
- * waits on. "not_required" when the provider has none outstanding; the
- * operation's own status remains the result.
+ * Completes the issuer's authentication (3-D Secure) a subscription change
+ * waits on, then confirms the change and answers it. A change with no
+ * `authenticate` next action is answered as it is.
  */
-export declare function authenticatePayment(client: BillingClient, operationId: string, psp: PspConfig): Promise<"authenticated" | "not_required">;
+export declare function authenticateChange(client: BillingClient, subscriptionId: string, change: SubscriptionChange, psp: PspConfig): Promise<SubscriptionChange>;

package/dist/buy-button.d.ts

@@ -1,7 +1,9 @@
 import { CheckoutAppearance } from './appearance';
-import { PayResult } from './types';
+import { Order } from './client/types';
 import * as React from "react";
 export interface BuyButtonProps {
+    /** The id of the merchant that sells the product. */
+    merchant: string;
     /** The product's catalog key. */
     product: string;
     /** The price's key within the product. */
@@ -10,18 +12,16 @@ export interface BuyButtonProps {
     label?: string;
     /**
      * A customer-chosen deposit, in the price currency's native units, for a
-     * price with `customer_amount`; the checkout charges exactly this.
+     * price with `customer_amount`; the order 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;
+    /** Where a redirect PSP (Stripe's hosted page) returns the buyer: one of the app's return origins. */
+    returnUrl?: string;
     /**
-     * The purchase succeeded. A hint: the host's own gate decides access, so
-     * send the buyer to the content it guards.
+     * The order is paid. A hint: the host's own gate decides access, so send
+     * the buyer to the content it guards.
      */
-    onPaid: (result: PayResult) => void;
+    onPaid: (order: Order) => void;
     /**
      * Buying needs a signed-in customer: called instead of the checkout when
      * `signedIn` is false or OpenRails answers 401.
@@ -32,4 +32,11 @@ export interface BuyButtonProps {
     appearance?: CheckoutAppearance;
     className?: string;
 }
-export declare function BuyButton(props: BuyButtonProps): React.JSX.Element;
+export declare function BuyButton({ merchant, product, price: priceKey, ...props }: BuyButtonProps): React.JSX.Element;
+export type PurchaseProps = Omit<BuyButtonProps, "merchant" | "product" | "price"> & {
+    /** The price to buy; the button waits while it is unknown. */
+    priceId?: string;
+    label: string;
+};
+/** One price's button and its order. Requires `BillingProvider`. */
+export declare function Purchase({ priceId, label, amount, returnUrl, onPaid, onSignInRequired, signedIn, appearance, className, }: PurchaseProps): React.JSX.Element;

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
 import { BillingError } from './errors';
-import { Account, PublicConfig, PaymentAuthentication, CurrencyScales, Invoice, ListPage, NewCard, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, SolanaToken, Subscription, SubscriptionChange, SubscriptionChangePreview } from './types';
+import { Account, CustomerConfig, CustomerLink, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, Subscription, SubscriptionChange, SubscriptionChangePreview } from './types';
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -8,7 +8,12 @@ export interface BillingClientOptions {
      * or combine the default with `getToken`.
      */
     fetch?: (input: string, init: RequestInit) => Promise<Response>;
-    /** Bearer for each request; omit when `fetch` authenticates. */
+    /**
+     * The customer's access token, sent as the bearer of every request but
+     * the two public reads (`getConfig`, `listProducts`); omit when `fetch`
+     * authenticates. A `tokenSource` keeps it fresh: a call answered 401
+     * `credential_expired` is then retried once with a new token.
+     */
     getToken?: () => string | null | undefined | Promise<string | null | undefined>;
     /** Sent as Accept-Language. */
     language?: () => string | null | undefined;
@@ -19,10 +24,11 @@ export interface BillingClientOptions {
     currencies?: CurrencyScales;
 }
 /**
- * A public catalog lookup: the products named by `keys` (at most 100 product
- * keys), in one page.
+ * A public catalog lookup: the products of `merchant` (its id) named by
+ * `keys` (at most 100 product keys), in one page.
  */
 export interface ProductListOptions {
+    merchant: string;
     keys: string[];
     signal?: AbortSignal;
 }
@@ -99,6 +105,12 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     setSubscriptionPaymentMethod(subscriptionId: string, paymentMethodId: string | null): Promise<Subscription>;
     /** What `changeSubscription` would charge now and at the next renewal. */
     previewSubscriptionChange(subscriptionId: string, change: SubscriptionChangeInput, signal?: AbortSignal): Promise<SubscriptionChangePreview>;
+    /**
+     * Reads the provider for a change awaiting the customer, after they
+     * completed its `next_action` (the issuer's authentication), and answers
+     * the change as it now stands.
+     */
+    confirmSubscriptionChange(subscriptionId: string): Promise<SubscriptionChange>;
     /**
      * Moves the subscription to another price of its tier group, to other
      * seats of a per-seat price, or both. An upgrade and more seats charge
@@ -106,7 +118,8 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      * Reuse `idempotencyKey` until the change resolves (`processing`, a
      * `subscription_change_in_flight` refusal or a lost response) so the
      * stored result replays instead of charging twice. A Solana wallet next
-     * action is completed with `signWalletAction`, then repeated with `signature`.
+     * action is completed with `signWalletAction`, then repeated with
+     * `signature`; an `authenticate` one with `authenticateChange`.
      */
     changeSubscription(subscriptionId: string, input: SubscriptionChangeInput & {
         idempotencyKey: string;
@@ -149,6 +162,16 @@ export declare function createBillingClient(options?: BillingClientOptions): {
         reusable?: boolean;
         idempotencyKey: string;
     }): Promise<OrderResult>;
+    /**
+     * The customer's orders, newest first: `origin: "usage"` their usage
+     * orders, `overdue` those still owed past their due date.
+     */
+    listOrders(opts?: CursorOptions & {
+        origin?: string;
+        status?: string;
+        subscriptionId?: string;
+        overdue?: boolean;
+    }): Promise<ListPage<Order>>;
     /** One of the customer's orders: the resumable handle of a purchase. */
     getOrder(orderId: string, signal?: AbortSignal): Promise<Order>;
     /**
@@ -170,14 +193,11 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      * script answered its `next_action`.
      */
     confirmPaymentMethod(paymentMethodId: string): Promise<PaymentMethod>;
-    /** The provider challenge a pending payment operation is waiting on. */
-    getPaymentAuthentication(operationId: string): Promise<PaymentAuthentication>;
-    confirmPaymentAuthentication(operationId: string): Promise<void>;
     /** `pending` when the provider is still converging (202). */
     removePaymentMethod(paymentMethodId: string): Promise<"removed" | "pending">;
     /**
      * Makes the card the default for one currency: it pays the currency's
-     * invoices and every subscription in it without its own card.
+     * usage orders and every subscription in it without its own card.
      */
     setDefaultPaymentMethod(input: {
         currency: string;
@@ -187,33 +207,42 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     listPayments(opts?: CursorOptions & {
         rail?: string;
     }): Promise<ListPage<Payment>>;
-    listInvoices(opts?: CursorOptions): Promise<ListPage<Invoice>>;
     /**
      * The customer's summary: balance and amount owed per currency, the card
      * that pays each currency, and unread notices.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
-    getInvoice(invoiceId: string, signal?: AbortSignal): Promise<Invoice>;
     /**
-     * The products on sale named by `keys`, each with its current prices.
-     * No keys name no products: nothing is fetched.
+     * The products `merchant` has on sale named by `keys`, each with its
+     * current prices: a public read, the same signed in or out. No keys
+     * name no products: nothing is fetched.
      */
     listProducts(opts: ProductListOptions): Promise<Page<Product>>;
     /**
-     * The deployment's public configuration: what the mount serves, the
-     * currency registry and the merchant's payment setup. React components
-     * share one copy through `useConfig()`.
+     * A challenge to link the customer to an openrails.dev account: its
+     * `nonce` goes in the network sign-in's authorization request.
+     */
+    createNetworkLinkChallenge(): Promise<NetworkLinkChallenge>;
+    /**
+     * Links the customer to the openrails.dev account whose fresh sign-in
+     * answered the challenge (its ID token).
+     */
+    createNetworkLink(params: {
+        challengeId: string;
+        idToken: string;
+    }): Promise<CustomerLink>;
+    /**
+     * The deployment's configuration, a public read: what the mount serves,
+     * the currency registry and the captcha. React components share one
+     * copy through `useConfig()`.
      */
     getConfig(signal?: AbortSignal): Promise<PublicConfig>;
     /**
-     * Accepted tokens with live prices. `priceId` adds each token's `quote`;
-     * `wallet` adds its `balance`.
+     * The customer's merchant: its payment setup (PSPs, Solana network and
+     * tokens) and how it presents itself. React components share one copy
+     * through `useCustomerConfig()`.
      */
-    listSolanaTokens(opts?: {
-        priceId?: string;
-        wallet?: string;
-        signal?: AbortSignal;
-    }): Promise<SolanaToken[]>;
+    getCustomerConfig(signal?: AbortSignal): Promise<CustomerConfig>;
     /** Currency code (upper case) to native-unit decimals. */
     currencies: Readonly<Record<string, number>>;
 };