@payai/x402-evm 2.4.0 → 2.4.2

package/dist/esm/rpc-DULZzRne.d.mts

@@ -0,0 +1,13 @@
+type EvmSchemeConfig = {
+    rpcUrl?: string;
+};
+type EvmSchemeConfigByChainId = Record<number, EvmSchemeConfig>;
+type EvmSchemeOptions = EvmSchemeConfig | EvmSchemeConfigByChainId;
+/** @deprecated Use EvmSchemeConfig */
+type ExactEvmSchemeConfig = EvmSchemeConfig;
+/** @deprecated Use EvmSchemeConfigByChainId */
+type ExactEvmSchemeConfigByChainId = EvmSchemeConfigByChainId;
+/** @deprecated Use EvmSchemeOptions */
+type ExactEvmSchemeOptions = EvmSchemeOptions;
+
+export type { ExactEvmSchemeOptions as E, ExactEvmSchemeConfig as a, ExactEvmSchemeConfigByChainId as b, EvmSchemeOptions as c, EvmSchemeConfig as d, EvmSchemeConfigByChainId as e };

package/dist/esm/scheme-DtbSS4Fk.d.mts

@@ -0,0 +1,307 @@
+import { PaymentRequirements, SettleResponse, SchemeNetworkClient, SchemeClientHooks, PaymentPayloadContext, PaymentPayloadResult, PaymentRequired } from '@payai/x402/types';
+import { C as ClientEvmSigner } from './signer-tYS6Y46X.mjs';
+import { C as ChannelConfig } from './types-CF8P2-NM.mjs';
+import { c as EvmSchemeOptions } from './rpc-DULZzRne.mjs';
+import { B as BatchSettlementClientContext, C as ClientChannelStorage } from './storage-6W5MO46W.mjs';
+
+/**
+ * Caller-tunable policy controlling how the client sizes channel deposits.
+ */
+interface BatchSettlementDepositPolicy {
+    depositMultiplier?: number;
+}
+/**
+ * Return shape for custom deposit sizing.
+ */
+type BatchSettlementDepositStrategyResult = string | bigint | false | undefined;
+/**
+ * Information supplied before the client signs a deposit authorization.
+ */
+interface BatchSettlementDepositStrategyContext {
+    paymentRequirements: PaymentRequirements;
+    channelConfig: ChannelConfig;
+    channelId: `0x${string}`;
+    clientContext: BatchSettlementClientContext;
+    requestAmount: string;
+    maxClaimableAmount: string;
+    currentBalance: string;
+    minimumDepositAmount: string;
+    depositAmount: string;
+}
+/**
+ * Custom deposit sizing callback for initial deposits and top-ups.
+ */
+type BatchSettlementDepositStrategy = (context: BatchSettlementDepositStrategyContext) => BatchSettlementDepositStrategyResult | Promise<BatchSettlementDepositStrategyResult>;
+/**
+ * Full options object accepted by `BatchSettlementEvmScheme`. Either this or a
+ * bare {@link BatchSettlementDepositPolicy} can be passed as the second
+ * constructor argument.
+ */
+interface BatchSettlementEvmSchemeOptions {
+    depositPolicy?: BatchSettlementDepositPolicy;
+    /** Optional callback for app-specific deposit sizing or skipping. */
+    depositStrategy?: BatchSettlementDepositStrategy;
+    storage?: ClientChannelStorage;
+    salt?: `0x${string}`;
+    payerAuthorizer?: `0x${string}`;
+    rpcUrl?: string;
+    /** When set, EIP-712 vouchers are signed with this key; deposits still use the main `signer`. */
+    voucherSigner?: ClientEvmSigner;
+}
+/**
+ * Resolved options after merging defaults — used internally by the scheme,
+ * recovery, and refund modules.
+ */
+interface ResolvedClientOptions {
+    depositPolicy?: BatchSettlementDepositPolicy;
+    depositStrategy?: BatchSettlementDepositStrategy;
+    storage: ClientChannelStorage;
+    salt: `0x${string}`;
+    payerAuthorizer?: `0x${string}`;
+    voucherSigner?: ClientEvmSigner;
+    extensionRpcOptions?: EvmSchemeOptions;
+}
+/**
+ * Discriminates a full options object from a bare deposit-policy object.
+ *
+ * @param o - Constructor argument that may be options, deposit policy only, or undefined.
+ * @returns `true` when `o` is a {@link BatchSettlementEvmSchemeOptions} object.
+ */
+declare function isBatchSettlementEvmSchemeOptions(o: BatchSettlementEvmSchemeOptions | BatchSettlementDepositPolicy | undefined): o is BatchSettlementEvmSchemeOptions;
+/**
+ * Normalises the constructor's second argument into a uniform options shape.
+ *
+ * @param second - Optional second constructor argument (options or deposit policy).
+ * @returns Resolved storage, salt, deposit policy, and optional payer authorizer.
+ */
+declare function resolveClientOptions(second?: BatchSettlementEvmSchemeOptions | BatchSettlementDepositPolicy): ResolvedClientOptions;
+/**
+ * Validates a {@link BatchSettlementDepositPolicy}, throwing on invalid fields.
+ *
+ * @param policy - The policy to validate (no-op when undefined).
+ */
+declare function validateDepositPolicy(policy: BatchSettlementDepositPolicy | undefined): void;
+/**
+ * Computes the deposit amount based on the deposit multiplier.
+ *
+ * @param policy - Deposit policy controlling multiplier (may be undefined).
+ * @param requestAmount - Amount requested for this operation, in token base units.
+ * @returns Deposit amount string in token base units.
+ */
+declare function depositAmountForRequest(policy: BatchSettlementDepositPolicy | undefined, requestAmount: bigint): string;
+
+/**
+ * Runtime dependency bag shared by every storage-bound client helper (channel,
+ * recovery, refund) and the {@link BatchSettlementEvmScheme} class.
+ */
+interface BatchSettlementClientDeps {
+    signer: ClientEvmSigner;
+    storage: ClientChannelStorage;
+    salt: `0x${string}`;
+    payerAuthorizer?: `0x${string}`;
+    voucherSigner?: ClientEvmSigner;
+}
+/**
+ * Constructs the immutable {@link ChannelConfig} from payment requirements and
+ * a client deps bag (signer, salt, optional payerAuthorizer / voucherSigner).
+ *
+ * @param deps - Client identity inputs.
+ * @param paymentRequirements - Server payment requirements providing receiver, asset, and extra fields.
+ * @returns The ChannelConfig that uniquely identifies this payment channel.
+ */
+declare function buildChannelConfig(deps: BatchSettlementClientDeps, paymentRequirements: PaymentRequirements): ChannelConfig;
+/**
+ * Updates local channel state from a parsed `SettleResponse`.
+ *
+ * @param storage - Client channel storage.
+ * @param settle - The parsed settle response.
+ */
+declare function processSettleResponse(storage: ClientChannelStorage, settle: SettleResponse): Promise<void>;
+/**
+ * Reconciles local channel state with the outcome of a cooperative refund.
+ *
+ * Deletes the channel record when the post-refund balance is zero (full refund),
+ * otherwise updates local state from the server snapshot.
+ *
+ * @param storage - Client channel storage.
+ * @param channelKey - Lowercased channel id used as the storage key.
+ * @param settleExtra - The `extra` block from the refund settle response.
+ */
+declare function updateChannelAfterRefund(storage: ClientChannelStorage, channelKey: string, settleExtra: Record<string, unknown>): Promise<void>;
+/**
+ * Processes the `PAYMENT-RESPONSE` header after a successful request.
+ *
+ * Decodes the header into a `SettleResponse` and delegates to
+ * {@link processSettleResponse}.
+ *
+ * @param storage - Client channel storage.
+ * @param getHeader - Function to retrieve a response header by name.
+ */
+declare function processPaymentResponse(storage: ClientChannelStorage, getHeader: (name: string) => string | null | undefined): Promise<void>;
+/**
+ * Recovers a channel record from onchain state (useful after a cold start or
+ * channel record loss).
+ *
+ * @param deps - Signer + storage + identity inputs.
+ * @param paymentRequirements - Server payment requirements used to derive the ChannelConfig.
+ * @returns The recovered client context.
+ */
+declare function recoverChannel(deps: BatchSettlementClientDeps, paymentRequirements: PaymentRequirements): Promise<BatchSettlementClientContext>;
+/**
+ * Reads `channels(channelId)` returning `[balance, totalClaimed]`.
+ *
+ * @param signer - Signer providing `readContract`.
+ * @param channelId - The `bytes32` channel id to query.
+ * @returns Tuple of `[balance, totalClaimed]` as bigints.
+ */
+declare function readChannelBalanceAndTotalClaimed(signer: ClientEvmSigner, channelId: `0x${string}`): Promise<[bigint, bigint]>;
+/**
+ * Returns whether a local channel record exists for the given channel.
+ *
+ * @param storage - Client channel storage.
+ * @param channelId - The channel identifier to check.
+ * @returns `true` when a channel record is stored.
+ */
+declare function hasChannel(storage: ClientChannelStorage, channelId: string): Promise<boolean>;
+/**
+ * Returns the local channel context for a channel, if present.
+ *
+ * @param storage - Client channel storage.
+ * @param channelId - The channel identifier.
+ * @returns Stored context or `undefined`.
+ */
+declare function getChannel(storage: ClientChannelStorage, channelId: string): Promise<BatchSettlementClientContext | undefined>;
+
+/**
+ * Caller-facing options for {@link refundChannel}.
+ */
+interface RefundOptions {
+    /** Token base units to refund; omit for a full refund (drains remaining balance). */
+    amount?: string;
+    /** Custom fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof fetch;
+}
+/**
+ * Sends a cooperative refund request to the channel that backs `url`.
+ *
+ * Flow:
+ * 1. Probe the URL with `GET` (no payment) to obtain the route's payment requirements.
+ * 2. Build the `ChannelConfig` and resolve the local session (or recover it).
+ * 3. Sign a zero-charge refund voucher (`maxClaimableAmount = chargedCumulativeAmount`).
+ * 4. Send the voucher via `PAYMENT-SIGNATURE`. On a corrective 402, run the
+ *    standard recovery path and retry once.
+ * 5. Return the parsed `SettleResponse` from the server.
+ *
+ * @param ctx - Identity inputs (storage, signers, salt, payerAuthorizer).
+ * @param url - Any protected route on the channel to refund (the resource handler is bypassed).
+ * @param options - Optional `amount` (partial refund) and `fetch` override.
+ * @returns The settle response describing the refund outcome.
+ * @throws When the probe fails, the receiver lacks an authorizer, or recovery fails.
+ */
+declare function refundChannel(ctx: BatchSettlementClientDeps, url: string, options?: RefundOptions): Promise<SettleResponse>;
+
+/**
+ * Client-side implementation of the `batch-settlement` scheme for EVM networks.
+ *
+ * Builds payment payloads (deposit + voucher or voucher-only), processes server
+ * responses to update local session state via {@link processSettleResponse},
+ * handles corrective 402 resynchronisation via
+ * {@link processCorrectivePaymentRequired}, and supports on-demand cooperative
+ * refund requests via {@link refundChannel}.
+ */
+declare class BatchSettlementEvmScheme implements SchemeNetworkClient {
+    private readonly signer;
+    readonly scheme: "batch-settlement";
+    readonly schemeHooks: SchemeClientHooks;
+    private readonly storage;
+    private readonly depositPolicy;
+    private readonly depositStrategy;
+    private readonly salt;
+    private readonly payerAuthorizer;
+    private readonly voucherSigner;
+    private readonly extensionRpcOptions;
+    /**
+     * Constructs a batched client scheme.
+     *
+     * @param signer - Client EVM wallet used for signing vouchers and ERC-3009 authorizations.
+     * @param optionsOrPolicy - Either a full options object or a bare deposit-policy.
+     */
+    constructor(signer: ClientEvmSigner, optionsOrPolicy?: BatchSettlementEvmSchemeOptions | BatchSettlementDepositPolicy);
+    /**
+     * Creates the payment payload for a batched request.
+     *
+     * If the channel has no onchain deposit (or needs a top-up), builds an
+     * ERC-3009 deposit payload bundled with a voucher. Otherwise, signs and
+     * returns a voucher-only payload.
+     *
+     * @param x402Version - Protocol version for the payload envelope.
+     * @param paymentRequirements - Server payment requirements (scheme, network, asset, amount).
+     * @param context - Optional payment payload context with extension hints.
+     * @returns A {@link PaymentPayloadResult} ready to be sent as the `X-PAYMENT` header.
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements, context?: PaymentPayloadContext): Promise<PaymentPayloadResult>;
+    /**
+     * Sends a cooperative refund request.
+     *
+     * @param url - The route URL backing the channel to refund.
+     * @param options - Optional `amount` (partial refund) and `fetch` override.
+     * @returns The settle response describing the refund outcome.
+     */
+    refund(url: string, options?: RefundOptions): Promise<SettleResponse>;
+    /**
+     * Updates local channel state from a settle response.
+     *
+     * @param settle - The parsed settle response from the server.
+     * @returns Resolves when local channel state has been updated.
+     */
+    processSettleResponse(settle: SettleResponse): Promise<void>;
+    /**
+     * Resyncs local channel state from a corrective 402 response.
+     *
+     * @param paymentRequired - The decoded 402 response body.
+     * @returns `true` if local state was successfully resynced and a retry is warranted.
+     */
+    processCorrectivePaymentRequired(paymentRequired: PaymentRequired): Promise<boolean>;
+    /**
+     * Builds the immutable {@link ChannelConfig} for a given set of payment
+     * requirements, using the scheme's own signer and salt.
+     *
+     * @param paymentRequirements - Server payment requirements for the channel.
+     * @returns The channel config that uniquely identifies the payment channel.
+     */
+    buildChannelConfig(paymentRequirements: PaymentRequirements): ChannelConfig;
+    /**
+     * Resolves the deposit amount after applying the optional custom strategy.
+     *
+     * @param context - Deposit attempt context exposed to the strategy.
+     * @returns The deposit amount to sign, or `false` to skip this deposit attempt.
+     */
+    private resolveDepositAmount;
+    /**
+     * Normalizes and validates a strategy-provided base-unit deposit amount.
+     *
+     * @param value - Strategy-provided string or bigint amount.
+     * @returns Normalized decimal string.
+     */
+    private normalizeStrategyDepositAmount;
+    /**
+     * Signs a voucher-only payment payload for the current channel.
+     *
+     * @param x402Version - Protocol version for the payload envelope.
+     * @param channelId - Channel identifier for the voucher.
+     * @param maxClaimableAmount - Cumulative ceiling for the voucher.
+     * @param network - CAIP-2 network identifier.
+     * @param config - Immutable channel configuration.
+     * @returns Voucher-only payment payload.
+     */
+    private createVoucherPayload;
+    /**
+     * Bundles the class state into the {@link BatchSettlementClientDeps} shape
+     * consumed by the `channel`, `recovery`, and `refund` modules.
+     *
+     * @returns Client deps wrapping the scheme's own signer and storage.
+     */
+    private deps;
+}
+
+export { BatchSettlementEvmScheme as B, type RefundOptions as R, type BatchSettlementClientDeps as a, type BatchSettlementDepositPolicy as b, type BatchSettlementDepositStrategy as c, type BatchSettlementDepositStrategyContext as d, type BatchSettlementDepositStrategyResult as e, type BatchSettlementEvmSchemeOptions as f, depositAmountForRequest as g, resolveClientOptions as h, isBatchSettlementEvmSchemeOptions as i, type ResolvedClientOptions as j, buildChannelConfig as k, getChannel as l, hasChannel as m, processSettleResponse as n, readChannelBalanceAndTotalClaimed as o, processPaymentResponse as p, recoverChannel as q, refundChannel as r, updateChannelAfterRefund as u, validateDepositPolicy as v };

package/dist/esm/scheme-gtqAIYPJ.d.mts

@@ -0,0 +1,47 @@
+import { SchemeNetworkClient, PaymentRequirements, PaymentPayloadContext, PaymentPayloadResult } from '@payai/x402/types';
+import { C as ClientEvmSigner } from './signer-tYS6Y46X.mjs';
+import { E as ExactEvmSchemeOptions } from './rpc-DULZzRne.mjs';
+
+/**
+ * EVM client implementation for the Exact payment scheme.
+ * Supports both EIP-3009 (transferWithAuthorization) and Permit2 flows.
+ *
+ * Routes to the appropriate authorization method based on
+ * `requirements.extra.assetTransferMethod`. Defaults to EIP-3009
+ * for backward compatibility with older facilitators.
+ *
+ * When the server advertises `eip2612GasSponsoring` and the asset transfer
+ * method is `permit2`, the scheme automatically signs an EIP-2612 permit
+ * if the user lacks Permit2 approval. This requires `readContract` on the signer.
+ */
+declare class ExactEvmScheme implements SchemeNetworkClient {
+    private readonly signer;
+    private readonly options?;
+    readonly scheme = "exact";
+    /**
+     * Creates a new ExactEvmClient instance.
+     *
+     * @param signer - The EVM signer for client operations.
+     *   Base flow only requires `address` + `signTypedData`.
+     *   Extension enrichment (EIP-2612 / ERC-20 approval sponsoring) additionally
+     *   requires optional capabilities like `readContract` and tx signing helpers.
+     * @param options - Optional RPC configuration used to backfill extension capabilities.
+     */
+    constructor(signer: ClientEvmSigner, options?: ExactEvmSchemeOptions | undefined);
+    /**
+     * Creates a payment payload for the Exact scheme.
+     * Routes to EIP-3009 or Permit2 based on requirements.extra.assetTransferMethod.
+     *
+     * For Permit2 flows, if the server advertises `eip2612GasSponsoring` and the
+     * signer supports `readContract`, automatically signs an EIP-2612 permit
+     * when Permit2 allowance is insufficient.
+     *
+     * @param x402Version - The x402 protocol version
+     * @param paymentRequirements - The payment requirements
+     * @param context - Optional context with server-declared extensions
+     * @returns Promise resolving to a payment payload result (with optional extensions)
+     */
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements, context?: PaymentPayloadContext): Promise<PaymentPayloadResult>;
+}
+
+export { ExactEvmScheme as E };

package/dist/esm/signer-tYS6Y46X.d.mts

@@ -0,0 +1,170 @@
+import { Log } from 'viem';
+
+/**
+ * ClientEvmSigner - Used by x402 clients to sign payment authorizations.
+ *
+ * Typically a viem WalletClient extended with publicActions:
+ * ```typescript
+ * const client = createWalletClient({
+ *   account: privateKeyToAccount('0x...'),
+ *   chain: baseSepolia,
+ *   transport: http(),
+ * }).extend(publicActions);
+ * ```
+ *
+ * Or composed via `toClientEvmSigner(account, publicClient)`.
+ */
+type ClientEvmSigner = {
+    readonly address: `0x${string}`;
+    signTypedData(message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    /**
+     * Optional on-chain reads.
+     * Required only for extension enrichment (EIP-2612 / ERC-20 approval).
+     */
+    readContract?(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    /**
+     * Optional: Signs a raw EIP-1559 transaction without broadcasting.
+     * Required for ERC-20 approval gas sponsoring when the token lacks EIP-2612.
+     */
+    signTransaction?(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        nonce: number;
+        gas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+        chainId: number;
+    }): Promise<`0x${string}`>;
+    /**
+     * Optional: Gets the current transaction count (nonce) for an address.
+     * Required for ERC-20 approval gas sponsoring.
+     */
+    getTransactionCount?(args: {
+        address: `0x${string}`;
+    }): Promise<number>;
+    /**
+     * Optional: Estimates current gas fees per gas.
+     * Required for ERC-20 approval gas sponsoring.
+     */
+    estimateFeesPerGas?(): Promise<{
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    }>;
+};
+/**
+ * FacilitatorEvmSigner - Used by x402 facilitators to verify and settle payments
+ * This is typically a viem PublicClient + WalletClient combination that can
+ * read contract state, verify signatures, write transactions, and wait for receipts
+ *
+ * Supports multiple addresses for load balancing, key rotation, and high availability
+ */
+type FacilitatorEvmSigner = {
+    /**
+     * Get all addresses this facilitator can use for signing
+     * Enables dynamic address selection for load balancing and key rotation
+     */
+    getAddresses(): readonly `0x${string}`[];
+    readContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    verifyTypedData(args: {
+        address: `0x${string}`;
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+        signature: `0x${string}`;
+    }): Promise<boolean>;
+    writeContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        /** Optional gas limit. When provided, skips eth_estimateGas simulation. */
+        gas?: bigint;
+    }): Promise<`0x${string}`>;
+    sendTransaction(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }): Promise<`0x${string}`>;
+    waitForTransactionReceipt(args: {
+        hash: `0x${string}`;
+    }): Promise<{
+        status: string;
+        logs?: readonly Log[];
+    }>;
+    getCode(args: {
+        address: `0x${string}`;
+    }): Promise<`0x${string}` | undefined>;
+};
+/**
+ * Composes a ClientEvmSigner from a local account and a public client.
+ *
+ * Use this when your signer (e.g., `privateKeyToAccount`) doesn't have
+ * `readContract`. The `publicClient` provides the on-chain read capability.
+ *
+ * Alternatively, use a WalletClient extended with publicActions directly:
+ * ```typescript
+ * const signer = createWalletClient({
+ *   account: privateKeyToAccount('0x...'),
+ *   chain: baseSepolia,
+ *   transport: http(),
+ * }).extend(publicActions);
+ * ```
+ *
+ * @param signer - A signer with `address` and `signTypedData` (and optionally `readContract`)
+ * @param publicClient - A client with optional read/nonce/fee helpers
+ * @param publicClient.readContract - The readContract method from the public client
+ * @param publicClient.getTransactionCount - Optional getTransactionCount for ERC-20 approval
+ * @param publicClient.estimateFeesPerGas - Optional estimateFeesPerGas for ERC-20 approval
+ * @returns A ClientEvmSigner with any available optional capabilities
+ *
+ * @example
+ * ```typescript
+ * const account = privateKeyToAccount("0x...");
+ * const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+ * const signer = toClientEvmSigner(account, publicClient);
+ * ```
+ */
+declare function toClientEvmSigner(signer: Omit<ClientEvmSigner, "readContract"> & {
+    readContract?: ClientEvmSigner["readContract"];
+}, publicClient?: {
+    readContract(args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    getTransactionCount?(args: {
+        address: `0x${string}`;
+    }): Promise<number>;
+    estimateFeesPerGas?(): Promise<{
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    }>;
+}): ClientEvmSigner;
+/**
+ * Converts a viem client with single address to a FacilitatorEvmSigner
+ * Wraps the single address in a getAddresses() function for compatibility
+ *
+ * @param client - The client to convert (must have 'address' property)
+ * @returns FacilitatorEvmSigner with getAddresses() support
+ */
+declare function toFacilitatorEvmSigner(client: Omit<FacilitatorEvmSigner, "getAddresses"> & {
+    address: `0x${string}`;
+}): FacilitatorEvmSigner;
+
+export { type ClientEvmSigner as C, type FacilitatorEvmSigner as F, toFacilitatorEvmSigner as a, toClientEvmSigner as t };

package/dist/esm/storage-6W5MO46W.d.mts

@@ -0,0 +1,50 @@
+/**
+ * Client-side channel fields mirrored from PAYMENT-RESPONSE / recovery flows.
+ */
+interface BatchSettlementClientContext {
+    /** Current cumulative amount charged by the server for this channel */
+    chargedCumulativeAmount?: string;
+    /** Current onchain channel balance */
+    balance?: string;
+    /** Total claimed onchain */
+    totalClaimed?: string;
+    /** Latest client-signed maxClaimableAmount cap (after corrective recovery, optional) */
+    signedMaxClaimable?: string;
+    /** Client voucher signature for {@link signedMaxClaimable} (optional) */
+    signature?: `0x${string}`;
+}
+interface ClientChannelStorage {
+    get(key: string): Promise<BatchSettlementClientContext | undefined>;
+    set(key: string, context: BatchSettlementClientContext): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Default in-memory {@link ClientChannelStorage} (channel records do not survive process restart).
+ */
+declare class InMemoryClientChannelStorage implements ClientChannelStorage {
+    private readonly channels;
+    /**
+     * Returns the channel record for `key` if present.
+     *
+     * @param key - Channel storage key (channelId).
+     * @returns Persisted context or undefined.
+     */
+    get(key: string): Promise<BatchSettlementClientContext | undefined>;
+    /**
+     * Stores or replaces the channel record for `key`.
+     *
+     * @param key - Channel storage key.
+     * @param context - Channel fields to persist.
+     * @returns Resolves when stored.
+     */
+    set(key: string, context: BatchSettlementClientContext): Promise<void>;
+    /**
+     * Removes the channel record for `key` if it exists.
+     *
+     * @param key - Channel storage key.
+     * @returns Resolves when removed.
+     */
+    delete(key: string): Promise<void>;
+}
+
+export { type BatchSettlementClientContext as B, type ClientChannelStorage as C, InMemoryClientChannelStorage as I };

package/dist/esm/storage-sZ1CDS4P.d.mts

@@ -0,0 +1,81 @@
+import { C as ChannelConfig } from './types-CF8P2-NM.mjs';
+
+interface Channel {
+    channelId: string;
+    channelConfig: ChannelConfig;
+    chargedCumulativeAmount: string;
+    signedMaxClaimable: string;
+    signature: string;
+    balance: string;
+    totalClaimed: string;
+    withdrawRequestedAt: number;
+    refundNonce: number;
+    onchainSyncedAt?: number;
+    lastRequestTimestamp: number;
+    pendingRequest?: PendingRequest;
+}
+interface PendingRequest {
+    pendingId: string;
+    signedMaxClaimable: string;
+    expiresAt: number;
+}
+interface ChannelUpdateResult {
+    channel: Channel | undefined;
+    status: "updated" | "unchanged" | "deleted";
+}
+interface ChannelStorage {
+    get(channelId: string): Promise<Channel | undefined>;
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record.
+     *
+     * Implementations must guarantee that no concurrent mutation can interleave between
+     * reading `current` and writing the callback result for all application instances that
+     * share the backend. The in-memory backend only provides this guarantee inside one JS
+     * runtime; production multi-instance deployments need storage with backend-level atomic
+     * conditional mutation, such as Redis/Valkey Lua scripts, SQL transactions, or Durable Objects.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+}
+/**
+ * In-memory {@link ChannelStorage} backed by a Map keyed by `channelId`.
+ */
+declare class InMemoryChannelStorage implements ChannelStorage {
+    private readonly channels;
+    private readonly channelLocks;
+    /**
+     * Returns the channel record for a channel, if present.
+     *
+     * @param channelId - The channel identifier.
+     * @returns The channel record or undefined when not found.
+     */
+    get(channelId: string): Promise<Channel | undefined>;
+    /**
+     * Lists all stored channel records.
+     *
+     * @returns All channel records in storage.
+     */
+    list(): Promise<Channel[]>;
+    /**
+     * Atomically inspects and mutates a channel record while holding a per-channel lock.
+     *
+     * @param channelId - The channel identifier.
+     * @param update - Mutation callback. Return `undefined` to delete, or `current` to leave unchanged.
+     * @returns The final stored channel and whether storage updated, stayed unchanged, or deleted.
+     */
+    updateChannel(channelId: string, update: (current: Channel | undefined) => Channel | undefined): Promise<ChannelUpdateResult>;
+    /**
+     * Runs `fn` after any prior locked work for the same channel key has finished.
+     *
+     * @param key - Lowercased channel id used as the lock key.
+     * @param fn - Async work to run while holding the logical per-channel lock.
+     * @returns The resolved result of `fn`.
+     */
+    private withChannelLock;
+}
+
+export { type ChannelStorage as C, InMemoryChannelStorage as I, type PendingRequest as P, type Channel as a, type ChannelUpdateResult as b };