mppx 0.8.15 → 0.8.18

package/dist/evm/client/Methods.d.ts

@@ -6,8 +6,8 @@ export declare function evm(parameters: evm.Parameters): readonly [import("../..
     readonly name: "evm";
     readonly intent: "charge";
     readonly schema: {
-        readonly credential: {
-            readonly payload: import("zod/mini").ZodMiniObject<{
+        credential: {
+            payload: import("zod/mini").ZodMiniObject<{
                 from: import("zod/mini").ZodMiniString<string>;
                 nonce: import("zod/mini").ZodMiniString<string>;
                 signature: import("zod/mini").ZodMiniString<string>;
@@ -18,7 +18,7 @@ export declare function evm(parameters: evm.Parameters): readonly [import("../..
                 value: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>;
         };
-        readonly request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
+        request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
             amount: import("zod/mini").ZodMiniString<string>;
             chainId: import("zod/mini").ZodMiniNumber<number>;
             currency: import("zod/mini").ZodMiniString<string>;
@@ -35,31 +35,31 @@ export declare function evm(parameters: evm.Parameters): readonly [import("../..
                 recipient: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>>>;
         }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
+            description?: string | undefined;
+            externalId?: string | undefined;
             amount: string;
             currency: `0x${string}`;
             methodDetails: {
+                chainId: number;
+                credentialTypes: string[];
+                decimals: number;
+                permit2Address?: `0x${string}` | undefined;
                 splits?: {
                     amount: string;
                     recipient: string;
                 }[] | undefined;
-                permit2Address?: `0x${string}` | undefined;
-                chainId: number;
-                credentialTypes: string[];
-                decimals: number;
             };
             recipient: `0x${string}`;
-            description?: string | undefined;
-            externalId?: string | undefined;
         }, {
             amount: string;
             chainId: number;
             currency: string;
-            decimals: number;
-            recipient: string;
             credentialTypes?: "authorization"[] | undefined;
+            decimals: number;
             description?: string | undefined;
             externalId?: string | undefined;
             permit2Address?: string | undefined;
+            recipient: string;
             splits?: {
                 amount: string;
                 recipient: string;

package/dist/evm/server/Charge.d.ts

@@ -13,7 +13,7 @@ export declare function charge(parameters: charge.NativeConfig): Method.Server<t
 export declare namespace charge {
     type Parameters = NativeConfig;
     type Native = Method.Server<typeof Methods.charge, Defaults>;
-    type NativeConfig = BaseConfig & CurrencyConfig & RecipientConfig;
+    type NativeConfig = BaseConfig & CurrencyConfig & RecipientConfig & Method.ComposableHooks<typeof Methods.charge>;
     type BaseConfig = {
         /** EIP-3009 token domain metadata. Required for raw addresses and viem tokens; inferred for known assets. */
         authorization?: Types.AuthorizationConfig | undefined;

package/dist/evm/server/Charge.js

@@ -12,6 +12,8 @@ export function charge(parameters) {
     const paths = createPaths(config);
     const transport = httpTransport(paths);
     return Method.toServer(Methods.charge, {
+        canOffer: parameters.canOffer,
+        onPaymentSuccess: parameters.onPaymentSuccess,
         defaults: {
             chainId: config.chainId,
             currency: config.currency,

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

@@ -7,8 +7,8 @@ export declare function evm<const parameters extends evm.Parameters>(parameters:
     readonly name: "evm";
     readonly intent: "charge";
     readonly schema: {
-        readonly credential: {
-            readonly payload: import("zod/mini").ZodMiniObject<{
+        credential: {
+            payload: import("zod/mini").ZodMiniObject<{
                 from: import("zod/mini").ZodMiniString<string>;
                 nonce: import("zod/mini").ZodMiniString<string>;
                 signature: import("zod/mini").ZodMiniString<string>;
@@ -19,7 +19,7 @@ export declare function evm<const parameters extends evm.Parameters>(parameters:
                 value: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>;
         };
-        readonly request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
+        request: import("zod/mini").ZodMiniPipe<import("zod/mini").ZodMiniObject<{
             amount: import("zod/mini").ZodMiniString<string>;
             chainId: import("zod/mini").ZodMiniNumber<number>;
             currency: import("zod/mini").ZodMiniString<string>;
@@ -36,31 +36,31 @@ export declare function evm<const parameters extends evm.Parameters>(parameters:
                 recipient: import("zod/mini").ZodMiniString<string>;
             }, import("zod/v4/core").$strip>>>;
         }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
+            description?: string | undefined;
+            externalId?: string | undefined;
             amount: string;
             currency: `0x${string}`;
             methodDetails: {
+                chainId: number;
+                credentialTypes: string[];
+                decimals: number;
+                permit2Address?: `0x${string}` | undefined;
                 splits?: {
                     amount: string;
                     recipient: string;
                 }[] | undefined;
-                permit2Address?: `0x${string}` | undefined;
-                chainId: number;
-                credentialTypes: string[];
-                decimals: number;
             };
             recipient: `0x${string}`;
-            description?: string | undefined;
-            externalId?: string | undefined;
         }, {
             amount: string;
             chainId: number;
             currency: string;
-            decimals: number;
-            recipient: string;
             credentialTypes?: "authorization"[] | undefined;
+            decimals: number;
             description?: string | undefined;
             externalId?: string | undefined;
             permit2Address?: string | undefined;
+            recipient: string;
             splits?: {
                 amount: string;
                 recipient: string;

package/dist/internal/HeaderCodec.d.ts

@@ -7,8 +7,8 @@ import type * as z from '../zod.js';
  * can opt into the exact wire encoding their protocol expects.
  */
 export declare function createJson<const schema extends z.ZodMiniType>(schema: schema): {
-    encode(value: z.core.output<schema>): string;
-    decode(value: string): z.core.output<schema>;
+    encode(value: z.infer<schema>): string;
+    decode(value: string): z.infer<schema>;
 };
 /** Error thrown when a JSON header value is not valid base64-encoded JSON. */
 export declare class InvalidJsonHeaderError extends Error {

package/dist/internal/types.d.ts

@@ -2,6 +2,12 @@
 export type Compute<type> = {
     [key in keyof type]: type[key];
 } & unknown;
+/** Recursively makes every property of a value readonly. */
+export type DeepReadonly<type> = type extends (...args: infer _arguments) => infer _return ? type : type extends readonly unknown[] ? {
+    readonly [key in keyof type]: DeepReadonly<type[key]>;
+} : type extends object ? {
+    readonly [key in keyof type]: DeepReadonly<type[key]>;
+} : type;
 declare const symbol: unique symbol;
 /**
  * Creates a branded type of `T` with the brand `U`.

package/dist/proxy/Proxy.d.ts

@@ -46,6 +46,8 @@ export declare namespace create {
         docs?: Service.Docs | undefined;
         /** Custom `fetch` implementation. Defaults to `globalThis.fetch`. */
         fetch?: typeof globalThis.fetch | undefined;
+        /** Default handler for failed upstream attempts. Services may override it. */
+        onUpstreamError?: Service.UpstreamErrorHandler | 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

@@ -99,7 +99,13 @@ export function create(config) {
         const endpoint = matched.value;
         const ctx = { request, service, upstreamPath };
         if (endpoint === true)
-            return proxyUpstream({ request, service, ctx, proxy });
+            return proxyUpstream({
+                request,
+                service,
+                ctx,
+                proxy,
+                onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
+            });
         const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay;
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
@@ -130,6 +136,7 @@ export function create(config) {
             service,
             ctx: { ...ctx, ...options },
             proxy,
+            onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
         });
         return result.withReceipt(upstreamRes);
     }
@@ -140,7 +147,7 @@ export function create(config) {
 }
 /** @internal */
 async function proxyUpstream(options) {
-    const { request, service, ctx, proxy } = options;
+    const { request, service, ctx, proxy, onUpstreamError } = options;
     const url = ctx.upstreamPath + new URL(request.url).search;
     const headers = Headers.scrub(request.headers);
     const method = request.method.toUpperCase();
@@ -154,14 +161,111 @@ async function proxyUpstream(options) {
         init.body = request.body;
         init.duplex = 'half';
     }
-    let upstreamReq = new globalThis.Request(new URL(url, new URL(service.baseUrl).origin), init);
+    const upstreamRequest = new globalThis.Request(new URL(url, new URL(service.baseUrl).origin), init);
+    if (!onUpstreamError)
+        return proxyUpstreamOnce({
+            ctx,
+            proxy,
+            service,
+            upstreamRequest,
+        });
+    for (let attempt = 1;; attempt++) {
+        const outcome = await proxyUpstreamAttempt({
+            ctx,
+            proxy,
+            service,
+            upstreamRequest,
+        });
+        let response = outcome.response;
+        if (response && service.rewriteResponse)
+            response = await service.rewriteResponse(response, ctx);
+        if (response?.ok)
+            return response;
+        const handlerResponse = response?.clone();
+        const action = await onUpstreamError({
+            ...ctx,
+            attempt,
+            error: outcome.error,
+            response: handlerResponse,
+            upstreamRequest: outcome.upstreamRequest,
+        });
+        if (!action.retry) {
+            if (action.response) {
+                if (response)
+                    void cancelResponseBody(response);
+                return action.response;
+            }
+            if (response) {
+                if (handlerResponse)
+                    void cancelResponseBody(handlerResponse);
+                return response;
+            }
+            throw outcome.error;
+        }
+        for (const failedResponse of [response, handlerResponse])
+            if (failedResponse)
+                void cancelResponseBody(failedResponse);
+        await waitForRetry(action.delay, request.signal);
+    }
+}
+/** Proxies one request without retaining a replay copy of its body. */
+async function proxyUpstreamOnce(options) {
+    const { ctx, proxy, service } = options;
+    let upstreamRequest = options.upstreamRequest;
     if (service.rewriteRequest)
-        upstreamReq = await service.rewriteRequest(upstreamReq, ctx);
-    let upstreamRes = await proxy(upstreamReq);
-    upstreamRes = Headers.scrubResponse(upstreamRes);
+        upstreamRequest = await service.rewriteRequest(upstreamRequest, ctx);
+    let response = await proxy(upstreamRequest);
+    response = Headers.scrubResponse(response);
     if (service.rewriteResponse)
-        upstreamRes = await service.rewriteResponse(upstreamRes, ctx);
-    return upstreamRes;
+        response = await service.rewriteResponse(response, ctx);
+    return response;
+}
+/** Performs one independently replayable upstream request attempt. */
+async function proxyUpstreamAttempt(options) {
+    const { ctx, proxy, service } = options;
+    let upstreamRequest = options.upstreamRequest.clone();
+    try {
+        if (service.rewriteRequest)
+            upstreamRequest = await service.rewriteRequest(upstreamRequest, ctx);
+        let response = await proxy(upstreamRequest);
+        response = Headers.scrubResponse(response);
+        return { error: undefined, response, upstreamRequest };
+    }
+    catch (error) {
+        return { error, response: undefined, upstreamRequest };
+    }
+}
+/** Cancels an unused failed response body before a retry. */
+async function cancelResponseBody(response) {
+    if (!response.body || response.bodyUsed)
+        return;
+    try {
+        await response.body.cancel();
+    }
+    catch {
+        return;
+    }
+}
+/** Waits for a retry delay while respecting request cancellation. */
+async function waitForRetry(delay = 0, signal) {
+    if (signal.aborted)
+        throw signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+    if (!Number.isFinite(delay) || delay <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            signal.removeEventListener('abort', onAbort);
+            reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+        };
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, delay);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+    });
 }
 function buildDiscoveryRoutes(services) {
     return services.flatMap((service) => Object.entries(service.routes).map(([pattern, endpoint]) => {
@@ -225,7 +329,11 @@ function matchesPaymentBinding(endpoint, binding) {
     const payment = Service.paymentOf(endpoint);
     if (!payment)
         return true;
-    return payment.method === binding.method && payment.intent === binding.intent;
+    const offers = Array.isArray(payment.offers) ? payment.offers : [payment];
+    return offers.some((offer) => typeof offer === 'object' &&
+        offer !== null &&
+        offer.method === binding.method &&
+        offer.intent === binding.intent);
 }
 function createFetchProxy(target, options) {
     const localFetch = options?.fetch ?? globalThis.fetch;

package/dist/proxy/Service.d.ts

@@ -10,6 +10,8 @@ export type Service = {
     docs?: Docs | undefined;
     /** Unique identifier used as the URL prefix (e.g. `'openai'` → `/{id}/...`). */
     id: string;
+    /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
+    onUpstreamError?: UpstreamErrorHandler | undefined;
     /** Hook to modify the upstream request before sending (e.g. inject auth headers). */
     rewriteRequest?: ((req: Request, ctx: Context) => Request | Promise<Request>) | undefined;
     /** Hook to modify the upstream response before returning to the client. */
@@ -57,11 +59,41 @@ export type Context = {
     service: Service;
     upstreamPath: string;
 } & EndpointOptions;
+/** Context passed to an upstream error handler after a failed proxy attempt. */
+export type UpstreamErrorContext = Context & {
+    /** One-based upstream attempt number. */
+    attempt: number;
+    /** Error thrown while preparing or sending the request. Undefined for HTTP error responses. */
+    error: unknown | undefined;
+    /** Non-2xx upstream response. Undefined when the attempt threw. */
+    response: Response | undefined;
+    /** Rewritten request sent to the upstream service. */
+    upstreamRequest: Request;
+};
+/** Action returned by an upstream error handler. */
+export type UpstreamErrorAction = {
+    /** Wait this many milliseconds before retrying. */
+    delay?: number | undefined;
+    retry: true;
+} | {
+    /** Optional response to return instead of the original failure. */
+    response?: Response | undefined;
+    retry: false;
+};
+/**
+ * Handles a non-2xx upstream response or thrown request error.
+ *
+ * This hook runs before the response is returned. It cannot observe failures
+ * from a streaming body after response headers have been sent.
+ */
+export type UpstreamErrorHandler<options = unknown> = (context: UpstreamErrorContext & Partial<Omit<options & {}, 'onUpstreamError' | 'routes'>>) => UpstreamErrorAction | Promise<UpstreamErrorAction>;
 export type From<options extends {
     routes: string;
 }> = {
     routes: EndpointMap<options['routes']>;
-} & Omit<options, 'routes'>;
+} & Omit<options, 'onUpstreamError' | 'routes'> & {
+    onUpstreamError?: UpstreamErrorHandler<options> | undefined;
+};
 /**
  * Creates a service definition.
  *
@@ -98,6 +130,8 @@ export declare namespace from {
         }) => string | undefined) | undefined;
         /** Shorthand: full request mutation function. Takes priority over `bearer`/`headers`. */
         mutate?: ((req: Request) => Request | Promise<Request>) | undefined;
+        /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
+        onUpstreamError?: UpstreamErrorHandler<options> | undefined;
         /** Hook to modify the upstream request. Receives typed per-endpoint options via `ctx`. */
         rewriteRequest?: ((req: Request, ctx: Context & Partial<options & {}>) => Request | Promise<Request>) | undefined;
         /** Map of route patterns to endpoint definitions. */
@@ -115,5 +149,6 @@ export declare function toLlmsTxt(services: Service[], options?: {
 }): string;
 /** Extracts per-endpoint options from an endpoint definition. */
 export declare function getOptions(endpoint: Endpoint): EndpointOptions | undefined;
+/** Derives discovery payment metadata from an explicitly priced endpoint handler. */
 export declare function paymentOf(endpoint: Endpoint): Record<string, unknown> | null;
 //# sourceMappingURL=Service.d.ts.map

package/dist/proxy/Service.js

@@ -1,4 +1,4 @@
-import { Value } from 'ox';
+import * as Metadata from '../discovery/internal/Metadata.js';
 /**
  * Creates a service definition.
  *
@@ -22,6 +22,7 @@ export function from(id, config) {
         description: config.description,
         docs: resolveDocs(config),
         id,
+        onUpstreamError: config.onUpstreamError,
         routes: config.routes,
         title: config.title,
         rewriteRequest: config.rewriteRequest
@@ -89,19 +90,19 @@ export function getOptions(endpoint) {
         return endpoint.options;
     return undefined;
 }
+/** Derives discovery payment metadata from an explicitly priced endpoint handler. */
 export function paymentOf(endpoint) {
     if (endpoint === true)
         return null;
     const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay;
     if (!('_internal' in handler))
         return null;
-    const { name, intent, defaults: _, schema: _s, _canonicalRequest, _stableBinding: _sb, authorize: _a, request: _r, respond: _re, stableBinding: _st, transport: _t, verify: _v, ...rest } = handler._internal;
-    const amount = (() => {
-        if (typeof rest.amount === 'string' && typeof rest.decimals === 'number')
-            return String(Value.from(rest.amount, rest.decimals));
-        return rest.amount;
-    })();
-    return { intent, method: name, ...rest, ...(amount !== undefined && { amount }) };
+    const metadata = handler._internal;
+    if (!metadata)
+        return null;
+    if (Metadata.isComposed(metadata))
+        return { offers: Metadata.offers(metadata).map(Metadata.paymentOffer) };
+    return Metadata.paymentOffer(metadata);
 }
 function resolveDocs(config) {
     if (config.docs) {

package/dist/proxy/services/anthropic.js

@@ -25,6 +25,7 @@ export function anthropic(config) {
             apiReference: 'https://docs.anthropic.com/en/api/getting-started',
             homepage: 'https://docs.anthropic.com/en/docs/intro-to-claude',
         },
+        onUpstreamError: config.onUpstreamError,
         rewriteRequest(request, ctx) {
             const apiKey = ctx.apiKey ?? config.apiKey;
             request.headers.set('x-api-key', apiKey);

package/dist/proxy/services/openai.js

@@ -26,6 +26,7 @@ export function openai(config) {
             homepage: 'https://platform.openai.com/docs',
             llms: 'https://context7.com/websites/platform_openai/llms.txt',
         },
+        onUpstreamError: config.onUpstreamError,
         rewriteRequest(request, ctx) {
             const apiKey = ctx.apiKey ?? config.apiKey;
             request.headers.delete('OpenAI-Organization');

package/dist/proxy/services/stripe.js

@@ -26,6 +26,7 @@ export function stripe(config) {
             homepage: 'https://docs.stripe.com',
             llms: 'https://docs.stripe.com/llms.txt',
         },
+        onUpstreamError: config.onUpstreamError,
         rewriteRequest(request, ctx) {
             const apiKey = ctx.apiKey ?? config.apiKey;
             request.headers.delete('Stripe-Account');

package/dist/server/Mppx.d.ts

@@ -1,11 +1,13 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import type * as Attestation from '../attestation/Types.js';
 import * as Challenge from '../Challenge.js';
 import * as Credential from '../Credential.js';
 import * as Errors from '../Errors.js';
-import type { MaybePromise } from '../internal/types.js';
+import type { DeepReadonly, MaybePromise } from '../internal/types.js';
 import * as Method from '../Method.js';
 import type * as Receipt from '../Receipt.js';
 import * as z from '../zod.js';
+import * as Html from './internal/html/config.js';
 import * as Transport from './Transport.js';
 export type Methods = readonly (Method.AnyServer | readonly Method.AnyServer[])[];
 export type ServerEventMap<methods extends readonly Method.Method[] = readonly Method.Method[], transport extends Transport.AnyTransport = Transport.AnyTransport> = {
@@ -36,6 +38,36 @@ export type ServerMethodDescriptor<method extends Pick<Method.Method, 'intent' |
     intent: method['intent'];
     name: method['name'];
 }>;
+/** A configured payment offer exposed to the server's `selectOffers` hook. */
+export type ServerOffer<method extends Method.Method = Method.Method> = method extends unknown ? ServerOfferFor<method> : never;
+type ServerOfferFor<method extends Method.Method> = Readonly<{
+    /** Canonical wire key for the configured method. */
+    key: `${method['name']}/${method['intent']}`;
+    /** Immutable method metadata for this offer. */
+    method: ServerOfferMethodDescriptor<method>;
+    /** Schema-normalized request configured for this offer. */
+    request: DeepReadonly<z.output<method['schema']['request']>>;
+}>;
+/** Immutable method metadata exposed to offer-selection hooks. */
+export type ServerOfferMethodDescriptor<method extends Method.Method = Method.Method> = Readonly<{
+    /** Optional public alias used to register this server method. */
+    alias?: method extends {
+        alias?: infer alias;
+    } ? alias : string;
+    intent: method['intent'];
+    name: method['name'];
+}>;
+/**
+ * Selects a subset of configured offers before payment challenges are issued.
+ *
+ * The hook must select at least one offer. Returned offers must come from the input,
+ * contain no duplicates, and preserve their original order. Offers and their
+ * normalized requests are deeply immutable. The incoming request is cloned so
+ * the hook may safely inspect its body when it has not already been consumed.
+ */
+export type SelectOffers<methods extends readonly Method.Method[]> = (offers: readonly ServerOffer<methods[number]>[], context: Readonly<{
+    request: globalThis.Request;
+}>) => MaybePromise<readonly ServerOffer<methods[number]>[]>;
 /** Context passed to `onChallengeCreated`. */
 export type ChallengeContext<method extends Method.Method = Method.Method, transport extends Transport.AnyTransport = Transport.AnyTransport> = Readonly<{
     capturedRequest?: Method.CapturedRequest | undefined;
@@ -136,7 +168,7 @@ export type Mppx<methods extends Methods = Methods, transport extends Transport.
      * })
      * ```
      */
-    compose(...entries: ComposeEntry<FlattenMethods<methods>>[]): (input: Request) => Promise<MethodFn.Response<Transport.Http>>;
+    compose(...entries: ComposeEntry<FlattenMethods<methods>>[]): ComposedHandler;
 } : {}) & Handlers<FlattenMethods<methods>, transport> & {
     /**
      * Generate Challenge objects for registered methods without going through
@@ -196,7 +228,7 @@ type TransportOverrideOf<mi> = mi extends {
 type EffectiveTransportOf<mi, defaultTransport extends Transport.AnyTransport> = [
     TransportOverrideOf<mi>
 ] extends [never] ? defaultTransport : TransportOverrideOf<mi>;
-declare const reservedMppxKeyValues: readonly ["challenge", "compose", "methods", "on", "onChallengeCreated", "onPaymentFailed", "onPaymentSuccess", "realm", "broadcastCredential", "transport", "validateCredential", "verifyCredential"];
+declare const reservedMppxKeyValues: readonly ['challenge', 'compose', 'methods', 'on', 'onChallengeCreated', 'onPaymentFailed', 'onPaymentSuccess', 'realm', 'broadcastCredential', 'transport', 'validateCredential', 'verifyCredential'];
 /** Public instance keys that payment method names and shorthand intents cannot shadow. */
 export type ReservedKey = (typeof reservedMppxKeyValues)[number];
 /** Public instance keys that payment method names and shorthand intents cannot shadow. */
@@ -207,18 +239,25 @@ type IsUniqueIntent<methods extends readonly Method.AnyServer[], intent extends
 }> extends infer M ? M extends M ? [Exclude<Extract<methods[number], {
     intent: intent;
 }>, M>] extends [never] ? true : false : never : never;
-/** Only includes shorthand intent keys when the intent is unique across methods. */
-type UniqueIntentHandlers<methods extends readonly Method.AnyServer[], transport extends Transport.AnyTransport> = {
-    [method_name in methods[number]['intent'] as IsUniqueIntent<methods, method_name> extends true ? method_name extends ReservedKey ? never : method_name : never]: MethodFn<Extract<methods[number], {
-        intent: method_name;
+/** Shorthand intent handlers. Single-method intents get direct handlers;
+ *  multi-method intents get an implicit compose wrapper. */
+type IntentHandlers<methods extends readonly Method.AnyServer[], transport extends Transport.AnyTransport> = {
+    [intent in methods[number]['intent'] as intent extends ReservedKey ? never : intent]: IsUniqueIntent<methods, intent> extends true ? MethodFn<Extract<methods[number], {
+        intent: intent;
     }>, EffectiveTransportOf<Extract<methods[number], {
-        intent: method_name;
+        intent: intent;
     }>, transport>, NonNullable<Extract<methods[number], {
-        intent: method_name;
+        intent: intent;
     }>['defaults']>> & MethodExtensions<Extract<methods[number], {
-        intent: method_name;
-    }>>;
+        intent: intent;
+    }>> : MultiMethodFn<Extract<methods[number], {
+        intent: intent;
+    }>, transport>;
 };
+/** Handler for an intent with multiple methods - takes the intersection of all methods' options. */
+type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (options: UnionToIntersection<MultiMethodFnDistribute<methods>>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+type MultiMethodFnDistribute<M> = M extends Method.Server<infer method, infer defaults, any, any, any> ? MethodFn.Options<method, NonNullable<defaults>> : never;
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 /** Nested handlers: `mppx.tempo.charge(...)`, grouped by method name then intent. */
 type PublicAlias<method extends Method.AnyServer> = method extends {
     alias?: infer alias;
@@ -237,7 +276,7 @@ type NestedHandlers<methods extends readonly Method.AnyServer[], transport exten
 };
 type Handlers<methods extends readonly Method.AnyServer[], transport extends Transport.AnyTransport> = {
     [mi in methods[number] as `${mi['name']}/${mi['intent']}`]: MethodFn<mi, EffectiveTransportOf<mi, transport>, NonNullable<mi['defaults']>> & MethodExtensions<mi>;
-} & UniqueIntentHandlers<methods, transport> & NestedHandlers<methods, transport> & {
+} & IntentHandlers<methods, transport> & NestedHandlers<methods, transport> & {
     [mi in methods[number] as PublicAlias<mi> extends string ? `${mi['name']}/${PublicAlias<mi>}` : never]: MethodFn<mi, EffectiveTransportOf<mi, transport>, NonNullable<mi['defaults']>> & MethodExtensions<mi>;
 };
 type MethodExtensions<method extends Method.AnyServer> = method extends {
@@ -272,12 +311,16 @@ type ChallengeFn<method extends Method.Method, defaults extends Record<string, u
 export declare function create<const methods extends Methods, const transport extends Transport.AnyTransport = Transport.Http>(config: create.Config<methods, transport>): Mppx<methods, transport>;
 export declare namespace create {
     type Config<methods extends Methods = Methods, transport extends Transport.AnyTransport = Transport.Http> = {
+        /** Request-attestation verifiers required before handling an HTTP payment request. */
+        attestation?: transport extends Transport.Http ? Attestation.VerifierMap | undefined : never;
         /** Array of configured methods. @example [tempo()] */
         methods: methods;
         /** Server realm (e.g., hostname). Resolution order: explicit value > env vars (`MPP_REALM`, `FLY_APP_NAME`, `VERCEL_URL`, etc.) > request URL hostname > `"MPP Payment"`. */
         realm?: string | undefined;
         /** Secret key for HMAC-bound challenge IDs for stateless verification. Must be at least 32 bytes. Auto-detected from `MPP_SECRET_KEY` environment variable. */
         secretKey?: string | undefined;
+        /** Selects a subset of composed HTTP offers before challenges are issued. Successfully matched credential dispatch bypasses this hook. */
+        selectOffers?: transport extends Transport.Http ? SelectOffers<FlattenMethods<methods>> | undefined : never;
         /** Transport to use. @default Transport.http() */
         transport?: transport | undefined;
     };
@@ -312,6 +355,25 @@ declare namespace MethodFn {
         withReceipt: Transport.WithReceipt<transport>;
     };
 }
+/** A configured handler — the return value of e.g. `mppx.charge({ ... })`. @internal */
+type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transport.Http>>) & {
+    _internal: {
+        _method: Method.AnyServer;
+        description?: string | undefined;
+        name: string;
+        intent: string;
+        html: Html.Options | undefined;
+        meta?: Record<string, string> | undefined;
+        scope?: string | undefined;
+        _canonicalRequest: Record<string, unknown>;
+        _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
+    };
+};
+type ComposedHandler = ((input: Request) => Promise<MethodFn.Response<Transport.Http>>) & {
+    _internal?: {
+        offers: readonly ConfiguredHandler['_internal'][];
+    };
+};
 /** An entry for `compose()`: a method reference, handler function ref, or string key paired with its options. */
 type ComposeEntry<methods extends readonly Method.AnyServer[]> = {
     [i in keyof methods]: readonly [
@@ -331,7 +393,7 @@ type ComposeEntry<methods extends readonly Method.AnyServer[]> = {
         MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
     ];
 }[number];
-export declare function compose(...args: readonly unknown[]): (input: Request) => Promise<MethodFn.Response<Transport.Http>>;
+export declare function compose(...args: readonly unknown[]): ComposedHandler;
 /**
  * Wraps a payment handler to create a Node.js HTTP listener.
  *