moltspay 1.4.1 → 1.6.0

package/dist/client/web/index.d.mts

@@ -0,0 +1,418 @@
+import { PublicKey, Transaction } from '@solana/web3.js';
+
+interface TypedDataDomain {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: string;
+    salt?: string;
+}
+interface TypedDataField {
+    name: string;
+    type: string;
+}
+interface TypedDataEnvelope<TMessage = Record<string, unknown>> {
+    domain: TypedDataDomain;
+    types: Record<string, readonly TypedDataField[]>;
+    primaryType: string;
+    message: TMessage;
+}
+
+/**
+ * Chain identifier mapping — pure, runtime-agnostic.
+ *
+ * Translates between x402 `network` field values (CAIP-2 style, e.g.
+ * `eip155:8453`, `solana:mainnet`) and MoltsPay's internal chain names
+ * (e.g. `base`, `solana`, `tempo_moderato`).
+ */
+type ChainName = 'base' | 'polygon' | 'base_sepolia' | 'tempo_moderato' | 'bnb' | 'bnb_testnet' | 'solana' | 'solana_devnet';
+
+/**
+ * Structured error classes used by both Node and Web clients.
+ *
+ * Every error carries a `code` field so callers can branch on the kind
+ * without string-matching `.message`.
+ */
+declare class MoltsPayError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class UnsupportedChainError extends MoltsPayError {
+    readonly chain: string;
+    constructor(chain: string, message?: string);
+}
+interface NeedsApprovalDetails {
+    chain: string;
+    spender: string;
+    token: string;
+    currentAllowance: string;
+    required: string;
+}
+declare class NeedsApprovalError extends MoltsPayError {
+    readonly details: NeedsApprovalDetails;
+    constructor(details: NeedsApprovalDetails, message?: string);
+}
+declare class InsufficientBalanceError extends MoltsPayError {
+    constructor(message: string);
+}
+declare class SpendingLimitExceededError extends MoltsPayError {
+    constructor(message: string);
+}
+declare class PaymentRejectedError extends MoltsPayError {
+    constructor(message: string);
+}
+declare class ServerError extends MoltsPayError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+/**
+ * PaymentSigner — runtime-agnostic signing interface.
+ *
+ * Implemented by:
+ *   - `NodeSigner` (src/client/node/signer.ts)  → wraps an ethers.Wallet + optional Solana Keypair
+ *   - `eip1193Signer(provider)` (src/client/web/signers/eip1193.ts, Phase 4) → delegates to MetaMask / WalletConnect / etc.
+ *   - `solanaSigner(adapter)` (src/client/web/signers/solana-adapter.ts, Phase 4) → delegates to @solana/wallet-adapter
+ *   - `composeSigners(...)` (Phase 4) → routes per-method between multiple backing signers
+ *
+ * The interface is intentionally narrow:
+ *   - `signTypedData` covers every EIP-712 signing path (EIP-3009 on Base/Polygon, EIP-2612 on Tempo, BNB PaymentIntent).
+ *   - `sendEvmTransaction` covers BNB approve (and any future EVM writes). Optional because most signers only sign.
+ *   - `signSolanaTransaction` covers Solana SPL transfer signing. Optional because not every signer supports Solana.
+ *
+ * Deliberately excluded: Tempo MPP's `Actions.token.transfer` path (uses viem's Tempo chain extension with custom
+ * `feeToken` semantics that do not map cleanly through a generic signer). The MPP flow stays Node-only and uses
+ * viem directly; the Web client does not implement MPP.
+ */
+
+interface PaymentSigner {
+    /**
+     * Return the EVM address (0x-prefixed, checksummed or lowercase; callers should normalize as needed).
+     * Required for every EVM payment path (Base / Polygon / BNB).
+     */
+    getEvmAddress(): Promise<string>;
+    /**
+     * Return the Solana address (base58). Required only when paying on `solana` or `solana_devnet`.
+     * Implementations that don't support Solana should omit or return `null`.
+     */
+    getSolanaAddress?(): Promise<string | null>;
+    /**
+     * Sign an EIP-712 typed-data envelope. Used for:
+     *   - EIP-3009 TransferWithAuthorization (Base / Polygon / Base Sepolia)
+     *   - EIP-2612 Permit (Tempo Moderato)
+     *   - BNB MoltsPay PaymentIntent
+     *
+     * Returns a 0x-prefixed 65-byte (r||s||v) signature.
+     */
+    signTypedData<TMessage>(envelope: TypedDataEnvelope<TMessage>): Promise<string>;
+    /**
+     * Send a raw EVM transaction and return its hash. Used for the BNB `approve` flow only in the
+     * initial release; future versions may use it for other write paths.
+     *
+     * `chainId` allows the signer to switch chains (e.g. EIP-1193 `wallet_switchEthereumChain`).
+     * `value` is hex-encoded wei; omitted when zero.
+     *
+     * Optional — omit on signers that cannot submit transactions (e.g. a read-only Ledger).
+     */
+    sendEvmTransaction?(args: {
+        chainId: number;
+        to: string;
+        data: string;
+        value?: string;
+    }): Promise<string>;
+    /**
+     * Sign a Solana transaction without submitting it. Server submits.
+     *
+     * `transactionBase64` is the serialized unsigned transaction (produced by
+     * `createSolanaPaymentTransaction` in core/solana-tx.ts).
+     * `partialSign` is `true` when the server specified a `feePayer` and the wallet is only signing
+     * for token-transfer authority (gasless Solana mode); `false` means the wallet is paying fees too.
+     *
+     * Returns the serialized signed transaction as base64.
+     */
+    signSolanaTransaction?(args: {
+        transactionBase64: string;
+        partialSign: boolean;
+    }): Promise<string>;
+}
+
+interface ServiceInfo {
+    id: string;
+    name: string;
+    description?: string;
+    price: number;
+    currency: string;
+    input: Record<string, any>;
+    output: Record<string, any>;
+    available: boolean;
+    provider?: ProviderInfo;
+    endpoint?: string;
+}
+interface ProviderInfo {
+    name: string;
+    username?: string;
+    description?: string;
+    wallet: string;
+    chain?: string;
+    chains?: string[] | {
+        chain: string;
+    }[];
+}
+interface ServicesResponse {
+    provider?: ProviderInfo;
+    services: ServiceInfo[];
+}
+
+/**
+ * Browser-side spending limits — optional opt-in only. Mirrors the Node
+ * CLI's daily-reset ledger but persists to `localStorage` instead of
+ * `~/.moltspay/spending.json`.
+ *
+ * Default: disabled. Rationale (from docs/WEB-CLIENT-DESIGN.md §Spending
+ * Limits on Web): external wallets already enforce per-signature policy,
+ * per-browser localStorage limits don't sync, and the UX of silently
+ * blocking a payment without consulting the wallet is worse than just
+ * letting the wallet prompt. Apps that want session-level caps can still
+ * opt in.
+ */
+interface SpendingLimitsConfig {
+    /** Maximum per single transaction. Currency-agnostic; measured in service units (USD). */
+    maxPerTx: number;
+    /** Maximum aggregate across the current calendar day (local time). */
+    maxPerDay: number;
+    /** `localStorage` key. Default: `moltspay:spending`. */
+    storageKey?: string;
+}
+declare class SpendingLedger {
+    private readonly storageKey;
+    private readonly maxPerTx;
+    private readonly maxPerDay;
+    constructor(config: SpendingLimitsConfig);
+    /** Load the persisted total for today. Fails silently on parse errors. */
+    private read;
+    private write;
+    /**
+     * Throw `SpendingLimitExceededError` if the requested charge would push
+     * per-tx or per-day limits over. Does NOT mutate state — callers record
+     * only after the payment clears via {@link record}.
+     */
+    check(amount: number): void;
+    /** Persist a successful charge. Silently no-ops in non-browser runtimes. */
+    record(amount: number): void;
+    /** Current aggregate for the active day. Intended for UI display. */
+    get todaySpending(): number;
+    /** Manually reset — mainly useful for tests. */
+    reset(): void;
+}
+
+/**
+ * EIP-1193 signer adapter — wraps `window.ethereum`-style providers into the
+ * runtime-agnostic `PaymentSigner` interface.
+ *
+ * Works with any EIP-1193 provider: MetaMask, Coinbase Wallet, Rainbow,
+ * Frame, a WalletConnect transport, etc. The caller supplies the provider;
+ * this module never imports a specific wallet connector.
+ *
+ * Methods used:
+ *   - `eth_requestAccounts`         (getEvmAddress)
+ *   - `eth_signTypedData_v4`        (signTypedData)
+ *   - `wallet_switchEthereumChain`  (sendEvmTransaction pre-flight; EIP-3326)
+ *   - `wallet_addEthereumChain`     (fallback when target chain is unknown; EIP-3085)
+ *   - `eth_sendTransaction`         (sendEvmTransaction)
+ */
+
+/** Minimal EIP-1193 provider shape. */
+interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+}
+/**
+ * Chain metadata passed alongside `sendEvmTransaction` so the signer can add
+ * the chain to the wallet if it is not already known. Required for Tempo /
+ * BNB which MetaMask does not ship preconfigured.
+ *
+ * Keyed by decimal chainId. The signer consults this table only when
+ * `wallet_switchEthereumChain` returns the "unknown chain" error (code 4902).
+ */
+interface Eip1193ChainMetadata {
+    chainName: string;
+    rpcUrls: string[];
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    blockExplorerUrls?: string[];
+}
+interface Eip1193SignerOptions {
+    /** Optional chain registry for `wallet_addEthereumChain` fallbacks. */
+    addChainMetadata?: Record<number, Eip1193ChainMetadata>;
+}
+/**
+ * Build an EIP-1193-backed `PaymentSigner`.
+ *
+ * The returned signer is stateless — every method issues a fresh provider
+ * request so account changes (user switches wallet, locks, etc.) are picked
+ * up on the next call. The caller is free to wrap this in their own cache if
+ * account drift mid-session is a concern.
+ */
+declare function eip1193Signer(provider: Eip1193Provider, options?: Eip1193SignerOptions): PaymentSigner;
+
+/**
+ * Solana wallet-adapter signer — wraps a wallet adapter (Phantom, Solflare,
+ * Backpack, any `@solana/wallet-adapter` compatible object) into a
+ * `PaymentSigner`.
+ *
+ * We intentionally accept only the subset of the WalletAdapter interface we
+ * actually use (`publicKey` + `signTransaction`) so the caller doesn't have
+ * to pull in the full `@solana/wallet-adapter-base` type transitively.
+ *
+ * Behavior matches `NodeSigner.signSolanaTransaction`:
+ *  - The wallet signs the serialized transaction and returns it base64-encoded.
+ *  - We never submit — the server does, after the x402 payload lands.
+ *  - `partialSign: true` is passed through to the adapter so the server's fee
+ *    payer signature is preserved (gasless Solana mode).
+ */
+
+/** Minimal Solana wallet-adapter shape the signer needs. */
+interface SolanaSignerAdapter {
+    /** Connected account's public key, or `null` if disconnected. */
+    publicKey: PublicKey | null;
+    /**
+     * Signs a legacy Solana `Transaction` and returns the same transaction with
+     * signatures attached. Wallet adapters already implement this — we simply
+     * delegate. We do NOT use `signAllTransactions` or `signMessage`.
+     */
+    signTransaction(tx: Transaction): Promise<Transaction>;
+}
+/**
+ * Build a `PaymentSigner` backed by a Solana wallet adapter.
+ *
+ * The returned signer exposes only Solana capabilities — `getEvmAddress`
+ * throws, because the Web Client dispatches by chain and never asks a Solana
+ * signer to sign EVM data. To support both EVM and Solana in one client,
+ * compose this with `eip1193Signer` via `composeSigners`.
+ */
+declare function solanaSigner(adapter: SolanaSignerAdapter): PaymentSigner;
+
+/**
+ * `composeSigners` — merge multiple `PaymentSigner`s into one, routing each
+ * method to the first underlying signer that can service it.
+ *
+ * Typical use: a dApp wants to pay on both EVM chains (via MetaMask) and
+ * Solana (via Phantom) from the same `MoltsPayWebClient` instance. Rather
+ * than re-instantiating the client per chain, the app composes the two:
+ *
+ *     const client = new MoltsPayWebClient({
+ *       signer: composeSigners(
+ *         eip1193Signer(window.ethereum),
+ *         solanaSigner(phantomAdapter),
+ *       ),
+ *     });
+ *
+ * Routing rule: for each method (`getEvmAddress`, `signTypedData`,
+ * `sendEvmTransaction`, `getSolanaAddress`, `signSolanaTransaction`), pick
+ * the first signer in argument order whose method returns a successful
+ * result. "Successful" = the method is defined on the signer AND does not
+ * throw the sentinel `NOT_SUPPORTED` error the adapters emit for off-chain
+ * methods (`solanaSigner.getEvmAddress` throws plainly, and that throw is
+ * caught and tried on the next signer).
+ *
+ * Falls through to the last signer's error if none match, so callers still
+ * see an actionable message.
+ */
+
+declare function composeSigners(...signers: PaymentSigner[]): PaymentSigner;
+
+/**
+ * MoltsPay Web Client
+ *
+ * Browser-native companion to `MoltsPayClient` (Node). The two share one
+ * protocol core (`src/client/core/`) — every x402 detail, typed-data builder,
+ * and chain mapping is identical. The Web Client differs only in that:
+ *
+ *   - It never reads or writes a wallet file. All signing is delegated to an
+ *     injected `PaymentSigner` (an EIP-1193 / wallet-adapter shim the app owns).
+ *   - It always posts to `/execute` and consumes `X-Payment-Required`. It
+ *     never negotiates MPP over `WWW-Authenticate` — Tempo is reached via the
+ *     EIP-2612 permit branch instead. See docs/WEB-CLIENT-DESIGN.md §Tempo.
+ *   - Spending limits are opt-in and backed by `localStorage` when enabled.
+ */
+
+interface MoltsPayWebClientOptions {
+    /** PaymentSigner to authorize every payment. Typically `eip1193Signer(window.ethereum)` or `composeSigners(...)`. */
+    signer: PaymentSigner;
+    /** Default chain for `pay()` when the server accepts multiple and the caller omits `options.chain`. */
+    defaultChain?: ChainName;
+    /** Enable `localStorage`-backed spending limits. Off by default. */
+    spendingLimits?: SpendingLimitsConfig;
+    /** Optional fetch override — useful for MSW tests or proxying. Defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Per-chain Solana RPC URL override. Required on mainnet in practice —
+     * the public `api.mainnet-beta.solana.com` endpoint returns 403 to browser
+     * requests. Point at Helius / QuickNode / Alchemy etc. Falls back to
+     * `SOLANA_CHAINS[chain].rpc` when omitted.
+     */
+    solanaRpc?: {
+        solana?: string;
+        solana_devnet?: string;
+    };
+}
+interface WebPayOptions {
+    /** Chain to pay on. Required when the server accepts more than one. */
+    chain?: ChainName;
+    /** Send user params at top level (`{ service, ...params }`) instead of wrapped (`{ service, params }`). */
+    rawData?: boolean;
+}
+declare class MoltsPayWebClient {
+    private readonly signer;
+    private readonly defaultChain?;
+    private readonly ledger;
+    private readonly fetchImpl;
+    private readonly solanaRpc?;
+    constructor(options: MoltsPayWebClientOptions);
+    private getSolanaConnection;
+    /** Fetch a provider's service manifest. Mirrors `MoltsPayClient.getServices`. */
+    getServices(serverUrl: string): Promise<ServicesResponse>;
+    /**
+     * Pay for a service via x402. Returns the service `result` field (or the
+     * whole JSON body if the server doesn't wrap). Throws `NeedsApprovalError`
+     * for BNB when allowance is insufficient — call {@link approveBnb} and retry.
+     */
+    pay(serverUrl: string, service: string, params: Record<string, unknown>, options?: WebPayOptions): Promise<Record<string, unknown>>;
+    /** Read-only balance check on the specified chain (or `defaultChain` if configured). */
+    getBalance(chain?: ChainName): Promise<{
+        usdc: number;
+        usdt?: number;
+        native: number;
+    }>;
+    /**
+     * Approve a spender for the BNB chain's USDC / USDT (one-time, costs BNB gas).
+     * The spender address is what the server advertised as `bnbSpender` in the
+     * 402 response. Amount defaults to `MaxUint256` so only one approval is ever
+     * needed per (chain, token, spender) tuple.
+     */
+    approveBnb(args: {
+        chain: 'bnb' | 'bnb_testnet';
+        spender: string;
+        token: 'USDC' | 'USDT';
+        amount?: string;
+    }): Promise<string>;
+    private resolveExecuteUrl;
+    private buildRequestBody;
+    private chooseChain;
+    /**
+     * Submit the x402 payload and return the service result. Shared by all
+     * scheme branches — the only thing they vary is how they build `payload`.
+     */
+    private submitPayment;
+    private payEIP3009;
+    private payTempoPermit;
+    private payBnb;
+    private paySolana;
+}
+
+export { type ChainName, type Eip1193ChainMetadata, type Eip1193Provider, type Eip1193SignerOptions, InsufficientBalanceError, MoltsPayError, MoltsPayWebClient, type MoltsPayWebClientOptions, NeedsApprovalError, PaymentRejectedError, type PaymentSigner, ServerError, type SolanaSignerAdapter, SpendingLedger, SpendingLimitExceededError, type SpendingLimitsConfig, UnsupportedChainError, type WebPayOptions, composeSigners, eip1193Signer, solanaSigner };