@openrails/billing-ui 0.234.0 → 0.235.0

package/CHANGELOG.md

@@ -1,9 +1,31 @@
 # Changelog
 
+## Checkout saves a new card under its PSP
+
+- Inside a `BillingProvider`, `Checkout` saved a new card with the session
+  option's id as `psp_id`, which `POST /me/payment-methods` refuses
+  (`invalid_param`); it now sends the option's `psp_id`.
+
+## A default card per currency
+
+- `setDefaultPaymentMethod({currency, paymentMethodId})` (`PUT
+  /me/default-payment-methods/{currency}`) replaces
+  `setCollectionPaymentMethod`: the default card pays the currency's invoices
+  and every subscription in it without its own card. `usePaymentMethods()`
+  has `setDefault` for `setCollection`, `PaymentMethod.default_currencies`
+  replaces `collection_currencies`, and the `payment_method.default_changed`
+  change replaces `payment_method.collection_changed`.
+- `AccountBilling` and `PaymentMethodsPanel` take `defaultCurrency` (was
+  `collectionCurrency`) and offer "Make default".
+- `setSubscriptionPaymentMethod(id, null)` and `setPaymentMethod(id, null)`
+  make a subscription follow the default card; `Subscription.payment_method_id`
+  is its own card, null when it follows. The change-card dialog offers "Your
+  default card" and opens on any card subscription (`collection_policy`).
+
 ## The customer's summary
 
-- `getAccount()` reads `GET /me`: the balance per currency, the card that
-  pays each currency, and the unread notice count.
+- `getAccount()` reads `GET /me`: the balance per currency, the default card
+  of each currency, and the unread notice count.
 - `Invoice.delinquent`: overdue past grace; new usage in its currency is
   refused until it is paid.
 
@@ -14,6 +36,21 @@
   final retry, and whether it waits for a new card. Null unless the
   subscription is `past_due` or `awaiting_method`.
 
+## Subscription changes and seats
+
+- `changeTier` and `previewTierChange` are `changeSubscription(id,
+  { priceId?, quantity?, idempotencyKey, signature? })` and
+  `previewSubscriptionChange(id, { priceId?, quantity? })`, on
+  `POST /me/subscriptions/{id}/change[/preview]`. `TierChange` and
+  `TierChangePreview` are `SubscriptionChange` and `SubscriptionChangePreview`:
+  no `action`, a `quantity`. `useSubscriptions().changeTier` is
+  `changeSubscription`, its pending state `change`, and its host event
+  `subscription.changed`.
+- `Subscription` has `quantity`: the seats of a per-seat price, null
+  otherwise; `scheduled_change.quantity` is the seats the next renewal bills. The `tier_change_*` codes are
+  `subscription_change_*`, and `quantity_not_allowed` refuses seats on a price
+  without them.
+
 ## The public catalog is under /catalog
 
 - `listProducts()` reads `GET /catalog/products` (was `GET /products`).

package/README.md

@@ -21,10 +21,11 @@ session document, billing fields, browser-autofill behavior, and the checkout
 request schema.
 
 The package lives in the OpenRails repository and shares its version: each
-OpenRails release `vX.Y.Z` attaches `openrails-billing-ui-X.Y.Z.tgz`.
+OpenRails release `vX.Y.Z` publishes `@openrails/billing-ui@X.Y.Z` to npm, with
+provenance.
 
 ```sh
-pnpm add https://github.com/open-rails/openrails/releases/download/vX.Y.Z/openrails-billing-ui-X.Y.Z.tgz
+pnpm add @openrails/billing-ui@X.Y.Z
 ```
 
 ## Checkout
@@ -125,7 +126,7 @@ const billing = createBillingClient({ baseUrl: "/billing/v1", fetch: auth.authFe
   <BillingProvider client={billing} onChange={() => queryClient.invalidateQueries({ queryKey: ["billing"] })}>
     <AccountBilling
       plansHref="/plans"
-      collectionCurrency="USD" // offers "Use for invoices"
+      defaultCurrency="USD" // offers "Make default"
       sendSolanaTransaction={(tx) => wallet.signAndSend(tx)} // signs a Solana cancel
     />
   </BillingProvider>
@@ -150,28 +151,31 @@ routes; `GET /config` is always served.
 | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
 | `listProducts()` (each product embeds its prices on sale)                                           | `GET /catalog/products`                                         |
 | `getConfig()` (capabilities, `currencies`, `payment` with PSPs, `solana.network` and tokens; `client.currencies` is the pinned registry) | `GET /config` |
-| `previewTierChange(id, priceId)`                                                                    | `POST /me/subscriptions/{id}/change-tier/preview`               |
-| `changeTier(id, { priceId, idempotencyKey, signature? })`                                         | `POST /me/subscriptions/{id}/change-tier`                       |
+| `previewSubscriptionChange(id, { priceId?, quantity? })`                                            | `POST /me/subscriptions/{id}/change/preview`                    |
+| `changeSubscription(id, { priceId?, quantity?, idempotencyKey, signature? })`                       | `POST /me/subscriptions/{id}/change`                            |
 | `listSolanaTokens({ priceId, wallet })`                                                             | `GET /solana/tokens`                                            |
 
 ```ts
-const preview = await billing.previewTierChange(sub.id, price.id) // amount_due_now, effective
-const change = await billing.changeTier(sub.id, {
-  priceId: price.id,
+const preview = await billing.previewSubscriptionChange(sub.id, { quantity: 5 }) // amount_due_now, effective
+const change = await billing.changeSubscription(sub.id, {
+  quantity: 5,
   idempotencyKey,
 })
 ```
 
-- `changeTier` is a money write. Mint one `idempotencyKey` per attempt and
+- A change moves to another price of the tier group (`priceId`), to other
+  seats of a per-seat price (`quantity`), or both. More seats and an upgrade
+  charge now; fewer seats and a downgrade apply at the next renewal.
+- `changeSubscription` is a money write. Mint one `idempotencyKey` per attempt and
   reuse it until the change resolves (`status: "processing"`, a
-  `tier_change_in_flight` refusal naming `metadata.operation_id`, a 5xx or a
+  `subscription_change_in_flight` refusal naming `metadata.operation_id`, a 5xx or a
   lost response), so OpenRails replays the stored result instead of charging
   twice. `requires_action` carries `operation_id` for `authenticatePayment`;
   replay the same key afterwards.
 - A rail that needs the customer's own step answers `requires_action` with a
   `next_action`. Solana's is `solana_sign_transactions`:
   `signWalletAction(change.next_action, send)` signs and sends its
-  transactions and returns the signature; repeat `changeTier` with the same
+  transactions and returns the signature; repeat `changeSubscription` with the same
   key and `signature`. `cancelSubscription(id, { reason, signature? })` works
   the same way: its answer is the subscription, unchanged and carrying
   `next_action` until the signed cancel lands. The hooks run this when given
@@ -215,11 +219,11 @@ provider:
 - `renderSubscriptionFooter={(s) => ...}` adds host content under a
   subscription row; `useBillingRefresh()` refetches after host-side changes.
 - Hooks: `useSubscriptions` (`cancel`, `resume`, `setPaymentMethod`,
-  `changeTier`, per-row `pending`, `nextCursor`), `usePaymentMethods` (`add`,
-  `remove`, `setCollection`), `usePayments` (cursor pages), `useProducts` (the
+  `changeSubscription`, per-row `pending`, `nextCursor`), `usePaymentMethods` (`add`,
+  `remove`, `setDefault`), `usePayments` (cursor pages), `useProducts` (the
   catalog).
   Actions resolve to `null` or a `BillingError`; they never throw.
-  `changeTier` resolves to the `TierChange` instead of `null`. Cancel, resume
+  `changeSubscription` resolves to the `SubscriptionChange` instead of `null`. Cancel, resume
   and the card change answer the subscription, which replaces the row.
 - Money is exact: `/me` amounts are int64 native-unit strings, scaled by the
   OpenRails currency registry (`currencies` option to extend it).

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

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

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

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

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

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

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 { Account, CardSetup, CheckoutSessionLink, PublicConfig, PaymentAuthentication, CurrencyScales, Invoice, ListPage, NewCard, NextAction, Page, Payment, PaymentMethod, Product, SolanaToken, Subscription, SubscriptionChange, SubscriptionChangePreview } from './types';
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -35,7 +35,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;
@@ -81,23 +89,23 @@ 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
@@ -120,8 +128,11 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     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>;

package/dist/client/errors.d.ts

@@ -16,10 +16,7 @@ export declare class BillingError extends Error {
     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 = "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" | "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_offer_unavailable" | "checkout_payment_in_progress" | "checkout_request_invalid" | "checkout_session_expired" | "checkout_session_not_found" | "checkout_session_unavailable" | "credential_custody_transition_required" | "credential_expired" | "credential_identity_mismatch" | "credential_operation_conflict" | "credential_revoked" | "credential_source_read_only" | "credential_store_read_only" | "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" | "delegated_principal_invalid" | "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_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_configuration_application_conflict" | "merchant_configuration_revision_conflict" | "merchant_context_mismatch" | "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" | "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" | "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" | "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" | "use_dpop_nonce" | "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;

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

@@ -39,20 +39,6 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["service_unavailable"];
     readonly errorSets: readonly ["tier:public"];
-}, {
-    readonly method: "GET";
-    readonly path: "/metrics";
-    readonly group: "meta";
-    readonly auth: "public";
-    readonly permission: null;
-    readonly sensitive: false;
-    readonly mountedWhen: null;
-    readonly request: null;
-    readonly responses: {
-        readonly 200: "text/plain";
-    };
-    readonly errors: readonly [];
-    readonly errorSets: readonly ["tier:public"];
 }, {
     readonly method: "GET";
     readonly path: "/v1/config";
@@ -360,7 +346,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "Subscription";
     };
-    readonly errors: readonly ["authentication_required", "card_declined", "invalid_param", "payment_method_not_psp_vaulted", "payment_method_psp_mismatch", "payment_method_same_vault", "payment_provider_rejected", "rebill_terms_committed", "resource_conflict", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["authentication_required", "card_declined", "default_payment_method_required", "invalid_param", "payment_method_not_psp_vaulted", "payment_method_psp_mismatch", "payment_method_same_vault", "payment_method_stale", "payment_provider_rejected", "rebill_terms_committed", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "GET";
@@ -407,32 +393,32 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "POST";
-    readonly path: "/v1/me/subscriptions/{id}/change-tier";
+    readonly path: "/v1/me/subscriptions/{id}/change";
     readonly group: "customer";
     readonly auth: "customer";
     readonly permission: null;
     readonly sensitive: false;
     readonly mountedWhen: null;
-    readonly request: "CustomerChangeTierParams";
+    readonly request: "CustomerChangeSubscriptionParams";
     readonly responses: {
-        readonly 200: "TierChange";
-        readonly 202: "TierChange";
+        readonly 200: "SubscriptionChange";
+        readonly 202: "SubscriptionChange";
     };
-    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", "rebill_terms_committed", "resource_conflict", "resource_not_found", "scheduled_change_exists", "service_unavailable", "solana_rpc_unavailable", "solana_transaction_refused", "subscription_not_active", "subscription_not_found", "tier_change_in_flight", "tier_change_period_unknown", "tier_change_provider_conflict", "tier_change_refused", "tier_change_requires_linked_plan", "tier_change_target_inactive", "tier_change_unsupported_on_rail"];
+    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}/change-tier/preview";
+    readonly path: "/v1/me/subscriptions/{id}/change/preview";
     readonly group: "customer";
     readonly auth: "customer";
     readonly permission: null;
     readonly sensitive: false;
     readonly mountedWhen: null;
-    readonly request: "ChangeTierParams";
+    readonly request: "PreviewSubscriptionChangeParams";
     readonly responses: {
-        readonly 200: "TierChangePreview";
+        readonly 200: "SubscriptionChangePreview";
     };
-    readonly errors: readonly ["authentication_required", "card_declined", "customer_email_required", "invalid_param", "payment_method_stale", "payment_provider_rejected", "price_change_currency_mismatch", "price_not_found", "product_not_found", "resource_conflict", "resource_not_found", "service_unavailable", "subscription_not_active", "subscription_not_found", "tier_change_in_flight", "tier_change_period_unknown", "tier_change_provider_conflict", "tier_change_requires_linked_plan", "tier_change_target_inactive", "tier_change_unsupported_on_rail"];
+    readonly errors: readonly ["authentication_required", "card_declined", "customer_email_required", "invalid_param", "payment_method_stale", "payment_provider_rejected", "price_change_currency_mismatch", "price_not_found", "product_not_found", "quantity_not_allowed", "resource_conflict", "resource_not_found", "service_unavailable", "subscription_change_already_scheduled", "subscription_change_credit_exceeds_price", "subscription_change_cycle_unknown", "subscription_change_in_flight", "subscription_change_period_unknown", "subscription_change_provider_conflict", "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: "GET";
@@ -605,17 +591,17 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "PUT";
-    readonly path: "/v1/me/collection-payment-method";
+    readonly path: "/v1/me/default-payment-methods/{currency}";
     readonly group: "customer";
     readonly auth: "customer";
     readonly permission: null;
     readonly sensitive: false;
     readonly mountedWhen: null;
-    readonly request: "CollectionPaymentMethod";
+    readonly request: "SetDefaultPaymentMethodParams";
     readonly responses: {
-        readonly 200: "CollectionPaymentMethod";
+        readonly 200: "DefaultPaymentMethod";
     };
-    readonly errors: readonly ["collection_payment_method_invalid", "invalid_param"];
+    readonly errors: readonly ["authentication_required", "card_declined", "default_payment_method_invalid", "invalid_param", "payment_method_not_psp_vaulted", "payment_method_psp_mismatch", "payment_method_same_vault", "payment_method_stale", "payment_provider_rejected", "rebill_terms_committed", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "GET";
@@ -660,6 +646,34 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["card_declined", "card_not_saved", "card_requires_https", "credential_custody_transition_required", "invalid_param", "payment_method_update_failed", "payment_method_update_retry_required", "payment_method_update_unsupported", "payment_provider_rejected", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:customer", "request"];
+}, {
+    readonly method: "PATCH";
+    readonly path: "/v1/me/payment-methods/{id}";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: "UpdatePaymentMethodParams";
+    readonly responses: {
+        readonly 200: "PaymentMethod";
+    };
+    readonly errors: readonly ["card_requires_https", "invalid_param", "payment_method_not_usable", "payment_method_update_unsupported", "payment_provider_rejected", "provider_outcome_unknown", "resource_not_found", "service_unavailable"];
+    readonly errorSets: readonly ["tier:customer", "request"];
+}, {
+    readonly method: "POST";
+    readonly path: "/v1/me/payment-methods/{id}/verify";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "PaymentMethod";
+    };
+    readonly errors: readonly ["card_attempts_blocked", "card_declined", "insufficient_funds", "invalid_param", "payment_method_not_usable", "payment_method_update_unsupported", "payment_provider_rejected", "provider_outcome_unknown", "resource_not_found", "service_unavailable"];
+    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "DELETE";
     readonly path: "/v1/me/payment-methods/{id}";