@openrails/billing-ui 0.230.0 → 0.234.0

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
 import { CheckoutSource } from '../source';
-import { BillingStatus, CardSetup, Currency, HostedCheckoutLink, PaymentAuthentication, CurrencyScales, Invoice, NewCard, Page, Payment, PaymentMethod, Price, Product, SolanaConfig, SolanaTierChange, SolanaTierChangeTx, SolanaToken, Subscription, TierChange, TierChangePreview } from './types';
+import { Account, CardSetup, CheckoutSessionLink, PublicConfig, PaymentAuthentication, CurrencyScales, Invoice, ListPage, NewCard, NextAction, Page, Payment, PaymentMethod, Product, SolanaToken, Subscription, TierChange, TierChangePreview } from './types';
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -18,12 +18,29 @@ 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;
+}
 export interface ListOptions {
     limit?: number;
     offset?: number;
+    /** A cursor list's next page: the previous page's `next_cursor`. */
+    cursor?: string;
+    signal?: AbortSignal;
+}
+/** A cursor list read: pass the previous page's `next_cursor` for the next. */
+export interface CursorOptions {
+    limit?: number;
+    cursor?: string | null;
     signal?: AbortSignal;
 }
-export type SolanaCancelStage = "preparing" | "signing" | "confirming";
 /**
  * Signs and submits a base64 transaction with the customer's wallet and
  * returns its signature. Throw `WalletRejectedError` when the user declines.
@@ -32,27 +49,39 @@ export type SendSolanaTransaction = (transactionBase64: string) => Promise<strin
 export declare class WalletRejectedError extends Error {
     constructor(message?: string);
 }
-export declare const CANCEL_FEEDBACK_MIN = 4;
-export declare const CANCEL_FEEDBACK_MAX = 500;
+export declare const CANCEL_REASON_MIN = 4;
+export declare const CANCEL_REASON_MAX = 500;
+/** A next action the customer's wallet completes. */
+export declare const isWalletAction: (next: NextAction | null | undefined) => boolean;
+/**
+ * Signs and sends a `solana_sign_transactions` next action's transactions in
+ * order and returns the last signature, the value the action is repeated
+ * with. A declined prompt is a local `wallet_rejected` error.
+ */
+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;
 export declare function createBillingClient(options?: BillingClientOptions): {
     baseUrl: string;
-    listSubscriptions(opts?: ListOptions & {
+    /** One page of the customer's subscriptions, newest first. */
+    listSubscriptions(opts?: CursorOptions & {
         status?: string;
-    }): Promise<Page<Subscription>>;
+    }): Promise<ListPage<Subscription>>;
     /** Includes `recovery` (list rows do not). */
     getSubscription(subscriptionId: string, signal?: AbortSignal): Promise<Subscription>;
     /**
-     * Queues the cancellation (202). Access and resumability follow the
-     * rail's cancel mode; re-read the subscription to observe the result.
+     * Cancels at period end and answers the subscription. When the rail needs
+     * the customer's step (`next_action`, a Solana wallet signature), the
+     * subscription is unchanged: complete it with `signWalletAction` and
+     * repeat with `signature`.
      */
     cancelSubscription(subscriptionId: string, input: {
-        feedback: string;
-    }): Promise<void>;
-    /** Queues the resumption (202). */
-    resumeSubscription(subscriptionId: string): Promise<void>;
-    setSubscriptionPaymentMethod(subscriptionId: string, paymentMethodId: string): Promise<void>;
+        reason: string;
+        signature?: string;
+    }): 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>;
     /**
@@ -60,35 +89,19 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      * 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.
+     * 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`.
      */
     changeTier(subscriptionId: string, input: {
         priceId: string;
         idempotencyKey: string;
+        signature?: string;
     }): Promise<TierChange>;
+    listPaymentMethods(opts?: CursorOptions): Promise<ListPage<PaymentMethod>>;
     /**
-     * Solana rail: the tier-change transaction for the wallet to sign and
-     * send. Pass the resulting signature to `confirmSolanaTierChange`.
-     */
-    prepareSolanaTierChange(subscriptionId: string, newPriceId: string): Promise<SolanaTierChangeTx>;
-    /**
-     * Records the landed transaction. Keep the signature until this succeeds:
-     * confirming it again replays the result (`already_confirmed`).
-     */
-    confirmSolanaTierChange(subscriptionId: string, input: {
-        signature: string;
-        newPriceId: string;
-    }): Promise<SolanaTierChange>;
-    /**
-     * On-chain cancellation for the solana rail: the server prepares an
-     * unsigned transaction, the wallet signs and submits it, the server
-     * verifies the signature and records the cancel.
-     */
-    cancelSubscriptionOnChain(subscriptionId: string, sendTransaction: SendSolanaTransaction, onStage?: (stage: SolanaCancelStage) => void): Promise<void>;
-    listPaymentMethods(opts?: ListOptions): Promise<Page<PaymentMethod>>;
-    /**
-     * Stores a card entered in the page: a Collect.js token
-     * (`cardSetupDriver` "collect_js") or the card itself ("card").
+     * Stores a card entered in the page with the PSP `psp_id`: a Collect.js
+     * token (`cardSetupDriver` "collect_js") or the card itself ("card").
      */
     addPaymentMethod(card: NewCard): Promise<PaymentMethod>;
     /**
@@ -107,56 +120,62 @@ 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 method the default collector for one currency's invoices. */
-    setDefaultPaymentMethod(input: {
+    /** Makes the card the one that collects one currency's invoices. */
+    setCollectionPaymentMethod(input: {
         currency: string;
         paymentMethodId: string;
     }): Promise<void>;
     /** Charges and refunds, newest first. `rail` filters by rail. */
-    listPayments(opts?: ListOptions & {
+    listPayments(opts?: CursorOptions & {
         rail?: string;
-    }): Promise<Page<Payment>>;
-    listInvoices(opts?: ListOptions): Promise<Page<Invoice>>;
+    }): Promise<ListPage<Payment>>;
+    listInvoices(opts?: CursorOptions): Promise<ListPage<Invoice>>;
+    /**
+     * The customer's summary: balance and amount owed per currency, the card
+     * that pays each currency, and unread notices.
+     */
+    getAccount(signal?: AbortSignal): Promise<Account>;
     getInvoice(invoiceId: string, signal?: AbortSignal): Promise<Invoice>;
-    getStatus(signal?: AbortSignal): Promise<BillingStatus>;
-    /** Active products with their active prices. */
+    /** Products on sale, each with its current prices. */
     listProducts(opts?: ListOptions): Promise<Page<Product>>;
-    /** Active prices. `product` is a `prod_` id; `type` is `recurring | one_time`. */
-    listPrices(opts?: ListOptions & {
-        currency?: string;
-        product?: string;
-        type?: string;
-    }): Promise<Page<Price>>;
-    /** The server's currency registry; `currencies` is the pinned copy. */
-    listCurrencies(signal?: AbortSignal): Promise<Currency[]>;
     /**
      * 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<HostedCheckoutLink>;
+    }): 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`.
+     */
+    checkoutSource(sessionId: string, opts?: CheckoutSourceOptions): CheckoutSource;
     /**
-     * Reads and pays one hosted checkout session. The id is the only
-     * credential: no bearer is sent. A refusal the buyer can answer (an
-     * invalid card form, too many attempts) resolves as `failed`; an expired
-     * or unknown session as `expired`.
+     * The deployment's public configuration: what the mount serves, the
+     * currency registry and the merchant's payment setup. React components
+     * share one copy through `useConfig()`.
      */
-    checkoutSource(sessionId: string): CheckoutSource;
-    /** Network and accepted tokens; served only with a Solana PSP. */
-    getSolanaConfig(signal?: AbortSignal): Promise<SolanaConfig>;
+    getConfig(signal?: AbortSignal): Promise<PublicConfig>;
     /**
-     * Accepted tokens with live prices. `priceId` or `checkoutSessionId` adds
-     * each token's `quote`; `wallet` adds its `balance`.
+     * Accepted tokens with live prices. `priceId` adds each token's `quote`;
+     * `wallet` adds its `balance`.
      */
     listSolanaTokens(opts?: {
         priceId?: string;
-        checkoutSessionId?: string;
         wallet?: string;
         signal?: AbortSignal;
     }): Promise<SolanaToken[]>;

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

@@ -0,0 +1 @@
+export declare const OPENRAILS_CURRENCY_SCALES: Readonly<Record<string, number>>;

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

@@ -0,0 +1,7 @@
+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 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;
+    type: OpenRailsErrorType;
+    meaning: string;
+}>>;