mppx 0.17.1 → 0.17.3

package/dist/tempo/server/internal/transport.d.ts

@@ -4,11 +4,13 @@ import * as ChannelStore from '../../session/server/ChannelStore.js';
 import type { SettleChargedSessionChannel } from '../../session/server/Settlement.js';
 import * as Sse_core from '../../session/server/Sse.js';
 declare const prepaidSessionTick: unique symbol;
+declare const prepaidRefundKey: unique symbol;
 /** SSE transport with Tempo session controller. */
 export type Sse = Transport.Sse<Sse_core.SessionController>;
 /** Receipt marker used to avoid double-charging a request already charged during verification. */
 export type PrepaidSessionReceipt = SessionReceipt & {
     [prepaidSessionTick]?: true | undefined;
+    [prepaidRefundKey]?: string | undefined;
 };
 /** Marks a session receipt as already charged for the current request. */
 export declare function markPrepaidSessionTick(receipt: SessionReceipt): SessionReceipt;
@@ -42,6 +44,10 @@ export declare namespace sse {
          * @default false
          */
         poll?: boolean | undefined;
+        /** Opt in to SDK-owned prepaid credits; leave false with an existing merchant refund handler. */
+        autoCreditPrepaid?: boolean | undefined;
+        /** Merchant reconciliation hook for prepaid items that fail before delivery; see `Sse.serve.Options.onRefundRequired`. */
+        onRefundRequired?: Sse_core.serve.Options['onRefundRequired'];
         /** Polling interval (in milliseconds). @default 10 */
         pollingInterval?: number | undefined;
     };

package/dist/tempo/server/internal/transport.js

@@ -14,8 +14,15 @@ import * as ChannelStore from '../../session/server/ChannelStore.js';
 import * as Sse_core from '../../session/server/Sse.js';
 import { captureRequestBodyProbe, shouldChargePlainResponse } from './request-body.js';
 const prepaidSessionTick = Symbol('mppx.prepaidSessionTick');
+const consumedPrepaidReceipts = new WeakSet();
+const prepaidRefundKey = Symbol('mppx.prepaidRefundKey');
 /** Marks a session receipt as already charged for the current request. */
 export function markPrepaidSessionTick(receipt) {
+    if (hasPrepaidSessionTick(receipt))
+        return receipt;
+    Object.defineProperty(receipt, prepaidRefundKey, {
+        value: `stream:${globalThis.crypto.randomUUID()}`,
+    });
     Object.defineProperty(receipt, prepaidSessionTick, {
         configurable: false,
         enumerable: false,
@@ -65,6 +72,11 @@ export function sse(options) {
             return base.respondChallenge(options);
         },
         async respondReceipt({ credential, envelope, receipt, response, challengeId, input }) {
+            if (hasPrepaidSessionTick(receipt)) {
+                if (consumedPrepaidReceipts.has(receipt))
+                    throw new Error('Prepaid receipt already used; verify a new payment before retrying delivery');
+                consumedPrepaidReceipts.add(receipt);
+            }
             const verifiedCredential = envelope?.credential ?? credential;
             const verifiedChallengeId = envelope?.challenge.id ?? challengeId;
             const verifiedRequest = envelope?.request ?? verifiedCredential.challenge.request;
@@ -86,20 +98,25 @@ export function sse(options) {
                 // Pass async generator functions directly so Sse.serve gives them
                 // a SessionController for manual charge(). Pass raw AsyncIterables
                 // as-is so Sse.serve auto-charges per yielded value.
-                const generate = resolveMeteredGenerate(resolved, unitType);
-                const stream = Sse_core.serve({
+                const generate = resolved;
+                const streamOptions = {
                     store,
                     channelId,
                     challengeId: verifiedChallengeId,
                     tickCost,
                     pollIntervalMs: pollingInterval,
                     generate,
+                    chargeOnce: unitType === 'request',
                     beforeCharge: () => options.beforeCharge?.(channelId),
                     onChargeCommitted: options.settleCharged,
                     prepaidUnits: hasPrepaidSessionTick(receipt) ? 1 : 0,
+                    refundIdempotencyKey: receipt[prepaidRefundKey],
+                    onRefundRequired: options.onRefundRequired,
+                    autoCreditPrepaid: options.autoCreditPrepaid,
                     signal: input.signal,
-                });
-                return Sse_core.toResponse(stream);
+                };
+                await Sse_core.preparePrepaidRefund(streamOptions);
+                return Sse_core.toResponse(Sse_core.serve(streamOptions));
             }
             const baseResponse = base.respondReceipt({
                 credential: verifiedCredential,
@@ -246,23 +263,6 @@ function isAsyncGeneratorFunction(value) {
 function isAsyncIterable(value) {
     return value !== null && typeof value === 'object' && Symbol.asyncIterator in value;
 }
-function resolveMeteredGenerate(value, unitType) {
-    if (isAsyncGeneratorFunction(value))
-        return value;
-    if (unitType !== 'request')
-        return value;
-    const iterable = value;
-    return async function* chargeOnce(stream) {
-        let charged = false;
-        for await (const chunk of iterable) {
-            if (!charged) {
-                await stream.charge();
-                charged = true;
-            }
-            yield chunk;
-        }
-    };
-}
 function isNullBodyStatus(status) {
     return [101, 204, 205, 304].includes(status);
 }

package/dist/tempo/session/client/ChannelStore.d.ts

@@ -15,6 +15,8 @@ export type ChannelStore = {
 };
 /** Channel persistence and update notification for credential results. */
 export type ChannelSink = {
+    /** Origin attached to newly created or recovered channels before persistence. */
+    origin?: string | undefined;
     store: ChannelStore;
     notifyUpdate: (entry: ChannelEntry) => void;
 };

package/dist/tempo/session/client/CredentialState.js

@@ -25,6 +25,8 @@ export function readCredentialCumulativeAmount(payload) {
  * can react to the close.
  */
 async function storeChannelEntry(sink, entry) {
+    if (sink.origin !== undefined)
+        entry = { ...entry, origin: sink.origin };
     if (entry.opened)
         await persistChannel(sink.store, entry);
     else

package/dist/tempo/session/client/Session.d.ts

@@ -132,7 +132,17 @@ export declare namespace session {
         allowCustomEscrow?: boolean | undefined;
         /** Automatically acquire the session currency from fallback stablecoins before open/top-up. */
         autoSwap?: AutoSwap.resolve.Value | undefined;
-        /** Pluggable persistence for reusable channels. Defaults to an in-memory store. */
+        /**
+         * HTTP origin authorized for credential creation and server-snapshot recovery.
+         * Fetch supplies the request origin, but recovering an unknown channel from its snapshot
+         * requires this explicit origin pin or a caller-supplied descriptor.
+         */
+        origin?: string | undefined;
+        /**
+         * Pluggable persistence for reusable channels. Defaults to an in-memory store.
+         * Use a separate store per HTTP origin: each payment scope holds one channel, and a
+         * channel already bound to another origin is rejected rather than overwritten or reused.
+         */
         channelStore?: ChannelStore | undefined;
         /**
          * Allowlist of TIP-20 currency addresses this client will pay sessions in, compared

package/dist/tempo/session/client/Session.js

@@ -147,6 +147,9 @@ export function session(parameters = {}) {
     const getAccount = Account.getResolver({ account });
     const maxDeposit = maxDepositParameter !== undefined ? parseUnits(maxDepositParameter, decimals) : undefined;
     const topUpAmount = topUpAmountParameter !== undefined ? parseUnits(topUpAmountParameter, decimals) : undefined;
+    const configuredOrigin = parameters.origin === undefined ? undefined : new URL(parameters.origin);
+    if (configuredOrigin && !['http:', 'https:'].includes(configuredOrigin.protocol))
+        throw new Error('Session origins require HTTP or HTTPS');
     const store = channelStore ?? createChannelStore();
     const sink = { store, notifyUpdate: (entry) => onChannelUpdate?.(entry) };
     const resolveCredentialAccount = async (resolved, context, entry) => {
@@ -194,6 +197,13 @@ export function session(parameters = {}) {
                 getClient,
             });
             const attempt = MethodResponse.getAttempt(parameters);
+            const origin = MethodResponse.getOrigin(parameters) ?? configuredOrigin?.origin;
+            if (origin !== undefined &&
+                (origin === 'null' || !['http:', 'https:'].includes(new URL(origin).protocol)))
+                throw new Error('Session payments require an HTTP or HTTPS origin');
+            if (configuredOrigin && origin !== configuredOrigin.origin)
+                throw new Error('Session channel origin mismatch');
+            const scopedSink = { ...sink, origin };
             let release = () => { };
             try {
                 const automatic = !hasSessionAction(context) && context?.descriptor === undefined;
@@ -203,10 +213,16 @@ export function session(parameters = {}) {
                         await attempt.prepare();
                 }
                 let entry = await store.get(resolved.key);
+                if (entry && entry.origin !== origin)
+                    throw new Error('Session channel origin mismatch');
+                if (origin && !entry && resolved.snapshot && !context?.descriptor && !configuredOrigin)
+                    throw new Error('Session snapshot recovery requires an explicitly configured origin or descriptor');
                 let plan = await resolveCredentialPlan(resolved, context, entry);
                 if (!automatic && attempt && plan.type === 'open') {
                     release = await lockChannel(store, resolved.key);
                     const nextEntry = await store.get(resolved.key);
+                    if (nextEntry && nextEntry.origin !== origin)
+                        throw new Error('Session channel origin mismatch');
                     if (nextEntry?.channelId !== entry?.channelId) {
                         entry = nextEntry;
                         if (entry?.opened) {
@@ -224,13 +240,13 @@ export function session(parameters = {}) {
                         store: {
                             get: (key) => store.get(key),
                             async set(next) {
-                                pendingOpen = next;
+                                pendingOpen = origin ? { ...next, origin } : next;
                             },
                             delete: (key) => store.delete(key),
                         },
                         notifyUpdate() { },
                     }
-                    : sink;
+                    : scopedSink;
                 const payload = await executeCredentialPlan(plan, credentialSink, AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies));
                 const credential = await serializeCredential(challenge, payload, resolved.chainId, plan.account);
                 if (attempt && pendingOpen) {
@@ -265,7 +281,12 @@ export function session(parameters = {}) {
             }
         },
     });
-    const topUpChannelIfNeeded = async ({ challenge, channel, deposit, fetch, input, requiredCumulative, signal, }) => {
+    function createSessionCredential(challenge, context, input) {
+        const parameters = { challenge, context };
+        MethodResponse.attachOrigin(parameters, resolveInputOrigin(input));
+        return method.createCredential(parameters);
+    }
+    const topUpChannelIfNeeded = async ({ autoSwap, challenge, channel, deposit, fetch, input, requiredCumulative, signal, }) => {
         return withFundingLock(store, entryKey(channel), async () => {
             signal?.throwIfAborted();
             const fundingChannel = await store.get(entryKey(channel));
@@ -285,11 +306,12 @@ export function session(parameters = {}) {
             });
             if (additionalDeposit > 0n)
                 await postTopUp({
+                    autoSwap,
                     additionalDeposit,
                     challenge,
                     channel,
                     channelId: channel.channelId,
-                    createSessionCredential: (challenge, context) => method.createCredential({ challenge, context }),
+                    createSessionCredential: (challenge, context) => createSessionCredential(challenge, context, input),
                     onUncertainFunding: async (entry) => {
                         const current = await store.get(entryKey(entry));
                         const unresolved = {
@@ -333,6 +355,9 @@ export function session(parameters = {}) {
         const channel = await store.get(resolved.key);
         if (!channel?.opened)
             return;
+        const origin = resolveInputOrigin(input);
+        if (channel.origin !== origin)
+            throw new Error('Session channel origin mismatch');
         const snapshot = resolved.snapshot?.channelId.toLowerCase() === channel.channelId.toLowerCase()
             ? resolved.snapshot
             : undefined;
@@ -347,6 +372,7 @@ export function session(parameters = {}) {
         if (!canSignDescriptor(account, channel.descriptor))
             return;
         await topUpChannelIfNeeded({
+            autoSwap: sessionContext?.autoSwap,
             challenge,
             channel,
             deposit,
@@ -356,7 +382,7 @@ export function session(parameters = {}) {
             signal,
         });
     });
-    return MethodResponse.register(method, async ({ challenge, credential, fetch, headers, input, refetch, response, signal }) => {
+    return MethodResponse.register(method, async ({ challenge, context, credential, fetch, headers, input, refetch, response, signal, }) => {
         if (!isTip1034SessionChallenge(challenge))
             return response;
         if (!isEventStream(response)) {
@@ -376,13 +402,14 @@ export function session(parameters = {}) {
         let channel = await store.get(channelKey);
         const driver = {
             assertVoucherWithinLocalLimit: (cumulativeAmount) => assertWithinMaxDeposit(cumulativeAmount, maxDeposit),
-            createSessionCredential: (challenge, context) => method.createCredential({ challenge, context }),
+            createSessionCredential: (challenge, context) => createSessionCredential(challenge, context, input),
             fetch,
             getChannel: () => channel ?? null,
             async topUpIfNeeded({ deposit, requiredCumulative, signal: topUpSignal }) {
                 if (!channel)
                     return;
                 await topUpChannelIfNeeded({
+                    autoSwap: context === undefined ? undefined : sessionContextSchema.parse(context).autoSwap,
                     challenge,
                     channel,
                     deposit: channel.deposit > deposit ? channel.deposit : deposit,
@@ -401,4 +428,10 @@ export function session(parameters = {}) {
         });
     });
 }
+function resolveInputOrigin(input) {
+    const url = new URL(input instanceof Request ? input.url : input, typeof globalThis.location === 'undefined' ? undefined : globalThis.location.href);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('Session payments require an HTTP or HTTPS origin');
+    return url.origin;
+}
 //# sourceMappingURL=Session.js.map

package/dist/tempo/session/client/SessionManager.d.ts

@@ -76,7 +76,7 @@ export declare namespace sessionManager {
         /** Enables same-route HEAD bootstrap from a server session snapshot before opening a new channel. */
         bootstrap?: boolean | undefined;
         /**
-         * Server origins allowed to request bootstrap proofs for a realm other than their hostname,
+         * Server origins allowed to request bootstrap proofs or session payments for a realm other than their hostname,
          * mapped to that realm, such as `{ 'https://api.example.com': 'MPP Payment' }`.
          */
         trustedTempoProofRealms?: ProofRealm.TrustedRealms | undefined;

package/dist/tempo/session/client/SessionManager.js

@@ -146,7 +146,7 @@ export function sessionManager(parameters) {
     async function getReusable(key) {
         const entry = await backing.get(key);
         if (entry?.opened && !ignoredChannelIds.has(entry.channelId)) {
-            if (entry.origin !== undefined && entry.origin !== sessionOrigin)
+            if (entry.origin !== sessionOrigin)
                 throw new Error('SessionManager: stored channel origin mismatch');
             return entry;
         }
@@ -290,6 +290,7 @@ export function sessionManager(parameters) {
         resolveAccount: parameters.resolveAccount,
     });
     const wrappedFetch = Fetch.from({
+        trustedTempoProofRealms: parameters.trustedTempoProofRealms,
         fetch: guardedFetch,
         identity: inheritedIdentity,
         methods: [method],
@@ -316,10 +317,13 @@ export function sessionManager(parameters) {
         },
     });
     function createSessionCredential(challenge, context) {
-        return method.createCredential({
+        const parameters = {
             challenge,
             context: mergeSessionCredentialContext(credentialContext, context),
-        });
+        };
+        if (sessionOrigin)
+            MethodResponse.attachOrigin(parameters, sessionOrigin);
+        return method.createCredential(parameters);
     }
     function updateSpentFromReceipt(receipt) {
         applySessionReceiptToRuntime({
@@ -954,7 +958,7 @@ export function sessionManager(parameters) {
         },
         rehydrate({ channel, challenge, input, spent }) {
             const origin = bindOrigin(input);
-            if (channel.origin !== undefined && channel.origin !== origin)
+            if (channel.origin !== origin)
                 throw new Error('SessionManager: stored channel origin mismatch');
             if (!channel.opened)
                 throw new Error('Cannot restore a closed session channel.');

package/dist/tempo/session/client/Transports.d.ts

@@ -201,6 +201,8 @@ export type TempoSessionChallenge = Challenge.Challenge<z.output<typeof Methods.
 export type CreateSessionCredential = (challenge: TempoSessionChallenge, context: SessionContext) => Promise<string>;
 /** Inputs for posting a precompile session top-up credential. */
 export type PostTopUpParameters = {
+    /** Request-local swap policy; undefined inherits the method default. */
+    autoSwap?: SessionContext['autoSwap'] | undefined;
     /** Additional deposit in raw token units. */
     additionalDeposit: bigint;
     /** Challenge used to authorize the management request. */

package/dist/tempo/session/client/Transports.js

@@ -331,6 +331,7 @@ export async function postTopUp(parameters) {
         challenge: parameters.challenge,
         context: {
             action: 'topUp',
+            ...(parameters.autoSwap === undefined ? {} : { autoSwap: parameters.autoSwap }),
             channelId,
             descriptor: channel.descriptor,
             additionalDepositRaw: parameters.additionalDeposit.toString(),
@@ -526,7 +527,9 @@ export async function closeHttpSession(parameters) {
             challengeId: closeChallenge.id,
             channelId: parameters.target.channelId,
             expectedCloseAmount: signedCloseAmount,
-            minimumSpent: parameters.getMinimumSpent?.() ?? 0n,
+            // HTTP credits can reduce previously acknowledged spend. Authorization and receipt scope
+            // remain bound to the exact close credential; a lower final charge benefits the payer.
+            minimumSpent: 0n,
             receipt,
         }))
         throw new Error('Session close response included a mismatched payment receipt.');

package/dist/tempo/session/precompile/Chain.js

@@ -451,6 +451,7 @@ export async function sendCredentialTransaction(parameters) {
         ...(allowedFeeTokens?.[0] ? { feeToken: transaction.feeToken ?? allowedFeeTokens[0] } : {}),
     };
     const completed = await FeePayer.preflightSponsorship({
+        policy: feePayerPolicy,
         transaction: sponsorshipTransaction,
         simulate: (request) => simulateTempoTransaction(client, request),
         async complete() {

package/dist/tempo/session/server/ChannelStore.d.ts

@@ -292,6 +292,13 @@ export interface BaseState {
     pendingSettlement?: PendingSettlement | undefined;
     /** Outcomes of keyed charges and credits, by `charge:<key>` and `credit:<key>`, until they expire. */
     idempotencyMarkers?: Record<string, IdempotencyMarker> | undefined;
+    /** Durable prepaid delivery obligations. Pending entries require delivery reconciliation, never blind refunds. */
+    prepaidRefunds?: Record<string, {
+        amount: string;
+        units: number;
+        status: 'pending' | 'failed';
+        createdAt: number;
+    }> | undefined;
     /** First block at which the close supervisor read this channel open on-chain. */
     closeSupervisedFromBlock?: bigint | undefined;
 }
@@ -500,6 +507,8 @@ export type ChargeOptions = {
 };
 /** Options for returning an amount to a channel at most once per key. */
 export type CreditOptions = {
+    /** Maximum live idempotency markers; existing keys remain replayable at capacity. */
+    maxMarkers?: number | undefined;
     /**
      * Key of the credit. Its first outcome, credited or declined, is final: a retry with the same key
      * and terms returns it without crediting again, and the same key with other terms throws

package/dist/tempo/session/server/ChannelStore.js

@@ -684,17 +684,22 @@ export async function creditChannel(store, channelId, amount, options) {
         throw new Error('Credit amount must be positive.');
     if (!Number.isSafeInteger(units) || units < 0)
         throw new Error('`units` must be a non-negative integer.');
+    const maxMarkers = options.maxMarkers ?? 1024;
+    if (!Number.isSafeInteger(maxMarkers) || maxMarkers < 1)
+        throw new Error('maxMarkers must be a positive safe integer');
     const now = Date.now();
     const expiresAt = now + (options.retention ?? defaultIdempotencyRetention);
     let result;
     try {
-        result = await applyChange(store, channelId, (current) => planCredit(current, { amount, expiresAt, idempotencyKey, now, units }));
+        result = await applyChange(store, channelId, (current) => planCredit(current, { amount, expiresAt, idempotencyKey, now, units, maxMarkers }));
     }
     catch (error) {
         return { status: 'unknown', error };
     }
     if (!result)
         throw new ChannelNotFoundError({ reason: 'channel not found' });
+    if (result === 'capacity')
+        throw new Error('Credit idempotency marker capacity reached; reconcile manually');
     if (result === 'conflict')
         throw new IdempotencyKeyConflictError({ idempotencyKey, operation: 'credit' });
     return result;
@@ -718,6 +723,8 @@ function planCredit(current, terms) {
                 : { status: 'declined', reason: recorded.outcome, channel: current, replayed: true },
         };
     }
+    if (Object.keys(markers).length >= terms.maxMarkers)
+        return { op: 'noop', result: 'capacity' };
     const reason = creditDeclineReason(current, amount, now);
     const marker = {
         amount,

package/dist/tempo/session/server/MeteredStream.d.ts

@@ -33,6 +33,10 @@ export type MeteredStreamOptions = {
     generate: SessionStreamGenerator;
     /** Verifies that the channel can still fund work and delivery; failures stop the stream. */
     beforeCharge?: (() => MaybePromise<void>) | undefined;
+    /** Charges automatic streams once per request instead of once per value. */
+    chargeOnce?: boolean | undefined;
+    /** Runs when an explicit manual charge consumes a prepaid unit. */
+    onPrepaidChargeCommitted?: (() => void) | undefined;
     /** Runs after a nonzero reserved charge has been committed. */
     onChargeCommitted?: ((channel: ChannelStore.State) => MaybePromise<unknown>) | undefined;
     /** Store polling interval when `waitForUpdate` is unavailable. */

package/dist/tempo/session/server/MeteredStream.js

@@ -9,6 +9,7 @@ export async function* meterIterable(options) {
         channelId: options.channelId,
         reservationId: globalThis.crypto.randomUUID(),
     };
+    let charged = false;
     let pending = false;
     const releaseOnAbort = () => {
         void releaseReservedCharges(reservation).catch(() => { });
@@ -22,6 +23,8 @@ export async function* meterIterable(options) {
         signal.throwIfAborted();
         if (amount === undefined && prepaidUnits > 0) {
             prepaidUnits -= 1;
+            if (manual)
+                options.onPrepaidChargeCommitted?.();
             return;
         }
         if ((amount ?? options.tickCost) === 0n)
@@ -67,8 +70,10 @@ export async function* meterIterable(options) {
                         await commit();
                     break;
                 }
-                if (!manual)
+                if (!manual && (!options.chargeOnce || !charged)) {
                     await charge();
+                    charged = true;
+                }
                 await commit();
                 yield value;
             }

package/dist/tempo/session/server/Sse.d.ts

@@ -1,6 +1,41 @@
 import type { Hex } from 'viem';
 import * as ChannelStore from './ChannelStore.js';
 import { type MeteredStreamOptions, type SessionController } from './MeteredStream.js';
+/** A failed prepaid delivery that needs merchant reconciliation. */
+export type PrepaidRefund = {
+    /** Channel that paid for the undelivered items. */
+    channelId: Hex;
+    /** Undelivered prepaid amount in raw token units; use externalRefundAmount for transfers. */
+    amount: bigint;
+    /** Captured share safe to refund externally, or null until reconciliation establishes it. */
+    externalRefundAmount: bigint | null;
+    /** Charge units included in the credit attempt. */
+    units: number;
+    /** Use this key for both credit retries and an idempotent merchant refund. */
+    idempotencyKey: string;
+    /** An unknown credit must be reconciled with the same key before refunding externally. */
+    credit: {
+        status: 'failed';
+        error: unknown;
+    } | Exclude<ChannelStore.CreditResult, {
+        status: 'credited';
+    }>;
+};
+/** Exposes durable retry information when no refund hook is configured or it fails. */
+export declare class PrepaidRefundError extends Error {
+    readonly refund: PrepaidRefund;
+    readonly name = "PrepaidRefundError";
+    constructor(refund: PrepaidRefund);
+}
+/** Maximum retained automatic refund operations per channel. Never evict live retry keys. */
+export declare const maxPrepaidRefunds = 128;
+/**
+ * Persist a delivery obligation before returning a managed response. Failed hook deliveries remain
+ * in `channel.prepaidRefunds` for a merchant worker. Pending entries require manual delivery
+ * reconciliation; failed entries may retry the credit with their original terms within 24 hours.
+ * Acknowledging the hook means the merchant has durably accepted responsibility for the job.
+ */
+export declare function preparePrepaidRefund(options: serve.Options): Promise<void>;
 /**
  * SSE (Server-Sent Events) utilities for metered streaming payments.
  *
@@ -31,6 +66,9 @@ export type { SessionController } from './MeteredStream.js';
  *    `stream.charge()` resolves, retaining them on cancellation or failure.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
+ * With `autoCreditPrepaid`, a failure before a prepaid item is enqueued attempts an idempotent credit.
+ * If credit is declined or uncertain, `onRefundRequired` handles merchant reconciliation.
+ *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
  */
 export declare function serve(options: serve.Options): ReadableStream<Uint8Array>;
@@ -42,12 +80,33 @@ export declare namespace serve {
         challengeId: string;
         tickCost: bigint;
         generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>);
+        /** Charge automatic iterables once per request; explicit manual charges are unaffected. */
+        chargeOnce?: boolean | undefined;
         /** Verifies live escrow before charging and delivering stream items. */
         beforeCharge?: MeteredStreamOptions['beforeCharge'];
         /** Callback invoked after each nonzero stream charge is committed. */
         onChargeCommitted?: MeteredStreamOptions['onChargeCommitted'];
         pollIntervalMs?: number | undefined;
+        /** Opt in to SDK-owned credits. Leave disabled when the merchant already refunds failed requests. @default false */
+        autoCreditPrepaid?: boolean | undefined;
+        /** Units charged before streaming. */
         prepaidUnits?: number | undefined;
+        /** Stable per-charge key used for automatic credit and merchant refund retries. Defaults to a random stream key. */
+        refundIdempotencyKey?: string | undefined;
+        /**
+         * Persist or perform an idempotent refund when a failed prepaid delivery cannot be credited.
+         * For `credit.status === 'unknown'`, retry `Session.Server.credit` with the supplied key,
+         * amount and units before refunding externally; the credit may already have committed.
+         * Retry within the credit marker retention (24 hours); later retries need manual reconciliation.
+         * Only transfer `externalRefundAmount` when non-null; closing, pending settlement and definite
+         * failures require reconciliation first. `failed` is a definite non-credit, not an uncertain write.
+         * Successful return must mean durable acceptance. Missing/throwing hooks leave obligations in
+         * `channel.prepaidRefunds`; run a recovery worker and reconcile pending delivery records manually.
+         * Records are bounded and never evicted while unresolved. A full ledger rejects new streams.
+         * Hook failures surface a `PrepaidRefundError` containing the retry information.
+         * Delivered items, explicit manual charges and client cancellation are not automatically refunded.
+         */
+        onRefundRequired?: ((refund: PrepaidRefund) => void | Promise<void>) | undefined;
         signal?: AbortSignal | undefined;
     };
 }