moltspay 2.0.0 → 2.4.0

package/dist/client/index.d.mts

@@ -17,6 +17,12 @@ interface ClientConfig {
      * accepts wins. e.g. `["base", "alipay"]`.
      */
     railPreference?: string[];
+    /**
+     * Buyer identity for the custodial balance rail (2.2.0). When set and the
+     * server's 402 offers `balance`, the client can pay password-free by
+     * carrying this id in the X-Payment payload. Treat it like a bearer token.
+     */
+    buyerId?: string;
 }
 interface WalletData {
     address: string;
@@ -75,6 +81,128 @@ interface MoltsPayClientOptions {
     alipaySessionId?: string;
 }
 
+interface X402PaymentRequirements {
+    scheme: string;
+    network: string;
+    amount?: string;
+    asset?: string;
+    payTo?: string;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+    maxAmountRequired?: string;
+    resource?: string;
+    description?: string;
+}
+
+/**
+ * WechatClient — buyer-side completion for the WeChat Pay Native rail (2.1.0).
+ *
+ * Mirrors {@link AlipayClient} so paying via WeChat looks the same as awaiting
+ * an EVM settle. The flow is simpler than Alipay's: the SERVER already placed
+ * the Native order when it built the 402, so its `wechatpay-native` accepts[]
+ * entry carries `extra.code_url` + `extra.out_trade_no`. There is no buyer-side
+ * CLI/wallet and no order creation here — a human scans the code_url with the
+ * WeChat app, and the client polls the resource endpoint, re-submitting the
+ * `out_trade_no` as the x402 payment proof until the server verifies the order
+ * as paid (`trade_state === SUCCESS`) and delivers the resource.
+ *
+ *   1. surface code_url + out_trade_no to the caller (onPaymentPending → QR)
+ *   2. poll POST <resource> with X-Payment{out_trade_no} every pollIntervalMs
+ *      - 200            → paid, return the resource body
+ *      - 402            → not yet paid, keep polling
+ *      - other          → terminal error
+ *   3. give up after timeoutMs
+ */
+
+interface WechatPendingInfo {
+    /** `weixin://wxpay/bizpayurl?pr=...` — render as a QR for the payer to scan. */
+    codeUrl: string;
+    /** Merchant order id; the proof echoed back to the server on each poll. */
+    outTradeNo: string;
+}
+type WechatSessionStatus = 'pending' | 'paid' | 'completed' | 'expired' | 'cancelled' | 'failed';
+interface WechatPaymentSession {
+    paymentSessionId: string;
+    status: WechatSessionStatus;
+    resourceUrl: string;
+    method: 'GET' | 'POST';
+    data?: string;
+    requirement: X402PaymentRequirements;
+    codeUrl: string;
+    outTradeNo: string;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+    context?: Record<string, unknown>;
+    lastHttpStatus?: number;
+    lastError?: string;
+    resultBody?: string;
+}
+interface WechatPayOptions {
+    /** Resource/execute URL to re-POST the proof to (same one that issued the 402). */
+    resourceUrl: string;
+    /** The server's `wechatpay-native` accepts[] entry (carries extra.code_url/out_trade_no). */
+    requirement: X402PaymentRequirements;
+    /** HTTP method of the original resource request (default POST). */
+    method?: 'GET' | 'POST';
+    /** Raw JSON body to replay on each poll (the `{ service, params }` payload). */
+    data?: string;
+    /** Surface the QR code_url + out_trade_no to the UI/caller (called once). */
+    onPaymentPending?: (info: WechatPendingInfo) => void;
+    /** Poll cadence in ms (default 3000). */
+    pollIntervalMs?: number;
+    /** Overall budget in ms (default 300000). */
+    timeoutMs?: number;
+    /** Cancellation. */
+    signal?: AbortSignal;
+}
+interface WechatStartOptions extends WechatPayOptions {
+    /** Optional channel/service metadata persisted with the session for recovery. */
+    context?: Record<string, unknown>;
+    /** Stable session id, mostly for tests/integration. Defaults to `mpay_sess_${uuid}`. */
+    paymentSessionId?: string;
+}
+interface WechatPaymentResult {
+    /** Raw resource body returned by the server on success (HTTP 200). */
+    body: string;
+    status: number;
+}
+interface WechatClientOptions {
+    /** Config directory; sessions are stored under `<configDir>/wechat-sessions`. */
+    configDir?: string;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+declare class WechatClient {
+    private readonly configDir;
+    private readonly sessionDir;
+    private readonly now;
+    constructor(options?: WechatClientOptions);
+    pay402(opts: WechatPayOptions): Promise<WechatPaymentResult>;
+    /**
+     * Start a recoverable WeChat payment session. This returns immediately after
+     * persisting `out_trade_no`, QR payload, original request body, and context.
+     */
+    start402(opts: WechatStartOptions): WechatPaymentSession;
+    /**
+     * Query a persisted session once by replaying the original request with the
+     * stored `out_trade_no` proof. 200 means paid + fulfilled; 402 means pending.
+     */
+    status(identifier: string): Promise<WechatPaymentSession>;
+    /** Poll a session until it completes, expires, fails, or is aborted. */
+    pollSession(identifier: string, opts?: Pick<WechatPayOptions, 'pollIntervalMs' | 'timeoutMs' | 'signal'>): Promise<WechatPaymentSession>;
+    /** `fulfill` is an idempotent status check: paid sessions return stored body. */
+    fulfill(identifier: string): Promise<WechatPaymentSession>;
+    /** Mark a local session cancelled. Closing the merchant order is server-side. */
+    cancel(identifier: string): WechatPaymentSession;
+    listSessions(): WechatPaymentSession[];
+    private buildPaymentHeader;
+    private loadSession;
+    private saveSession;
+    private updateSession;
+    private ensureSessionDir;
+}
+
 /**
  * MoltsPay Client - Pay for AI Agent services
  *
@@ -86,6 +214,20 @@ interface MoltsPayClientOptions {
  *   const result = await client.pay('http://provider:3000', 'text-to-video', { prompt: '...' });
  */
 
+/** A recoverable balance top-up session, persisted under `<configDir>/balance-topup-sessions`. */
+interface BalanceTopupSession {
+    out_trade_no: string;
+    buyer_id: string;
+    pack: string;
+    server_url: string;
+    code_url: string;
+    status: 'pending' | 'credited' | 'expired';
+    created_at: string;
+    expires_at: string;
+    context?: Record<string, any>;
+    tx_id?: string;
+    balance?: string;
+}
 interface PayOptions {
     /** Token to pay with (default: USDC, or auto-select based on balance) */
     token?: TokenSymbol;
@@ -101,6 +243,11 @@ interface PayOptions {
      * alipay-bot-backed {@link AlipayClient} and needs no EVM wallet.
      */
     rail?: string;
+    /**
+     * Balance rail (2.2.0): buyer identity for password-free payment.
+     * Falls back to the persisted `config.buyerId`. Bearer semantics.
+     */
+    buyerId?: string;
     /** Alipay: surfaced once the payment URL + tradeNo are known. */
     onPaymentPending?: (info: {
         paymentUrl: string;
@@ -113,6 +260,39 @@ interface PayOptions {
     timeoutMs?: number;
     /** Cancellation (alipay poll loop). */
     signal?: AbortSignal;
+    /**
+     * WeChat: after `startWechatPayment()`, let the SDK client poll in the
+     * background and invoke the callbacks below. `pay --rail wechat` always polls
+     * because it is the blocking terminal wrapper.
+     */
+    autoPoll?: boolean;
+    /** WeChat: called when the background poll fulfills the resource. */
+    onWechatPaymentCompleted?: (session: WechatPaymentSession) => void | Promise<void>;
+    /** WeChat: called when background poll expires, fails, or is cancelled. */
+    onWechatPaymentFailed?: (session: WechatPaymentSession) => void | Promise<void>;
+    /**
+     * Balance rail (2.3.0): when a password-free deduct finds an insufficient
+     * balance, auto-fund via a WeChat top-up pack, then retry once. Default true.
+     * Set false to fail fast instead.
+     */
+    autoTopup?: boolean;
+    /**
+     * Balance rail top-up mode (2.5.0). `'auto'` (default): block through the
+     * top-up scan + retry (terminal use). `'manual'`: on an insufficient
+     * balance, create the order, surface the QR via `onTopupRequired`, and
+     * return a `{ status: 'topup_required', out_trade_no, code_url, pack,
+     * server_url }` result WITHOUT polling — the caller confirms + retries in
+     * later turns (recoverable flow for turn-based agents).
+     */
+    topupMode?: 'auto' | 'manual';
+    /** Balance rail: pack to fund with; defaults to the server's `default_pack`. */
+    topupPack?: string;
+    /** Balance rail: poll interval while waiting for the top-up scan (default 2000ms). */
+    topupPollIntervalMs?: number;
+    /** Balance rail: called when a top-up pack QR must be shown (scan once). */
+    onTopupRequired?: (pack: string, codeUrl: string) => void;
+    /** Balance rail: called after the top-up is credited (new balance). */
+    onTopupCredited?: (balance: string) => void;
 }
 declare class MoltsPayClient {
     private configDir;
@@ -171,6 +351,132 @@ declare class MoltsPayClient {
      * resource body.
      */
     private payViaAlipay;
+    /**
+     * Pay for a service over the WeChat Pay Native fiat rail (2.1.0).
+     *
+     * Mirrors {@link payViaAlipay} and needs no EVM wallet. The server placed the
+     * Native order when it built the 402, so its `wechatpay-native` accepts[]
+     * entry already carries `extra.code_url` + `extra.out_trade_no`. Flow: hit the
+     * resource to get the 402, confirm the server offers the wechat rail, surface
+     * the code_url (caller renders a QR), then poll the resource with the
+     * out_trade_no proof until the server verifies the order paid and delivers.
+     */
+    private payViaWechat;
+    /**
+     * The ethers wallet used to sign balance-rail deductions: the client's EVM
+     * wallet if it has one, else a per-configDir identity key persisted at
+     * `<configDir>/balance-identity.key` (0600) so a balance-only client works
+     * without a full crypto wallet. Under `agent 统一代付`, one key spends every
+     * account the agent tops up.
+     */
+    private balanceSigner;
+    /** The balance-rail spending signer address (lowercase 0x…). Stable per
+     *  configDir; this is the identity the server TOFU-binds and later verifies. */
+    getBalanceSignerAddress(): string;
+    /** The buyer id for the balance rail: explicit option > persisted config. */
+    private resolveBuyerId;
+    /**
+     * Pay via the custodial balance rail (2.2.0, password-free).
+     *
+     * No wallet, no QR: the request carries `{buyer_id, request_id}` in the
+     * X-Payment payload and the server deducts the prepaid balance atomically
+     * before running the skill. The client-generated `request_id` makes the
+     * charge idempotent — a network retry can never double-deduct.
+     */
+    private payViaBalance;
+    /** One password-free deduct attempt. Never throws on an HTTP error; the
+     *  caller inspects `{ ok, status, error }` to decide whether to auto-fund. */
+    private balanceDeduct;
+    /**
+     * Non-blocking: POST /balance/topup/order, persist a recoverable session, and
+     * return at once (no polling). Use with {@link confirmBalanceTopup} for
+     * turn-based agents; the blocking {@link topupBalancePack} is built on this.
+     */
+    createBalanceTopupOrder(serverUrl: string, opts?: {
+        pack?: string;
+        buyerId?: string;
+        context?: Record<string, any>;
+    }): Promise<{
+        outTradeNo: string;
+        codeUrl: string;
+        pack: string;
+        maxTimeoutSeconds: number;
+    }>;
+    /**
+     * One-shot: POST /balance/topup/confirm for a single order. No polling.
+     * Updates the persisted session on credit. `serverUrl` defaults to the one
+     * recorded in the session (recover by out_trade_no alone).
+     */
+    confirmBalanceTopup(outTradeNo: string, opts?: {
+        serverUrl?: string;
+    }): Promise<{
+        credited: boolean;
+        pending?: boolean;
+        balance?: string;
+        txId?: string;
+        reason?: string;
+    }>;
+    /**
+     * Blocking terminal wrapper: create the order then poll confirm until the
+     * scan is credited (or the order expires). Built on
+     * {@link createBalanceTopupOrder} + {@link confirmBalanceTopup}.
+     */
+    topupBalancePack(serverUrl: string, opts?: {
+        pack?: string;
+        buyerId?: string;
+        pollIntervalMs?: number;
+        signal?: AbortSignal;
+        onCodeUrl?: (pack: string, codeUrl: string) => void;
+    }): Promise<{
+        balance: string;
+        outTradeNo: string;
+        txId?: string;
+    }>;
+    private balanceTopupSessionDir;
+    private saveBalanceTopupSession;
+    /** Read a persisted top-up session by out_trade_no, or null. */
+    getBalanceTopupSession(outTradeNo: string): BalanceTopupSession | null;
+    /** List persisted top-up sessions, newest first. */
+    listBalanceTopupSessions(): BalanceTopupSession[];
+    /** Abortable sleep used by the top-up poll loop. */
+    private sleep;
+    /** Persist the buyer id used by the balance rail (bearer semantics). */
+    setBuyerId(buyerId: string): void;
+    /** GET /balance — custodial balance, limits, and today's spend for a buyer. */
+    getBuyerBalance(serverUrl: string, buyerId?: string): Promise<Record<string, any>>;
+    /**
+     * POST /balance/topup — report an externally settled payment (on-chain
+     * tx hash / Alipay trade_no / WeChat out_trade_no) so the server verifies
+     * and credits the ledger. Idempotent per reference.
+     */
+    topupBalance(serverUrl: string, opts: {
+        rail: 'crypto' | 'alipay' | 'wechat';
+        amount: string;
+        buyerId?: string;
+        txHash?: string;
+        chain?: string;
+        tradeNo?: string;
+        outTradeNo?: string;
+    }): Promise<Record<string, any>>;
+    /** GET /balance/transactions — ledger history for a buyer, newest first. */
+    listBalanceTransactions(serverUrl: string, opts?: {
+        buyerId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, any>>;
+    /**
+     * Start a recoverable WeChat Pay Native session and return immediately with
+     * QR metadata. The SDK client persists enough context to poll/fulfill later.
+     */
+    startWechatPayment(serverUrl: string, service: string, params: Record<string, any>, options?: PayOptions): Promise<WechatPaymentSession>;
+    /** Query a persisted WeChat session once. */
+    getWechatPaymentStatus(identifier: string): Promise<WechatPaymentSession>;
+    /** Idempotently fulfill a paid WeChat session, returning stored or fetched result. */
+    fulfillWechatPayment(identifier: string): Promise<WechatPaymentSession>;
+    /** Mark a local WeChat session as cancelled. */
+    cancelWechatPayment(identifier: string): WechatPaymentSession;
+    /** List persisted WeChat sessions, newest first. */
+    listWechatPaymentSessions(): WechatPaymentSession[];
     /**
      * Handle MPP (Machine Payments Protocol) payment flow
      * Called when pay() detects WWW-Authenticate header in 402 response
@@ -280,4 +586,4 @@ declare class MoltsPayClient {
     }): Promise<any>;
 }
 
-export { type ClientConfig, MoltsPayClient, type MoltsPayClientOptions, type PayOptions, type PaymentRequired, type ProviderInfo, type ServiceInfo, type ServicesResponse, type VerifyResponse, type WalletData };
+export { type BalanceTopupSession, type ClientConfig, MoltsPayClient, type MoltsPayClientOptions, type PayOptions, type PaymentRequired, type ProviderInfo, type ServiceInfo, type ServicesResponse, type VerifyResponse, type WalletData, WechatClient, type WechatClientOptions, type WechatPayOptions, type WechatPaymentResult, type WechatPaymentSession, type WechatPendingInfo, type WechatSessionStatus, type WechatStartOptions };