@openrails/billing-ui 0.234.0 → 0.236.0

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
-import { CheckoutSource } from '../source';
-import { Account, CardSetup, CheckoutSessionLink, PublicConfig, PaymentAuthentication, CurrencyScales, Invoice, ListPage, NewCard, NextAction, Page, Payment, PaymentMethod, Product, SolanaToken, Subscription, TierChange, TierChangePreview } from './types';
+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';
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -18,15 +18,13 @@ export interface BillingClientOptions {
      */
     currencies?: CurrencyScales;
 }
-export interface CheckoutSourceOptions {
-    /**
-     * A customer surface's base: its `/me` prefix, such as `/billing/v1/me` or
-     * a host's own `/api/v1/merchants/acme/billing/me`. The session is read and
-     * paid there with this client's credential, which proves the session's
-     * customer, so its saved cards pay. Default: the session id alone, at
-     * `{baseUrl}/checkout-sessions`.
-     */
-    customerBase?: string;
+/**
+ * A public catalog lookup: the products named by `keys` (at most 100 product
+ * keys), in one page.
+ */
+export interface ProductListOptions {
+    keys: string[];
+    signal?: AbortSignal;
 }
 export interface ListOptions {
     limit?: number;
@@ -35,7 +33,15 @@ export interface ListOptions {
     cursor?: string;
     signal?: AbortSignal;
 }
-/** A cursor list read: pass the previous page's `next_cursor` for the next. */
+/**
+ * A subscription change: another price of its tier group, other seats of a
+ * per-seat price, or both. A quantity for a price that is not per seat is
+ * refused (`quantity_not_allowed`).
+ */
+export interface SubscriptionChangeInput {
+    priceId?: string;
+    quantity?: number;
+}
 export interface CursorOptions {
     limit?: number;
     cursor?: string | null;
@@ -61,6 +67,14 @@ export declare const isWalletAction: (next: NextAction | null | undefined) => bo
 export declare function signWalletAction(next: NextAction, sendTransaction: SendSolanaTransaction): Promise<string>;
 /** Total wait a GET may spend on its one retry. */
 export declare const RETRY_BUDGET_MS = 2000;
+/**
+ * An order request's answer. `error` is set when the payment failed: the
+ * order is open again and its `payment.last_payment_error` says why.
+ */
+export interface OrderResult {
+    order: Order;
+    error?: BillingError;
+}
 export declare function createBillingClient(options?: BillingClientOptions): {
     baseUrl: string;
     /** One page of the customer's subscriptions, newest first. */
@@ -81,47 +95,91 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     }): Promise<Subscription>;
     /** Undoes a scheduled cancel before the period ends. */
     resumeSubscription(subscriptionId: string): Promise<Subscription>;
-    setSubscriptionPaymentMethod(subscriptionId: string, paymentMethodId: string): Promise<Subscription>;
-    /** What `changeTier` would charge now and at the next renewal. */
-    previewTierChange(subscriptionId: string, priceId: string, signal?: AbortSignal): Promise<TierChangePreview>;
+    /** Gives the subscription its own card; `null` makes it follow the default. */
+    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>;
     /**
-     * Moves the subscription to another price of its tier group: an upgrade
-     * charges the saved card now, a downgrade applies at period end.
-     * `idempotencyKey` identifies this attempt; reuse it until the change
-     * resolves (`processing`, a `tier_change_in_flight` refusal or a lost
-     * response) so the stored result replays instead of charging twice. A
-     * wallet next action (Solana) is completed with `signWalletAction` and
-     * the change repeated with `signature`.
+     * 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
+     * the saved card now; a downgrade and fewer seats apply at period end.
+     * 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`.
      */
-    changeTier(subscriptionId: string, input: {
-        priceId: string;
+    changeSubscription(subscriptionId: string, input: SubscriptionChangeInput & {
         idempotencyKey: string;
         signature?: string;
-    }): Promise<TierChange>;
+    }): Promise<SubscriptionChange>;
     listPaymentMethods(opts?: CursorOptions): Promise<ListPage<PaymentMethod>>;
     /**
-     * Stores a card entered in the page with the PSP `psp_id`: a Collect.js
-     * token (`cardSetupDriver` "collect_js") or the card itself ("card").
+     * Saves a card entered in the page with the PSP `psp_id` in one call: the
+     * token of its own fields, or the card itself ("card"). A Stripe card the
+     * bank wants authenticated answers `requires_action`.
      */
     addPaymentMethod(card: NewCard): Promise<PaymentMethod>;
+    /** The customer's cart, priced now. */
+    getCart(signal?: AbortSignal): Promise<Cart>;
     /**
-     * Starts an in-page card setup with a PSP whose browser SDK collects the
-     * card (see `cardSetupDriver`). `idempotencyKey` identifies this attempt.
+     * Puts a price in the cart or changes its line, and answers the cart.
+     * `quantity` 0 removes the line; omitted, the price's default. `amount`
+     * is the customer's choice on a price that takes one.
      */
-    createCardSetup(input: {
-        pspId: string;
+    setCartLine(priceId: string, input?: {
+        quantity?: number;
+        amount?: string;
+    }): Promise<Cart>;
+    /** Empties the cart. */
+    clearCart(): Promise<void>;
+    /**
+     * 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.
+     */
+    createOrder(input: {
+        lines?: {
+            price_id: string;
+            quantity?: number;
+            amount?: string;
+        }[];
+        cart?: boolean;
+        expectedTotal?: string;
+        payment?: OrderPaymentInput;
+        reusable?: boolean;
+        idempotencyKey: string;
+    }): Promise<OrderResult>;
+    /** One of the customer's orders: the resumable handle of a purchase. */
+    getOrder(orderId: string, signal?: AbortSignal): Promise<Order>;
+    /**
+     * Pays an open order. A failed payment resolves with the order (open,
+     * `payment.last_payment_error` saying why) and `error`, the 402.
+     * `idempotencyKey` is minted when the pay button renders: a retry with it
+     * answers what the first request answered.
+     */
+    payOrder(orderId: string, input: {
+        payment: OrderPaymentInput;
+        expectedTotal: string;
+        reusable?: boolean;
         idempotencyKey: string;
-    }): Promise<CardSetup>;
-    getCardSetup(setupId: string, signal?: AbortSignal): Promise<CardSetup>;
-    /** Verifies the setup with the provider; `payment_method_id` once saved. */
-    confirmCardSetup(setupId: string): Promise<CardSetup>;
+    }): Promise<OrderResult>;
+    /** Reads the provider after the customer completed `next_action`. */
+    confirmOrder(orderId: string): Promise<OrderResult>;
+    /**
+     * Finishes saving a card the bank asked to authenticate, after the PSP's
+     * 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 one that collects one currency's invoices. */
-    setCollectionPaymentMethod(input: {
+    /**
+     * Makes the card the default for one currency: it pays the currency's
+     * invoices and every subscription in it without its own card.
+     */
+    setDefaultPaymentMethod(input: {
         currency: string;
         paymentMethodId: string;
     }): Promise<void>;
@@ -136,34 +194,11 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
     getInvoice(invoiceId: string, signal?: AbortSignal): Promise<Invoice>;
-    /** Products on sale, each with its current prices. */
-    listProducts(opts?: ListOptions): Promise<Page<Product>>;
-    /**
-     * Mints a hosted checkout session for the signed-in customer and one
-     * price. Render it with `<CheckoutFrame url>` when the session has a
-     * `url`, else with `<Checkout source={client.checkoutSource(id)}>`.
-     * Select a price by `priceId`, or by both `productKey` and `priceKey`.
-     * `successUrl` brings the buyer back from a redirect rail; it must be on
-     * one of this app's return origins.
-     */
-    createCheckoutSession(input: {
-        priceKey?: string;
-        productKey?: string;
-        priceId?: string;
-        /** Customer-selected deposit in the price currency’s native units. */
-        amount?: string;
-        /** Defaults to true for recurring prices; false buys the initial term only. */
-        autoRenew?: boolean;
-        successUrl?: string;
-    }): Promise<CheckoutSessionLink>;
     /**
-     * Reads and pays one hosted checkout session. By default the id is the
-     * only credential: no bearer is sent. With `customerBase` the session's
-     * customer reads and pays it on that customer surface, signed in. A
-     * refusal the buyer can answer (an invalid card form, too many attempts)
-     * resolves as `failed`; an expired or unknown session as `expired`.
+     * The products on sale named by `keys`, each with its current prices.
+     * No keys name no products: nothing is fetched.
      */
-    checkoutSource(sessionId: string, opts?: CheckoutSourceOptions): CheckoutSource;
+    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

package/dist/client/errors.d.ts

@@ -5,6 +5,8 @@ export interface BillingErrorBody {
     request_id?: string;
     param?: string;
     metadata?: Record<string, unknown>;
+    /** The order a failed payment left open (402 card_error). */
+    order?: unknown;
 }
 export declare class BillingError extends Error {
     readonly status: number;
@@ -13,13 +15,12 @@ export declare class BillingError extends Error {
     readonly param?: string;
     readonly requestId?: string;
     readonly metadata: Record<string, unknown>;
+    /** The order a failed payment left open, unvalidated. */
+    readonly order?: unknown;
     constructor(status: number, body: BillingErrorBody);
 }
 export declare const isBillingError: (value: unknown) => value is BillingError;
-/**
- * A server failure (HTTP 5xx) from any client or host source that carries a
- * numeric `status`. It is surfaced at once, never retried behind the caller.
- */
+/** A server failure (HTTP 5xx) from any client or host source that carries a numeric `status`. */
 export declare const isServerError: (value: unknown) => boolean;
 export declare function localError(code: string, message: string): BillingError;
 export declare function readBillingError(res: Response): Promise<BillingError>;

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

@@ -1,4 +1,4 @@
-export type OpenRailsErrorCode = "access_token_invalid" | "access_token_issuer_unknown" | "access_token_merchant_not_bound" | "admission_captured" | "admission_not_found" | "allowance_meter_not_found" | "allowance_source_in_use" | "allowance_source_invalid" | "already_owned" | "api_host_claim_missing" | "api_host_reserved" | "api_host_taken" | "api_host_unproven" | "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" | "catalog_updates_disabled" | "checkout_attempt_closed" | "checkout_attempt_expired" | "checkout_offer_unavailable" | "checkout_payment_in_progress" | "checkout_request_invalid" | "checkout_session_expired" | "checkout_session_not_found" | "checkout_session_unavailable" | "collection_payment_method_invalid" | "collection_payment_method_required" | "creation_refused" | "credential_custody_transition_required" | "credential_expired" | "credential_identity_mismatch" | "credential_operation_conflict" | "credential_revoked" | "credential_source_read_only" | "credential_store_read_only" | "credentials_manage_required" | "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_proof_required" | "customer_session_required" | "dashboard_invalid" | "database_busy" | "default_rate_card_not_found" | "default_rate_card_required" | "delegated_principal_invalid" | "email_unverified" | "finding_action_failed" | "finding_not_actionable" | "hold_not_found" | "host_event_not_found" | "host_merchant_mismatch" | "host_principal_invalid" | "idempotency_key_in_use" | "idempotency_key_required" | "idempotency_key_reused" | "insufficient_credits" | "insufficient_funds" | "insufficient_scope" | "internal_error" | "invalid_api_host" | "invalid_cursor" | "invalid_customer_id" | "invalid_email" | "invalid_host_event_request" | "invalid_name" | "invalid_param" | "invalid_payment_method" | "invalid_psp_reference" | "invalid_query" | "invalid_request_body" | "invalid_settlement_status_request" | "invalid_user" | "invites_disabled" | "invoice_action_not_allowed" | "invoice_not_retryable" | "invoice_retry_idempotency_conflict" | "invoice_retry_in_progress" | "invoice_retry_outcome_unknown" | "invoker_scoped_principal" | "last_owner" | "members_manage_required" | "merchant_binding_mismatch" | "merchant_configuration_application_conflict" | "merchant_configuration_revision_conflict" | "merchant_context_mismatch" | "merchant_creation_payment_method_required" | "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" | "name_reserved" | "name_taken" | "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_retry_required" | "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" | "rename_too_soon" | "renames_disabled" | "request_body_too_large" | "resource_access_denied" | "resource_conflict" | "resource_not_found" | "role_escalation" | "route_not_found" | "scheduled_change_exists" | "sender_proof_required" | "service_credential_customer_scope_denied" | "service_credential_invalid" | "service_credential_merchant_unresolved" | "service_credential_resource_scope_denied" | "service_unavailable" | "solana_rpc_unavailable" | "solana_transaction_refused" | "spend_delegation_not_found" | "step_up_required" | "step_up_unavailable" | "subscription_not_active" | "subscription_not_found" | "subscription_paid_through" | "subscription_resumable" | "tier_change_already_scheduled" | "tier_change_cadence_unsupported" | "tier_change_credit_exceeds_price" | "tier_change_cycle_unknown" | "tier_change_idempotency_conflict" | "tier_change_idempotency_key_required" | "tier_change_in_flight" | "tier_change_period_unknown" | "tier_change_provider_conflict" | "tier_change_refused" | "tier_change_renewal_due" | "tier_change_requires_linked_plan" | "tier_change_target_inactive" | "tier_change_unsupported_on_rail" | "trial_unsupported_on_rail" | "unknown_field" | "unknown_role" | "unsupported_media_type" | "usage_meter_invalid" | "usage_meter_not_found" | "usage_rate_card_invalid" | "use_dpop_nonce" | "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_expired" | "checkout_not_found" | "checkout_offer_unavailable" | "checkout_payment_in_progress" | "checkout_request_invalid" | "checkout_session_expired" | "checkout_session_not_found" | "checkout_session_unavailable" | "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_proof_required" | "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" | "invoice_action_not_allowed" | "invoice_not_retryable" | "invoice_retry_idempotency_conflict" | "invoice_retry_in_progress" | "invoice_retry_outcome_unknown" | "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_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_retry_required" | "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" | "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 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;