@openrails/billing-ui 0.0.0-stage → 0.230.0

package/dist/account/subscriptions-panel.d.ts

@@ -0,0 +1,19 @@
+import { CheckoutAppearance } from '../appearance';
+import { SendSolanaTransaction } from '../client/client';
+import { Subscription } from '../client/types';
+import { SubscriptionsOptions } from '../react/hooks';
+import * as React from "react";
+export interface SubscriptionsPanelProps extends SubscriptionsOptions {
+    /**
+     * Wallet for Solana-rail subscriptions. Without it their cancel action is
+     * hidden.
+     */
+    sendSolanaTransaction?: SendSolanaTransaction;
+    /** Empty-state link to the host's plans page (uses `navigate` if set). */
+    plansHref?: string;
+    /** Host content under a row, e.g. a plan-change control. */
+    renderSubscriptionFooter?: (subscription: Subscription) => React.ReactNode;
+    appearance?: CheckoutAppearance;
+    className?: string;
+}
+export declare function SubscriptionsPanel({ sendSolanaTransaction, plansHref, renderSubscriptionFooter, appearance, className, ...options }: SubscriptionsPanelProps): React.JSX.Element;

package/dist/appearance.d.ts

@@ -0,0 +1,23 @@
+import { CSSProperties } from 'react';
+export type CheckoutTheme = "light" | "dark" | "auto" | "inherit";
+export interface CheckoutVariables {
+    background?: string;
+    foreground?: string;
+    card?: string;
+    mutedForeground?: string;
+    faintForeground?: string;
+    border?: string;
+    input?: string;
+    primary?: string;
+    primaryForeground?: string;
+    destructive?: string;
+    ring?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+export interface CheckoutAppearance {
+    theme?: CheckoutTheme;
+    variables?: CheckoutVariables;
+}
+export declare function appearanceStyle(appearance: CheckoutAppearance | undefined): CSSProperties | undefined;
+export declare function appearanceTheme(appearance: CheckoutAppearance | undefined): CheckoutTheme;

package/dist/authenticate.d.ts

@@ -0,0 +1,8 @@
+import { BillingClient } from './client/client';
+import { PspConfig } from './psp';
+/**
+ * Completes the provider challenge (3-D Secure) a pending payment operation
+ * waits on. "not_required" when the provider has none outstanding; the
+ * operation's own status remains the result.
+ */
+export declare function authenticatePayment(client: BillingClient, operationId: string, psp: PspConfig): Promise<"authenticated" | "not_required">;

package/dist/checkout-frame.d.ts

@@ -0,0 +1,17 @@
+import { CheckoutFrameTheme } from './frame';
+import { CheckoutSessionStatus } from './types';
+import * as React from "react";
+export interface CheckoutFrameProps {
+    /** The minted session's `url` (createCheckoutSession). */
+    url: string;
+    onComplete?: (status: CheckoutSessionStatus) => void;
+    /** Default "auto": the buyer's system preference. */
+    theme?: CheckoutFrameTheme;
+    /** Accessible name of the frame. */
+    title?: string;
+    /** Height before the page reports its own, in pixels. Default 480. */
+    minHeight?: number;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function CheckoutFrame({ url, onComplete, theme, title, minHeight, className, style, }: CheckoutFrameProps): React.JSX.Element | null;

package/dist/checkout-page.d.ts

@@ -0,0 +1,16 @@
+import { CheckoutAppearance } from './appearance';
+import { CheckoutLayout } from './checkout';
+import { BillingClient } from './client/client';
+import * as React from "react";
+export interface CheckoutPageProps {
+    /** OpenRails mount on this host. Default "/billing/v1". */
+    baseUrl?: string;
+    /** Replaces the client built from `baseUrl`. */
+    client?: BillingClient;
+    /** This host's branding; the framing app chooses the theme. */
+    appearance?: CheckoutAppearance;
+    layout?: CheckoutLayout;
+    defaultCountry?: string;
+    className?: string;
+}
+export declare function CheckoutPage({ baseUrl, client, appearance, layout, defaultCountry, className, }: CheckoutPageProps): React.JSX.Element;

package/dist/checkout.d.ts

@@ -0,0 +1,24 @@
+import { CheckoutAppearance } from './appearance';
+import { CheckoutSource } from './source';
+import { CheckoutPhase, PayResult } from './types';
+import * as React from "react";
+export type CheckoutLayout = "auto" | "wide" | "compact";
+export interface CheckoutProps {
+    source: CheckoutSource;
+    appearance?: CheckoutAppearance;
+    layout?: CheckoutLayout;
+    /** Billing country to preselect; default: the browser locale's region. */
+    defaultCountry?: string;
+    /** Return target after an off-page card verification (Stripe setup). */
+    cardSetupReturnURL?: (setupId: string) => string;
+    onComplete?: (result: PayResult) => void;
+    /**
+     * Leaves for a redirect rail's page. Default: navigate the top window,
+     * which a nested frame may not do; <CheckoutPage> asks its app instead.
+     */
+    onRedirect?: (url: string) => void;
+    onPhaseChange?: (phase: CheckoutPhase) => void;
+    completionMode?: "embedded" | "redirect";
+    className?: string;
+}
+export declare function Checkout({ source, appearance, layout, defaultCountry, cardSetupReturnURL, onComplete, onRedirect, onPhaseChange, completionMode, className, }: CheckoutProps): React.JSX.Element;

package/dist/client/client.d.ts

@@ -0,0 +1,167 @@
+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';
+export interface BillingClientOptions {
+    /** OpenRails embedded mount. Default "/billing/v1". */
+    baseUrl?: string;
+    /**
+     * Transport. Pass an authenticating fetch (auth-ui's `client.authFetch`)
+     * or combine the default with `getToken`.
+     */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /** Bearer for each request; omit when `fetch` authenticates. */
+    getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Sent as Accept-Language. */
+    language?: () => string | null | undefined;
+    /**
+     * Extra or overriding currency scales (code -> native-unit decimals). The
+     * pinned OpenRails registry is built in; `/me` amounts carry no scale.
+     */
+    currencies?: CurrencyScales;
+}
+export interface ListOptions {
+    limit?: number;
+    offset?: number;
+    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.
+ */
+export type SendSolanaTransaction = (transactionBase64: string) => Promise<string>;
+export declare class WalletRejectedError extends Error {
+    constructor(message?: string);
+}
+export declare const CANCEL_FEEDBACK_MIN = 4;
+export declare const CANCEL_FEEDBACK_MAX = 500;
+/** 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 & {
+        status?: string;
+    }): Promise<Page<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.
+     */
+    cancelSubscription(subscriptionId: string, input: {
+        feedback: string;
+    }): Promise<void>;
+    /** Queues the resumption (202). */
+    resumeSubscription(subscriptionId: string): Promise<void>;
+    setSubscriptionPaymentMethod(subscriptionId: string, paymentMethodId: string): Promise<void>;
+    /** What `changeTier` would charge now and at the next renewal. */
+    previewTierChange(subscriptionId: string, priceId: string, signal?: AbortSignal): Promise<TierChangePreview>;
+    /**
+     * 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.
+     */
+    changeTier(subscriptionId: string, input: {
+        priceId: string;
+        idempotencyKey: string;
+    }): Promise<TierChange>;
+    /**
+     * 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").
+     */
+    addPaymentMethod(card: NewCard): Promise<PaymentMethod>;
+    /**
+     * Starts an in-page card setup with a PSP whose browser SDK collects the
+     * card (see `cardSetupDriver`). `idempotencyKey` identifies this attempt.
+     */
+    createCardSetup(input: {
+        pspId: string;
+        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>;
+    /** 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 method the default collector for one currency's invoices. */
+    setDefaultPaymentMethod(input: {
+        currency: string;
+        paymentMethodId: string;
+    }): Promise<void>;
+    /** Charges and refunds, newest first. `rail` filters by rail. */
+    listPayments(opts?: ListOptions & {
+        rail?: string;
+    }): Promise<Page<Payment>>;
+    listInvoices(opts?: ListOptions): Promise<Page<Invoice>>;
+    getInvoice(invoiceId: string, signal?: AbortSignal): Promise<Invoice>;
+    getStatus(signal?: AbortSignal): Promise<BillingStatus>;
+    /** Active products with their active 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)}>`.
+     * `successUrl` brings the buyer back from a redirect rail; it must be on
+     * one of this app's return origins.
+     */
+    createCheckoutSession(input: {
+        priceKey?: string;
+        priceId?: string;
+        successUrl?: string;
+    }): Promise<HostedCheckoutLink>;
+    /**
+     * 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`.
+     */
+    checkoutSource(sessionId: string): CheckoutSource;
+    /** Network and accepted tokens; served only with a Solana PSP. */
+    getSolanaConfig(signal?: AbortSignal): Promise<SolanaConfig>;
+    /**
+     * Accepted tokens with live prices. `priceId` or `checkoutSessionId` adds
+     * each token's `quote`; `wallet` adds its `balance`.
+     */
+    listSolanaTokens(opts?: {
+        priceId?: string;
+        checkoutSessionId?: string;
+        wallet?: string;
+        signal?: AbortSignal;
+    }): Promise<SolanaToken[]>;
+    /** Currency code (upper case) to native-unit decimals. */
+    currencies: Readonly<Record<string, number>>;
+};
+export type BillingClient = ReturnType<typeof createBillingClient>;
+export declare const isWalletRejection: (error: unknown) => boolean;

package/dist/client/errors.d.ts

@@ -0,0 +1,26 @@
+export interface BillingErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    request_id?: string;
+    param?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class BillingError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly requestId?: string;
+    readonly metadata: Record<string, 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.
+ */
+export declare const isServerError: (value: unknown) => boolean;
+export declare function localError(code: string, message: string): BillingError;
+export declare function readBillingError(res: Response): Promise<BillingError>;
+export declare function toBillingError(error: unknown): BillingError;

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

@@ -0,0 +1,2 @@
+export type OpenRailsCustomerRoute = "GET /billing/v1/me/balance" | "POST /billing/v1/me/billing-portal" | "POST /billing/v1/me/checkout" | "POST /billing/v1/me/checkout/sessions" | "GET /billing/v1/me/checkout/{id}" | "POST /billing/v1/me/checkout/{id}/confirm" | "PUT /billing/v1/me/collection-payment-method" | "PUT /billing/v1/me/default-payment-method" | "GET /billing/v1/me/entitlements/active" | "GET /billing/v1/me/invoices" | "GET /billing/v1/me/invoices/{id}" | "POST /billing/v1/me/invoices/{id}/pay-now" | "GET /billing/v1/me/notifications" | "GET /billing/v1/me/notifications/unread-count" | "POST /billing/v1/me/notifications/{id}/read" | "GET /billing/v1/me/payment-methods" | "POST /billing/v1/me/payment-methods" | "POST /billing/v1/me/payment-methods/stripe-setup" | "GET /billing/v1/me/payment-methods/stripe-setup/{id}" | "POST /billing/v1/me/payment-methods/stripe-setup/{id}/confirm" | "DELETE /billing/v1/me/payment-methods/{id}" | "PUT /billing/v1/me/payment-methods/{id}" | "GET /billing/v1/me/payment-operations/{id}/authentication" | "POST /billing/v1/me/payment-operations/{id}/authentication/confirm" | "GET /billing/v1/me/payments" | "GET /billing/v1/me/products" | "GET /billing/v1/me/products/{product_id}/access" | "GET /billing/v1/me/spend-limits" | "GET /billing/v1/me/status" | "GET /billing/v1/me/subscriptions" | "GET /billing/v1/me/subscriptions/{id}" | "POST /billing/v1/me/subscriptions/{id}/cancel" | "POST /billing/v1/me/subscriptions/{id}/change-tier" | "POST /billing/v1/me/subscriptions/{id}/change-tier/preview" | "PUT /billing/v1/me/subscriptions/{id}/payment-method" | "GET /billing/v1/me/subscriptions/{id}/provider-cutover" | "POST /billing/v1/me/subscriptions/{id}/provider-cutover" | "POST /billing/v1/me/subscriptions/{id}/provider-cutover/preview" | "POST /billing/v1/me/subscriptions/{id}/resume" | "POST /billing/v1/me/subscriptions/{id}/retry-now" | "POST /billing/v1/me/subscriptions/{id}/solana-cancel" | "POST /billing/v1/me/subscriptions/{id}/solana-cancel-tx" | "POST /billing/v1/me/subscriptions/{id}/solana-tier-change" | "POST /billing/v1/me/subscriptions/{id}/solana-tier-change/confirm" | "GET /billing/v1/me/tier" | "GET /billing/v1/me/transactions" | "GET /billing/v1/me/usage";
+export declare const OPENRAILS_CURRENCY_SCALES: Readonly<Record<string, number>>;

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { CANCEL_FEEDBACK_MAX, CANCEL_FEEDBACK_MIN, createBillingClient, isWalletRejection, RETRY_BUDGET_MS, WalletRejectedError, type BillingClient, type BillingClientOptions, type ListOptions, type SendSolanaTransaction, type SolanaCancelStage, } from './client';
+export { BillingError, isBillingError, isServerError, readBillingError, toBillingError, type BillingErrorBody, } from './errors';
+export type { BillingStatus, CardSetup, CardSummary, Currency, CurrencyScales, HostedCheckoutLink, Invoice, NewCard, Page, Payment, PaymentAuthentication, PaymentMethod, PaymentOperation, PaymentRecovery, Price, Product, SolanaConfig, SolanaTierChange, SolanaTierChangeTx, SolanaToken, Subscription, SubscriptionPrice, SubscriptionProduct, SubscriptionStatus, TierChange, TierChangePreview, } from './types';
+export { amountToDecimal, formatAmount, type Amount } from '../lib/money';