mppx 0.17.3 → 0.17.4

package/dist/cloudflare/Channels.js

@@ -0,0 +1,325 @@
+import { zeroAddress } from 'viem';
+import { ChannelNotFoundError, VerificationFailedError } from '../Errors.js';
+import * as Store from '../Store.js';
+import { parsePkhSource } from '../tempo/internal/proof.js';
+import { tip20ChannelEscrow } from '../tempo/session/precompile/Protocol.js';
+import { isPrecompileState } from '../tempo/session/server/ChannelStore.js';
+import { settle as settleChannel, SettlementCheckpointError, } from '../tempo/session/server/Settlement.js';
+import { isChannelState, pendingClose, unsettledAmount } from './ChannelStore.js';
+/**
+ * Tempo session channel storage on a {@link ChannelStore} Durable Object namespace, to spread
+ * into `tempo.session()`: `store` keeps each channel in its own object, which schedules its
+ * settlement, and `resolveChannelId` finds the payer's open channel to the same payee, token,
+ * escrow, operator and chain, so a client that lost its state resumes it instead of opening another.
+ * The lookup needs the payer's identity, which only a `bootstrap` HEAD proof supplies: enable
+ * `bootstrap` on the session and in the client's session manager, or it never resolves.
+ *
+ * The store keeps that lookup current: after a write opens, closes or finalizes a channel,
+ * it adds or removes the channel under its payer and authorized signer. Each lookup entry is
+ * its own key holding the payer's open channels there, most recent first, so closing one leaves
+ * the others findable. The lookup returns the first whose channel still resumes, so a delayed
+ * write for a channel that has since closed cannot hide an open one, and mppx validates any
+ * channel it resolves before reusing it.
+ *
+ * @example
+ * ```ts
+ * import { channels } from 'mppx/cloudflare'
+ * import { tempo } from 'mppx/server'
+ *
+ * tempo.session({ account, bootstrap: true, currency, getClient, ...channels(env.MPPX_CHANNELS) })
+ * ```
+ */
+export function channels(namespace, options) {
+    const base = Store.durableObject(namespace, options);
+    const escrowContract = options?.escrowContract ?? tip20ChannelEscrow;
+    /** Removes `channelId` from the entry under `key`. */
+    async function remove(key, channelId) {
+        await base.update(key, (current) => {
+            const ids = lookupIds(current);
+            if (!ids.includes(channelId))
+                return noop;
+            const rest = ids.filter((id) => id !== channelId);
+            return rest.length
+                ? { op: 'set', value: rest, result: undefined }
+                : { op: 'delete', result: undefined };
+        });
+    }
+    /**
+     * Adds `channelId` to the front of the entry under `key` while its stored channel still
+     * resumes, so a delayed add after its close leaves it out. A full entry drops channels that no
+     * longer resume before the oldest open one, keeping the most recent {@link maxLookupChannels}.
+     */
+    async function add(key, channelId) {
+        for (let attempt = 1;; attempt++) {
+            const ids = lookupIds(await base.get(key));
+            if (ids.includes(channelId))
+                return;
+            if (!resumable(await base.get(channelId)))
+                return;
+            const full = ids.length >= maxLookupChannels;
+            const states = full ? await Promise.all(ids.map((id) => base.get(id))) : [];
+            const closed = new Set(ids.filter((_, i) => full && !resumable(states[i])));
+            const added = await base.update(key, (current) => {
+                const listed = lookupIds(current);
+                if (listed.includes(channelId))
+                    return { op: 'noop', result: true };
+                // The entry changed since its channels were read: read them again, a few times at most.
+                if (attempt < maxLookupAttempts && !sameIds(listed, ids))
+                    return { op: 'noop', result: false };
+                return {
+                    op: 'set',
+                    value: [channelId, ...listed.filter((id) => !closed.has(id))].slice(0, maxLookupChannels),
+                    result: true,
+                };
+            });
+            if (added)
+                return;
+        }
+    }
+    /**
+     * Moves the lookup entries of a channel from its previous state to its next one. Entries
+     * for the next state are written on every write, not only when they change: the channel
+     * commits before its entries, so a failed entry write is repaired by the channel's next
+     * write instead of staying missing. Writing an entry that is already there changes nothing.
+     * Best effort: the channel write has already committed, so a failed entry write must not
+     * report it as failed (a charge would apply without its Receipt).
+     */
+    async function sync(previous, next) {
+        const before = lookupKeys(previous);
+        const after = lookupKeys(next);
+        await Promise.allSettled([
+            ...before
+                .filter((key) => !after.includes(key))
+                .map((key) => remove(key, previous.channelId)),
+            ...after.map((key) => add(key, next.channelId)),
+        ]);
+    }
+    const store = {
+        ...base,
+        async put(key, value) {
+            const previous = await base.get(key);
+            await base.put(key, value);
+            await sync(previous, value);
+        },
+        async delete(key) {
+            const previous = await base.get(key);
+            await base.delete(key);
+            await sync(previous, null);
+        },
+        async update(key, fn) {
+            // The last call of `fn` is the one the compare-and-swap committed.
+            const applied = {
+                previous: null,
+            };
+            const result = await base.update(key, (current) => {
+                applied.previous = current;
+                applied.change = fn(current);
+                return applied.change;
+            });
+            const { change, previous } = applied;
+            if (change && change.op !== 'noop')
+                await sync(previous, change.op === 'set' ? change.value : null);
+            return result;
+        },
+    };
+    const resolveChannelId = async ({ paymentRequest, source }) => {
+        const payer = source ? parsePkhSource(source) : null;
+        const { recipient } = paymentRequest;
+        if (!payer || !recipient)
+            return undefined;
+        if (paymentRequest.chainId !== undefined && paymentRequest.chainId !== payer.chainId)
+            return undefined;
+        const operator = paymentRequest.operator ?? zeroAddress;
+        const ids = lookupIds(await base.get(lookupKey({
+            chainId: payer.chainId,
+            escrowContract: paymentRequest.escrowContract ?? escrowContract,
+            payee: recipient,
+            operator,
+            payer: payer.address,
+            token: paymentRequest.currency,
+        })));
+        // An ID a delayed write left for a channel that has since closed resumes nothing.
+        for (const id of ids) {
+            const state = await base.get(id);
+            if (!resumable(state))
+                continue;
+            // mppx verifies a challenge without an operator against the zero operator, and only
+            // channels without one (legacy escrow channels) are not keyed by theirs.
+            if (isPrecompileState(state)
+                ? state.operator.toLowerCase() !== operator.toLowerCase()
+                : paymentRequest.operator !== undefined)
+                continue;
+            return id;
+        }
+        return undefined;
+    };
+    return { resolveChannelId, store };
+}
+/**
+ * Settles the channels of a settlement queue batch on-chain, from the Worker's `queue()`
+ * handler. Each message is acknowledged once its channel settled or has nothing left to
+ * settle, and when settlement cannot succeed (the channel is gone or has no voucher); any
+ * other failure, such as a fee over the fee payer's cap, retries it after 30 s, doubling up
+ * to 10 minutes. The {@link ChannelStore} watchdog sends a channel again if its job never settles it.
+ *
+ * @example
+ * ```ts
+ * import { channels, settle } from 'mppx/cloudflare'
+ *
+ * export default {
+ *   async queue(batch, env) {
+ *     await settle(batch, { account, getClient, store: channels(env.MPPX_CHANNELS).store })
+ *   },
+ * }
+ * ```
+ */
+export async function settle(batch, parameters) {
+    const { getClient, settle: settle_ = settleChannel, store, ...options } = parameters;
+    for (const message of batch.messages) {
+        try {
+            const channelId = message.body
+                ?.channelId;
+            // A malformed job can never settle: drop it instead of failing the batch.
+            if (typeof channelId !== 'string') {
+                message.ack();
+                continue;
+            }
+            const state = await store.get(channelId);
+            // A duplicate job, such as one the watchdog sent while the first was queued, has nothing left.
+            if (!isChannelState(state) || state.finalized || unsettledAmount(state) <= 0n) {
+                message.ack();
+                continue;
+            }
+            // The server's own cooperative close captures it: check again once that close lands or expires.
+            if (pendingClose(state)) {
+                message.retry({ delaySeconds: 60 });
+                continue;
+            }
+            // Another job or a scheduled settlement is settling it: check again once that one is done.
+            const leaseOwner = await claim(store, channelId);
+            if (!leaseOwner) {
+                message.retry({ delaySeconds: 60 });
+                continue;
+            }
+            // Waiting for the receipt can outlast the lease: keep it while the settlement runs, so no
+            // other job claims the channel and broadcasts the same voucher.
+            const renewal = setInterval(() => {
+                void renew(store, channelId, leaseOwner).catch(() => undefined);
+            }, settlementLeaseMs / 2);
+            try {
+                await settle_(store, await getClient({ chainId: state.chainId }), channelId, options);
+            }
+            finally {
+                clearInterval(renewal);
+                await release(store, channelId, leaseOwner).catch(() => undefined);
+            }
+            message.ack();
+        }
+        catch (error) {
+            if (isPermanent(error))
+                message.ack();
+            else
+                message.retry({ delaySeconds: Math.min(30 * 2 ** Math.max(0, message.attempts - 1), 600) });
+        }
+    }
+}
+const noop = { op: 'noop', result: undefined };
+/** How long a settlement claim holds before another job may take over, as scheduled settlement's. */
+const settlementLeaseMs = 5 * 60_000;
+/**
+ * Claims a channel's settlement with the lease scheduled settlement takes, so overlapping jobs,
+ * or a job and a scheduled settlement, never broadcast the same voucher twice. Returns the
+ * lease's owner, or `undefined` while another one holds a live lease.
+ */
+async function claim(store, channelId) {
+    const owner = globalThis.crypto.randomUUID();
+    const now = Date.now();
+    return store.update(channelId, (current) => {
+        if (!isChannelState(current))
+            return { op: 'noop', result: undefined };
+        const lease = current.scheduledSettlementLease;
+        if (lease && lease.expiresAt > now)
+            return { op: 'noop', result: undefined };
+        return {
+            op: 'set',
+            value: {
+                ...current,
+                scheduledSettlementLease: { expiresAt: now + settlementLeaseMs, owner },
+            },
+            result: owner,
+        };
+    });
+}
+/** Extends a settlement lease {@link claim} took while its owner still holds it. */
+async function renew(store, channelId, owner) {
+    await store.update(channelId, (current) => {
+        if (!isChannelState(current) || current.scheduledSettlementLease?.owner !== owner)
+            return noop;
+        return {
+            op: 'set',
+            value: {
+                ...current,
+                scheduledSettlementLease: { expiresAt: Date.now() + settlementLeaseMs, owner },
+            },
+            result: undefined,
+        };
+    });
+}
+/** Releases a settlement lease {@link claim} took, unless another owner has taken it since. */
+async function release(store, channelId, owner) {
+    await store.update(channelId, (current) => {
+        if (!isChannelState(current) || current.scheduledSettlementLease?.owner !== owner)
+            return noop;
+        const { scheduledSettlementLease: _, ...channel } = current;
+        return { op: 'set', value: channel, result: undefined };
+    });
+}
+/**
+ * Whether a settlement failed for good: the channel or its voucher is gone, the account cannot
+ * settle it, or the transaction confirmed and only recording it failed.
+ */
+function isPermanent(error) {
+    return (error instanceof ChannelNotFoundError ||
+        error instanceof VerificationFailedError ||
+        error instanceof SettlementCheckpointError);
+}
+/**
+ * The lookup key of a payer's channel to a payee, token, escrow, operator and chain. The operator
+ * is part of it so that channels opened with other operators cannot push a matching one out of
+ * the entry's {@link maxLookupChannels}.
+ */
+function lookupKey(lookup) {
+    const { chainId, escrowContract, operator, payee, payer, token } = lookup;
+    return `mppx:session-lookup:v3:${[payer, payee, token, escrowContract, operator].map((address) => address.toLowerCase()).join(':')}:${chainId}`;
+}
+/** Most channels a lookup entry keeps per payer, payee, token, escrow, operator and chain. */
+const maxLookupChannels = 8;
+/** Reads of a full lookup entry's channels before adding to it regardless of concurrent changes. */
+const maxLookupAttempts = 3;
+/** Whether two lookup entries list the same channels in the same order. */
+function sameIds(a, b) {
+    return a.length === b.length && a.every((id, i) => id === b[i]);
+}
+/** The channel IDs of a lookup entry, most recent first. */
+function lookupIds(entry) {
+    return Array.isArray(entry) ? entry.filter((id) => typeof id === 'string') : [];
+}
+/** Whether a payer may resume a stored channel: open, with no close requested. */
+function resumable(state) {
+    return isChannelState(state) && !state.finalized && !state.closeRequestedAt;
+}
+/** The lookup keys of a channel a payer may resume. */
+function lookupKeys(state) {
+    if (!resumable(state))
+        return [];
+    const signers = new Set([state.payer.toLowerCase(), state.authorizedSigner.toLowerCase()]);
+    return [...signers].map((payer) => lookupKey({
+        chainId: state.chainId,
+        escrowContract: state.escrowContract,
+        operator: isPrecompileState(state) ? state.operator : zeroAddress,
+        payee: state.payee,
+        payer,
+        token: state.token,
+    }));
+}
+//# sourceMappingURL=Channels.js.map

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,5 @@
+/** Durable Object class that stores Tempo session channels and schedules their settlement. */
+export { ChannelStore } from './ChannelStore.js';
+/** Channel store and lookup for `tempo.session()`, and the settlement queue consumer. */
+export { channels, settle } from './Channels.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cloudflare/index.js

@@ -0,0 +1,5 @@
+/** Durable Object class that stores Tempo session channels and schedules their settlement. */
+export { ChannelStore } from './ChannelStore.js';
+/** Channel store and lookup for `tempo.session()`, and the settlement queue consumer. */
+export { channels, settle } from './Channels.js';
+//# sourceMappingURL=index.js.map

package/dist/internal/sse.js

@@ -21,17 +21,19 @@ export function createParser(onEvent) {
             event = '';
             return;
         }
-        if (line.startsWith(':'))
-            return;
         const colon = line.indexOf(':');
+        if (colon === 0)
+            return;
         const field = colon === -1 ? line : line.slice(0, colon);
-        let value = colon === -1 ? '' : line.slice(colon + 1);
-        if (value.startsWith(' '))
-            value = value.slice(1);
-        if (field === 'data')
-            data = data === undefined ? value : `${data}\n${value}`;
-        else if (field === 'event')
+        if (field !== 'data' && field !== 'event')
+            return;
+        let value = '';
+        if (colon !== -1)
+            value = line.slice(line.charCodeAt(colon + 1) === 32 ? colon + 2 : colon + 1);
+        if (field === 'event')
             event = value;
+        else
+            data = data === undefined ? value : data + '\n' + value;
     }
     return {
         /** Parses the next chunk of the stream. */
@@ -48,15 +50,30 @@ export function createParser(onEvent) {
                     chunk = chunk.slice(1);
             }
             buffer += chunk;
-            if (!/[\r\n]/.test(chunk))
+            if (chunk.indexOf('\n') === -1 && chunk.indexOf('\r') === -1)
                 return;
+            // Scan with indexOf rather than a global RegExp: it is several times faster on
+            // line-dense bodies.
             let start = 0;
-            const terminator = /\r\n?|\n/g;
-            for (let match = terminator.exec(buffer); match; match = terminator.exec(buffer)) {
-                parseLine(buffer.slice(start, match.index));
-                start = terminator.lastIndex;
-                if (match[0] === '\r' && start === buffer.length)
-                    skipLineFeed = true;
+            let lineFeed = buffer.indexOf('\n');
+            let carriageReturn = buffer.indexOf('\r');
+            while (lineFeed !== -1 || carriageReturn !== -1) {
+                const end = lineFeed === -1
+                    ? carriageReturn
+                    : carriageReturn === -1
+                        ? lineFeed
+                        : Math.min(lineFeed, carriageReturn);
+                parseLine(buffer.slice(start, end));
+                start = end + 1;
+                if (end === carriageReturn) {
+                    if (start === buffer.length)
+                        skipLineFeed = true;
+                    else if (lineFeed === start)
+                        start++;
+                    carriageReturn = buffer.indexOf('\r', start);
+                }
+                if (lineFeed !== -1 && lineFeed < start)
+                    lineFeed = buffer.indexOf('\n', start);
             }
             buffer = buffer.slice(start);
         },

package/dist/internal/version.d.ts

@@ -1,5 +1,5 @@
 /** Current mppx package version. */
-export declare const version = "0.17.3";
+export declare const version = "0.17.4";
 /** Canonical SDK identifier for this mppx release. */
-export declare const sdkIdentifier = "mppx/0.17.3";
+export declare const sdkIdentifier = "mppx/0.17.4";
 //# sourceMappingURL=version.d.ts.map

package/dist/internal/version.js

@@ -1,6 +1,6 @@
 // Generated by scripts/sync-version.ts.
 /** Current mppx package version. */
-export const version = '0.17.3';
+export const version = '0.17.4';
 /** Canonical SDK identifier for this mppx release. */
 export const sdkIdentifier = `mppx/${version}`;
 //# sourceMappingURL=version.js.map

package/dist/stripe/server/Methods.d.ts

@@ -7,6 +7,7 @@ import * as PaymentIntent from '../internal/payment-intent.js';
 import type { StripeClient } from '../internal/types.js';
 import { charge as charge_ } from './Charge.js';
 import { findOrCreateDepositAddress as _findOrCreateDepositAddress } from './internal/deposit-address.js';
+import { recordPayment as _recordPayment } from './internal/record-payment.js';
 import { type ConnectConfig } from './internal/request.js';
 export declare namespace stripe {
     type Network = 'tempo' | 'base' | 'solana';
@@ -162,6 +163,7 @@ export declare namespace stripe {
     const charge: typeof charge_;
     const create: typeof stripe;
     const findOrCreateDepositAddress: typeof _findOrCreateDepositAddress;
+    const recordPayment: typeof _recordPayment;
 }
 export {};
 //# sourceMappingURL=Methods.d.ts.map

package/dist/stripe/server/Methods.js

@@ -9,7 +9,7 @@ import { charge as charge_ } from './Charge.js';
 import { buildAnalytics } from './internal/analytics.js';
 import { findOrCreateDepositAddress as _findOrCreateDepositAddress } from './internal/deposit-address.js';
 import * as HostedFeePayer from './internal/hosted-fee-payer.js';
-import { recordCryptoPayment } from './internal/record-payment.js';
+import { recordCryptoPayment, recordPayment as _recordPayment } from './internal/record-payment.js';
 const defaultMethodNames = ['tempo', 'spt'];
 const additionalBuiltinKeys = ['base', 'tempo'];
 class DefaultMethodsBuilder {
@@ -276,6 +276,7 @@ export function stripe(parameters) {
     stripe.charge = charge_;
     stripe.create = stripe;
     stripe.findOrCreateDepositAddress = _findOrCreateDepositAddress;
+    stripe.recordPayment = _recordPayment;
 })(stripe || (stripe = {}));
 function neededNetworks(excluded, additional) {
     const networks = [];

package/dist/stripe/server/internal/record-payment.d.ts

@@ -15,4 +15,53 @@ export declare function recordCryptoPayment(client: StripeClient, parameters: {
     analyticsMetadata: Record<string, string>;
     paymentIntentOptions?: PaymentIntent.Options | undefined;
 }): Promise<void>;
+/**
+ * Records a settled crypto payment as a Stripe PaymentIntent in `transaction_verification` mode,
+ * the same call mppx makes after a Stripe-backed payment settles. Use it to record payments mppx
+ * could not, such as when the process stopped between the broadcast and the recording.
+ *
+ * The transaction hash (`reference`) is the Stripe idempotency key, as it is for mppx's own
+ * recording, so a repeat call for the same reference does not create a second PaymentIntent while
+ * Stripe keeps the key (at least 24 hours): it returns `replayed`, or `key_conflict` when an
+ * earlier call sent different parameters (such as mppx's own metadata). Stripe also caches failed
+ * responses under the key, so `key_conflict` does not mean a PaymentIntent exists: confirm it in
+ * Stripe before treating the payment as recorded. mppx's own recording uses
+ * `<reference>_fallback` instead only when Stripe rejected the server's `paymentIntentOptions`.
+ *
+ * Unlike mppx's own recording, it throws when Stripe fails, so the caller can retry.
+ */
+export declare function recordPayment(client: StripeClient, parameters: recordPayment.Parameters): Promise<recordPayment.ReturnType>;
+export declare namespace recordPayment {
+    type Parameters = {
+        /** Amount in the token's raw units (6 decimals), as in the Challenge request. */
+        amount: string;
+        /** Stripe Connect settings, when the payment belongs to a connected account. */
+        connect?: ConnectConfig | undefined;
+        /** PaymentIntent metadata. */
+        metadata?: Record<string, string> | undefined;
+        /** Network the payment settled on. */
+        network: stripe.Network;
+        /** Transaction hash of the settled payment. */
+        reference: string;
+    };
+    type ReturnType = {
+        /** A PaymentIntent was created, or Stripe replayed the earlier one for this reference. */
+        status: 'created' | 'replayed';
+        paymentIntentId: string;
+        /**
+         * The PaymentIntent's Stripe status. Only `succeeded` means Stripe verified the
+         * transaction; others, such as `processing` or `requires_action`, need a later lookup.
+         */
+        paymentIntentStatus: string;
+    } | {
+        /**
+         * An earlier call used this reference with different parameters. Stripe caches failed
+         * responses too, so whether that call created a PaymentIntent is unknown.
+         */
+        status: 'key_conflict';
+    } | {
+        /** The amount is below Stripe's 1 cent minimum, so nothing was recorded. */
+        status: 'below_minimum';
+    };
+}
 //# sourceMappingURL=record-payment.d.ts.map

package/dist/stripe/server/internal/record-payment.js

@@ -12,29 +12,17 @@ const NETWORK_CONFIG = {
 export function recordCryptoPayment(client, parameters) {
     const { network, reference, amount, connect, analyticsMetadata, paymentIntentOptions } = parameters;
     const { customer, hooks, metadata, receipt_email } = paymentIntentOptions ?? {};
-    const { stripeNetworkName, tokenDecimals } = NETWORK_CONFIG[network];
-    const amountCents = Number(BigInt(amount) / 10n ** BigInt(tokenDecimals - 2));
+    const amountCents = toAmountCents(network, amount);
     if (amountCents < 1) {
         console.warn(`[stripe] skipping PI recording: ${amount} raw units on ${network} floors to ${amountCents} cents (below Stripe minimum)`);
         return Promise.resolve();
     }
-    const requiredParams = {
-        amount: amountCents,
-        currency: 'usd',
-        confirm: true,
-        payment_method_data: { type: 'crypto' },
-        payment_method_types: ['crypto'],
-        payment_method_options: {
-            crypto: {
-                mode: 'transaction_verification',
-                transaction_verification_options: {
-                    network: stripeNetworkName,
-                    transaction_hash: reference,
-                },
-            },
-        },
+    const requiredParams = paymentIntentParams({
+        amountCents,
         metadata: analyticsMetadata,
-    };
+        network,
+        reference,
+    });
     const options = {
         idempotencyKey: reference,
         ...(connect && { connect }),
@@ -60,6 +48,75 @@ export function recordCryptoPayment(client, parameters) {
         console.error('[stripe] failed to record crypto payment:', err);
     });
 }
+/**
+ * Records a settled crypto payment as a Stripe PaymentIntent in `transaction_verification` mode,
+ * the same call mppx makes after a Stripe-backed payment settles. Use it to record payments mppx
+ * could not, such as when the process stopped between the broadcast and the recording.
+ *
+ * The transaction hash (`reference`) is the Stripe idempotency key, as it is for mppx's own
+ * recording, so a repeat call for the same reference does not create a second PaymentIntent while
+ * Stripe keeps the key (at least 24 hours): it returns `replayed`, or `key_conflict` when an
+ * earlier call sent different parameters (such as mppx's own metadata). Stripe also caches failed
+ * responses under the key, so `key_conflict` does not mean a PaymentIntent exists: confirm it in
+ * Stripe before treating the payment as recorded. mppx's own recording uses
+ * `<reference>_fallback` instead only when Stripe rejected the server's `paymentIntentOptions`.
+ *
+ * Unlike mppx's own recording, it throws when Stripe fails, so the caller can retry.
+ */
+export async function recordPayment(client, parameters) {
+    const { amount, connect, metadata = {}, network, reference } = parameters;
+    const amountCents = toAmountCents(network, amount);
+    if (amountCents < 1)
+        return { status: 'below_minimum' };
+    try {
+        const result = await createPaymentIntent(client, paymentIntentParams({ amountCents, metadata, network, reference }), { idempotencyKey: reference, ...(connect && { connect }) });
+        return {
+            paymentIntentId: result.id,
+            paymentIntentStatus: result.status,
+            status: result.replayed ? 'replayed' : 'created',
+        };
+    }
+    catch (error) {
+        if (isIdempotencyError(error))
+            return { status: 'key_conflict' };
+        throw error;
+    }
+}
+/** Converts raw token units to whole US cents, rounding down. */
+function toAmountCents(network, amount) {
+    const { tokenDecimals } = NETWORK_CONFIG[network];
+    return Number(BigInt(amount) / 10n ** BigInt(tokenDecimals - 2));
+}
+/** The PaymentIntent parameters every recording sends. */
+function paymentIntentParams(parameters) {
+    const { amountCents, metadata, network, reference } = parameters;
+    return {
+        amount: amountCents,
+        currency: 'usd',
+        confirm: true,
+        payment_method_data: { type: 'crypto' },
+        payment_method_types: ['crypto'],
+        payment_method_options: {
+            crypto: {
+                mode: 'transaction_verification',
+                transaction_verification_options: {
+                    network: NETWORK_CONFIG[network].stripeNetworkName,
+                    transaction_hash: reference,
+                },
+            },
+        },
+        metadata,
+    };
+}
+/** Returns whether Stripe rejected a reused idempotency key sent with different parameters. */
+function isIdempotencyError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const candidate = error;
+    return (candidate.type === 'StripeIdempotencyError' ||
+        candidate.rawType === 'idempotency_error' ||
+        candidate.raw?.type === 'idempotency_error');
+}
 /** Returns whether Stripe definitively rejected request parameters before creating a PI. */
 function isDefinitiveInvalidRequestError(error) {
     if (typeof error !== 'object' || error === null)

package/dist/tempo/Methods.d.ts

@@ -33,6 +33,11 @@ export declare const charge: {
             }, z.core.$strip>, z.ZodMiniObject<{
                 signature: z.ZodMiniString<string>;
                 type: z.ZodMiniLiteral<"proof">;
+            }, z.core.$strip>, z.ZodMiniObject<{
+                hash: z.ZodMiniString<string>;
+                senderTag: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"zone">;
+                zoneId: z.ZodMiniNumber<number>;
             }, z.core.$strip>], "type">;
         };
         request: z.ZodMiniPipe<z.ZodMiniObject<{
@@ -55,6 +60,7 @@ export declare const charge: {
                 pull: "pull";
                 push: "push";
             }>>>;
+            zones: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniLiteral<true>, z.ZodMiniArray<z.ZodMiniNumber<number>>]>>;
         }, z.core.$strip>, z.ZodMiniTransform<{
             currency: string;
             description?: string | undefined;
@@ -71,6 +77,7 @@ export declare const charge: {
                     amount: string;
                 }[] | undefined;
                 supportedModes?: ("pull" | "push")[] | undefined;
+                zones?: true | number[] | undefined;
             } | undefined;
         }, {
             machineTokenEnabled?: boolean | undefined;
@@ -89,6 +96,7 @@ export declare const charge: {
                 recipient: `0x${string}`;
             }[] | undefined;
             supportedModes?: ("pull" | "push")[] | undefined;
+            zones?: true | number[] | undefined;
         }>>;
     };
 };