@payai/x402-evm 2.4.1 → 2.4.2

package/dist/cjs/batch-settlement/client/file-storage.d.ts

@@ -0,0 +1,47 @@
+import { F as FileChannelStorageOptions } from '../../types-CF8P2-NM.js';
+import { C as ClientChannelStorage, B as BatchSettlementClientContext } from '../../storage-6W5MO46W.js';
+import 'viem';
+
+/**
+ * Node.js file-backed {@link ClientChannelStorage} for the batched client scheme.
+ * Each channel's context is persisted as `{root}/client/{channelId}.json` so that channel
+ * records survive process restarts.
+ */
+declare class FileClientChannelStorage implements ClientChannelStorage {
+    private readonly root;
+    /**
+     * Creates file-backed client channel storage under the given root directory.
+     *
+     * @param options - Configuration including the storage root directory.
+     */
+    constructor(options: FileChannelStorageOptions);
+    /**
+     * Loads the stored client context for a channel, if present.
+     *
+     * @param key - Channel storage key (typically a lowercased channelId).
+     * @returns Parsed context or `undefined` when the file is missing.
+     */
+    get(key: string): Promise<BatchSettlementClientContext | undefined>;
+    /**
+     * Persists the client context for a channel.
+     *
+     * @param key - Channel storage key.
+     * @param context - Context record to write.
+     */
+    set(key: string, context: BatchSettlementClientContext): Promise<void>;
+    /**
+     * Removes the persisted context file for a channel, if it exists.
+     *
+     * @param key - Channel storage key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Absolute path to the JSON file for a channel.
+     *
+     * @param key - Channel storage key.
+     * @returns Filesystem path under `{root}/client/...`.
+     */
+    private filePath;
+}
+
+export { FileChannelStorageOptions, FileClientChannelStorage };

package/dist/cjs/batch-settlement/client/file-storage.js

@@ -0,0 +1,116 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/batch-settlement/client/fileStorage.ts
+var fileStorage_exports = {};
+__export(fileStorage_exports, {
+  FileClientChannelStorage: () => FileClientChannelStorage
+});
+module.exports = __toCommonJS(fileStorage_exports);
+var import_promises2 = require("fs/promises");
+var import_node_path2 = require("path");
+
+// src/batch-settlement/storage-utils.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+function isNodeEnoent(err) {
+  if (!err || typeof err !== "object" || !("code" in err)) return false;
+  return err.code === "ENOENT";
+}
+async function readJsonFile(filePath) {
+  try {
+    const raw = await (0, import_promises.readFile)(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (isNodeEnoent(err)) return void 0;
+    throw err;
+  }
+}
+async function writeJsonAtomic(filePath, value) {
+  const dir = (0, import_node_path.dirname)(filePath);
+  await (0, import_promises.mkdir)(dir, { recursive: true });
+  const tmp = (0, import_node_path.join)(dir, `.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  const body = `${JSON.stringify(value, null, 2)}
+`;
+  await (0, import_promises.writeFile)(tmp, body, "utf8");
+  try {
+    await (0, import_promises.rename)(tmp, filePath);
+  } catch {
+    await (0, import_promises.unlink)(filePath).catch(() => {
+    });
+    await (0, import_promises.rename)(tmp, filePath);
+  }
+}
+
+// src/batch-settlement/client/fileStorage.ts
+var FileClientChannelStorage = class {
+  /**
+   * Creates file-backed client channel storage under the given root directory.
+   *
+   * @param options - Configuration including the storage root directory.
+   */
+  constructor(options) {
+    this.root = options.directory;
+  }
+  /**
+   * Loads the stored client context for a channel, if present.
+   *
+   * @param key - Channel storage key (typically a lowercased channelId).
+   * @returns Parsed context or `undefined` when the file is missing.
+   */
+  async get(key) {
+    return readJsonFile(this.filePath(key));
+  }
+  /**
+   * Persists the client context for a channel.
+   *
+   * @param key - Channel storage key.
+   * @param context - Context record to write.
+   */
+  async set(key, context) {
+    await writeJsonAtomic(this.filePath(key), context);
+  }
+  /**
+   * Removes the persisted context file for a channel, if it exists.
+   *
+   * @param key - Channel storage key.
+   */
+  async delete(key) {
+    try {
+      await (0, import_promises2.unlink)(this.filePath(key));
+    } catch (err) {
+      if (isNodeEnoent(err)) return;
+      throw err;
+    }
+  }
+  /**
+   * Absolute path to the JSON file for a channel.
+   *
+   * @param key - Channel storage key.
+   * @returns Filesystem path under `{root}/client/...`.
+   */
+  filePath(key) {
+    return (0, import_node_path2.join)(this.root, "client", `${key.toLowerCase()}.json`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileClientChannelStorage
+});
+//# sourceMappingURL=file-storage.js.map

package/dist/cjs/batch-settlement/client/file-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/batch-settlement/client/fileStorage.ts","../../../../src/batch-settlement/storage-utils.ts"],"sourcesContent":["import { unlink } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { isNodeEnoent, readJsonFile, writeJsonAtomic } from \"../storage-utils\";\nimport type { FileChannelStorageOptions } from \"../types\";\nimport type { ClientChannelStorage, BatchSettlementClientContext } from \"./storage\";\n\nexport type { FileChannelStorageOptions };\n\n/**\n * Node.js file-backed {@link ClientChannelStorage} for the batched client scheme.\n * Each channel's context is persisted as `{root}/client/{channelId}.json` so that channel\n * records survive process restarts.\n */\nexport class FileClientChannelStorage implements ClientChannelStorage {\n  private readonly root: string;\n\n  /**\n   * Creates file-backed client channel storage under the given root directory.\n   *\n   * @param options - Configuration including the storage root directory.\n   */\n  constructor(options: FileChannelStorageOptions) {\n    this.root = options.directory;\n  }\n\n  /**\n   * Loads the stored client context for a channel, if present.\n   *\n   * @param key - Channel storage key (typically a lowercased channelId).\n   * @returns Parsed context or `undefined` when the file is missing.\n   */\n  async get(key: string): Promise<BatchSettlementClientContext | undefined> {\n    return readJsonFile<BatchSettlementClientContext>(this.filePath(key));\n  }\n\n  /**\n   * Persists the client context for a channel.\n   *\n   * @param key - Channel storage key.\n   * @param context - Context record to write.\n   */\n  async set(key: string, context: BatchSettlementClientContext): Promise<void> {\n    await writeJsonAtomic(this.filePath(key), context);\n  }\n\n  /**\n   * Removes the persisted context file for a channel, if it exists.\n   *\n   * @param key - Channel storage key.\n   */\n  async delete(key: string): Promise<void> {\n    try {\n      await unlink(this.filePath(key));\n    } catch (err: unknown) {\n      if (isNodeEnoent(err)) return;\n      throw err;\n    }\n  }\n\n  /**\n   * Absolute path to the JSON file for a channel.\n   *\n   * @param key - Channel storage key.\n   * @returns Filesystem path under `{root}/client/...`.\n   */\n  private filePath(key: string): string {\n    return join(this.root, \"client\", `${key.toLowerCase()}.json`);\n  }\n}\n","import { mkdir, readFile, rename, unlink, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\n/**\n * Returns true when `err` is a Node.js `ENOENT` filesystem error (file does not exist).\n *\n * @param err - The thrown value to inspect.\n * @returns `true` for `ENOENT`, `false` for any other value or error code.\n */\nexport function isNodeEnoent(err: unknown): boolean {\n  if (!err || typeof err !== \"object\" || !(\"code\" in err)) return false;\n  return (err as NodeJS.ErrnoException).code === \"ENOENT\";\n}\n\n/**\n * Reads a JSON file and parses it. Returns `undefined` if the file does not exist.\n * Other errors (permission, malformed JSON) are rethrown.\n *\n * @param filePath - Path to the JSON file.\n * @returns Parsed value, or `undefined` for `ENOENT`.\n */\nexport async function readJsonFile<T>(filePath: string): Promise<T | undefined> {\n  try {\n    const raw = await readFile(filePath, \"utf8\");\n    return JSON.parse(raw) as T;\n  } catch (err: unknown) {\n    if (isNodeEnoent(err)) return undefined;\n    throw err;\n  }\n}\n\n/**\n * Writes JSON to `filePath` atomically (temp file in the same directory, then rename).\n * Creates parent directories as needed.\n *\n * @param filePath - Destination file path; parent dirs are created if missing.\n * @param value - JSON-serializable value to persist.\n */\nexport async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {\n  const dir = dirname(filePath);\n  await mkdir(dir, { recursive: true });\n  const tmp = join(dir, `.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);\n  const body = `${JSON.stringify(value, null, 2)}\\n`;\n  await writeFile(tmp, body, \"utf8\");\n  try {\n    await rename(tmp, filePath);\n  } catch {\n    // On Windows, rename() onto an existing file throws EEXIST; unlink + rename is intentional.\n    await unlink(filePath).catch(() => {});\n    await rename(tmp, filePath);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAAA,mBAAuB;AACvB,IAAAC,oBAAqB;;;ACDrB,sBAA2D;AAC3D,uBAA8B;AAQvB,SAAS,aAAa,KAAuB;AAClD,MAAI,CAAC,OAAO,OAAO,QAAQ,YAAY,EAAE,UAAU,KAAM,QAAO;AAChE,SAAQ,IAA8B,SAAS;AACjD;AASA,eAAsB,aAAgB,UAA0C;AAC9E,MAAI;AACF,UAAM,MAAM,UAAM,0BAAS,UAAU,MAAM;AAC3C,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,SAAS,KAAc;AACrB,QAAI,aAAa,GAAG,EAAG,QAAO;AAC9B,UAAM;AAAA,EACR;AACF;AASA,eAAsB,gBAAgB,UAAkB,OAA+B;AACrF,QAAM,UAAM,0BAAQ,QAAQ;AAC5B,YAAM,uBAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AACpC,QAAM,UAAM,uBAAK,KAAK,IAAI,QAAQ,GAAG,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC,MAAM;AAChG,QAAM,OAAO,GAAG,KAAK,UAAU,OAAO,MAAM,CAAC,CAAC;AAAA;AAC9C,YAAM,2BAAU,KAAK,MAAM,MAAM;AACjC,MAAI;AACF,cAAM,wBAAO,KAAK,QAAQ;AAAA,EAC5B,QAAQ;AAEN,cAAM,wBAAO,QAAQ,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACrC,cAAM,wBAAO,KAAK,QAAQ;AAAA,EAC5B;AACF;;;ADrCO,IAAM,2BAAN,MAA+D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQpE,YAAY,SAAoC;AAC9C,SAAK,OAAO,QAAQ;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,IAAI,KAAgE;AACxE,WAAO,aAA2C,KAAK,SAAS,GAAG,CAAC;AAAA,EACtE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,IAAI,KAAa,SAAsD;AAC3E,UAAM,gBAAgB,KAAK,SAAS,GAAG,GAAG,OAAO;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,OAAO,KAA4B;AACvC,QAAI;AACF,gBAAM,yBAAO,KAAK,SAAS,GAAG,CAAC;AAAA,IACjC,SAAS,KAAc;AACrB,UAAI,aAAa,GAAG,EAAG;AACvB,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,SAAS,KAAqB;AACpC,eAAO,wBAAK,KAAK,MAAM,UAAU,GAAG,IAAI,YAAY,CAAC,OAAO;AAAA,EAC9D;AACF;","names":["import_promises","import_node_path"]}

package/dist/cjs/batch-settlement/client/index.d.ts

@@ -0,0 +1,111 @@
+import { a as BatchSettlementClientDeps } from '../../scheme-CvkPJXBD.js';
+export { b as BatchSettlementDepositPolicy, c as BatchSettlementDepositStrategy, d as BatchSettlementDepositStrategyContext, e as BatchSettlementDepositStrategyResult, B as BatchSettlementEvmScheme, f as BatchSettlementEvmSchemeOptions, R as RefundOptions, j as ResolvedClientOptions, k as buildChannelConfig, g as depositAmountForRequest, l as getChannel, m as hasChannel, i as isBatchSettlementEvmSchemeOptions, p as processPaymentResponse, n as processSettleResponse, o as readChannelBalanceAndTotalClaimed, q as recoverChannel, r as refundChannel, h as resolveClientOptions, u as updateChannelAfterRefund, v as validateDepositPolicy } from '../../scheme-CvkPJXBD.js';
+export { B as BatchSettlementClientContext, C as ClientChannelStorage, I as InMemoryClientChannelStorage } from '../../storage-6W5MO46W.js';
+import { PaymentRequirements, PaymentPayloadResult, SchemeClientHooks, PaymentRequired } from '@payai/x402/types';
+import { C as ClientEvmSigner } from '../../signer-tYS6Y46X.js';
+import { C as ChannelConfig, d as BatchSettlementVoucherFields, t as BatchSettlementChannelStateExtra, u as BatchSettlementVoucherStateExtra } from '../../types-CF8P2-NM.js';
+import { PaymentResponseContext } from '@payai/x402/client';
+import '../../rpc-DULZzRne.js';
+import 'viem';
+
+/**
+ * Computes the chain-bound channel id from a {@link ChannelConfig} struct.
+ *
+ * @param config - The immutable channel configuration.
+ * @param networkOrChainId - CAIP-2 network identifier or numeric EVM chain id.
+ * @returns The `bytes32` channel id as a hex string.
+ */
+declare function computeChannelId(config: ChannelConfig, networkOrChainId: string | number): `0x${string}`;
+
+/**
+ * Creates a deposit payload that bundles an ERC-3009 `receiveWithAuthorization` approval
+ * together with a cumulative voucher signature.
+ *
+ * When the facilitator submits this payload onchain, the contract atomically transfers
+ * tokens from the payer into the channel and records the initial voucher.
+ *
+ * @param signer - Client wallet used to sign the ERC-3009 authorization (`from` = payer).
+ * @param x402Version - Protocol version to embed in the payload envelope.
+ * @param paymentRequirements - Server-provided payment requirements (asset, network, amount, etc.).
+ * @param channelConfig - Immutable channel configuration (payer, receiver, token, …).
+ * @param depositAmount - Number of tokens (decimal string) to deposit into the channel.
+ * @param maxClaimableAmount - Cumulative ceiling for the accompanying voucher.
+ * @param voucherSigner - Optional key that signs the voucher; defaults to `signer` (same as payer).
+ * @returns A {@link PaymentPayloadResult} containing the signed deposit + voucher payload.
+ */
+declare function createBatchSettlementEIP3009DepositPayload(signer: ClientEvmSigner, x402Version: number, paymentRequirements: PaymentRequirements, channelConfig: ChannelConfig, depositAmount: string, maxClaimableAmount: string, voucherSigner?: ClientEvmSigner): Promise<PaymentPayloadResult>;
+
+/**
+ * Signs a cumulative voucher using the client's wallet.
+ *
+ * The voucher authorises the receiver to claim up to `maxClaimableAmount` from the
+ * channel identified by `channelId`.  The signature covers the EIP-712 `Voucher` struct
+ * under the batched domain.
+ *
+ * @param signer - Client wallet used to produce the EIP-712 signature.
+ * @param channelId - Identifier of the payment channel. This is the EIP-712
+ * hash of the `ChannelConfig` typed data for the batch settlement domain; see
+ * `computeChannelId`.
+ * @param maxClaimableAmount - Cumulative ceiling the receiver may claim (decimal string in token units).
+ * @param network - CAIP-2 network identifier (e.g. `eip155:84532`).
+ * @returns Signed voucher fields ready to be included in a payment payload.
+ */
+declare function signVoucher(signer: ClientEvmSigner, channelId: `0x${string}`, maxClaimableAmount: string, network: string): Promise<BatchSettlementVoucherFields>;
+
+/**
+ * Creates storage-aware client hooks for batch-settlement payment responses.
+ *
+ * @param deps - Client identity and storage inputs.
+ * @returns Scheme hooks for response reconciliation and corrective recovery.
+ */
+declare function createBatchSettlementClientHooks(deps: BatchSettlementClientDeps): SchemeClientHooks;
+/**
+ * Reconciles batch-settlement client state after a paid request or refund attempt.
+ *
+ * @param deps - Client identity and storage inputs.
+ * @param ctx - Core payment response context.
+ * @returns A recovery signal when corrective recovery succeeds.
+ */
+declare function handleBatchSettlementPaymentResponse(deps: BatchSettlementClientDeps, ctx: PaymentResponseContext): Promise<void | {
+    recovered: true;
+}>;
+
+/**
+ * Handles a corrective 402 response from the server when the client's
+ * cumulative base is out of sync.
+ *
+ * Validates the server-provided state (chargedCumulativeAmount,
+ * signedMaxClaimable, signature) against onchain data and the client's own
+ * signing key, then updates the local channel state if everything checks out.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param paymentRequired - The decoded 402 response body.
+ * @returns `true` if the channel state was successfully resynced and the request can be retried.
+ */
+declare function processCorrectivePaymentRequired(deps: BatchSettlementClientDeps, paymentRequired: PaymentRequired): Promise<boolean>;
+/**
+ * Recovers channel state from a corrective 402 that includes a server-provided
+ * voucher signature. Verifies the signature matches the client's own signing
+ * key before accepting.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param accept - Batch settlement payment requirements from the corrective 402.
+ * @param channelState - Server channel snapshot from `accept.extra.channelState`.
+ * @param voucherState - Latest signed voucher proof from `accept.extra.voucherState`.
+ * @returns `true` when local channel state was updated successfully.
+ */
+declare function recoverFromSignature(deps: BatchSettlementClientDeps, accept: PaymentRequirements, channelState: BatchSettlementChannelStateExtra, voucherState: BatchSettlementVoucherStateExtra): Promise<boolean>;
+/**
+ * Recovers channel state purely from onchain state when the server has no stored
+ * voucher (e.g. after a cooperative refund deleted the channel record). The onchain
+ * `totalClaimed` becomes the new baseline — no signature verification is
+ * needed because the contract is the source of truth when no outstanding
+ * voucher exists.
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param accept - Batch settlement payment requirements from the corrective 402.
+ * @returns `true` when local channel state was updated from onchain data.
+ */
+declare function recoverFromOnChainState(deps: BatchSettlementClientDeps, accept: PaymentRequirements): Promise<boolean>;
+
+export { BatchSettlementClientDeps, computeChannelId, createBatchSettlementClientHooks, createBatchSettlementEIP3009DepositPayload, handleBatchSettlementPaymentResponse, processCorrectivePaymentRequired, recoverFromOnChainState, recoverFromSignature, signVoucher };