@openrails/billing-ui 0.248.0 → 0.249.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Hosts sell the products their pages carry
+
+- Breaking: the browser never reads the catalog. `listProducts`, `useProducts`,
+  `ProductListOptions` and `ProductsState` are removed with OpenRails' public
+  `GET /products`; your server reads the catalog with the Go client and puts the
+  products in its page (`billing.BuyerPrices`).
+- Breaking: `<ProductList products>` takes the host's products (no `merchant`
+  or `keys`); `<BuyButton price>` takes one of their prices (no `merchant`,
+  `product` or price key). `Purchase` is folded into `BuyButton`.
+- `createOrder({ checkout: { ui_mode: "embedded" } })` creates the order with
+  its embedded checkout in one call: `order.checkout.url` on the checkout host,
+  as long as the order is open, returning nowhere (`success_url` null), for the
+  merchant's own signed-in person. Without `payment` it
+  answers the customer's open order of the same lines when there is one (with
+  a fresh URL); `idempotencyKey` is needed only with `payment`.
+- On a site the merchant registered to frame its checkout, `BuyButton` creates
+  the order that way and frames it (`<EmbeddedCheckout>`); elsewhere it pays on
+  the page as before. It stores nothing and sends no key: a reload or a
+  reopened dialog answers the same open order.
+
 ## Entitlements read
 
 - `getEntitlements()` lists the entitlement keys the customer holds

package/README.md

@@ -64,33 +64,41 @@ const billing = createBillingClient({
 })
 ```
 
-`<BuyButton>` buys one price, `<ProductList>` the products your server names by
-key (a course, its bundle and the membership that also unlocks it; the Go
-`Client.ListProducts` finds the products granting an entitlement): a
-`BuyButton` per price ("$4.99", "Rent for 3 days, $1.99",
-"$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.
+The browser never reads the catalog (Stripe's and Paddle's model): your
+server reads the products it sells with the Go `Client.ListProducts` (by key,
+or those granting an entitlement) and puts them in its own page's response,
+their prices as a buyer sees them (`billing.BuyerPrices`). `<BuyButton price>`
+buys one of those prices, `<ProductList products>` sells those products (a
+course, its bundle and the membership that also unlocks it): 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 button creates the customer's
+order (`POST /me/orders`) and pays it in a dialog. On a page of a site the
+merchant registered to frame its checkout (`merchant.embed_origins` in
+`GET /me/config`), it creates the order with its embedded checkout in the same
+call (`createOrder({ lines, checkout: { ui_mode: "embedded" } })`) and frames
+`order.checkout.url` from the checkout host (`<EmbeddedCheckout>`); anywhere
+else it pays on the page (`<OrderCheckout>`). The embedded checkout returns
+nowhere: the frame says it is paid and tells the page (`onPaid`), and a
+redirect PSP comes back inside it. Nothing is stored: OpenRails answers the
+customer's open order of the same lines, so a second click, a reopened dialog
+or a reload pays the same order (with a fresh URL), and a paid or expired one
+is bought again as a new 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
+  price={course.prices[0]} // from your server's page response
   signedIn={signedIn}
   onSignInRequired={() => openSignIn()}
   onPaid={() => navigate("/courses/css-101")} // your gate now admits them
 />
 
 <ProductList
-  merchant={merchantId}
-  keys={["course-101", "course-bundle", "channel-membership"]} // from your server, or products={...} from its Client.ListProducts
+  products={products} // from your server's page response
   signedIn={signedIn}
   onSignInRequired={() => openSignIn()}
   onPaid={() => navigate("/courses/css-101")}
@@ -107,13 +115,13 @@ page, and the checkout charges exactly that:
 ```tsx
 import { decimalToAmount } from "@openrails/billing-ui/client"
 
-// `depositPrice` is in a product from listProducts; `currency` from getConfig().currencies.
+// `depositPrice` is in a product your server sent; `currency` from getConfig().currencies.
 // `enteredAmount` is the text from an <input inputMode="decimal">, e.g. "100".
 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 merchant={merchantId} product="api-credits" price="deposit" amount={valid ? amount : undefined} label="Add credits" {...handlers} />
+<BuyButton price={depositPrice} amount={valid ? amount : undefined} label="Add credits" {...handlers} />
 ```
 
 OpenRails validates the bounds and whole currency minor units before accepting
@@ -205,15 +213,13 @@ host content and links. The customer imports above do not load admin code or
 styles. See the [BillingAdmin integration guide](https://github.com/open-rails/openrails/blob/master/docs/billing-admin.md)
 for merchant selection, permissions, localization, and standalone console setup.
 
-## Catalog and plan changes
+## Configuration and plan changes
 
-The client also reads the public catalog and changes a subscription's plan.
-The catalog read and `GET /config` are public routes: the client sends them
-no bearer.
+The client also reads the configuration and changes a subscription's plan.
+`GET /config` is a public route: the client sends it no bearer.
 
 | Call                                                                                                | Route                                                           |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `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`                    |
@@ -278,8 +284,7 @@ provider:
   subscription row; `useBillingRefresh()` refetches after host-side changes.
 - Hooks: `useSubscriptions` (`cancel`, `resume`, `setPaymentMethod`,
   `changeSubscription`, per-row `pending`, `nextCursor`), `usePaymentMethods` (`add`,
-  `remove`, `setDefault`), `usePayments` (cursor pages), `useProducts` (a
-  catalog lookup by product key).
+  `remove`, `setDefault`), `usePayments` (cursor pages).
   Actions resolve to `null` or a `BillingError`; they never throw.
   `changeSubscription` resolves to the `SubscriptionChange` instead of `null`. Cancel, resume
   and the card change answer the subscription, which replaces the row.

package/dist/buy-button.d.ts

@@ -1,14 +1,14 @@
 import { CheckoutAppearance } from './appearance';
-import { Order } from './client/types';
+import { Order, Price } 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. */
-    price: string;
-    /** The button's text; by default the price's amount and terms, from the catalog. */
+    /**
+     * The price to buy, from a product the host's server put in its page (the
+     * Go Client's ListProducts, its prices as a buyer sees them:
+     * `billing.BuyerPrices`). The browser never reads the catalog.
+     */
+    price: Price;
+    /** The button's text; by default the price's amount and terms. */
     label?: string;
     /**
      * A customer-chosen deposit, in the price currency's native units, for a
@@ -32,11 +32,5 @@ export interface BuyButtonProps {
     appearance?: CheckoutAppearance;
     className?: string;
 }
-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;
+export declare function BuyButton({ price, label, amount, returnUrl, onPaid, onSignInRequired, signedIn, appearance, className, }: BuyButtonProps): React.JSX.Element;

package/dist/client/client.d.ts

@@ -1,5 +1,6 @@
 import { BillingError } from './errors';
-import { Account, CustomerConfig, CustomerEntitlement, CustomerLink, LowBalanceLine, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, CardCaptureReference, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, Subscription, SubscriptionChange, SubscriptionChangePreview, Usage } from './types';
+import { Account, CustomerConfig, CustomerEntitlement, CustomerLink, LowBalanceLine, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, CardCaptureReference, NextAction, Cart, Order, OrderPaymentInput, Payment, PaymentMethod, Subscription, SubscriptionChange, SubscriptionChangePreview, Usage } from './types';
+import type * as wire from "./generated/wire";
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -10,8 +11,8 @@ export interface BillingClientOptions {
     fetch?: (input: string, init: RequestInit) => Promise<Response>;
     /**
      * 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
+     * the public read (`getConfig`); 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>;
@@ -23,15 +24,6 @@ export interface BillingClientOptions {
      */
     currencies?: CurrencyScales;
 }
-/**
- * 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;
-}
 export interface ListOptions {
     limit?: number;
     offset?: number;
@@ -161,7 +153,12 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     /**
      * Creates an order from `lines` or the cart (`cart: true`), and with
      * `payment` pays it in the same call; `expectedTotal` is the total the
-     * customer saw. A failed payment resolves as payOrder's does.
+     * customer saw; `idempotencyKey`, required with `payment`, names the
+     * payment attempt. A failed payment resolves as payOrder's does. Without
+     * `payment` the customer's open order of the same lines is answered when
+     * there is one. With `checkout` the order answers its embedded checkout,
+     * `order.checkout.url` on the checkout host, for `<EmbeddedCheckout>`,
+     * fresh on every answer: the merchant's own signed-in person only.
      */
     createOrder(input: {
         lines?: {
@@ -173,7 +170,8 @@ export declare function createBillingClient(options?: BillingClientOptions): {
         expectedTotal?: string;
         payment?: OrderPaymentInput;
         reusable?: boolean;
-        idempotencyKey: string;
+        checkout?: wire.MyOrderCheckoutParams;
+        idempotencyKey?: string;
     }): Promise<OrderResult>;
     /**
      * The customer's orders, newest first: `origin: "usage"` their usage
@@ -257,12 +255,6 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      * 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>>;
     /**
      * A challenge to link the customer to an openrails.dev account: its
      * `nonce` goes in the network sign-in's authorization request.

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

@@ -1,4 +1,4 @@
-export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "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" | "destructive_actions_held" | "finding_action_failed" | "finding_not_actionable" | "finding_requires_merchant_config" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "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_mismatch" | "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_in_use" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_cancel_held" | "provider_outcome_unknown" | "provider_writes_held" | "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_not_priced" | "usage_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid";
+export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "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_platform_cards" | "billing_archive_unavailable" | "billing_archive_unsupported_state" | "billing_policy_not_found" | "cancel_unsupported_on_rail" | "captcha_invalid" | "captcha_required" | "card_attempts_blocked" | "card_custody_reserved" | "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" | "destructive_actions_held" | "entitlement_required" | "finding_action_failed" | "finding_not_actionable" | "finding_requires_merchant_config" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "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_mismatch" | "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" | "platform_vault_unavailable" | "platform_vault_unreachable" | "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_in_use" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_cancel_held" | "provider_outcome_unknown" | "provider_writes_held" | "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_not_priced" | "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

@@ -98,7 +98,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
         readonly 200: "Order";
         readonly 201: "Order";
     };
-    readonly errors: readonly ["already_owned", "card_attempts_blocked", "card_declined", "customer_action_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_line_unavailable", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "quantity_not_allowed", "resource_conflict", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["already_owned", "card_attempts_blocked", "card_declined", "checkout_embed_origins_required", "customer_action_required", "customer_session_required", "entitlement_required", "hosted_checkout_unavailable", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_line_unavailable", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "quantity_not_allowed", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "GET";
@@ -140,7 +140,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "Order";
     };
-    readonly errors: readonly ["card_attempts_blocked", "card_declined", "customer_action_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["card_attempts_blocked", "card_declined", "customer_action_required", "entitlement_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "POST";
@@ -231,7 +231,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
         readonly 200: "Order";
         readonly 201: "Order";
     };
-    readonly errors: readonly ["already_owned", "checkout_embed_origins_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_line_unavailable", "quantity_not_allowed", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["already_owned", "checkout_embed_origins_required", "entitlement_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_line_unavailable", "quantity_not_allowed", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:application", "request"];
 }, {
     readonly method: "POST";
@@ -360,20 +360,6 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["service_unavailable"];
     readonly errorSets: readonly ["tier:customer"];
-}, {
-    readonly method: "GET";
-    readonly path: "/v1/products";
-    readonly group: "checkout";
-    readonly auth: "public";
-    readonly permission: null;
-    readonly sensitive: false;
-    readonly mountedWhen: null;
-    readonly request: null;
-    readonly responses: {
-        readonly 200: "ListPage<Product>";
-    };
-    readonly errors: readonly ["invalid_query", "resource_not_found"];
-    readonly errorSets: readonly ["tier:public", "request"];
 }, {
     readonly method: "POST";
     readonly path: "/v1/catalog/apply";
@@ -1823,7 +1809,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 201: "PSP";
     };
-    readonly errors: readonly ["invalid_param", "psp_claim_requires_proof", "psp_credentials_rejected", "psp_exists", "psp_key_taken", "revision_mismatch", "service_unavailable"];
+    readonly errors: readonly ["invalid_param", "platform_vault_unreachable", "psp_claim_requires_proof", "psp_credentials_rejected", "psp_exists", "psp_key_taken", "revision_mismatch", "service_unavailable"];
     readonly errorSets: readonly ["tier:merchant", "request"];
 }, {
     readonly method: "GET";
@@ -1939,7 +1925,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "MerchantConfigurationState";
     };
-    readonly errors: readonly ["invalid_param", "revision_mismatch", "service_unavailable"];
+    readonly errors: readonly ["card_custody_reserved", "invalid_param", "platform_vault_unavailable", "platform_vault_unreachable", "resource_conflict", "revision_mismatch", "service_unavailable"];
     readonly errorSets: readonly ["tier:merchant", "request"];
 }, {
     readonly method: "GET";
@@ -2024,7 +2010,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "application/x-ndjson";
     };
-    readonly errors: readonly ["billing_archive_unavailable", "billing_archive_unsupported_state"];
+    readonly errors: readonly ["billing_archive_platform_cards", "billing_archive_unavailable", "billing_archive_unsupported_state"];
     readonly errorSets: readonly ["tier:merchant"];
 }, {
     readonly method: "POST";
@@ -2041,7 +2027,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "BillingArchiveImport";
     };
-    readonly errors: readonly ["billing_archive_integrity", "billing_archive_invalid_artifact", "billing_archive_merchant_mismatch", "billing_archive_not_empty", "billing_archive_unavailable", "billing_archive_unsupported_state", "request_body_too_large"];
+    readonly errors: readonly ["billing_archive_integrity", "billing_archive_invalid_artifact", "billing_archive_merchant_mismatch", "billing_archive_not_empty", "billing_archive_platform_cards", "billing_archive_unavailable", "billing_archive_unsupported_state", "request_body_too_large"];
     readonly errorSets: readonly ["tier:merchant", "request"];
 }, {
     readonly method: "POST";
@@ -2607,7 +2593,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "Order";
     };
-    readonly errors: readonly ["card_attempts_blocked", "card_declined", "customer_action_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["card_attempts_blocked", "card_declined", "customer_action_required", "entitlement_required", "idempotency_key_in_use", "idempotency_key_required", "idempotency_key_reused", "invalid_param", "order_not_payable", "order_payment_in_progress", "order_total_changed", "payment_failed", "payment_method_stale", "payment_option_unavailable", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:network", "request"];
 }, {
     readonly method: "POST";

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

@@ -145,6 +145,7 @@ export type ApplyProduct = {
     archived?: boolean | null;
     ownership?: "consumable" | "extend" | "unique" | null;
     entitlements?: string[];
+    required_entitlements?: string[];
     credit_grant?: CreditGrantSpec | null;
     prices?: Record<string, ApplyPrice>;
     rate_cards?: RateCard[] | null;
@@ -455,6 +456,7 @@ export type CreateMyOrderParams = {
     expected_total?: string;
     payment?: OrderPaymentParams;
     reusable?: boolean;
+    checkout?: MyOrderCheckoutParams;
 };
 export type CreateNetworkLinkParams = {
     challenge_id?: string;
@@ -531,6 +533,7 @@ export type CreateProductParams = {
     display_name?: string;
     description?: string;
     entitlements?: string[];
+    required_entitlements?: string[];
     credit_grant?: CreditGrantSpec;
     tier_group?: string;
     tier_rank?: number;
@@ -699,10 +702,18 @@ export type DeclaredBilling = {
     subscriptions?: DeclaredSubscription[];
     transactions?: DeclaredTransaction[];
     admin_grants?: DeclaredAdminGrant[];
+    purchases?: DeclaredPurchase[];
 };
 export type DeclaredCustomer = {
     customer?: string;
 };
+export type DeclaredOrderLine = {
+    price?: string;
+    quantity?: number;
+    unit_amount?: string;
+    description?: string;
+    access_ends_at?: string;
+};
 export type DeclaredPaymentMethod = {
     customer?: string;
     rail?: string;
@@ -722,6 +733,25 @@ export type DeclaredProviderSchedule = {
     interval_months?: number;
     first_due_at?: string;
 };
+export type DeclaredPurchase = {
+    source_id?: string;
+    customer?: string;
+    rail?: string;
+    psp?: PSPRef;
+    transaction_id?: string;
+    currency?: string;
+    amount?: string;
+    paid_at?: string;
+    lines?: DeclaredOrderLine[];
+    settlement?: DeclaredSettlement;
+    evidence?: unknown;
+};
+export type DeclaredSettlement = {
+    asset?: string;
+    quantity?: string;
+    payer?: string;
+    recipient?: string;
+};
 export type DeclaredStripeInvoice = {
     id?: string;
     customer_reference?: string;
@@ -1006,6 +1036,7 @@ export type MerchantConfigurationState = {
     revision: number;
     display_name: string;
     settings: MerchantSettings;
+    platform_vault: PlatformVaultState;
 };
 export type MerchantProfile = {
     logo_url?: string;
@@ -1028,6 +1059,7 @@ export type MerchantSettings = {
     dunning_policy?: DunningPolicy;
     checkout?: MerchantCheckoutSettings;
     balance_notices?: BalanceNoticeSettings;
+    card_custody?: "hosted" | "merchant" | "platform";
     billing_policies?: BillingPolicy[];
     billing_policy_bindings?: BillingPolicyBinding[];
     delegated_invoker_wasted_spend_limits?: BudgetWindow[];
@@ -1131,6 +1163,9 @@ export type MetricsSchema = {
     limits: MetricsLimits;
     query_shape: string;
 };
+export type MyOrderCheckoutParams = {
+    ui_mode?: "embedded" | "hosted";
+};
 export type NetworkLink = {
     link: CustomerLink;
     merchant: PublicMerchant;
@@ -1204,7 +1239,7 @@ export type OrderCheckout = {
     url: string | null;
     ui_mode: "embedded" | "hosted";
     expires_at: string;
-    success_url: string;
+    success_url: string | null;
     cancel_url: string | null;
     saved_payment_methods: boolean;
 };
@@ -1250,6 +1285,7 @@ export type OrderLineRefusal = {
     message: string;
     owned_by: string | null;
     hint: string | null;
+    missing?: string[];
 };
 export type OrderPayment = {
     status: "processing" | "requires_action" | "requires_payment_method" | "succeeded";
@@ -1513,6 +1549,9 @@ export type PerUnitPrice = {
     maximum_amount?: string;
     matrix?: Matrix;
 };
+export type PlatformVaultState = {
+    available: boolean;
+};
 export type PreviewMyOrderParams = {
     lines?: OrderLineParams[];
     cart?: boolean;
@@ -1616,6 +1655,7 @@ export type Product = {
     display_name: string;
     description: string;
     entitlements: string[];
+    required_entitlements: string[];
     credit_grant?: CreditGrantSpec;
     tier_group: string | null;
     tier_rank: number;
@@ -2016,6 +2056,7 @@ export type UpdateProductParams = {
     display_name?: string | null;
     description?: string | null;
     entitlements?: string[];
+    required_entitlements?: string[];
     credit_grant?: CreditGrantSpec | null;
     tier_group?: string | null;
     tier_rank?: number | null;

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { CANCEL_REASON_MAX, CANCEL_REASON_MIN, createBillingClient, isWalletAction, isWalletRejection, RETRY_BUDGET_MS, signWalletAction, WalletRejectedError, type BillingClient, type BillingClientOptions, type ListOptions, type OrderResult, type ProductListOptions, type SendSolanaTransaction, type SubscriptionChangeInput, type UsageOptions, } from './client';
+export { CANCEL_REASON_MAX, CANCEL_REASON_MIN, createBillingClient, isWalletAction, isWalletRejection, RETRY_BUDGET_MS, signWalletAction, WalletRejectedError, type BillingClient, type BillingClientOptions, type ListOptions, type OrderResult, type SendSolanaTransaction, type SubscriptionChangeInput, type UsageOptions, } from './client';
 export { redeemAssertion, tokenSource, type RedeemAssertionOptions, type TokenResponse, type TokenSource, type TokenSourceOptions, } from './token-source';
 export { BillingError, isBillingError, isServerError, readBillingError, toBillingError, type BillingErrorBody, } from './errors';
 export type { Account, Balance, CaptchaConfig, CardSummary, Cart, Currency, CurrencyScales, CustomerConfig, CustomerEntitlement, CustomerLink, PaymentConfig, PaymentFailure, PublicConfig, PublicMerchant, ListPage, LowBalanceLine, NetworkLinkChallenge, NewCard, CardCaptureReference, NextAction, Order, OrderLine, OrderLineRefusal, OrderPaymentInput, OrderPreviewLine, Page, Payment, PaymentMethod, PaymentRecovery, Price, Product, Subscription, SubscriptionDunning, SubscriptionProduct, SubscriptionStatus, SubscriptionChange, SubscriptionChangePreview, Usage, UsageRow, } from './types';

package/dist/client/types.d.ts

@@ -425,11 +425,11 @@ export declare const orderSchema: z.ZodObject<{
     checkout: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         ui_mode: z.ZodCatch<z.ZodEnum<{
-            embedded: "embedded";
             hosted: "hosted";
+            embedded: "embedded";
         }>>;
         expires_at: z.ZodString;
-        success_url: z.ZodString;
+        success_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         cancel_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         saved_payment_methods: z.ZodBoolean;
     }, z.core.$strip>>>;
@@ -460,12 +460,13 @@ export declare const orderSchema: z.ZodObject<{
     created_at: z.ZodString;
 }, z.core.$strip>;
 export type Order = z.infer<typeof orderSchema>;
-/** Why a line cannot be bought: `already_owned`, `unavailable`, ... */
+/** Why a line cannot be bought: `already_owned`, `entitlement_required`, `unavailable`, ... */
 export declare const orderLineRefusalSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     owned_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     hint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    missing: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type OrderLineRefusal = z.infer<typeof orderLineRefusalSchema>;
 /** One line priced as an order would freeze it, or why it cannot be bought. */
@@ -484,6 +485,7 @@ export declare const orderPreviewLineSchema: z.ZodObject<{
         message: z.ZodString;
         owned_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         hint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        missing: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type OrderPreviewLine = z.infer<typeof orderPreviewLineSchema>;
@@ -510,6 +512,7 @@ export declare const cartSchema: z.ZodObject<{
             message: z.ZodString;
             owned_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             hint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            missing: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     payment_options: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
@@ -555,6 +558,7 @@ export declare const productSchema: z.ZodObject<{
     display_name: z.ZodString;
     description: z.ZodString;
     entitlements: z.ZodArray<z.ZodString>;
+    required_entitlements: z.ZodOptional<z.ZodArray<z.ZodString>>;
     credit_grant: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         currency: z.ZodString;
         amount: z.ZodOptional<z.ZodNullable<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;