@openrails/billing-ui 0.237.0 → 0.239.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## Public products and staff route groups
+
+- Breaking: public `listProducts()` now reads `GET /products`. Catalog
+  management uses `/catalog`, merchant configuration `/merchant`, and metrics
+  `/metrics`; customer support stays under `/admin`.
+
+## Provider operations removed
+
+- Breaking: `OpenRailsErrorCode` and `OPENRAILS_ERROR_CODES` lose
+  `provider_operation_not_found`, `provider_operation_conflict`,
+  `provider_operation_not_open`, `provider_operation_has_billing_evidence`,
+  `provider_operation_refused`, `provider_operation_not_refused` and
+  `provider_billing_observation_conflict`.
+
+## Usage report
+
+- `getUsage({ currency, groupBy, from, to, limit, cursor })` reads a page of
+  the customer's usage (`GET /me/usage`): `Usage`, its `rows` by total
+  amount, largest first, and `next_cursor` (null on the last page). A page
+  holds at most 1,000 groups (default 100); a cursor reads only the report it
+  came from.
+
+## 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
@@ -235,15 +292,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

@@ -42,11 +42,33 @@ 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: a
+"$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
@@ -56,6 +78,7 @@ 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}
@@ -64,6 +87,7 @@ 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()}
@@ -87,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
@@ -140,23 +164,25 @@ 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 read is a public route, 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 /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`                            |
 
@@ -173,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
@@ -188,7 +215,7 @@ 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:
@@ -208,8 +235,6 @@ provider:
   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` (SavePaymentMethod, AccountBilling)
   preselects the billing country, else the browser locale's region.
 
@@ -263,3 +288,7 @@ pnpm contract:check  # fail if a generated contract file is stale
 `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.
+
+## License
+
+MIT; see [LICENSE](LICENSE). Only this package is MIT: the rest of the OpenRails repository is under the Functional Source License (FSL-1.1-ALv2).

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

@@ -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

@@ -2,6 +2,8 @@ import { CheckoutAppearance } from './appearance';
 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. */
@@ -30,8 +32,8 @@ export interface BuyButtonProps {
     appearance?: CheckoutAppearance;
     className?: string;
 }
-export declare function BuyButton(props: BuyButtonProps): React.JSX.Element;
-export type PurchaseProps = Omit<BuyButtonProps, "product" | "price"> & {
+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;

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
 import { BillingError } from './errors';
-import { Account, CustomerLink, NetworkLinkChallenge, PublicConfig, PaymentAuthentication, CurrencyScales, ListPage, NewCard, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, 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, Usage } 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;
 }
@@ -47,6 +53,18 @@ export interface CursorOptions {
     cursor?: string | null;
     signal?: AbortSignal;
 }
+/**
+ * A page of the customer's usage report in `currency`, grouped by `groupBy`
+ * (event type by default). `from` and `to` are RFC 3339 or a date; left out,
+ * the month before now, or with `cursor` the window of the page it came from.
+ * `limit` is at most 1,000 groups (default 100).
+ */
+export interface UsageOptions extends CursorOptions {
+    currency: string;
+    groupBy?: "event_type" | "resource" | "invoker";
+    from?: string;
+    to?: string;
+}
 /**
  * Signs and submits a base64 transaction with the customer's wallet and
  * returns its signature. Throw `WalletRejectedError` when the user declines.
@@ -99,6 +117,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 +130,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;
@@ -180,9 +205,6 @@ 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">;
     /**
@@ -203,8 +225,14 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
     /**
-     * The products on sale named by `keys`, each with its current prices.
-     * No keys name no products: nothing is fetched.
+     * A page of the customer's usage: its groups by total amount, largest
+     * first. Pass the answer's `next_cursor` as `cursor` for the next page.
+     */
+    getUsage(opts: UsageOptions): Promise<Usage>;
+    /**
+     * 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>>;
     /**
@@ -221,11 +249,17 @@ export declare function createBillingClient(options?: BillingClientOptions): {
         idToken: string;
     }): Promise<CustomerLink>;
     /**
-     * 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()`.
+     * 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>;
+    /**
+     * The customer's merchant: its payment setup (PSPs, Solana network and
+     * tokens) and how it presents itself. React components share one copy
+     * through `useCustomerConfig()`.
+     */
+    getCustomerConfig(signal?: AbortSignal): Promise<CustomerConfig>;
     /** Currency code (upper case) to native-unit decimals. */
     currencies: Readonly<Record<string, number>>;
 };

package/dist/client/generated/error-codes.d.ts

@@ -1,4 +1,4 @@
-export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "allowance_meter_not_found" | "allowance_source_in_use" | "allowance_source_invalid" | "already_owned" | "application_required" | "as_of_required" | "authentication_required" | "authentication_unavailable" | "authorization_unavailable" | "billing_archive_integrity" | "billing_archive_invalid_artifact" | "billing_archive_merchant_mismatch" | "billing_archive_not_empty" | "billing_archive_unavailable" | "billing_archive_unsupported_state" | "billing_policy_not_found" | "cancel_unsupported_on_rail" | "captcha_invalid" | "captcha_required" | "card_attempts_blocked" | "card_declined" | "card_not_saved" | "card_requires_https" | "catalog_benefit_overlap" | "catalog_revision_conflict" | "checkout_attempt_closed" | "checkout_attempt_expired" | "checkout_attempts_exhausted" | "checkout_embed_origins_required" | "checkout_expired" | "checkout_not_found" | "credential_expired" | "credential_revoked" | "credit_grant_held" | "credit_grant_not_found" | "credit_grant_unavailable" | "csrf_origin_denied" | "currency_unsupported" | "custodian_capture_unavailable" | "customer_action_required" | "customer_email_required" | "customer_not_found" | "customer_payment_unsupported" | "customer_session_required" | "dashboard_invalid" | "database_busy" | "default_payment_method_invalid" | "default_payment_method_required" | "default_rate_card_not_found" | "default_rate_card_required" | "finding_action_failed" | "finding_not_actionable" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "idempotency_key_in_progress" | "idempotency_key_in_use" | "idempotency_key_required" | "idempotency_key_reused" | "insufficient_credits" | "insufficient_funds" | "internal_error" | "invalid_cursor" | "invalid_customer_id" | "invalid_host_event_request" | "invalid_param" | "invalid_payment_method" | "invalid_psp_reference" | "invalid_query" | "invalid_request_body" | "invalid_settlement_status_request" | "invoker_scoped_principal" | "merchant_binding_mismatch" | "merchant_config_read_only" | "merchant_directory_unavailable" | "merchant_not_found" | "merchant_selector_invalid" | "merchant_unresolved" | "meter_in_use" | "meter_rate_card_conflict" | "method_not_allowed" | "metrics_query_invalid" | "model_unavailable" | "network_account_linked" | "network_link_challenge_invalid" | "network_link_conflict" | "network_link_in_use" | "network_terms_required" | "order_action_not_allowed" | "order_has_recurring_line" | "order_line_unavailable" | "order_not_cancelable" | "order_not_payable" | "order_payment_in_progress" | "order_total_changed" | "payment_duplicate_refused" | "payment_exceeds_due" | "payment_failed" | "payment_idempotency_conflict" | "payment_in_progress" | "payment_method_delete_failed" | "payment_method_delete_unsupported" | "payment_method_not_psp_vaulted" | "payment_method_not_usable" | "payment_method_psp_mismatch" | "payment_method_required" | "payment_method_same_vault" | "payment_method_stale" | "payment_method_update_failed" | "payment_method_update_unsupported" | "payment_not_found" | "payment_not_refundable" | "payment_not_retryable" | "payment_option_unavailable" | "payment_provider_rejected" | "permission_required" | "price_change_currency_mismatch" | "price_change_target_archived" | "price_increase_notice_too_short" | "price_key_cadence_conflict" | "price_key_not_found" | "price_migration_not_found" | "price_not_found" | "price_not_sellable" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_billing_observation_conflict" | "provider_cancel_held" | "provider_operation_conflict" | "provider_operation_has_billing_evidence" | "provider_operation_not_found" | "provider_operation_not_open" | "provider_operation_not_refused" | "provider_operation_refused" | "provider_outcome_unknown" | "psp_claim_requires_proof" | "psp_credentials_rejected" | "psp_exists" | "psp_key_taken" | "psp_last_active" | "psp_not_found" | "purchase_review_resolved" | "quantity_not_allowed" | "rate_card_currency_mismatch" | "rate_card_has_overrides" | "rate_card_product_not_found" | "rate_limit_exceeded" | "rebill_terms_committed" | "refund_failed" | "refund_rail_unavailable" | "refund_unsupported" | "request_body_too_large" | "resource_access_denied" | "resource_conflict" | "resource_not_found" | "revision_mismatch" | "route_not_found" | "running_charge_not_found" | "scheduled_change_exists" | "service_credential_customer_scope_denied" | "service_unavailable" | "solana_rpc_unavailable" | "solana_transaction_refused" | "step_up_required" | "step_up_unavailable" | "stored_credential_required" | "subscription_change_already_scheduled" | "subscription_change_cadence_unsupported" | "subscription_change_credit_exceeds_price" | "subscription_change_cycle_unknown" | "subscription_change_idempotency_conflict" | "subscription_change_idempotency_key_required" | "subscription_change_in_flight" | "subscription_change_period_unknown" | "subscription_change_provider_conflict" | "subscription_change_refused" | "subscription_change_renewal_due" | "subscription_change_requires_linked_plan" | "subscription_change_target_inactive" | "subscription_change_unsupported_on_rail" | "subscription_not_active" | "subscription_not_found" | "subscription_paid_through" | "subscription_resumable" | "trial_unsupported_on_rail" | "unknown_field" | "unsupported_media_type" | "usage_meter_invalid" | "usage_meter_not_found" | "usage_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid" | "widget_generation_invalid";
+export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "allowance_meter_not_found" | "allowance_source_in_use" | "allowance_source_invalid" | "already_owned" | "application_required" | "as_of_required" | "authentication_required" | "authentication_unavailable" | "authorization_unavailable" | "billing_archive_integrity" | "billing_archive_invalid_artifact" | "billing_archive_merchant_mismatch" | "billing_archive_not_empty" | "billing_archive_unavailable" | "billing_archive_unsupported_state" | "billing_policy_not_found" | "cancel_unsupported_on_rail" | "captcha_invalid" | "captcha_required" | "card_attempts_blocked" | "card_declined" | "card_not_saved" | "card_requires_https" | "catalog_benefit_overlap" | "catalog_revision_conflict" | "checkout_attempt_closed" | "checkout_attempt_expired" | "checkout_attempts_exhausted" | "checkout_embed_origins_required" | "checkout_expired" | "checkout_not_found" | "credential_expired" | "credential_revoked" | "credit_grant_held" | "credit_grant_not_found" | "credit_grant_unavailable" | "csrf_origin_denied" | "currency_unsupported" | "custodian_capture_unavailable" | "customer_action_required" | "customer_email_required" | "customer_issuer_mismatch" | "customer_not_found" | "customer_payment_unsupported" | "customer_session_required" | "dashboard_invalid" | "database_busy" | "default_payment_method_invalid" | "default_payment_method_required" | "default_rate_card_not_found" | "finding_action_failed" | "finding_not_actionable" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "idempotency_key_in_progress" | "idempotency_key_in_use" | "idempotency_key_required" | "idempotency_key_reused" | "insufficient_credits" | "insufficient_funds" | "internal_error" | "invalid_cursor" | "invalid_customer_id" | "invalid_host_event_request" | "invalid_param" | "invalid_payment_method" | "invalid_psp_reference" | "invalid_query" | "invalid_request_body" | "invalid_settlement_status_request" | "invoker_scoped_principal" | "merchant_config_read_only" | "merchant_unresolved" | "meter_in_use" | "meter_rate_card_conflict" | "method_not_allowed" | "metrics_query_invalid" | "model_unavailable" | "network_account_linked" | "network_link_challenge_invalid" | "network_link_conflict" | "network_link_in_use" | "network_terms_required" | "order_action_not_allowed" | "order_has_recurring_line" | "order_line_unavailable" | "order_not_cancelable" | "order_not_payable" | "order_payment_in_progress" | "order_total_changed" | "payment_duplicate_refused" | "payment_exceeds_due" | "payment_failed" | "payment_idempotency_conflict" | "payment_in_progress" | "payment_method_delete_failed" | "payment_method_delete_unsupported" | "payment_method_not_psp_vaulted" | "payment_method_not_usable" | "payment_method_psp_mismatch" | "payment_method_required" | "payment_method_same_vault" | "payment_method_stale" | "payment_method_update_failed" | "payment_method_update_unsupported" | "payment_not_found" | "payment_not_refundable" | "payment_not_retryable" | "payment_option_unavailable" | "payment_provider_rejected" | "permission_required" | "price_change_currency_mismatch" | "price_change_target_archived" | "price_increase_notice_too_short" | "price_key_cadence_conflict" | "price_key_not_found" | "price_migration_not_found" | "price_not_found" | "price_not_sellable" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_cancel_held" | "provider_outcome_unknown" | "psp_claim_requires_proof" | "psp_credentials_rejected" | "psp_exists" | "psp_key_taken" | "psp_last_active" | "psp_not_found" | "purchase_review_resolved" | "quantity_not_allowed" | "rate_card_product_not_found" | "rate_limit_exceeded" | "rebill_terms_committed" | "refund_failed" | "refund_rail_unavailable" | "refund_unsupported" | "request_body_too_large" | "resource_access_denied" | "resource_conflict" | "resource_not_found" | "revision_mismatch" | "route_not_found" | "running_charge_not_found" | "scheduled_change_exists" | "service_credential_customer_scope_denied" | "service_unavailable" | "solana_rpc_unavailable" | "solana_transaction_refused" | "step_up_required" | "step_up_unavailable" | "stored_credential_required" | "subscription_change_already_scheduled" | "subscription_change_cadence_unsupported" | "subscription_change_credit_exceeds_price" | "subscription_change_cycle_unknown" | "subscription_change_idempotency_conflict" | "subscription_change_idempotency_key_required" | "subscription_change_in_flight" | "subscription_change_period_unknown" | "subscription_change_provider_conflict" | "subscription_change_refused" | "subscription_change_renewal_due" | "subscription_change_requires_linked_plan" | "subscription_change_target_inactive" | "subscription_change_unsupported_on_rail" | "subscription_not_active" | "subscription_not_found" | "subscription_paid_through" | "subscription_resumable" | "trial_unsupported_on_rail" | "unknown_field" | "unsupported_media_type" | "usage_meter_invalid" | "usage_meter_not_found" | "usage_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid";
 export type OpenRailsErrorType = "api_error" | "authentication_error" | "authorization_error" | "card_error" | "invalid_request_error" | "rate_limit_error";
 export declare const OPENRAILS_ERROR_CODES: Readonly<Record<OpenRailsErrorCode, {
     status: number;

package/dist/client/generated/routes.d.ts

@@ -3,7 +3,10 @@ export type OpenRailsRoute = {
     path: string;
     group: string;
     auth: string;
-    permission: string | null;
+    permission: {
+        merchant: string | null;
+        root: string;
+    } | null;
     sensitive: boolean;
     mountedWhen: string | null;
     request: string | null;
@@ -53,6 +56,20 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly [];
     readonly errorSets: readonly ["tier:public"];
+}, {
+    readonly method: "GET";
+    readonly path: "/v1/me/config";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "CustomerConfig";
+    };
+    readonly errors: readonly ["service_unavailable"];
+    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "POST";
     readonly path: "/v1/me/orders/preview";
@@ -224,7 +241,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "GET";
-    readonly path: "/v1/catalog/products";
+    readonly path: "/v1/products";
     readonly group: "checkout";
     readonly auth: "public";
     readonly permission: null;
@@ -234,7 +251,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "ListPage<Product>";
     };
-    readonly errors: readonly ["invalid_query"];
+    readonly errors: readonly ["invalid_query", "resource_not_found"];
     readonly errorSets: readonly ["tier:public", "request"];
 }, {
     readonly method: "POST";
@@ -336,6 +353,21 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["authentication_required", "card_declined", "customer_action_required", "customer_email_required", "invalid_param", "payment_duplicate_refused", "payment_method_stale", "payment_provider_rejected", "price_change_currency_mismatch", "price_not_found", "product_not_found", "quantity_not_allowed", "rebill_terms_committed", "resource_conflict", "resource_not_found", "scheduled_change_exists", "service_unavailable", "solana_rpc_unavailable", "solana_transaction_refused", "subscription_change_already_scheduled", "subscription_change_credit_exceeds_price", "subscription_change_cycle_unknown", "subscription_change_idempotency_conflict", "subscription_change_idempotency_key_required", "subscription_change_in_flight", "subscription_change_period_unknown", "subscription_change_provider_conflict", "subscription_change_refused", "subscription_change_renewal_due", "subscription_change_requires_linked_plan", "subscription_change_target_inactive", "subscription_change_unsupported_on_rail", "subscription_not_active", "subscription_not_found"];
     readonly errorSets: readonly ["tier:customer", "request"];
+}, {
+    readonly method: "POST";
+    readonly path: "/v1/me/subscriptions/{id}/confirm";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "SubscriptionChange";
+        readonly 202: "SubscriptionChange";
+    };
+    readonly errors: readonly ["authentication_required", "card_declined", "customer_session_required", "invalid_param", "payment_not_found", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable", "subscription_change_refused", "subscription_not_found"];
+    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "POST";
     readonly path: "/v1/me/subscriptions/{id}/change/preview";
@@ -404,36 +436,8 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "Usage";
     };
-    readonly errors: readonly ["currency_unsupported"];
+    readonly errors: readonly ["currency_unsupported", "invalid_cursor"];
     readonly errorSets: readonly ["tier:customer", "request"];
-}, {
-    readonly method: "GET";
-    readonly path: "/v1/me/payment-operations/{id}/authentication";
-    readonly group: "customer";
-    readonly auth: "customer";
-    readonly permission: null;
-    readonly sensitive: false;
-    readonly mountedWhen: null;
-    readonly request: null;
-    readonly responses: {
-        readonly 200: "StripeEngineAuthentication";
-    };
-    readonly errors: readonly ["card_attempts_blocked", "card_declined", "card_not_saved", "custodian_capture_unavailable", "customer_session_required", "idempotency_key_reused", "insufficient_funds", "invalid_param", "payment_method_required", "payment_method_stale", "payment_not_found", "payment_provider_rejected", "resource_access_denied", "resource_conflict", "resource_not_found", "service_unavailable"];
-    readonly errorSets: readonly ["tier:customer"];
-}, {
-    readonly method: "POST";
-    readonly path: "/v1/me/payment-operations/{id}/authentication/confirm";
-    readonly group: "customer";
-    readonly auth: "customer";
-    readonly permission: null;
-    readonly sensitive: false;
-    readonly mountedWhen: null;
-    readonly request: null;
-    readonly responses: {
-        readonly 200: "PaymentOperation";
-    };
-    readonly errors: readonly ["card_attempts_blocked", "card_declined", "card_not_saved", "custodian_capture_unavailable", "customer_session_required", "idempotency_key_reused", "insufficient_funds", "invalid_param", "payment_method_required", "payment_method_stale", "payment_not_found", "payment_provider_rejected", "resource_access_denied", "resource_conflict", "resource_not_found", "service_unavailable"];
-    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "GET";
     readonly path: "/v1/me/payments";
@@ -547,6 +551,34 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["invalid_param", "resource_not_found", "route_not_found"];
     readonly errorSets: readonly ["tier:customer"];
+}, {
+    readonly method: "GET";
+    readonly path: "/v1/me/agreements";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "ListPage<Agreement>";
+    };
+    readonly errors: readonly ["invalid_cursor"];
+    readonly errorSets: readonly ["tier:customer", "request"];
+}, {
+    readonly method: "POST";
+    readonly path: "/v1/me/agreements/{id}/revoke";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "AgreementRevocation";
+    };
+    readonly errors: readonly ["cancel_unsupported_on_rail", "customer_action_required", "invalid_param", "payment_in_progress", "provider_cancel_held", "resource_not_found", "service_unavailable", "subscription_not_active"];
+    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "GET";
     readonly path: "/v1/me/notifications";