@rio-pay/sdk 0.0.0-stage → 0.0.1-alpha.2

package/dist/components/payments-modal.d.ts

@@ -0,0 +1,245 @@
+import { type ReactNode } from "react";
+import { type Problem, type CheckoutCopy, type Stage } from "../lib/payments";
+import type { DecoratorItem, PayLine } from "../lib/payments-options";
+export declare const CSS: string;
+export declare const Spinner: ({ small }: {
+    small?: boolean;
+}) => import("react").JSX.Element;
+declare const CheckMark: ({ size }: {
+    size?: number;
+}) => import("react").JSX.Element;
+declare const CopyIcon: () => import("react").JSX.Element;
+export declare const Alert: () => import("react").JSX.Element;
+export declare const Info: () => import("react").JSX.Element;
+export { CheckMark, CopyIcon };
+/** The USDC mark, inline so it needs no request and no dependency. */
+export declare function UsdcLogo({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+export interface ChainBadge {
+    letter: string;
+    hue: number;
+    /** Official chain mark to draw instead of the letter (known chains only). */
+    icon?: "sei" | "base" | "solana" | null;
+}
+/** A plain inline mark for a token we ship no logo for: a coloured disc with its symbol's first letter (no request, no image). */
+export declare function TokenGlyph({ token, size }: {
+    token: {
+        symbol: string;
+        logo: string;
+    };
+    size?: number;
+}): import("react").JSX.Element;
+/** The token's mark (the USDC logo unless another token is given) with a small generated chain badge (a letter on a hue, no image) at its corner. */
+export declare function TokenMark({ size, badge, token }: {
+    size?: number;
+    badge?: ChainBadge | null;
+    token?: {
+        symbol: string;
+        logo: string;
+    } | null;
+}): import("react").JSX.Element;
+/** The token's symbol (USDC unless another token is given) with the chain name as a small subscript. The chain name is service data. */
+export declare function TokenLabel({ chain, symbol }: {
+    chain: string;
+    symbol?: string;
+}): import("react").JSX.Element;
+export interface ModalOption {
+    id: string;
+    chain: string;
+    /** The token this option spends when it is not USDC ("ETH"); with `logo` it picks the token mark. */
+    symbol?: string;
+    logo?: string;
+    badge?: ChainBadge | null;
+    balanceText: string | null;
+    disabled: boolean;
+    /** Short line under (or instead of) the balance: "Not enough", "Needs a different wallet", "Couldn't check". */
+    reason: string | null;
+    /** The balance is being read for the first time: show a skeleton. */
+    loading?: boolean;
+}
+export declare function OptionPicker({ options, selectedId, open, locked, label, amount, onOpenChange, onSelect, }: {
+    options: ModalOption[];
+    selectedId: string | null;
+    open: boolean;
+    locked: boolean;
+    label: string;
+    /** The read-only amount, shown on the right of the box. */
+    amount: ReactNode;
+    onOpenChange: (open: boolean) => void;
+    onSelect: (id: string) => void;
+}): import("react").JSX.Element;
+/**
+ * The chosen chain's balances (USDC, then gas), one line above the amount box. It cycles every ~2.5 s with a
+ * fade; hovering it, focusing into it or pressing its pause control holds it, and under prefers-reduced-motion
+ * the CSS shows both values side by side with nothing animating. A low-gas warning stays on screen instead of
+ * cycling away. Screen readers get one polite sentence, re-announced only when the chosen option changes.
+ */
+export declare function Decorator({ items, paused, lowGas, pauseLabel, optionKey, interval, }: {
+    items: DecoratorItem[];
+    paused: boolean;
+    lowGas: string;
+    pauseLabel: string;
+    optionKey?: string | null;
+    interval?: number;
+}): import("react").JSX.Element | null;
+export interface WalletChipInfo {
+    /** "MetaMask"; null when the wallet did not name itself. */
+    name: string | null;
+    /** Shortened address for the chip. */
+    short: string;
+    address: string;
+}
+export interface WalletActions {
+    onCopy: () => void;
+    onSwitch: () => void;
+    onDisconnect: () => void;
+}
+/** The connected wallet: a button that opens copy address / switch wallet / disconnect (inert while a payment is in flight). */
+export declare function WalletChip({ wallet, copy, actions, inert }: {
+    wallet: WalletChipInfo;
+    copy: CheckoutCopy;
+    actions: WalletActions | null;
+    inert: boolean;
+}): import("react").JSX.Element;
+export interface PickerWallet {
+    id: string;
+    name: string;
+    icon: string | null;
+    lastUsed: boolean;
+}
+/** The inline wallet chooser shown when several wallets are installed. */
+export declare function WalletList({ wallets, busyId, copy, onPick }: {
+    wallets: PickerWallet[];
+    busyId: string | null;
+    copy: CheckoutCopy;
+    onPick: (id: string) => void;
+}): import("react").JSX.Element;
+export declare function Stepper({ stages, copy, tx, walletName }: {
+    stages: Stage[];
+    copy: CheckoutCopy;
+    tx: {
+        i: number;
+        total: number;
+    } | null;
+    walletName?: string | null;
+}): import("react").JSX.Element;
+export declare function ProblemNotice({ problem, copy, noticeRef, children, }: {
+    problem: Problem;
+    copy: CheckoutCopy;
+    noticeRef?: React.RefObject<HTMLDivElement | null>;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function DoneView({ copy, amountText, receipt, finalizing, slot, returnHref, doneRef, onDone, }: {
+    copy: CheckoutCopy;
+    amountText: string;
+    receipt: string;
+    finalizing: boolean;
+    slot?: ReactNode;
+    returnHref: string | null;
+    doneRef?: React.RefObject<HTMLElement | null>;
+    onDone?: () => void;
+}): import("react").JSX.Element;
+/** Mirrors the real geometry (title row, label row, box, button) so nothing moves when the content arrives. */
+export declare function PayingSkeleton(): import("react").JSX.Element;
+/**
+ * A native modal <dialog>: browser-provided focus trap, Esc, inert background and top layer (so it also
+ * works inside a host's own dialog, whose transforms would break `position: fixed`). Closing plays a short
+ * exit (the dialog has none of its own) and keeps the content mounted until it ends.
+ */
+export declare function ModalShell({ open, onClose, onBackdrop, titleId, children, initialFocus, }: {
+    open: boolean;
+    onClose: () => void;
+    /** Backdrop click. Defaults to `onClose`; pass a no-op to make the backdrop inert (mid-payment). */
+    onBackdrop?: () => void;
+    titleId: string;
+    children: ReactNode;
+    initialFocus?: React.RefObject<HTMLElement | null>;
+}): import("react").JSX.Element;
+export declare function Header({ title, titleId, titleRef, closeLabel, onClose, back, }: {
+    title: string;
+    titleId: string;
+    titleRef?: React.RefObject<HTMLHeadingElement | null>;
+    closeLabel: string;
+    onClose: (() => void) | null;
+    back?: {
+        label: string;
+        onClick: () => void;
+    } | null;
+}): import("react").JSX.Element;
+export interface Cta {
+    label: string;
+    disabled: boolean;
+    /** A step is running: the button keeps its place and colour and shows a spinner. */
+    busy: boolean;
+    /** A spinner on a disabled (muted) button, e.g. while balances are being read. */
+    spinner?: boolean;
+    onClick: () => void;
+    ref?: React.RefObject<HTMLButtonElement | null>;
+}
+/** What the buyer pays in their own token, as a polite status (so a price change is announced, never silent). */
+export declare function PayLineView({ line, copy, onRetry }: {
+    line: PayLine;
+    copy: CheckoutCopy;
+    onRetry?: () => void;
+}): import("react").JSX.Element;
+export interface ModalCardProps {
+    copy: CheckoutCopy;
+    titleId: string;
+    titleRef?: React.RefObject<HTMLHeadingElement | null>;
+    /** Header text; defaults to `copy.title`. */
+    title?: string;
+    amountText: string;
+    /** "pick" = choose + connect + pay; "paying" = stepper; "done"; "manual" = pay another way; "wallets" = wallet chooser. */
+    phase: "loading" | "pick" | "paying" | "done" | "manual" | "wallets";
+    wallet?: WalletChipInfo | null;
+    walletActions?: WalletActions | null;
+    walletPicker?: {
+        wallets: PickerWallet[];
+        busyId: string | null;
+        onPick: (id: string) => void;
+    } | null;
+    onClose: (() => void) | null;
+    onBack?: (() => void) | null;
+    options: ModalOption[];
+    selectedId: string | null;
+    menuOpen: boolean;
+    onMenuChange: (open: boolean) => void;
+    onSelect: (id: string) => void;
+    decorator: DecoratorItem[];
+    /** "You pay 0.0004 ETH": what the buyer pays when the chosen option is another token. Absent for USDC options. */
+    payLine?: PayLine | null;
+    onPayLineRetry?: () => void;
+    /** Re-announce the decorator only when this changes (the chosen option). */
+    decoratorKey?: string | null;
+    /** Balances are being re-read in the background; the old numbers stay on screen. */
+    refreshing?: boolean;
+    cta: Cta | null;
+    message?: ReactNode;
+    notice?: ReactNode;
+    stages: Stage[] | null;
+    tx: {
+        i: number;
+        total: number;
+    } | null;
+    /** The connected wallet's name, for "Confirm in {wallet}". */
+    walletName?: string | null;
+    /** One calm line shown in stage 3 only (derived from the service's estimate). */
+    slow: boolean;
+    /** Asks before closing mid-payment; the card shows it inline. */
+    closeGuard?: {
+        onStay: () => void;
+        onClose: () => void;
+    } | null;
+    done: {
+        receipt: string;
+        finalizing: boolean;
+        slot?: ReactNode;
+        returnHref: string | null;
+        ref?: React.RefObject<HTMLElement | null>;
+        onDone?: () => void;
+    } | null;
+    manual?: ReactNode;
+    onPayAnotherWay: (() => void) | null;
+}
+export declare function ModalCard(p: ModalCardProps): import("react").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ChargeCreateResult, ChargeStatus, Confirmation, CreatedCharge, CheckoutCopy, PlatformChargeStatus, } from "./lib/payments";
+export type { PostCreateChargeOptions } from "./lib/create-charge";
+export type { WebhookEvent, WebhookEventType } from "./lib/events";

package/dist/lib/create-charge.d.ts

@@ -0,0 +1,28 @@
+import type { ChargeCreateResult } from "./payments";
+export interface PostCreateChargeOptions {
+    /** Default `"POST"`. */
+    method?: "POST" | "PUT" | "PATCH";
+    /** Merged over the default `content-type: application/json`. A function is called on every request, so it can read a token at call time. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Passed to `fetch` as is; when omitted, `fetch`'s own default applies. */
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    /** A custom `fetch`. Default: the global `fetch`, looked up at call time. */
+    fetch?: typeof fetch;
+    /** Picks the charge out of a success body. Default: the body itself (the flat charge). */
+    selectCharge?: (json: unknown) => unknown;
+    /** Reads the error text and code out of a failure body. Default: the top-level `error` and `code` strings. */
+    selectError?: (json: unknown) => {
+        error?: string;
+        code?: string;
+    } | null | undefined;
+}
+/**
+ * POSTs `body` (JSON-stringified unless it is already a string) to your route and resolves a `ChargeCreateResult`.
+ *
+ * Your route answers a success (2xx) with the created charge as JSON (flat by default; see `selectCharge`) and a failure
+ * with an error status and `{ error, code? }` (see `selectError`). A 409 means the order already has a different charge
+ * (for example its amount changed): create a new order id. A 2xx without an object charge, a non-JSON body, a network
+ * error or an abort resolve to status 503.
+ */
+export declare function postCreateCharge(url: string, body: unknown, options?: PostCreateChargeOptions): Promise<ChargeCreateResult>;

package/dist/lib/events.d.ts

@@ -0,0 +1,10 @@
+export type WebhookEventType = "charge.confirmed" | "charge.confirmation_revoked" | "charge.funded" | "charge.settled" | "charge.underpaid" | "charge.expired" | "merchant.claimed" | "merchant.activated" | "subscription.created" | "subscription.activated" | "subscription.renewed" | "subscription.past_due" | "subscription.expired" | "subscription.canceled" | "subscription.reminder_due" | "ping";
+export interface WebhookEvent<T = unknown> {
+    /** Unique per event; delivery is at-least-once, so dedupe on it. */
+    id: string;
+    /** A `WebhookEventType`, or a type this SDK version does not know yet (the service may add types; handle unknown ones by ignoring them). */
+    type: WebhookEventType | (string & {});
+    /** ISO 8601 timestamp. */
+    created: string;
+    data: T;
+}

package/dist/lib/payments-client.d.ts

@@ -0,0 +1,48 @@
+import { type SseFrame } from "./payments-sse";
+export declare class VendorApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface RetryOptions {
+    /** Extra attempts after the first. */
+    retries?: number;
+    baseMs?: number;
+}
+/** Transient = nothing reached the service (status 0), a timeout, rate limiting or a 5xx. Everything else is deterministic. */
+export declare function isTransient(e: unknown, opts?: {
+    retryRateLimit?: boolean;
+}): boolean;
+/** Exponential backoff with jitter. Only for calls that are idempotent (every call this client makes is). */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions & {
+    retryRateLimit?: boolean;
+}): Promise<T>;
+export declare function vendorApi(serviceUrl: string, chargeId: string, secret: string, retry?: RetryOptions): {
+    charge: <T>() => Promise<T>;
+    /** GET /events: reads the charge's event stream with fetch (the secret stays in the header). Resolves when the stream ends or `signal` aborts; rejects when it cannot be opened or breaks. */
+    events: (onFrame: (f: SseFrame) => void, signal?: AbortSignal) => Promise<void>;
+    /** GET /options: the USDC options the buyer can pay with. */
+    options: () => Promise<unknown>;
+    /** POST /pay: what the buyer's wallet must sign or send for `optionId`. The response never carries fee or quote details. */
+    pay: (optionId: string, buyer: string) => Promise<unknown>;
+    authorize: (body: unknown) => Promise<unknown>;
+    /** POST /rails/cctp/submit: the service checks the buyer-signed Solana transaction, pays its fee and sends it. Returns `{ signature }`. Safe to retry. */
+    submitSolana: (transaction: string) => Promise<unknown>;
+    /** Reports a payment the buyer just sent so the service can follow it. `buyer` binds the hint to the paying wallet (LI.FI). */
+    fundingAttempt: (sourceChain: string, txHash: string, opts?: {
+        rail?: string;
+        buyer?: string;
+    }) => Promise<unknown>;
+    /**
+     * GET /rails/lifi/quote: what it takes to pay with another token, priced and already validated by the service
+     * (the browser is never handed unvalidated transaction data). Not retried: a quote is cheap to ask again and goes stale.
+     */
+    lifiQuote: (optionId: string, buyer: string) => Promise<unknown>;
+};
+/**
+ * Read-only JSON-RPC against a list of public endpoints (an option's `rpc_urls`): tries each in
+ * order and throws the last failure. Used for balances only; never carries a secret.
+ */
+export declare function jsonRpc(urls: string[], method: string, params: unknown[], opts?: {
+    timeoutMs?: number;
+}): Promise<unknown>;

package/dist/lib/payments-options.d.ts

@@ -0,0 +1,225 @@
+import { type AddChainParams, type CreatedCharge, type CheckoutCopy } from "./payments";
+export type OptionKind = "evm" | "solana";
+export interface PaymentOption {
+    id: string;
+    kind: OptionKind;
+    /** `lifi` = "pay with another token": the buyer's source token on a source chain, priced by a quote shown before paying. Absent for the USDC options. */
+    rail?: "lifi";
+    chain: {
+        id: number | string;
+        name: string;
+        display_name: string | null;
+    };
+    /** The token this option spends. For USDC options that is USDC; for `lifi` options any supported token (`native` = the chain's gas token, address 0x0). */
+    token: {
+        symbol: string;
+        address: string;
+        decimals: number;
+        logo: string;
+        native?: boolean;
+    };
+    native: {
+        symbol: string;
+        decimals: number;
+    } | null;
+    default: boolean;
+    route: "direct" | "bridge";
+    /** The service pays the network fee for this option, so the buyer needs no gas. */
+    gasless?: true;
+    add_chain: AddChainParams | null;
+    rpc_urls: string[];
+}
+/** GET /options body (`{ data: [...] }`) or a bare array; malformed entries are dropped, order is kept. */
+export declare function parseOptions(raw: unknown): PaymentOption[];
+/** The chain name shown on the token chip: service data, never hardcoded. */
+export declare function optionLabel(o: PaymentOption): string;
+/** The settlement chain's direct option, synthesised from the created charge: what "pay another way" shows when /options is unavailable. */
+export declare function settlementOption(created: Pick<CreatedCharge, "chain">): PaymentOption;
+/**
+ * The option "pay another way" shows the charge address on (a plain transfer, e.g. an exchange withdrawal): the settlement
+ * chain's USDC option, or one built from the charge when the options could not be loaded, so the address always carries its
+ * chain name.
+ */
+export declare const manualOption: (created: Pick<CreatedCharge, "chain">, options: PaymentOption[]) => PaymentOption;
+/** Direct EVM pays and gasless options are a signature only (the service pays); everything else spends the buyer's own gas. */
+export declare function needsGas(o: PaymentOption): boolean;
+export type OptionBalance = {
+    status: "loading";
+} | {
+    status: "ok";
+    usdc: bigint;
+    native: bigint | null;
+} | {
+    status: "error";
+};
+export type Balances = Record<string, OptionBalance | undefined>;
+/** "19.60", "0.1234", "1,234.00": at least 2 and at most 4 decimals, truncated (never rounded up). */
+export declare function formatTokenAmount(raw: bigint, decimals: number): string;
+export declare const isLifi: (o: Pick<PaymentOption, "rail">) => boolean;
+/**
+ * Whether a known balance can pay. USDC options need the whole amount. A LI.FI option's price in its own token is only known
+ * after a quote, so a balance only has to be non-zero here; the quote (quoteAffordability) makes the exact call.
+ */
+export declare function hasEnough(o: PaymentOption, bal: Extract<OptionBalance, {
+    status: "ok";
+}>, amount: string): boolean;
+export interface RowState {
+    balanceText: string | null;
+    disabled: boolean;
+    /** Why the row says what it says: short on USDC, a different wallet kind is needed, or the read failed. */
+    reason: "not_enough" | "needs_wallet" | "unreadable" | null;
+    /** The balance is being read for the first time: the row shows a skeleton. */
+    loading: boolean;
+}
+/**
+ * What one dropdown row shows: the balance once known; disabled only when it is known to be short.
+ * With `connected`, a row whose wallet kind is not connected (while the other kind is) says so instead of staying blank.
+ */
+export declare function rowState(o: PaymentOption, bal: OptionBalance | undefined, amount: string, connected?: Record<OptionKind, boolean>): RowState;
+/**
+ * Display order for the dropdown: options the buyer can pay with (largest balance first, settlement option
+ * first on a tie), then options we cannot judge (other wallet kind, unreadable), then short ones. Every option
+ * stays listed. While any connected option is still being read the service order is kept, so rows never
+ * jump around mid-load.
+ */
+export declare function sortOptions(options: PaymentOption[], balances: Balances, connected: Record<OptionKind, boolean>, amount: string): PaymentOption[];
+/**
+ * The rows the dropdown lists: nothing until a wallet is connected (the chip just says USDC), then only the connected
+ * wallet's options that hold something. A balance below the amount still counts (the row shows it, disabled). Options
+ * still being read or that could not be read stay, since a zero is not known; every other zero drops out.
+ */
+export declare function visibleOptions(options: PaymentOption[], balances: Balances, connected: Record<OptionKind, boolean>): PaymentOption[];
+/**
+ * A small generated chain mark for every option (no images): a letter from the chain's label and one of six hues.
+ * Hues come from a hash of the label and are probed so the options in one list never share one (up to six).
+ */
+export declare function chainBadges(labels: string[]): {
+    letter: string;
+    hue: number;
+}[];
+/**
+ * Best option to pre-select: sufficient balance first (settlement option preferred, then the largest balance).
+ * Options whose balance could not be read stay eligible as a last resort so a flaky endpoint is never a dead end.
+ */
+export declare function pickBestOption(options: PaymentOption[], balances: Balances, amount: string): string | null;
+export interface DecoratorItem {
+    label: string;
+    value: string;
+    /** Gentle "low gas" flag; only ever set where the option spends the buyer's own gas. */
+    warn: boolean;
+}
+export type GasState = "na" | "ok" | "low" | "none";
+/**
+ * Whether the buyer can cover gas for this option. `none` (a known zero) blocks paying; `low` only warns;
+ * `na` = the option spends no gas of the buyer's or the balance is unknown.
+ */
+export declare function gasState(o: PaymentOption, bal: OptionBalance | undefined): GasState;
+/** The balances the decorator row cycles through, each shown as a plain "amount SYMBOL" (e.g. "19.60 USDC", then "4.31 SEI"). `label` is only a stable key. */
+export declare function decoratorItems(o: PaymentOption, bal: OptionBalance | undefined, copy: CheckoutCopy): DecoratorItem[];
+export type BalanceSummary = "idle" | "loading" | "empty" | "short" | "ok";
+/**
+ * How the connected wallet(s) look overall, for the calm message under the amount:
+ * `empty` = every readable option is at zero, `short` = some USDC but not enough anywhere.
+ * An option whose balance could not be read never counts against the buyer.
+ */
+export declare function summarizeBalances(options: PaymentOption[], balances: Balances, connected: Record<OptionKind, boolean>, amount: string): BalanceSummary;
+export interface PrimaryAction {
+    /** `connect` opens the wallet for the option's kind; `pay` starts the payment. */
+    kind: "connect" | "pay";
+    disabled: boolean;
+    /** Why a `pay` is disabled; the button says it instead of "Pay". `unavailable`: the price for another token could not be had. */
+    reason: "checking" | "not_enough" | "needs_gas" | "unavailable" | null;
+}
+/** What the single primary button does for the chosen option. `lifi` is the price state of a "pay with another token" option. */
+export declare function primaryAction(option: PaymentOption | null, connected: Record<OptionKind, boolean>, balance: OptionBalance | undefined, amount: string, lifi?: LifiQuoteState): PrimaryAction;
+/** A priced, validated payment for one "other token" option, as the service returned it (GET /rails/lifi/quote). */
+export interface LifiQuote {
+    optionId: string;
+    /** What leaves the buyer's wallet in the source token (for the gas token: the transaction value). */
+    pay: {
+        amount: bigint;
+        symbol: string;
+        decimals: number;
+    };
+    /** Approval(s) first, then the payment: the same shape every EVM pay plan uses. */
+    txs: {
+        description: string;
+        to: string;
+        data: string;
+        value: string;
+    }[];
+    chainName: string | null;
+    addChain: AddChainParams | null;
+    estimatedSeconds: number | null;
+    /** Epoch ms after which the service no longer stands behind the transactions. */
+    expiresAt: number;
+    /** Source-chain gas the route is expected to use, native base units. */
+    gasEstimate: bigint | null;
+}
+export type LifiQuoteState = {
+    status: "idle";
+} | {
+    status: "loading";
+    previous: LifiQuote | null;
+} | {
+    status: "ready";
+    quote: LifiQuote;
+} | {
+    status: "unavailable";
+};
+/** Validates a service quote; throws on anything the widget cannot act on or could not show truthfully. */
+export declare function parseLifiQuote(raw: unknown): LifiQuote;
+export type LifiQuoteEvent = {
+    type: "reset";
+} | {
+    type: "fetch";
+} | {
+    type: "ok";
+    quote: LifiQuote;
+    optionId?: string;
+} | {
+    type: "fail";
+};
+/**
+ * The price state of the chosen "other token" option. A refresh keeps the old price on screen (marked as updating) until the
+ * new one lands; a failure drops the price entirely, so a stale one can never be paid. `ok` for another option is ignored.
+ */
+export declare function lifiQuoteReducer(state: LifiQuoteState, ev: LifiQuoteEvent): LifiQuoteState;
+/** A quote may be paid only while the service still stands behind it, with a margin for the wallet prompts. */
+export declare function quoteStillGood(q: {
+    expiresAt: number;
+}, nowMs: number): boolean;
+/** A fresh price that is dearer than the one the buyer was shown must be shown again before anything is signed. */
+export declare function priceWentUp(shown: LifiQuote | null, fresh: LifiQuote): boolean;
+/** The wait before refreshing a quote: 15 s before it expires, never sooner than a second. */
+export declare function quoteRefreshDelayMs(q: {
+    expiresAt: number;
+}, nowMs: number): number;
+/**
+ * An amount in the token's own units at a readable precision: up to 4 digits after the leading zeros (more for a small value,
+ * fewer for a big one), grouped thousands. `up` (what the buyer pays) never understates; `down` (what they hold) never overstates.
+ */
+export declare function formatPayAmount(raw: bigint, decimals: number, round?: "up" | "down"): string;
+export type Affordability = "ok" | "not_enough" | "needs_gas";
+/**
+ * Whether the connected wallet can afford a quote: the token amount, and gas in the SOURCE chain's native token. For the gas token
+ * itself the payment and the gas come out of one balance. An unreadable or unknown balance never blocks (the wallet will say if short).
+ */
+export declare function quoteAffordability(o: PaymentOption, bal: OptionBalance | undefined, q: {
+    pay: LifiQuote["pay"];
+    gasEstimate: bigint | null;
+}): Affordability;
+export interface PayLine {
+    kind: "loading" | "refreshing" | "ready" | "unavailable";
+    /** "You pay 0.0004018 ETH", or the calm status. */
+    text: string;
+    /** "Usually takes about 18 min". */
+    eta: string | null;
+    /** Shown while the old price is on screen and a new one is coming. */
+    note?: string;
+}
+/** The line that tells the buyer what they pay in their own token. Absent for every other option. */
+export declare function lifiPayLine(o: PaymentOption, state: LifiQuoteState, copy: CheckoutCopy): PayLine | null;
+export type ChainIconKey = "sei" | "base" | "solana";
+/** Which official chain mark an option gets, from its (service-provided) chain id. Unknown chains fall back to the letter badge. */
+export declare function chainIconKey(o: Pick<PaymentOption, "kind" | "chain">): ChainIconKey | null;

package/dist/lib/payments-pay.d.ts

@@ -0,0 +1,82 @@
+import { type AddChainParams, type PayStep, type CheckoutCopy, type TypedDataPayload } from "./payments";
+import { type LifiQuote, type PaymentOption } from "./payments-options";
+import { type Eip1193Provider } from "./payments-wallet";
+import { type SolanaSession } from "./payments-solana";
+export type PaySession = {
+    kind: "evm";
+    provider: Eip1193Provider;
+    account: string;
+} | {
+    kind: "solana";
+    session: SolanaSession;
+    account: string;
+};
+export interface PayApi {
+    /** For a "pay with another token" option this is the already-priced quote the buyer was shown (see the checkout), not POST /pay. */
+    pay(optionId: string, buyer: string): Promise<unknown>;
+    authorize(body: unknown): Promise<unknown>;
+    /** Hands a buyer-signed Solana transaction to the service, which pays the fee and sends it. */
+    submitSolana(transaction: string): Promise<unknown>;
+    /** `opts.rail`/`opts.buyer` name the rail and the paying wallet for rails that bind the hint to the buyer (LI.FI). */
+    fundingAttempt(sourceChain: string, txHash: string, opts?: {
+        rail?: string;
+        buyer?: string;
+    }): Promise<unknown>;
+}
+export interface PayHooks {
+    step(step: Exclude<PayStep, "idle" | "processing" | "paid">): void;
+    /** Wallet prompt `i` (0-based) of `total` transactions. */
+    tx?(i: number, total: number): void;
+}
+export type PayPlan = 
+/** `extra`: fields the service wants back with the signature (a gasless bridge payment: which chain, the nonce's salt). */
+{
+    type: "sign";
+    typedData: TypedDataPayload;
+    extra: Record<string, string>;
+} | {
+    type: "evm";
+    txs: {
+        description: string;
+        to: string;
+        data: string;
+        value: string;
+    }[];
+    chainName: string | null;
+    addChain: AddChainParams | null;
+    estimatedSeconds: number | null;
+    /** Present for another-token quotes: what the buyer pays in their own token. */
+    pay: LifiQuote["pay"] | null;
+    gasEstimate: bigint | null;
+}
+/** `sponsored`: the wallet only signs; the service pays the fee and sends it. */
+ | {
+    type: "solana";
+    transaction: string;
+    sponsored: boolean;
+    estimatedSeconds: number | null;
+};
+/** The quote the buyer was shown, in the response shape `parsePayPlan` reads: paying it is the same code path as every other EVM plan. */
+export declare function quotePlanInput(q: LifiQuote): unknown;
+/** Validates a POST /pay response; throws on anything the widget cannot act on. */
+export declare function parsePayPlan(raw: unknown): PayPlan;
+type PayArgs = {
+    option: PaymentOption;
+    session: PaySession;
+    amount: string;
+    api: PayApi;
+    hooks: PayHooks;
+    copy: CheckoutCopy;
+    signal?: AbortSignal;
+    intervalMs?: number;
+    /** How long to follow a sent payment on chain before leaving it to the charge's status (defaults per chain). */
+    timeoutMs?: number;
+};
+/**
+ * Resolves once the payment is on its way. When the service says another payment of this charge already is (an earlier
+ * try, another tab), it resolves the same way: the buyer waits for that one instead of paying twice.
+ */
+export declare function executePayment(args: PayArgs): Promise<{
+    estimatedSeconds: number | null;
+}>;
+export {};