moltspay 1.6.0 → 2.4.0

package/dist/facilitators/index.d.ts

@@ -1,6 +1,6 @@
-import { B as BaseFacilitator, H as HealthCheckResult, X as X402PaymentPayload, f as X402PaymentRequirements, V as VerifyResult, e as SettleResult } from '../registry-OsEO2dOu.js';
-export { F as Facilitator, a as FacilitatorConfig, b as FacilitatorFee, c as FacilitatorRegistry, d as FacilitatorSelection, S as SelectionStrategy, g as createRegistry, h as getDefaultRegistry } from '../registry-OsEO2dOu.js';
-export { C as CDPFacilitator, a as CDPFacilitatorConfig } from '../cdp-DeohBe1o.js';
+import { B as BaseFacilitator, H as HealthCheckResult, X as X402PaymentPayload, a as X402PaymentRequirements, V as VerifyResult, S as SettleResult } from '../registry-DIo0WNoO.js';
+export { c as Facilitator, F as FacilitatorConfig, b as FacilitatorFee, d as FacilitatorRegistry, e as FacilitatorSelection, f as SelectionStrategy, g as createRegistry, h as getDefaultRegistry } from '../registry-DIo0WNoO.js';
+export { C as CDPFacilitator, a as CDPFacilitatorConfig } from '../cdp-B5PhDUTC.js';
 import { Keypair, PublicKey, Connection, Transaction } from '@solana/web3.js';
 
 /**
@@ -267,4 +267,663 @@ declare class SolanaFacilitator extends BaseFacilitator {
  */
 declare function createSolanaPaymentTransaction(senderPubkey: PublicKey, recipientPubkey: PublicKey, amount: bigint, chain: SolanaChainName, feePayerPubkey?: PublicKey, connection?: Connection): Promise<Transaction>;
 
-export { BNBFacilitator, type BNBPaymentIntent, BaseFacilitator, HealthCheckResult, SettleResult, SolanaFacilitator, type SolanaPaymentPayload, TempoFacilitator, VerifyResult, X402PaymentPayload, X402PaymentRequirements, createIntentTypedData, createSolanaPaymentTransaction };
+/**
+ * Alipay AI Pay Facilitator (2.0.0)
+ *
+ * Implements the `Facilitator` interface for Alipay's AI Pay 402
+ * protocol. Adds a fiat rail (CNY) alongside the existing USDC/EVM/SVM
+ * rails. Server-side only; clients shell out to the `alipay-bot` CLI
+ * (see `AlipayClient` under `src/client/alipay/` in 1.7.0-rc.2).
+ *
+ * Key protocol differences from x402:
+ * - Wire challenge is Base64URL-encoded `Payment-Needed` header with
+ *   nested `{protocol, method}` JSON (not flat `accepts[]`).
+ * - Amount unit is **yuan** (CNY decimal string, not atomic units).
+ * - Signature is RSA2 (SHA256WithRSA), not EIP-712 / EIP-3009.
+ * - Verify/settle hit Alipay Open API HTTP endpoints, not chain RPC.
+ *
+ * The server emits **both** `X-Payment-Required` and `Payment-Needed`
+ * headers so that legacy `alipay-bot` skills (`@alipay/agent-payment@1.0.9`)
+ * keep working without changes.
+ *
+ * @see ../../docs/ALIPAY-RAIL.md — end-user integration guide
+ * @see ../../docs/ALIPAY-INTEGRATION-DESIGN.md — architecture & decisions
+ * @see ../../docs/ALIPAY-INTEGRATION-PLAN.md — implementation milestones
+ *
+ * Stub for 1.7.0-rc.1; bodies tracked in ALIPAY-INTEGRATION-PLAN.md §1.
+ */
+
+/** Network identifier exposed via `Facilitator.supportedNetworks`. */
+declare const ALIPAY_NETWORK = "alipay";
+/** x402 `scheme` string identifying the Alipay rail in `accepts[]`. */
+declare const ALIPAY_SCHEME = "alipay-aipay";
+/** Default production gateway URL. */
+declare const ALIPAY_GATEWAY_PROD = "https://openapi.alipay.com/gateway.do";
+/** Sandbox gateway URL (for testing without real CNY). */
+declare const ALIPAY_GATEWAY_SANDBOX = "https://openapi.alipaydev.com/gateway.do";
+/**
+ * Facilitator-level configuration sourced from `provider.alipay` in
+ * `moltspay.services.json`. The server resolves `private_key_path` and
+ * `alipay_public_key_path` to PEM strings before constructing the facilitator.
+ */
+interface AlipayFacilitatorConfig {
+    /** Merchant Alipay ID (16 digits, e.g. `"2088641494699428"`). */
+    seller_id: string;
+    /** Application ID from Alipay Open Platform. */
+    app_id: string;
+    /** Merchant legal name; appears in `method.seller_name` of the 402 challenge. */
+    seller_name: string;
+    /** Fallback `service_id` when a service doesn't override it. */
+    service_id_default: string;
+    /** RSA2 merchant private key (PEM). Loaded from `private_key_path` by the server. */
+    private_key_pem: string;
+    /** Alipay platform public key (PEM). Loaded from `alipay_public_key_path` by the server. */
+    alipay_public_key_pem: string;
+    /** Open API gateway URL. Defaults to {@link ALIPAY_GATEWAY_PROD}. */
+    gateway_url?: string;
+    /** Signature algorithm. Only `RSA2` is supported. */
+    sign_type?: 'RSA2';
+}
+/**
+ * Inputs required to construct a 402 `Payment-Needed` challenge for a service.
+ */
+interface CreatePaymentRequirementsOpts$1 {
+    /** Per-service Alipay `service_id` (overrides `provider.alipay.service_id_default`). */
+    serviceId: string;
+    /** CNY price as decimal string in **yuan** (e.g. `"1.00"` = 1 CNY). */
+    priceCny: string;
+    /** Goods name shown to the user in the Alipay app. */
+    goodsName: string;
+    /** Resource identifier (typically the request URL or its hash). */
+    resourceId: string;
+    /** Client-supplied `out_trade_no`; if omitted the facilitator generates one. */
+    outTradeNo?: string;
+}
+/**
+ * Both headers the server emits in a 402 response:
+ * - `x402Accepts` → `X-Payment-Required` (x402 standard, for new MoltsPay clients)
+ * - `paymentNeededHeader` → `Payment-Needed` (Alipay standard, for legacy `alipay-bot`)
+ *
+ * The two headers are mirrors of each other; the single source of truth lives
+ * in the server config.
+ */
+interface AlipayPaymentRequirements {
+    x402Accepts: X402PaymentRequirements;
+    paymentNeededHeader: string;
+}
+/**
+ * Decoded `Payment-Proof` header from the buyer's request.
+ *
+ * The proof is Base64URL of `{protocol: {...}, method: {...}}` where:
+ * - `protocol.trade_no` is the 32-digit Alipay trade number
+ * - `protocol.payment_proof` is the RSA2-signed payment proof
+ * - `method.client_session` echoes the buyer's session for replay protection
+ */
+interface AlipayPaymentProof {
+    protocol: {
+        payment_proof: string;
+        trade_no: string;
+        [k: string]: unknown;
+    };
+    method: {
+        client_session: string;
+        [k: string]: unknown;
+    };
+}
+/**
+ * Alipay AI Pay facilitator.
+ *
+ * Construction is cheap; expensive setup (key parsing, gateway probe) is
+ * deferred to `healthCheck()`.
+ */
+declare class AlipayFacilitator extends BaseFacilitator {
+    readonly name = "alipay";
+    readonly displayName = "Alipay AI Pay";
+    readonly supportedNetworks: string[];
+    private readonly config;
+    constructor(config: AlipayFacilitatorConfig);
+    /**
+     * Build the 402 challenge for a service: signs the 8-field payload with
+     * RSA2, packages the nested `{protocol, method}` JSON as Base64URL for
+     * `Payment-Needed`, and emits the parallel x402 `accepts[]` entry.
+     */
+    createPaymentRequirements(opts: CreatePaymentRequirementsOpts$1): Promise<AlipayPaymentRequirements>;
+    /**
+     * Verify a `Payment-Proof` by calling
+     * `alipay.aipay.agent.payment.verify` against the Alipay Open API.
+     *
+     * The proof is conveyed via `paymentPayload.payload`, which may be:
+     * - a raw Base64URL string (the `Payment-Proof` header value), or
+     * - an object `{ paymentProof: string }` / `{ proofHeader: string }`.
+     *
+     * All failure modes (malformed payload, network errors, Alipay
+     * `code != 10000`) return `{ valid: false, error }`. No exception
+     * escapes, regardless of client-supplied input.
+     */
+    verify(paymentPayload: X402PaymentPayload, _requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * Settle by calling `alipay.aipay.agent.fulfillment.confirm` after the
+     * service resource has been returned to the buyer.
+     *
+     * Per the design (see ALIPAY-INTEGRATION-DESIGN.md §5.1, risk row
+     * (a fulfillment-confirm failure), this is **fire-and-forget**: the caller (registry /
+     * server) is expected to log fulfillment failures but NOT roll back
+     * the already-delivered resource.
+     *
+     * Re-decodes `paymentPayload.payload` to extract `trade_no` (verify
+     * does the same; the redundant Base64URL decode is negligible).
+     */
+    settle(paymentPayload: X402PaymentPayload, _requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * Validate that the configured RSA keys parse and that the Open API
+     * gateway is reachable. Does NOT make a real business API call (would
+     * burn quota and could appear as a legitimate verify attempt in logs).
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /** Bundle the facilitator config into the shape openapi.ts wants. */
+    private getOpenApiConfig;
+}
+
+/**
+ * WeChat Pay v3 JSON API caller.
+ *
+ * Wraps the REST/JSON gateway (`https://api.mch.weixin.qq.com`). Handles:
+ * - SHA256-RSA request signing + the `Authorization` header (see ./sign.ts)
+ * - JSON body / response marshalling
+ * - optional response signature verification against the WeChat platform
+ *   public key (enabled when `platform_public_key_pem` is configured)
+ * - uniform error surfacing: non-2xx throws a {@link WechatApiError} carrying
+ *   the gateway `code`/`message`
+ *
+ * Unlike Alipay's form-urlencoded gateway, v3 is plain REST: the method +
+ * path + body are signed, and the business payload IS the HTTP body (no
+ * `biz_content` wrapper).
+ *
+ * @see https://pay.weixin.qq.com/docs/merchant/development/interface-rules/
+ */
+/** Default production base URL for the v3 REST gateway. */
+declare const WECHAT_API_BASE = "https://api.mch.weixin.qq.com";
+
+/**
+ * WeChat Pay v3 Facilitator (Native, scenario A).
+ *
+ * Implements the `Facilitator` interface for WeChat Pay's v3 **Native**
+ * (scan-to-pay) flow. Adds a CNY fiat rail alongside the USDC/EVM/SVM and
+ * Alipay rails. Server-side only.
+ *
+ * Scenario A — "agent issues a code, payer is not pre-bound":
+ * - `createPaymentRequirements` places a Native order and returns its
+ *   `code_url`. The code is **payer-agnostic** (no openid, unlike JSAPI):
+ *   any WeChat user can scan it. It is **one-code-one-payment** — the first
+ *   payer settles the order; collect again by issuing a new code.
+ * - `verify` polls the order (`trade_state === 'SUCCESS'`).
+ * - `settle` re-confirms SUCCESS and returns the `transaction_id` (Native
+ *   captures funds at SUCCESS; there is no separate capture step).
+ *
+ * Key protocol differences from Alipay AI Pay (see docs/WECHAT-RAIL-DESIGN.md §3):
+ * - REST/JSON gateway, not a form-urlencoded `gateway.do`.
+ * - SHA256-RSA over `METHOD\nURL\nTS\nNONCE\nBODY\n`, packed into the
+ *   `Authorization` header (handled by ./wechat/api.ts + ./wechat/sign.ts).
+ * - Amount unit is **fen** (integer cents), not yuan — `cnyToFen` converts.
+ *
+ * Async callback decryption (AES-256-GCM) and the notify webhook are NOT in
+ * this milestone; scenario A confirms via polling. They land in Phase 2.
+ *
+ * @see ./wechat/sign.ts — signing primitives
+ * @see ./wechat/api.ts — v3 JSON caller
+ * @see ../../docs/WECHAT-RAIL-DESIGN.md — design & scenario
+ */
+
+/** Network identifier exposed via `Facilitator.supportedNetworks`. */
+declare const WECHAT_NETWORK = "wechat";
+/** x402 `scheme` string identifying the WeChat Native rail in `accepts[]`. */
+declare const WECHAT_SCHEME = "wechatpay-native";
+/** Validation regex for `price_cny` (decimal string, unit yuan, <= 2 decimals). */
+declare const WECHAT_AMOUNT_REGEX: RegExp;
+/** Default order lifetime if the caller doesn't pass one (Native convention). */
+declare const WECHAT_TIME_EXPIRE_MS: number;
+
+/**
+ * Facilitator-level config sourced from `provider.wechat` in
+ * `moltspay.services.json`. The server resolves `private_key_path` /
+ * `platform_public_key_path` to PEM strings before constructing this.
+ */
+interface WechatFacilitatorConfig {
+    /** Merchant id (mchid). */
+    mchid: string;
+    /** App id (official account / mini-program / app). */
+    appid: string;
+    /** Merchant API certificate serial number. */
+    serial_no: string;
+    /** Merchant RSA private key (PEM). */
+    private_key_pem: string;
+    /** WeChat platform certificate public key (PEM). Enables response verify. */
+    platform_public_key_pem?: string;
+    /** APIv3 key (32 bytes). Only needed for callback decryption (Phase 2). */
+    apiv3_key?: string;
+    /** Async result notify URL. **Required by Native order create** even when polling. */
+    notify_url: string;
+    /** Base URL; defaults to {@link WECHAT_API_BASE}. */
+    api_base?: string;
+}
+/** Inputs to place a Native order (402 challenge) for a service. */
+interface CreatePaymentRequirementsOpts {
+    /** CNY price as a decimal string in **yuan** (e.g. `"10.00"`). */
+    priceCny: string;
+    /** Order description shown to the payer in the WeChat app. */
+    description: string;
+    /** Client-supplied `out_trade_no`; generated when omitted. */
+    outTradeNo?: string;
+    /** Order lifetime; defaults to {@link WECHAT_TIME_EXPIRE_MS}. */
+    expiresInMs?: number;
+    /**
+     * Passthrough metadata WeChat echoes back on order-query and callback
+     * (v3 `attach`, max 128 bytes once JSON-serialized). Used to bind an
+     * otherwise payer-agnostic Native order to a `buyer_id` for balance
+     * top-ups. Read it back with {@link parseWechatAttach}.
+     */
+    attach?: Record<string, string>;
+}
+/** Result of placing a Native order. */
+interface WechatPaymentRequirements {
+    /** x402 `accepts[]` entry (carries `extra.code_url` + `extra.out_trade_no`). */
+    x402Accepts: X402PaymentRequirements;
+    /** `weixin://wxpay/bizpayurl?pr=...` — render verbatim as a QR. */
+    codeUrl: string;
+    /** The order's merchant trade number, used to poll `verify`/`settle`. */
+    outTradeNo: string;
+}
+/**
+ * WeChat Pay v3 Native facilitator.
+ *
+ * Construction is cheap; key parsing / gateway probe is deferred to
+ * `healthCheck()`.
+ */
+declare class WechatFacilitator extends BaseFacilitator {
+    readonly name = "wechat";
+    readonly displayName = "WeChat Pay";
+    readonly supportedNetworks: string[];
+    private readonly config;
+    constructor(config: WechatFacilitatorConfig);
+    /**
+     * Place a Native order and build the 402 challenge. The returned
+     * `code_url` is payer-agnostic — any WeChat user may scan it.
+     */
+    createPaymentRequirements(opts: CreatePaymentRequirementsOpts): Promise<WechatPaymentRequirements>;
+    /**
+     * Poll an order: `trade_state === 'SUCCESS'` ⇒ paid. All failure modes
+     * (missing out_trade_no, gateway error, not-yet-paid) return
+     * `{ valid: false, error }`; no exception escapes.
+     */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * Confirm settlement. Native captures funds at SUCCESS, so this is an
+     * idempotent re-confirm that returns the `transaction_id`. Like Alipay's
+     * fulfillment confirm, failures are surfaced but non-fatal to an
+     * already-delivered resource (caller logs, does not roll back).
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * Validate keys parse, apiv3 key length, and gateway reachability. Does
+     * NOT make a business API call.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /** Query a Native order by out_trade_no. The query string is part of the signed path. */
+    private queryOrder;
+    /** Project the facilitator config down to what api.ts needs. */
+    private getApiConfig;
+}
+/**
+ * Safely parse the `attach` string echoed back on order-query / callback into
+ * the object passed to {@link CreatePaymentRequirementsOpts.attach}. Returns
+ * null for a missing, non-string, or malformed value (a per-transaction order
+ * that carried no attach, or tampered input) so callers never throw on it.
+ */
+declare function parseWechatAttach(attach: unknown): Record<string, string> | null;
+
+/**
+ * Custodial balance ledger (SQLite).
+ *
+ * Backs the balance ("password-free" / password-free) rail: buyers top up once and
+ * subsequent purchases are deducted server-side — no signature or scan per
+ * transaction. All amounts are **integer cents** (`*_sat`, 1 USD = 100) to
+ * avoid floating-point drift; the dollar<->cent boundary is `toSat`/`fromSat`.
+ *
+ * Uses the Node built-in `node:sqlite` (zero new dependencies). That module
+ * is only available on Node >= 22.5, so it is loaded lazily inside the
+ * constructor: servers that don't enable the balance rail keep the package's
+ * `node >= 18` floor.
+ *
+ * Concurrency: `DatabaseSync` is synchronous and single-connection, so every
+ * ledger call is naturally serialized within the process — the
+ * check-and-deduct UPDATE (`... WHERE balance_sat >= ?`) is atomic without
+ * explicit transactions. WAL mode keeps concurrent readers cheap.
+ *
+ * @see ../../../docs/BALANCE-RAIL-DESIGN.md — data model & semantics
+ */
+/** Buyer account row (amounts in integer cents). */
+interface BuyerRow {
+    buyer_id: string;
+    display_name: string | null;
+    balance_sat: number;
+    total_topup_sat: number;
+    total_spent_sat: number;
+    daily_limit_sat: number;
+    single_limit_sat: number;
+    status: 'active' | 'frozen' | 'banned';
+    /**
+     * TOFU-bound originator signer address (EVM, lowercase 0x…) for the
+     * WeChat fiat auth flow. Null for legacy accounts never seen with a
+     * signature; bound on first signed request. @see ./auth.ts
+     */
+    signer_address: string | null;
+    /**
+     * Gateway-attested WeChat payer openid that funded this account, recorded
+     * on top-up confirm. Anchors the custodial balance to a real WeChat user.
+     * Null for accounts never funded via WeChat (crypto/alipay/operator).
+     */
+    wechat_openid: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Ledger transaction row (amounts in integer cents, always positive). */
+interface LedgerTxRow {
+    id: string;
+    buyer_id: string;
+    type: 'topup' | 'deduct' | 'refund';
+    amount_sat: number;
+    service: string | null;
+    description: string | null;
+    /** Client-supplied idempotency key (deducts). Unique when present. */
+    request_id: string | null;
+    /** External settlement reference: on-chain tx hash / Alipay or WeChat trade no. */
+    external_ref: string | null;
+    /** For refunds: the deduct row being reversed. */
+    refunds_tx_id: string | null;
+    status: 'completed' | 'refunded';
+    created_at: string;
+}
+type DeductErrorCode = 'buyer_not_found' | 'buyer_not_active' | 'insufficient_balance' | 'exceeds_single_limit' | 'exceeds_daily_limit';
+interface DeductResult {
+    success: boolean;
+    /** Ledger transaction id (also returned on an idempotent replay). */
+    txId?: string;
+    /** True when `request_id` matched an existing deduct — nothing was charged. */
+    replayed?: boolean;
+    balanceSat?: number;
+    error?: DeductErrorCode;
+    /** Populated for limit errors. */
+    limitSat?: number;
+}
+interface DeductOpts {
+    buyerId: string;
+    amountSat: number;
+    /** Idempotency key; a replay returns the original tx without deducting. */
+    requestId?: string;
+    service?: string;
+    description?: string;
+}
+interface TopupOpts {
+    buyerId: string;
+    amountSat: number;
+    /** On-chain tx hash / Alipay trade_no / WeChat out_trade_no. Unique — a
+     *  replayed reference credits nothing and returns the original row. */
+    externalRef: string;
+    description?: string;
+}
+interface RefundResult {
+    success: boolean;
+    txId?: string;
+    balanceSat?: number;
+    /** True when the deduct was already refunded — nothing was credited. */
+    replayed?: boolean;
+    error?: 'tx_not_found' | 'not_a_deduct';
+}
+interface LedgerConfig {
+    /** SQLite file path, or ':memory:' for tests. */
+    dbPath: string;
+    /** Default per-transaction limit for new buyers, integer cents. */
+    defaultSingleLimitSat?: number;
+    /** Default daily limit for new buyers, integer cents. */
+    defaultDailyLimitSat?: number;
+    /**
+     * Ledger quote currency (e.g. 'USD', 'CNY'). Recorded once in `ledger_meta`
+     * on first init and enforced on every subsequent open: the minor unit
+     * (`*_sat`) is 1/100 of this currency, so reopening a USD ledger as CNY would
+     * silently reinterpret every balance. Defaults to "USD".
+     */
+    currency?: string;
+}
+/** Convert a decimal string/number of dollars to integer cents. Throws on >2dp. */
+declare function toSat(amount: string | number): number;
+/** Convert integer cents back to a 2-decimal string. */
+declare function fromSat(sat: number): string;
+declare class BalanceLedger {
+    private readonly db;
+    private readonly defaultSingleLimitSat;
+    private readonly defaultDailyLimitSat;
+    constructor(config: LedgerConfig);
+    /** Fetch a buyer, or null. */
+    getBuyer(buyerId: string): BuyerRow | null;
+    /** Fetch a buyer, creating an empty active account on first sight. */
+    getOrCreateBuyer(buyerId: string, displayName?: string): BuyerRow;
+    /**
+     * Record the gateway-attested WeChat payer openid that funded a buyer, on
+     * top-up confirm. Idempotent and observational (stage 1a): it never
+     * overwrites an existing binding with a *different* openid — a conflict is
+     * reported to the caller (possible account sharing / spoof) but not
+     * enforced here. Creates the buyer if absent.
+     */
+    bindOpenid(buyerId: string, openid: string): {
+        bound: boolean;
+        conflict: boolean;
+        existing: string | null;
+    };
+    /**
+     * TOFU-bind the account's spending signer address (EVM, lowercase). First
+     * signed request records it; later requests must match. A mismatch is
+     * reported (`conflict`) so the caller can reject under `enforce` — it is
+     * never silently overwritten. Creates the buyer if absent.
+     */
+    bindSigner(buyerId: string, address: string): {
+        bound: boolean;
+        conflict: boolean;
+        existing: string | null;
+    };
+    /** Sum of today's (UTC) completed deducts minus refunds issued against them. */
+    spentTodaySat(buyerId: string): number;
+    /**
+     * Read-only deduction precheck (the rail's `verify`). Never mutates.
+     * Returns the same error codes `deduct` would.
+     */
+    checkDeduct(buyerId: string, amountSat: number): DeductResult;
+    /**
+     * Atomic deduction (the rail's `settle`). Check + UPDATE run inside one
+     * SQLite transaction; a `request_id` replay returns the original tx
+     * without charging again.
+     */
+    deduct(opts: DeductOpts): DeductResult;
+    /**
+     * Credit a top-up. `externalRef` is the settlement proof reference
+     * (on-chain tx hash / fiat trade number) and is unique: replaying the same
+     * reference returns the original row without crediting twice.
+     */
+    topup(opts: TopupOpts): {
+        txId: string;
+        balanceSat: number;
+        replayed?: boolean;
+    };
+    /**
+     * Reverse a deduct (service failed after the charge). Idempotent: the
+     * unique index on `refunds_tx_id` means a second refund of the same deduct
+     * returns the original refund row.
+     */
+    refund(deductTxId: string, reason?: string): RefundResult;
+    /** Paged transaction history, newest first (rowid breaks same-second ties). */
+    listTransactions(buyerId: string, limit?: number, offset?: number): LedgerTxRow[];
+    /** Quick integrity probe for healthCheck(). */
+    integrityOk(): boolean;
+    close(): void;
+}
+
+/** Domain tag — separates these signatures from any other message a key signs. */
+declare const BALANCE_AUTH_DOMAIN = "moltspay-balance-auth:v1";
+/** Accepted clock skew between client timestamp and server (replay window). */
+declare const BALANCE_AUTH_MAX_SKEW_MS: number;
+/** Rollout gate for balance-rail user auth. */
+type BalanceAuthMode = 'off' | 'shadow' | 'enforce';
+/** Signature material carried in the balance X-Payment payload. */
+interface BalanceAuthFields {
+    /** Unix seconds when the client signed. */
+    timestamp: number;
+    /** EIP-191 signature over {@link buildDeductMessage}. */
+    signature: string;
+}
+/**
+ * Canonical message a client signs to authorize one deduction. Both sides
+ * MUST build this identically. `amount` is intentionally omitted — the
+ * service id determines the price server-side, and `request_id` (unique per
+ * charge) + `timestamp` (windowed) already bound replay.
+ */
+declare function buildDeductMessage(f: {
+    buyerId: string;
+    requestId: string;
+    service: string;
+    timestamp: number;
+}): string;
+interface AuthVerifyResult {
+    ok: boolean;
+    /** Recovered signer address (lowercase 0x…), present when the signature parsed. */
+    recovered?: string;
+    /** Failure code when `ok` is false: no_signature | malformed | timestamp_skew | bad_signature. */
+    reason?: string;
+}
+/**
+ * Verify a deduction signature and recover the signer address. Never throws.
+ * Does NOT decide binding/enforcement — the caller compares `recovered`
+ * against the account's bound signer and applies `auth_mode`.
+ */
+declare function verifyDeductAuth(opts: {
+    auth: BalanceAuthFields | null;
+    buyerId: string;
+    requestId: string;
+    service: string;
+    nowMs: number;
+}): AuthVerifyResult;
+
+/**
+ * Custodial Balance Facilitator (password-free rail).
+ *
+ * Third payment mode beside per-transaction crypto signing and fiat QR
+ * (Alipay/WeChat): buyers top up once into a server-custodied SQLite ledger
+ * and subsequent purchases are deducted directly — no signature, no scan.
+ *
+ * Interface mapping (differs from the QR rails — see BALANCE-RAIL-DESIGN.md):
+ * - `createPaymentRequirements` is **pure**: it formats the `accepts[]` entry
+ *   without any I/O. Nothing is minted per 402, so the WeChat rail's
+ *   order-per-challenge double-charge class of bug cannot occur here.
+ * - `verify` is a read-only funds/limits precheck.
+ * - `settle` is **the atomic deduction** (single SQLite transaction),
+ *   idempotent on the client-supplied `request_id`.
+ * - `refund` (rail-specific, not on the Facilitator interface) reverses a
+ *   deduct when the skill fails after the charge.
+ *
+ * Execution order at the server is therefore inverted relative to QR rails:
+ *   QR:      verify(paid?) → run skill → settle (confirm, fire-and-forget)
+ *   balance: verify(funds?) → settle (deduct) → run skill → [fail → refund]
+ *
+ * @see ./balance/ledger.ts — SQLite ledger (atomicity, idempotency, limits)
+ * @see ../../docs/BALANCE-RAIL-DESIGN.md — design
+ */
+
+/** Network identifier exposed via `Facilitator.supportedNetworks`. */
+declare const BALANCE_NETWORK = "balance";
+/** x402 `scheme` string identifying the custodial balance rail in `accepts[]`. */
+declare const BALANCE_SCHEME = "balance";
+
+/**
+ * Facilitator-level config sourced from `provider.balance` in
+ * `moltspay.services.json`.
+ */
+interface BalanceFacilitatorConfig {
+    /** SQLite ledger file path (created on first init). ':memory:' for tests. */
+    db_path: string;
+    /** Ledger quote currency. Default 'USD'. */
+    currency?: string;
+    /** Default per-transaction limit for new buyers, decimal string. Default "5.00". */
+    single_limit?: string;
+    /** Default daily limit for new buyers, decimal string. Default "10.00". */
+    daily_limit?: string;
+    /**
+     * User-auth rollout gate for deductions. Default 'off' (bare buyer_id, as
+     * before). 'shadow' verifies + TOFU-binds the signer but never blocks;
+     * 'enforce' rejects unsigned/mismatched deductions.
+     */
+    auth_mode?: BalanceAuthMode;
+}
+/** The buyer-identifying payload carried in X-Payment for this rail. */
+interface BalancePaymentPayload {
+    buyer_id: string;
+    /** Client-generated idempotency key: replays never double-deduct. */
+    request_id?: string;
+    /** Originator signature (present when the client signs). @see ./balance/auth.ts */
+    auth?: BalanceAuthFields;
+}
+/** Extract {buyer_id, request_id, auth} from an x402 payload, or null. */
+declare function extractBalancePayload(payment: X402PaymentPayload): BalancePaymentPayload | null;
+/**
+ * Custodial balance facilitator. Construction opens (or creates) the SQLite
+ * ledger; on Node < 22.5 it throws with an actionable message.
+ */
+declare class BalanceFacilitator extends BaseFacilitator {
+    readonly name = "balance";
+    readonly displayName = "Custodial Balance";
+    readonly supportedNetworks: string[];
+    readonly currency: string;
+    /** User-auth rollout gate for deductions (off | shadow | enforce). */
+    readonly authMode: BalanceAuthMode;
+    private readonly ledger;
+    constructor(config: BalanceFacilitatorConfig);
+    /** Direct ledger access for the server's balance-management endpoints. */
+    getLedger(): BalanceLedger;
+    /**
+     * Build the `accepts[]` entry for a service. Pure — no I/O, nothing minted.
+     */
+    createPaymentRequirements(opts: {
+        price: string;
+        serviceId?: string;
+    }): X402PaymentRequirements;
+    /** Read-only funds/limits precheck. Never mutates the ledger. */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * The atomic deduction. Idempotent on `request_id`; the returned
+     * `transaction` is the ledger tx id (usable for `refund`).
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /** Reverse a deduct after a downstream failure. Idempotent per deduct. */
+    refund(deductTxId: string, reason?: string): RefundResult;
+    /**
+     * Credit a gateway-verified external settlement to a buyer's balance. The
+     * single entry point for every funding path -- WeChat callback, WeChat
+     * polling, and the operator `/balance/topup` endpoint -- so they share one
+     * idempotency boundary: `externalRef` is unique in the ledger, so a replay
+     * credits nothing and returns the original transaction (`replayed: true`).
+     * Callers must pass a gateway-verified `amountSat`, never a client-declared
+     * amount.
+     */
+    credit(opts: {
+        buyerId: string;
+        amountSat: number;
+        externalRef: string;
+        description?: string;
+    }): {
+        txId: string;
+        balance: string;
+        balanceSat: number;
+        replayed: boolean;
+    };
+    healthCheck(): Promise<HealthCheckResult>;
+    private describeDeductError;
+}
+
+export { ALIPAY_GATEWAY_PROD, ALIPAY_GATEWAY_SANDBOX, ALIPAY_NETWORK, ALIPAY_SCHEME, AlipayFacilitator, type AlipayFacilitatorConfig, type AlipayPaymentProof, type AlipayPaymentRequirements, BALANCE_AUTH_DOMAIN, BALANCE_AUTH_MAX_SKEW_MS, BALANCE_NETWORK, BALANCE_SCHEME, BNBFacilitator, type BNBPaymentIntent, type BalanceAuthFields, type BalanceAuthMode, BalanceFacilitator, type BalanceFacilitatorConfig, BalanceLedger, type BalancePaymentPayload, BaseFacilitator, type BuyerRow, type CreatePaymentRequirementsOpts$1 as CreatePaymentRequirementsOpts, type DeductResult, HealthCheckResult, type LedgerTxRow, type RefundResult, SettleResult, SolanaFacilitator, type SolanaPaymentPayload, TempoFacilitator, VerifyResult, WECHAT_AMOUNT_REGEX, WECHAT_API_BASE, WECHAT_NETWORK, WECHAT_SCHEME, WECHAT_TIME_EXPIRE_MS, WechatFacilitator, type WechatFacilitatorConfig, type WechatPaymentRequirements, X402PaymentPayload, X402PaymentRequirements, buildDeductMessage, createIntentTypedData, createSolanaPaymentTransaction, extractBalancePayload, fromSat, parseWechatAttach, toSat, verifyDeductAuth };