mppx 0.17.0 → 0.17.1

package/dist/cli/sessions/store.js

@@ -33,6 +33,7 @@ export class SessionBusyError extends Error {
     }
 }
 const storedChannelSchema = z.object({
+    origin: z.optional(z.string()),
     channelId: z.hash(),
     cumulativeAmount: z.string(),
     deposit: z.string(),
@@ -183,6 +184,11 @@ export function createSessionRegistry(options = {}) {
         const previous = previousValue === undefined ? undefined : parseStoredSession(previousValue, file);
         if (previous)
             assertSameSession(previous, input, file);
+        const origin = previous?.channel.origin ?? channel.origin;
+        if (previous?.channel.origin && channel.origin && previous.channel.origin !== channel.origin)
+            throw stateError(file, 'Session payment origin mismatch.');
+        if (origin !== undefined && new URL(origin).origin !== origin)
+            throw stateError(file, 'Session payment origin must be a normalized origin.');
         const challenge = parseSessionChallenge(input.challenge, file);
         assertChallengeMatchesChannel(challenge, channel, file);
         const receipt = input.receipt
@@ -193,7 +199,7 @@ export function createSessionRegistry(options = {}) {
         const spent = maxBigInt(input.spent ?? 0n, receipt ? BigInt(receipt.spent) : 0n, previous ? BigInt(previous.spent) : 0n);
         if (spent > cumulativeAmount)
             throw stateError(file, 'Session spend exceeds the locally authorized cumulative amount.');
-        const storedChannel = sanitizeStoredChannel(serializeEntry({ ...channel, cumulativeAmount }), file);
+        const storedChannel = sanitizeStoredChannel(serializeEntry({ ...channel, cumulativeAmount, ...(origin !== undefined && { origin }) }), file);
         const timestamp = monotonicTimestamp(previous?.updatedAt, now(), file);
         const latestReceipt = selectLatestReceipt(previous?.receipt, receipt);
         const account = sanitizeAccount(input.account, file);

package/dist/cli/validate/helpers.d.ts

@@ -37,7 +37,7 @@ export type Counts = {
     skipped: number;
 };
 export declare function printResults(results: CheckResult[], counts: Counts): void;
-/** Fetches the validation target without allowing it to redirect probes elsewhere. */
+/** Fetches a validation target without automatic payments or redirected probes. */
 export declare function fetchWithTimeout(url: RequestInfo | URL, init: RequestInit, timeoutMs?: number): Promise<Response>;
 export declare function formatBytes(bytes: number): string;
 export declare const HTTP_METHODS: Set<string>;

package/dist/cli/validate/helpers.js

@@ -1,3 +1,4 @@
+import { identityOf, skipPayment, unwrapFetch } from '../../client/internal/Fetch.js';
 import { pc } from '../utils.js';
 export function check(label, detail) {
     return detail ? { label, detail, severity: 'pass' } : { label, severity: 'pass' };
@@ -57,12 +58,23 @@ export function printResults(results, counts) {
             counts.skipped++;
     }
 }
-/** Fetches the validation target without allowing it to redirect probes elsewhere. */
+/** Fetches a validation target without automatic payments or redirected probes. */
 export async function fetchWithTimeout(url, init, timeoutMs = 15_000) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        return await fetch(url, { ...init, redirect: 'error', signal: controller.signal });
+        const fetch = globalThis.fetch;
+        const base = unwrapFetch(fetch);
+        const identity = identityOf(fetch);
+        const options = {
+            [skipPayment]: true,
+            ...init,
+            redirect: 'error',
+            signal: controller.signal,
+        };
+        return identity
+            ? (await identity.send((input, init) => base(input, { ...init, [skipPayment]: true }), new Request(url, options))).response
+            : await base(url, options);
     }
     finally {
         clearTimeout(timeout);

package/dist/client/Mppx.js

@@ -71,7 +71,10 @@ export function create(config) {
     function onPaymentResponse(handler) {
         return events.on('payment.response', handler);
     }
-    async function preparePayment(response, options) {
+    async function preparePayment(response, options, 
+    // Credential context known before selection, such as an explicit session close passed to
+    // `createCredential`, so methods can accept offers they would otherwise skip.
+    selectionContext) {
         const eventResponse = snapshotResponse(response);
         const challenges = await transport.getChallenges(response, options?.request);
         const challengeSnapshots = Object.freeze(challenges.map((candidate) => snapshotValue(candidate)));
@@ -79,7 +82,12 @@ export function create(config) {
         let challenge;
         let mi;
         try {
-            const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences);
+            let candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences, selectionContext);
+            // Without a context yet, as in `preparePayment(response).createCredential(context)`, fall back
+            // to offers a method skips only by policy: an explicit close may still use them, and the
+            // method enforces the policy for anything else when the credential is created.
+            if (candidates.length === 0 && selectionContext === undefined)
+                candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences, AcceptPayment.deferredContext);
             const orderedCandidates = await resolveChallengeOrder(candidates, options?.orderChallenges ?? orderChallenges);
             const selected = orderedCandidates[0];
             if (!selected)
@@ -237,7 +245,7 @@ export function create(config) {
         preparePayment,
         prepareRequest: prepareRequest,
         async createCredential(response, context, options) {
-            const prepared = await preparePayment(response, options);
+            const prepared = await preparePayment(response, options, context);
             return prepared.createCredential(context);
         },
     };

package/dist/client/internal/Fetch.d.ts

@@ -6,6 +6,8 @@ import type * as Method from '../../Method.js';
 import type * as z from '../../zod.js';
 import * as Transport from '../Transport.js';
 import * as ProofRealm from './ProofRealm.js';
+/** Per-request payment opt-out preserved by forwarding fetch layers. @internal */
+export declare const skipPayment: unique symbol;
 export type ClientEventMap<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], response = Response> = {
     'challenge.received': ChallengeReceivedPayload<methods, response>;
     'credential.created': CredentialCreatedPayload<methods, response>;

package/dist/client/internal/Fetch.js

@@ -14,6 +14,8 @@ import * as ProofRealm from './ProofRealm.js';
 const MPPX_FETCH_WRAPPER = Symbol.for('mppx.fetch.wrapper');
 /** Identity runner of an mppx fetch wrapper, inherited when that wrapper is wrapped again. */
 const MPPX_FETCH_IDENTITY = Symbol.for('mppx.fetch.identity');
+/** Per-request payment opt-out preserved by forwarding fetch layers. @internal */
+export const skipPayment = Symbol.for('mppx.fetch.skipPayment');
 const defaultMaxPaymentRetries = 3;
 const maxErrorBodyBytes = 64 * 1024;
 const errorBodyTimeoutMs = 2_000;
@@ -125,6 +127,8 @@ export function from(config) {
         const initialRequest = prepareInitialRequest(input, init, callerHeaders, paymentPreferences.header, hasExplicitAcceptPayment, acceptPaymentPolicy);
         let response = await send(cloneRequestInput(initialRequest.input), initialRequest.init);
         const transportRequest = withCapturedBody(initialRequest.init, await capturedBody);
+        if (init?.[skipPayment])
+            return response;
         if (!(await transport.isPaymentRequired(response, transportRequest)))
             return response;
         // Only extract context for payment handling after confirming 402.
@@ -139,7 +143,7 @@ export function from(config) {
         try {
             for (let retry = 0; retry < maxPaymentRetries; retry++) {
                 challenges = await transport.getChallenges(response, transportRequest);
-                const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries);
+                const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries, context);
                 const orderedCandidates = await resolveChallengeOrder(candidates, requestOrderChallenges ??
                     orderChallenges);
                 const selected = orderedCandidates[0];
@@ -161,7 +165,7 @@ export function from(config) {
                 if (challenge.expires)
                     Expires.assert(challenge.expires, challenge.id);
                 await identity?.challenge(response, { challenge: selectedChallenge }, resolveRequestUrl(initialRequest.input).href);
-                const paymentInput = resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input);
+                const paymentInput = await resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input, fetchInit);
                 ProofRealm.assert(selectedChallenge, () => resolveRequestUrl(paymentInput), trustedTempoProofRealms);
                 const previousCredential = preparedCredential;
                 const key = Challenge.serialize(selectedChallenge);
@@ -184,6 +188,8 @@ export function from(config) {
                         await settleAttempt(previousCredential, { status: 'rejected' });
                         preparedCredential = undefined;
                     }
+                    // A new payment must not start for a request the caller already aborted.
+                    resolveRequestSignal(input, init)?.throwIfAborted();
                     const credentialContext = overrideContext ?? context;
                     if (!MethodChallenge.has(selected.method))
                         return resolveCredential(selectedChallenge, selected.method, credentialContext);
@@ -807,7 +813,21 @@ function resolveRequestUrl(input) {
         return new URL(input.url);
     return new URL(input, isBrowser() ? globalThis.location.href : undefined);
 }
-function resolvePaymentRetryInput(response, fallback, initialInput) {
+/** Rejects Request modes whose paid retry cannot carry a credential to the server. */
+function assertPayableRequest(input, init) {
+    const request = input instanceof Request ? input : undefined;
+    const mode = init.mode ?? request?.mode;
+    // Fetch strips the Authorization header from no-cors requests.
+    if (mode === 'no-cors')
+        throw new Error('Cannot automatically pay a no-cors request: it cannot carry a credential.');
+    const cache = init.cache ?? request?.cache;
+    // A cache-only retry never reaches the server.
+    if (cache === 'only-if-cached')
+        throw new Error('Cannot automatically pay an only-if-cached request: its retry cannot reach the server.');
+}
+/** Retains Request state while targeting the same-origin challenge response URL. */
+async function resolvePaymentRetryInput(response, fallback, initialInput, init) {
+    assertPayableRequest(fallback, init);
     if (!response.url)
         return fallback;
     const responseUrl = new URL(response.url);
@@ -815,6 +835,42 @@ function resolvePaymentRetryInput(response, fallback, initialInput) {
     if (responseUrl.origin !== initialUrl.origin) {
         throw new Error(`Refusing to send payment credential across redirect from ${initialUrl.origin} to ${responseUrl.origin}`);
     }
+    const method = (init.method ?? (fallback instanceof Request ? fallback.method : 'GET')).toUpperCase();
+    // Fetch does not expose the redirect chain, so a non-GET/HEAD request may
+    // have become a GET before reaching the challenge (301/302/303).
+    if (response.redirected && method !== 'GET' && method !== 'HEAD')
+        throw new Error(`Cannot automatically pay a redirected ${method} request. Use prepareRequest() to preserve redirect semantics.`);
+    if (fallback instanceof Request) {
+        // A replacement body makes a consumed or locked original body irrelevant.
+        // Otherwise retain the original body for any later payment challenges.
+        const source = init.body != null ? fallback : fallback.clone();
+        // User-created requests cannot use navigate mode; retry a navigation as same-origin.
+        const request = new Request(source, fallback.mode === 'navigate' && init.mode === undefined
+            ? { ...init, mode: 'same-origin' }
+            : init);
+        // Fetch never sends a URL fragment, and the response URL has none.
+        if (request.url.split('#')[0] === response.url)
+            return request;
+        if (request.body) {
+            // Retargeting would turn the body into a stream without a length (and keepalive rejects
+            // streams). Retarget a buffered copy so the paid retry keeps its Content-Length.
+            return new Request(response.url, {
+                body: await request.arrayBuffer(),
+                cache: request.cache,
+                credentials: request.credentials,
+                headers: request.headers,
+                integrity: request.integrity,
+                keepalive: request.keepalive,
+                method: request.method,
+                mode: request.mode,
+                redirect: request.redirect,
+                referrer: request.referrer,
+                referrerPolicy: request.referrerPolicy,
+                signal: request.signal,
+            });
+        }
+        return new Request(response.url, request);
+    }
     return response.url;
 }
 //# sourceMappingURL=Fetch.js.map

package/dist/internal/AcceptPayment.d.ts

@@ -3,10 +3,17 @@ import type { MaybePromise } from './types.js';
 type MethodLike = {
     canHandleChallenge?: ((parameters: {
         challenge: Challenge.Challenge;
+        context?: unknown;
     }) => boolean) | undefined;
     intent: string;
     name: string;
 };
+/**
+ * Selection context for flows that receive the credential context only after an offer is chosen,
+ * such as `preparePayment()`. Methods may accept offers they would otherwise skip by policy and
+ * enforce that policy when the credential is created.
+ */
+export declare const deferredContext: unique symbol;
 /** Supported challenge paired with the configured client method that can sign it. */
 export type ChallengeCandidate<method extends MethodLike = MethodLike> = method extends MethodLike ? {
     challenge: Challenge.Challenge<Record<string, unknown>, method['intent'], method['name']>;
@@ -79,8 +86,11 @@ export declare function selectChallenge<const methods extends readonly MethodLik
     challenge: Challenge.Challenge;
     method: methods[number];
 } | undefined;
-/** Returns supported challenge candidates ordered by client payment preferences. */
-export declare function selectChallengeCandidates<const methods extends readonly MethodLike[]>(challenges: readonly Challenge.Challenge[], methods: methods, preferences: readonly Entry[]): ChallengeCandidate<methods[number]>[];
+/**
+ * Returns supported challenge candidates ordered by client payment preferences.
+ * `context` is the caller's credential context, when known before selection.
+ */
+export declare function selectChallengeCandidates<const methods extends readonly MethodLike[]>(challenges: readonly Challenge.Challenge[], methods: methods, preferences: readonly Entry[], context?: unknown): ChallengeCandidate<methods[number]>[];
 /** Returns the canonical `method/intent` key for a method or challenge-like value. */
 export declare function keyOf(value: {
     intent: string;

package/dist/internal/AcceptPayment.js

@@ -1,4 +1,10 @@
 import * as x402_ChallengeBrand from '../x402/internal/ChallengeBrand.js';
+/**
+ * Selection context for flows that receive the credential context only after an offer is chosen,
+ * such as `preparePayment()`. Methods may accept offers they would otherwise skip by policy and
+ * enforce that policy when the credential is created.
+ */
+export const deferredContext = Symbol('mppx.deferredContext');
 /** Builds the typed key tree used by callback-style preference config. */
 export function buildKeys(methods) {
     const keys = {};
@@ -70,8 +76,11 @@ export function selectChallenge(challenges, methods, preferences) {
         method: candidate.method,
     };
 }
-/** Returns supported challenge candidates ordered by client payment preferences. */
-export function selectChallengeCandidates(challenges, methods, preferences) {
+/**
+ * Returns supported challenge candidates ordered by client payment preferences.
+ * `context` is the caller's credential context, when known before selection.
+ */
+export function selectChallengeCandidates(challenges, methods, preferences, context) {
     const methodsByKey = new Map();
     for (const method of methods) {
         const key = keyOf(method);
@@ -90,7 +99,7 @@ export function selectChallengeCandidates(challenges, methods, preferences) {
         if (!match || match.q <= 0)
             return [];
         return matchingMethods
-            .filter((method) => method.canHandleChallenge?.({ challenge }) ?? true)
+            .filter((method) => method.canHandleChallenge?.(context === undefined ? { challenge } : { challenge, context }) ?? true)
             .map((method) => ({
             challenge,
             index,

package/dist/internal/version.d.ts

@@ -1,5 +1,5 @@
 /** Current mppx package version. */
-export declare const version = "0.17.0";
+export declare const version = "0.17.1";
 /** Canonical SDK identifier for this mppx release. */
-export declare const sdkIdentifier = "mppx/0.17.0";
+export declare const sdkIdentifier = "mppx/0.17.1";
 //# 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.0';
+export const version = '0.17.1';
 /** Canonical SDK identifier for this mppx release. */
 export const sdkIdentifier = `mppx/${version}`;
 //# sourceMappingURL=version.js.map

package/dist/mcp/client/McpClient.js

@@ -100,7 +100,7 @@ function createPaymentAwareCallTool(callTool, config) {
     const paymentPreferences = AcceptPayment.resolve(methods, config.paymentPreferences);
     const retryWithPayment = async (params, call, paymentRequired, cause, attemptsRemaining = maxPaymentAttempts) => {
         const challenges = paymentRequired.challenges;
-        const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries);
+        const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, paymentPreferences.entries, call.context);
         const orderedCandidates = config.orderChallenges
             ? await config.orderChallenges(candidates)
             : candidates;

package/dist/proxy/Proxy.d.ts

@@ -1,5 +1,8 @@
 import type * as http from 'node:http';
+import * as Replay from './internal/Replay.js';
 import * as Service from './Service.js';
+/** Options for {@link create.Config.replay}. */
+export type ReplayOptions = Replay.Options;
 /** A paid API proxy that gates upstream services behind the mppx 402 protocol. */
 export type Proxy = {
     /** Fetch API handler. Works with Bun, Deno, Next.js, Hono, Elysia, SvelteKit, etc. */
@@ -48,6 +51,18 @@ export declare namespace create {
         fetch?: typeof globalThis.fetch | undefined;
         /** Default handler for failed upstream attempts. Services may override it. */
         onUpstreamError?: Service.UpstreamErrorHandler | undefined;
+        /**
+         * Lets a payer collect a paid response after losing the connection.
+         *
+         * The paid upstream request runs detached from the client (its response must
+         * start within `ttl`), and its outcome is recorded under a key derived from the
+         * credential and the request's method, target and body. A retry with the
+         * same credential and request never pays again: it gets the stored
+         * response, `202` while the delivery runs, or, after a failed delivery, a
+         * new upstream attempt up to `maxAttempts`. Streamed (`text/event-stream`)
+         * and oversized responses are delivered but not stored. Off by default.
+         */
+        replay?: ReplayOptions | undefined;
         /** Services to proxy. Each service is mounted at `/{serviceId}/`. */
         services: Service.Service[];
         /** Human-readable title for the proxy shown in `llms.txt`. */

package/dist/proxy/Proxy.js

@@ -4,6 +4,7 @@ import * as Scope from '../server/internal/scope.js';
 import * as Mppx from '../server/Mppx.js';
 import * as Request from '../server/Request.js';
 import * as Headers from './internal/Headers.js';
+import * as Replay from './internal/Replay.js';
 import * as Route from './internal/Route.js';
 import * as Service from './Service.js';
 /**
@@ -34,6 +35,7 @@ import * as Service from './Service.js';
  */
 export function create(config) {
     const fetchImpl = config.fetch ?? globalThis.fetch;
+    const replay = config.replay ? Replay.resolve(config.replay) : undefined;
     const services = new Map(config.services.map((s) => {
         const proxy = createFetchProxy(s.baseUrl, { fetch: fetchImpl });
         return [s.id, { service: s, proxy }];
@@ -108,13 +110,59 @@ export function create(config) {
                 proxy,
                 onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
             });
+        // With replay, a paid request whose credential already paid for this exact
+        // request collects its recorded delivery instead of paying again.
+        let paidRequest = request;
+        let replayBody;
+        let replayKey;
+        // Routes with identity verifiers keep paying normally: a replay would skip them.
+        const credential = replay && !fallbackMatch && !requiresIdentity(handler)
+            ? Replay.credentialOf(request, credentialHeaders(handler))
+            : undefined;
+        if (replay && credential) {
+            const body = await Replay.readBody(request, replay.maxRequestBodySize);
+            if (!body)
+                return new Response('Payload Too Large', { status: 413 });
+            replayBody = body;
+            paidRequest = Replay.withBody(request, body);
+            replayKey = Replay.key({
+                body,
+                credential,
+                method: request.method,
+                target: url.origin + url.pathname + url.search,
+            });
+            const found = await Replay.lookup(replay, replayKey);
+            if (found.type === 'respond')
+                return found.response;
+            if (found.type === 'retry') {
+                const options = Service.getOptions(endpoint);
+                return Replay.deliver({
+                    applyReceipt: (response) => Replay.withReceiptHeader(response, found.receipt),
+                    attempts: found.attempts,
+                    replay,
+                    replayKey,
+                    requestHeaders: found.requestHeaders,
+                    run: (signal) => {
+                        // Send the headers of the request that was paid for, not the retry's.
+                        const upstream = Replay.withBody(paidRequest, body, signal, found.requestHeaders);
+                        return proxyUpstream({
+                            request: upstream,
+                            service,
+                            ctx: { ...ctx, request: upstream, ...options },
+                            proxy,
+                            onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                        });
+                    },
+                });
+            }
+        }
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
                 basePath: config.basePath,
                 routeKey: matched.key,
                 serviceId,
             });
-        const result = await handler(getConfiguredScope(handler) ? request : Scope.attach(request, scope));
+        const result = await handler(getConfiguredScope(handler) ? paidRequest : Scope.attach(paidRequest, scope));
         if (result.status === 402)
             return result.challenge;
         const managementResponse = (() => {
@@ -132,6 +180,26 @@ export function create(config) {
         if (fallbackMatch)
             return new Response('Method Not Allowed', { status: 405 });
         const options = Service.getOptions(endpoint);
+        if (replay && replayKey && replayBody) {
+            const body = replayBody;
+            return Replay.deliver({
+                applyReceipt: (response) => result.withReceipt(response),
+                attempts: 1,
+                replay,
+                replayKey,
+                requestHeaders: [...Headers.scrub(paidRequest.headers).entries()],
+                run: (signal) => {
+                    const upstream = Replay.withBody(paidRequest, body, signal);
+                    return proxyUpstream({
+                        request: upstream,
+                        service,
+                        ctx: { ...ctx, request: upstream, ...options },
+                        proxy,
+                        onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+                    });
+                },
+            });
+        }
         const upstreamRes = await proxyUpstream({
             request,
             service,
@@ -284,6 +352,26 @@ function buildDiscoveryRoutes(services) {
         };
     }));
 }
+/** Headers the handler reads Payment credentials from, lowercased (Authorization by default). */
+function credentialHeaders(handler) {
+    const internal = ('_internal' in handler ? handler._internal : undefined);
+    const headers = internal?.offers
+        ? internal.offers.flatMap((offer) => offer.credentialHeaders ?? [])
+        : (internal?.credentialHeaders ?? []);
+    const names = [...new Set(headers.map((header) => header.toLowerCase()))];
+    return names.length > 0 ? names : ['authorization'];
+}
+/** Whether a paid handler, or any offer of a composed one, requires identity verifiers. */
+function requiresIdentity(handler) {
+    if (!('_internal' in handler))
+        return false;
+    const internal = handler._internal;
+    if (!internal)
+        return false;
+    if (internal.offers)
+        return internal.offers.some((offer) => offer._identity);
+    return internal._identity === true;
+}
 function getConfiguredScope(handler) {
     if (!('_internal' in handler))
         return undefined;

package/dist/proxy/internal/Replay.d.ts

@@ -0,0 +1,105 @@
+import type * as Store from '../../Store.js';
+/** Options for replaying paid proxy deliveries. */
+export type Options = {
+    /**
+     * Upstream attempts per credential, including the first, before a retry gets `502`.
+     * A retry after a failed delivery (an upstream error, a 5xx or a body that broke
+     * off) sends the paid request upstream again without charging, so a
+     * non-idempotent upstream may run the operation twice; set `1` to only ever
+     * replay a recorded response. @default 3
+     */
+    maxAttempts?: number | undefined;
+    /** Largest response body, in bytes, kept for replay. Larger or streamed bodies are delivered but not kept. @default 1_048_576 */
+    maxBodySize?: number | undefined;
+    /** Largest request body, in bytes, a paid request may carry; larger ones get `413`. @default 1_048_576 */
+    maxRequestBodySize?: number | undefined;
+    /** `Retry-After` seconds returned while a delivery is still in flight. @default 5 */
+    retryAfter?: number | undefined;
+    /** Atomic store shared by every proxy instance that may receive a retry. */
+    store: Store.AtomicStore;
+    /**
+     * How long to wait for the upstream to start responding, and how long its outcome is kept after it is
+     * recorded, in milliseconds. Expired records are removed when they are next
+     * looked up, as with mppx's replay markers; give the backing store its own
+     * key expiry to reclaim records nobody retries. @default 900_000
+     */
+    ttl?: number | undefined;
+    /** Keeps background work alive after the response returns, such as Cloudflare's `ctx.waitUntil`. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** Replay options with defaults applied. */
+export type Resolved = {
+    maxAttempts: number;
+    maxBodySize: number;
+    maxRequestBodySize: number;
+    retryAfter: number;
+    store: Store.AtomicStore;
+    ttl: number;
+    waitUntil: ((promise: Promise<unknown>) => void) | undefined;
+};
+/** A delivery record, keyed by credential and request. */
+export type Record = {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'pending';
+} | {
+    attempts: number;
+    expires: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    status: 'failed';
+} | {
+    expires: number;
+    status: 'delivered';
+} | {
+    body: string;
+    expires: number;
+    headers: [string, string][];
+    responseStatus: number;
+    status: 'complete';
+    statusText: string;
+};
+/** Applies defaults to replay options. */
+export declare function resolve(options: Options): Resolved;
+/** Returns the request's Payment credential header value, if it carries one. */
+export declare function credentialOf(request: Request, headerNames?: readonly string[]): string | undefined;
+/** Reads a request body, or returns null when it is larger than maxRequestBodySize. */
+export declare function readBody(request: Request, maxRequestBodySize: number): Promise<Uint8Array<ArrayBuffer> | null>;
+/** Derives the replay key from the credential and the exact request (origin, path, query, method, body) it paid for. */
+export declare function key(parameters: {
+    body: Uint8Array;
+    credential: string;
+    method: string;
+    target: string;
+}): string;
+/** Rebuilds a request around an already-read body, optionally with another abort signal. */
+export declare function withBody(request: Request, body: Uint8Array, signal?: AbortSignal, headers?: HeadersInit): Request;
+/** What a request with a known credential should do. */
+export type Lookup = {
+    type: 'none';
+} | {
+    response: Response;
+    type: 'respond';
+} | {
+    attempts: number;
+    receipt: string | null;
+    requestHeaders: [string, string][];
+    type: 'retry';
+};
+/** Looks up a delivery and, for a failed one, claims the next upstream attempt. */
+export declare function lookup(replay: Resolved, replayKey: string): Promise<Lookup>;
+/** Runs a paid upstream delivery detached from the client and records its outcome. */
+export declare function deliver(parameters: {
+    applyReceipt: (response: Response) => Response | Promise<Response>;
+    attempts: number;
+    replay: Resolved;
+    replayKey: string;
+    /** The upstream headers of the paid request; a retried delivery reuses them. */
+    requestHeaders: [string, string][];
+    run: (signal: AbortSignal) => Promise<Response>;
+}): Promise<Response>;
+/** Adds a stored receipt to a response built for a retried delivery. */
+export declare function withReceiptHeader(response: Response, receipt: string | null): Response;
+//# sourceMappingURL=Replay.d.ts.map