mppx 0.17.0 → 0.17.3

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

@@ -262,10 +262,20 @@ export function requestInitWithAuthorization(input, init, credential, challenge)
     }, Challenge.credentialHeader(challenge), credential);
 }
 /** Returns the exact resource URL used for out-of-band management POSTs, without its fragment. */
+/** Returns whether a value is a `Request`, including one from another realm such as an iframe. */
+export function isRequest(value) {
+    return (value instanceof Request ||
+        (typeof value === 'object' &&
+            value !== null &&
+            !(value instanceof URL) &&
+            typeof value.url === 'string' &&
+            typeof value.method === 'string' &&
+            typeof value.clone === 'function'));
+}
 export function managementInput(input) {
     try {
         const base = typeof location === 'undefined' ? undefined : location.href;
-        const url = input instanceof Request
+        const url = isRequest(input)
             ? new URL(input.url)
             : input instanceof URL
                 ? new URL(input)
@@ -321,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(),
@@ -456,6 +467,21 @@ export async function closeHttpSession(parameters) {
     }
     let closeChallenge = parameters.target.challenge;
     let signedCloseAmount = parameters.signedCloseAmount;
+    const request = isRequest(parameters.lastUrl) ? parameters.lastUrl : undefined;
+    // Retain transport policy without inheriting the resource body or cancellation. Redirects stay
+    // manual so the credential never follows one.
+    const requestOptions = request
+        ? {
+            cache: request.cache,
+            credentials: request.credentials,
+            integrity: request.integrity,
+            keepalive: request.keepalive,
+            // Fetch rejects `navigate` in a request init; a navigation becomes `same-origin`, as Fetch does.
+            mode: request.mode === 'navigate' ? 'same-origin' : request.mode,
+            referrer: request.referrer,
+            referrerPolicy: request.referrerPolicy,
+        }
+        : undefined;
     const postClose = async (challenge, refreshed = false) => {
         closeChallenge = challenge;
         signedCloseAmount =
@@ -467,7 +493,11 @@ export async function closeHttpSession(parameters) {
             descriptor: parameters.target.channel.descriptor,
             cumulativeAmountRaw: signedCloseAmount,
         });
-        return parameters.fetch(parameters.lastUrl, {
+        // Close is a separate management POST, independent of the resource Request.
+        // A Request's URL is absolute. Pass other inputs unchanged so the configured fetch resolves
+        // relative URLs exactly as it did for the paid resource.
+        return parameters.fetch(request ? managementInput(request) : parameters.lastUrl, {
+            ...requestOptions,
             method: 'POST',
             redirect: 'manual',
             headers: managementHeaders(challenge, credential, parameters.lastUrl, parameters.headers),
@@ -497,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/precompile/Voucher.js

@@ -67,6 +67,10 @@ function getVoucherPayload(verifyingContract, chainId, voucher) {
 function isPrimitiveEnvelope(type) {
     return type === 'secp256k1' || type === 'p256' || type === 'webAuthn';
 }
+/** Detects a viem/tempo access key account the same way `Account.signVoucher` does. */
+function isAccessKeyAccount(account) {
+    return account.source === 'accessKey' && 'accessKeyAddress' in account;
+}
 function signCanonicalTempoVoucher(account, parameters) {
     // viem/tempo's canonical TIP-1034 voucher signer accepts Tempo account
     // extensions that are wider than viem's base Account type. Keep that
@@ -109,13 +113,22 @@ export async function signVoucher(client, account, voucher, verifyingContract, c
  * Signs a distinct EIP-712 authorization for cooperatively closing a channel.
  */
 export async function signCloseAuthorization(client, account, authorization, verifyingContract, chainId) {
-    const signature = await signTypedData(client, {
-        account,
-        domain: getVoucherDomain(verifyingContract, chainId),
-        types: closeAuthorizationTypes,
-        primaryType: 'CloseAuthorization',
-        message: authorization,
-    });
+    // `signTypedData` wraps access key signatures in a keychain envelope, which
+    // TIP-1034 rejects. Sign the hash raw instead, as viem/tempo's
+    // `Account.signVoucher` does for vouchers: the access key is the channel's
+    // authorized signer.
+    const signature = isAccessKeyAccount(account)
+        ? await account.sign({
+            hash: getCloseAuthorizationPayload(verifyingContract, chainId, authorization),
+            raw: true,
+        })
+        : await signTypedData(client, {
+            account,
+            domain: getVoucherDomain(verifyingContract, chainId),
+            types: closeAuthorizationTypes,
+            primaryType: 'CloseAuthorization',
+            message: authorization,
+        });
     const envelope = SignatureEnvelope.from(signature);
     if (!isPrimitiveEnvelope(envelope.type))
         throw new Error(`TIP-1034 close authorizations require a TIP-1020 primitive signature; received "${envelope.type}".`);

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/Session.d.ts

@@ -184,7 +184,8 @@ export declare namespace session {
         /**
          * Charges request-priced content (`unitType: 'request'`) in the same store update that accepts
          * its voucher, before the response, instead of in a second update when the response is
-         * delivered. The server must then refund requests it cannot serve.
+         * delivered. Always enabled for SSE request-priced content, including POST requests that
+         * return plain responses. The server must refund requests it cannot serve.
          */
         chargeOnAcceptance?: boolean | undefined;
         /**

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

@@ -363,7 +363,7 @@ export function session(p) {
             minVoucherDelta: parameters.minVoucherDelta,
             request,
         });
-        const chargeAmount = parameters.chargeOnAcceptance &&
+        const chargeAmount = (parameters.chargeOnAcceptance || parameters.sse) &&
             shouldChargeVoucherOnAcceptance({
                 capturedRequest: envelope?.capturedRequest,
                 payloadAction: payload.action,
@@ -433,6 +433,7 @@ export function session(p) {
             getRequestAmount: () => BigInt(context.request.amount ?? challenge.request.amount),
             sseEnabled: Boolean(parameters.sse),
             markPrepaidReceipt: Transport.markPrepaidSessionTick,
+            unitType: context.request.unitType,
             charge: (channelId, requestAmount) => chargeSessionChannel({ store, channelId, amount: requestAmount }),
             settleCharged: settleAcceptedCharge,
         });

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

@@ -167,13 +167,15 @@ export type ApplyVerifiedHttpAccountingParameters = {
     receipt: SessionReceipt;
     /** Marks an SSE receipt whose first content unit was charged during verification. */
     markPrepaidReceipt?: ((receipt: SessionReceipt) => SessionReceipt) | undefined;
-    /** Whether SSE transport is enabled. SSE accounting is stream-driven, not HTTP-response-driven. */
+    /** Pricing unit; request-priced content is charged before handing control to the application. */
+    unitType?: unknown;
+    /** Whether SSE transport is enabled. Non-request units are charged as the stream advances. */
     sseEnabled: boolean;
     /** Runs optional server settlement policy after a successful content charge. */
     settleCharged: SettleChargedSessionChannel;
 };
 /** Returns whether an accepted credential will authorize and charge an HTTP content response. */
-export declare function shouldApplyVerifiedHttpAccounting(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction' | 'sseEnabled'>): boolean;
+export declare function shouldApplyVerifiedHttpAccounting(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction' | 'sseEnabled' | 'unitType'>): boolean;
 /**
  * Returns whether a voucher pays for its request in the store update that accepts it. A
  * request-priced content request is charged exactly once, so this is the charge the HTTP

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

@@ -161,12 +161,12 @@ export async function releaseScheduledSettlement(parameters) {
 }
 /** Returns whether an accepted credential will authorize and charge an HTTP content response. */
 export function shouldApplyVerifiedHttpAccounting(parameters) {
-    const { capturedRequest, payloadAction, sseEnabled } = parameters;
+    const { capturedRequest, payloadAction, sseEnabled, unitType } = parameters;
     if (!capturedRequest)
         return false;
     if (payloadAction !== 'open' && payloadAction !== 'voucher')
         return false;
-    if (sseEnabled && capturedRequest.method === 'POST')
+    if (sseEnabled && capturedRequest.method === 'POST' && unitType !== 'request')
         return false;
     return isSessionContentRequest(capturedRequest);
 }

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;
     };
 }

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

@@ -1,7 +1,58 @@
 import * as Constants from '../../../Constants.js';
 import * as Credential from '../../../Credential.js';
 import { createSessionReceipt, extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptEvent, readSessionChallengeAmount, requireSessionCredentialContext, } from '../precompile/Protocol.js';
+import * as ChannelStore from './ChannelStore.js';
 import { meterIterable, } from './MeteredStream.js';
+/** Exposes durable retry information when no refund hook is configured or it fails. */
+export class PrepaidRefundError extends Error {
+    refund;
+    name = 'PrepaidRefundError';
+    constructor(refund) {
+        super('Prepaid stream delivery failed and requires merchant refund reconciliation.');
+        this.refund = refund;
+    }
+}
+/** Maximum retained automatic refund operations per channel. Never evict live retry keys. */
+export 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 async function preparePrepaidRefund(options) {
+    if (!options.autoCreditPrepaid || !options.prepaidUnits || options.tickCost === 0n)
+        return;
+    if (!options.refundIdempotencyKey)
+        throw new Error('Automatic refunds require a stable refundIdempotencyKey');
+    const key = options.refundIdempotencyKey;
+    const amount = (BigInt(options.prepaidUnits) * options.tickCost).toString();
+    await options.store.updateChannel(options.channelId, (current) => {
+        if (!current)
+            throw new Error('Cannot prepare prepaid refund: channel not found');
+        const existing = current.prepaidRefunds?.[key];
+        if (existing) {
+            if (existing.amount !== amount || existing.units !== options.prepaidUnits)
+                throw new Error('Prepaid refund key conflicts with an existing delivery');
+            return current;
+        }
+        const liveMarkers = Object.values(current.idempotencyMarkers ?? {}).filter((marker) => marker.expiresAt > Date.now()).length;
+        if (Object.keys(current.prepaidRefunds ?? {}).length + liveMarkers >= maxPrepaidRefunds)
+            throw new Error('Prepaid refund capacity reached; reconcile outstanding deliveries');
+        return {
+            ...current,
+            prepaidRefunds: {
+                ...current.prepaidRefunds,
+                [key]: {
+                    amount,
+                    units: options.prepaidUnits,
+                    status: 'pending',
+                    createdAt: Date.now(),
+                },
+            },
+        };
+    });
+}
 /**
  * SSE (Server-Sent Events) utilities for metered streaming payments.
  *
@@ -30,6 +81,9 @@ export { extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptE
  *    `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 function serve(options) {
@@ -38,11 +92,100 @@ export function serve(options) {
     const abortController = new AbortController();
     let streamController;
     let terminal = false;
+    let preparation = Promise.resolve();
+    let termination;
+    let committedPrepaidAwaitingDelivery = 0;
+    let undeliveredPrepaidUnits = options.prepaidUnits ?? 0;
+    if (!Number.isSafeInteger(undeliveredPrepaidUnits) || undeliveredPrepaidUnits < 0)
+        throw new Error('prepaidUnits must be a non-negative safe integer');
+    const refundIdempotencyKey = options.refundIdempotencyKey ?? `stream:${globalThis.crypto.randomUUID()}`;
+    ChannelStore.assertIdempotencyOptions({ idempotencyKey: refundIdempotencyKey });
+    const refundOptions = { ...options, refundIdempotencyKey };
+    const clearObligation = async () => {
+        if (!options.autoCreditPrepaid)
+            return;
+        await store.updateChannel(channelId, (current) => {
+            if (!current?.prepaidRefunds?.[refundIdempotencyKey])
+                return current;
+            const prepaidRefunds = { ...current.prepaidRefunds };
+            delete prepaidRefunds[refundIdempotencyKey];
+            return { ...current, prepaidRefunds };
+        });
+    };
+    const creditFailedDelivery = async () => {
+        if (!options.autoCreditPrepaid)
+            return;
+        if (undeliveredPrepaidUnits === 0 || tickCost === 0n) {
+            await clearObligation();
+            return;
+        }
+        const recordFailure = await store
+            .updateChannel(channelId, (current) => {
+            if (!current?.prepaidRefunds?.[refundIdempotencyKey])
+                throw new Error('Prepaid refund obligation missing');
+            return {
+                ...current,
+                prepaidRefunds: {
+                    ...current.prepaidRefunds,
+                    [refundIdempotencyKey]: {
+                        ...current.prepaidRefunds[refundIdempotencyKey],
+                        status: 'failed',
+                        amount: (BigInt(undeliveredPrepaidUnits) * tickCost).toString(),
+                        units: undeliveredPrepaidUnits,
+                    },
+                },
+            };
+        })
+            .then(() => undefined, (error) => ({ error }));
+        const amount = BigInt(undeliveredPrepaidUnits) * tickCost;
+        const result = recordFailure
+            ? { status: 'failed', error: recordFailure.error }
+            : await ChannelStore.creditChannel(store, channelId, amount, {
+                idempotencyKey: refundIdempotencyKey,
+                units: undeliveredPrepaidUnits,
+                maxMarkers: maxPrepaidRefunds,
+            }).catch((error) => ({ status: 'failed', error }));
+        if (result.status === 'credited') {
+            await clearObligation();
+            return;
+        }
+        let externalRefundAmount = null;
+        if (result.status === 'declined' && result.reason === 'finalized') {
+            const captured = result.channel.settledOnChain - (result.channel.spent - amount);
+            externalRefundAmount = captured < 0n ? 0n : captured > amount ? amount : captured;
+            if (externalRefundAmount === 0n) {
+                await clearObligation();
+                return;
+            }
+        }
+        const refund = {
+            channelId,
+            amount,
+            externalRefundAmount,
+            units: undeliveredPrepaidUnits,
+            idempotencyKey: refundIdempotencyKey,
+            credit: result,
+        };
+        if (!options.onRefundRequired)
+            throw new PrepaidRefundError(refund);
+        try {
+            await options.onRefundRequired(refund);
+            await clearObligation();
+        }
+        catch {
+            throw new PrepaidRefundError(refund);
+        }
+    };
     const iterator = meterIterable({
         store,
         channelId,
         tickCost,
         generate,
+        chargeOnce: options.chargeOnce,
+        onPrepaidChargeCommitted() {
+            undeliveredPrepaidUnits = Math.max(0, undeliveredPrepaidUnits - 1);
+            committedPrepaidAwaitingDelivery += 1;
+        },
         beforeCharge: options.beforeCharge,
         onChargeCommitted: options.onChargeCommitted,
         pollIntervalMs,
@@ -54,23 +197,33 @@ export function serve(options) {
     const cleanup = () => signal?.removeEventListener('abort', abort);
     const terminate = (reason) => {
         if (terminal)
-            return;
+            return termination;
         terminal = true;
         abortController.abort(reason);
         cleanup();
         void Promise.resolve()
             .then(() => iterator.return?.(undefined))
             .catch(() => { });
-        try {
-            streamController?.close();
-        }
-        catch { }
+        termination = preparation
+            .catch(() => { })
+            .then(clearObligation)
+            .finally(() => {
+            try {
+                streamController?.close();
+            }
+            catch { }
+        });
+        return termination;
+    };
+    const abort = () => {
+        void terminate(signal?.reason)?.catch(() => { });
     };
-    const abort = () => terminate(signal?.reason);
     signal?.addEventListener('abort', abort, { once: true });
     return new ReadableStream({
-        start(controller) {
+        async start(controller) {
             streamController = controller;
+            preparation = preparePrepaidRefund(refundOptions);
+            await preparation;
             if (signal?.aborted)
                 abort();
         },
@@ -86,8 +239,13 @@ export function serve(options) {
                         return;
                     const value = next.value;
                     controller.enqueue(encoder.encode(formatMessageEvent(value)));
+                    if (committedPrepaidAwaitingDelivery > 0)
+                        committedPrepaidAwaitingDelivery -= 1;
+                    else
+                        undeliveredPrepaidUnits = Math.max(0, undeliveredPrepaidUnits - 1);
                     return;
                 }
+                await clearObligation();
                 if (!abortController.signal.aborted) {
                     const channel = await store.getChannel(channelId);
                     if (channel) {
@@ -114,14 +272,21 @@ export function serve(options) {
                     return;
                 terminal = true;
                 cleanup();
-                if (!abortController.signal.aborted)
-                    controller.error(e);
+                if (!abortController.signal.aborted) {
+                    try {
+                        await creditFailedDelivery();
+                        controller.error(e);
+                    }
+                    catch (refundError) {
+                        controller.error(new AggregateError([e, refundError], 'Stream delivery and prepaid refund failed.'));
+                    }
+                }
                 else
                     controller.close();
             }
         },
         cancel(reason) {
-            terminate(reason);
+            return terminate(reason);
         },
     });
 }