moltspay 1.5.0 → 2.0.0

package/dist/index.d.mts

@@ -4,7 +4,82 @@ export { CHAINS, ERC20_ABI, getChain, getChainById, listChains } from './chains/
 export { c as createWallet, g as getWalletAddress, l as loadWallet, w as walletExists } from './createWallet-D53qu7ie.mjs';
 export { VerifyPaymentParams, VerifyPaymentResult, getTransactionStatus, verifyPayment, waitForTransaction } from './verify/index.mjs';
 export { CDPWallet, getCDPWalletAddress, initCDPWallet, isCDPAvailable, loadCDPWallet } from './cdp/index.mjs';
-export { B as BaseFacilitator, F as Facilitator, a as FacilitatorConfig, b as FacilitatorFee, c as FacilitatorRegistry, d as FacilitatorSelection, H as HealthCheckResult, S as SelectionStrategy, e as SettleResult, V as VerifyResult, X as X402PaymentPayload, f as X402PaymentRequirements, g as createRegistry, h as getDefaultRegistry } from './registry-OsEO2dOu.mjs';
-export { C as CDPFacilitator, a as CDPFacilitatorConfig } from './cdp-p_eHuQpb.mjs';
+export { B as BaseFacilitator, c as Facilitator, F as FacilitatorConfig, b as FacilitatorFee, d as FacilitatorRegistry, e as FacilitatorSelection, H as HealthCheckResult, f as SelectionStrategy, S as SettleResult, V as VerifyResult, X as X402PaymentPayload, a as X402PaymentRequirements, g as createRegistry, h as getDefaultRegistry } from './registry-DIo0WNoO.mjs';
+export { C as CDPFacilitator, a as CDPFacilitatorConfig } from './cdp-D-5Hg3y_.mjs';
 import 'ethers';
 import './index-D_2FkLwV.mjs';
+
+/**
+ * Alipay rail log management (design §5.2 observability).
+ *
+ * The Alipay rail's latency lives in a chain of `alipay-bot` subprocess spawns
+ * and gateway round-trips that, in production, are invisible: the only output is
+ * the verbatim CLI passthrough the skill guide mandates on stdout. This module
+ * adds a structured, opt-in log channel so every node of the `pay402` state
+ * machine — and how long it took — can be observed and routed into the host
+ * app's log pipeline, WITHOUT changing default behavior or polluting stdout.
+ *
+ * Usage (host app):
+ *   import { setAlipayLogLevel, setAlipayLogSink } from 'moltspay';
+ *   setAlipayLogLevel('info');                       // or env MOLTSPAY_ALIPAY_LOG=info
+ *   setAlipayLogSink((line) => myLogger.info(line));  // default: process.stderr
+ *
+ * Levels: 'off' (default) < 'info' (node timings + flow totals) < 'debug'
+ * (adds per-spawn start/exit and per-poll ticks). The level is read from
+ * MOLTSPAY_ALIPAY_LOG at load and can be overridden at runtime.
+ */
+type AlipayLogLevel = 'off' | 'info' | 'debug';
+/** A single structured log record. The sink receives both the line and this. */
+interface AlipayLogEvent {
+    /** ISO-8601 timestamp. */
+    ts: string;
+    level: 'info' | 'debug';
+    /** Event name: flow.start | flow.pending | flow.settled | flow.failed |
+     *  step.start | step.end | cli.exit | poll.tick. */
+    event: string;
+    /** Correlation id grouping all lines of one payment flow (session/tradeNo). */
+    flow?: string;
+    /** Node/step name, e.g. 'ensure-cli', 'payment-intent', '402-buyer-pay'. */
+    step?: string;
+    /** Elapsed milliseconds (on *.end / *.exit / flow.* total events). */
+    ms?: number;
+    [k: string]: unknown;
+}
+type AlipayLogSink = (line: string, event: AlipayLogEvent) => void;
+/** Set the verbosity at runtime (overrides the MOLTSPAY_ALIPAY_LOG env). */
+declare function setAlipayLogLevel(next: AlipayLogLevel): void;
+/** Current effective level. */
+declare function getAlipayLogLevel(): AlipayLogLevel;
+/** Route alipay log lines anywhere (host log pipeline, file, collector, …). */
+declare function setAlipayLogSink(fn: AlipayLogSink): void;
+declare const alipayLog: {
+    info: (event: string, fields?: Record<string, unknown>) => void;
+    debug: (event: string, fields?: Record<string, unknown>) => void;
+    /** True if anything at all would be logged (cheap guard for hot paths). */
+    enabled: () => boolean;
+};
+
+/**
+ * AlipayClient — the 8-step `pay402()` state machine (design §5.2.3).
+ *
+ * The Alipay skill guide §5 forbids skipping any step; each maps to one
+ * `alipay-bot` spawn. This class drives them in order and hands the caller a
+ * single terminal `AlipayPaymentResult`, so paying via Alipay looks the same
+ * as awaiting an EVM settle (design §5.2.3 "关键设计").
+ *
+ *   0.  ensureCli()                          version gate (≥ MIN_CLI_VERSION)
+ *   1b. alipay-bot payment-intent …          session handshake
+ *   2.  alipay-bot check-wallet              → NeedsWalletSetupError if unopened
+ *   3.  dump Payment-Needed → tmp file        (internal, user-invisible)
+ *   4.  alipay-bot 402-buyer-pay -f … -r …   → paymentUrl + tradeNo → onPaymentPending
+ *   5.  pollUntil(tradeNo)                    3s poll until paid / rejected / timeout
+ *   7.  return resource body
+ *   8.  alipay-bot 402-buyer-fulfillment-ack  fire-and-forget
+ */
+
+/** Clear the check-wallet cache (tests, or after the user (un)binds a wallet). */
+declare function resetWalletCache(): void;
+/** Clear the payment-intent skip-cache (tests, or after (un)bind / session reset). */
+declare function resetIntentCache(): void;
+
+export { type AlipayLogEvent, type AlipayLogLevel, type AlipayLogSink, alipayLog, getAlipayLogLevel, resetIntentCache, resetWalletCache, setAlipayLogLevel, setAlipayLogSink };

package/dist/index.d.ts

@@ -4,7 +4,82 @@ export { CHAINS, ERC20_ABI, getChain, getChainById, listChains } from './chains/
 export { c as createWallet, g as getWalletAddress, l as loadWallet, w as walletExists } from './createWallet-D53qu7ie.js';
 export { VerifyPaymentParams, VerifyPaymentResult, getTransactionStatus, verifyPayment, waitForTransaction } from './verify/index.js';
 export { CDPWallet, getCDPWalletAddress, initCDPWallet, isCDPAvailable, loadCDPWallet } from './cdp/index.js';
-export { B as BaseFacilitator, F as Facilitator, a as FacilitatorConfig, b as FacilitatorFee, c as FacilitatorRegistry, d as FacilitatorSelection, H as HealthCheckResult, S as SelectionStrategy, e as SettleResult, V as VerifyResult, X as X402PaymentPayload, f as X402PaymentRequirements, g as createRegistry, h as getDefaultRegistry } from './registry-OsEO2dOu.js';
-export { C as CDPFacilitator, a as CDPFacilitatorConfig } from './cdp-DeohBe1o.js';
+export { B as BaseFacilitator, c as Facilitator, F as FacilitatorConfig, b as FacilitatorFee, d as FacilitatorRegistry, e as FacilitatorSelection, H as HealthCheckResult, f as SelectionStrategy, S as SettleResult, V as VerifyResult, X as X402PaymentPayload, a as X402PaymentRequirements, g as createRegistry, h as getDefaultRegistry } from './registry-DIo0WNoO.js';
+export { C as CDPFacilitator, a as CDPFacilitatorConfig } from './cdp-B5PhDUTC.js';
 import 'ethers';
 import './index-D_2FkLwV.js';
+
+/**
+ * Alipay rail log management (design §5.2 observability).
+ *
+ * The Alipay rail's latency lives in a chain of `alipay-bot` subprocess spawns
+ * and gateway round-trips that, in production, are invisible: the only output is
+ * the verbatim CLI passthrough the skill guide mandates on stdout. This module
+ * adds a structured, opt-in log channel so every node of the `pay402` state
+ * machine — and how long it took — can be observed and routed into the host
+ * app's log pipeline, WITHOUT changing default behavior or polluting stdout.
+ *
+ * Usage (host app):
+ *   import { setAlipayLogLevel, setAlipayLogSink } from 'moltspay';
+ *   setAlipayLogLevel('info');                       // or env MOLTSPAY_ALIPAY_LOG=info
+ *   setAlipayLogSink((line) => myLogger.info(line));  // default: process.stderr
+ *
+ * Levels: 'off' (default) < 'info' (node timings + flow totals) < 'debug'
+ * (adds per-spawn start/exit and per-poll ticks). The level is read from
+ * MOLTSPAY_ALIPAY_LOG at load and can be overridden at runtime.
+ */
+type AlipayLogLevel = 'off' | 'info' | 'debug';
+/** A single structured log record. The sink receives both the line and this. */
+interface AlipayLogEvent {
+    /** ISO-8601 timestamp. */
+    ts: string;
+    level: 'info' | 'debug';
+    /** Event name: flow.start | flow.pending | flow.settled | flow.failed |
+     *  step.start | step.end | cli.exit | poll.tick. */
+    event: string;
+    /** Correlation id grouping all lines of one payment flow (session/tradeNo). */
+    flow?: string;
+    /** Node/step name, e.g. 'ensure-cli', 'payment-intent', '402-buyer-pay'. */
+    step?: string;
+    /** Elapsed milliseconds (on *.end / *.exit / flow.* total events). */
+    ms?: number;
+    [k: string]: unknown;
+}
+type AlipayLogSink = (line: string, event: AlipayLogEvent) => void;
+/** Set the verbosity at runtime (overrides the MOLTSPAY_ALIPAY_LOG env). */
+declare function setAlipayLogLevel(next: AlipayLogLevel): void;
+/** Current effective level. */
+declare function getAlipayLogLevel(): AlipayLogLevel;
+/** Route alipay log lines anywhere (host log pipeline, file, collector, …). */
+declare function setAlipayLogSink(fn: AlipayLogSink): void;
+declare const alipayLog: {
+    info: (event: string, fields?: Record<string, unknown>) => void;
+    debug: (event: string, fields?: Record<string, unknown>) => void;
+    /** True if anything at all would be logged (cheap guard for hot paths). */
+    enabled: () => boolean;
+};
+
+/**
+ * AlipayClient — the 8-step `pay402()` state machine (design §5.2.3).
+ *
+ * The Alipay skill guide §5 forbids skipping any step; each maps to one
+ * `alipay-bot` spawn. This class drives them in order and hands the caller a
+ * single terminal `AlipayPaymentResult`, so paying via Alipay looks the same
+ * as awaiting an EVM settle (design §5.2.3 "关键设计").
+ *
+ *   0.  ensureCli()                          version gate (≥ MIN_CLI_VERSION)
+ *   1b. alipay-bot payment-intent …          session handshake
+ *   2.  alipay-bot check-wallet              → NeedsWalletSetupError if unopened
+ *   3.  dump Payment-Needed → tmp file        (internal, user-invisible)
+ *   4.  alipay-bot 402-buyer-pay -f … -r …   → paymentUrl + tradeNo → onPaymentPending
+ *   5.  pollUntil(tradeNo)                    3s poll until paid / rejected / timeout
+ *   7.  return resource body
+ *   8.  alipay-bot 402-buyer-fulfillment-ack  fire-and-forget
+ */
+
+/** Clear the check-wallet cache (tests, or after the user (un)binds a wallet). */
+declare function resetWalletCache(): void;
+/** Clear the payment-intent skip-cache (tests, or after (un)bind / session reset). */
+declare function resetIntentCache(): void;
+
+export { type AlipayLogEvent, type AlipayLogLevel, type AlipayLogSink, alipayLog, getAlipayLogLevel, resetIntentCache, resetWalletCache, setAlipayLogLevel, setAlipayLogSink };