moltspay 1.5.0 → 2.0.0

package/dist/facilitators/index.d.ts

@@ -1,7 +1,7 @@
-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 { Keypair, PublicKey, Transaction } from '@solana/web3.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';
 
 /**
  * Tempo Testnet Facilitator
@@ -20,10 +20,32 @@ declare class TempoFacilitator extends BaseFacilitator {
     readonly displayName = "Tempo Testnet";
     readonly supportedNetworks: string[];
     private rpcUrl;
+    private settlerWallet;
     constructor();
+    /**
+     * Settler EOA address advertised to clients via `X-Payment-Required.extra.tempoSpender`.
+     * Web Client uses this as the `spender` field in the signed EIP-2612 Permit.
+     * Returns null if no TEMPO_SETTLER_KEY is configured — permit settlement unavailable.
+     */
+    getSpenderAddress(): string | null;
     healthCheck(): Promise<HealthCheckResult>;
     verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * Structural validation of an EIP-2612 permit payload. Does NOT submit
+     * anything on-chain — actual submission happens in settlePermit().
+     */
+    private verifyPermit;
+    private verifyTxHash;
     settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * EIP-2612 permit settlement path. Submits two transactions on Tempo:
+     *   1. pathUSD.permit(owner, spender=settler, value, deadline, v, r, s)
+     *   2. pathUSD.transferFrom(owner, payTo, value)
+     *
+     * The settler EOA pays Tempo gas (via the TIP-20 `feeToken` mechanism — no
+     * native tTEMPO required; any held TIP-20 token balance covers fees).
+     */
+    private settlePermit;
     private getTransactionReceipt;
 }
 
@@ -243,6 +265,163 @@ declare class SolanaFacilitator extends BaseFacilitator {
  * @param chain - Solana chain (solana or solana_devnet)
  * @param feePayerPubkey - Optional fee payer public key for gasless transactions
  */
-declare function createSolanaPaymentTransaction(senderPubkey: PublicKey, recipientPubkey: PublicKey, amount: bigint, chain: SolanaChainName, feePayerPubkey?: PublicKey): Promise<Transaction>;
+declare function createSolanaPaymentTransaction(senderPubkey: PublicKey, recipientPubkey: PublicKey, amount: bigint, chain: SolanaChainName, feePayerPubkey?: PublicKey, connection?: Connection): Promise<Transaction>;
+
+/**
+ * Alipay AI 收 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 **元** (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 {
+    /** Per-service Alipay `service_id` (overrides `provider.alipay.service_id_default`). */
+    serviceId: string;
+    /** CNY price as decimal string in **元** (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 收 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 \u6536";
+    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): 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
+     * "履约确认失败"), 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;
+}
 
-export { BNBFacilitator, type BNBPaymentIntent, BaseFacilitator, HealthCheckResult, SettleResult, SolanaFacilitator, type SolanaPaymentPayload, TempoFacilitator, VerifyResult, X402PaymentPayload, X402PaymentRequirements, createIntentTypedData, createSolanaPaymentTransaction };
+export { ALIPAY_GATEWAY_PROD, ALIPAY_GATEWAY_SANDBOX, ALIPAY_NETWORK, ALIPAY_SCHEME, AlipayFacilitator, type AlipayFacilitatorConfig, type AlipayPaymentProof, type AlipayPaymentRequirements, BNBFacilitator, type BNBPaymentIntent, BaseFacilitator, type CreatePaymentRequirementsOpts, HealthCheckResult, SettleResult, SolanaFacilitator, type SolanaPaymentPayload, TempoFacilitator, VerifyResult, X402PaymentPayload, X402PaymentRequirements, createIntentTypedData, createSolanaPaymentTransaction };