mppx 0.15.0 → 0.16.0

package/dist/identity/Client.js

@@ -0,0 +1,133 @@
+import * as Challenge from '../Challenge.js';
+import * as Credential from '../Credential.js';
+import * as SigningContext from './internal/SigningContext.js';
+/** x402 credential headers (v2 and v1); a request carrying one is a paid attempt. */
+const x402CredentialHeaders = ['payment-signature', 'x-payment'];
+/**
+ * Creates the client runner for a list of provers.
+ *
+ * Provers run in list order on every attempt, sharing one attempt context.
+ * List request signers last so their signatures cover headers added by
+ * earlier provers.
+ */
+export function from(provers) {
+    if (provers.length === 0)
+        throw new TypeError('Mppx client identity must configure at least one prover.');
+    // Scopes are matched exactly: a string scope would fall back to substring matching.
+    for (const prover of provers)
+        if (prover.scope !== '*' && !Array.isArray(prover.scope))
+            throw new TypeError('Identity prover scope must be "*" or an array of origins.');
+    const inScope = (url) => {
+        const origin = new URL(url).origin;
+        return provers.filter((prover) => prover.scope === '*' || prover.scope.includes(origin));
+    };
+    async function sendOnce(fetch, request, context, resendable) {
+        // Keep the original readable only when it may be resent; otherwise a clone would tee
+        // (and buffer) a streamed body that is never read again.
+        const source = resendable ? request.clone() : request;
+        const scoped = inScope(request.url);
+        if (scoped.length === 0)
+            return { request: source, response: await fetch(source) };
+        const attempt = Object.freeze({ ...context, ...SigningContext.create() });
+        let sent = new Request(source, {
+            redirect: request.redirect === 'follow' ? 'error' : request.redirect,
+        });
+        for (const prover of scoped)
+            sent = await prover.prove(sent, attempt);
+        return { request: sent, response: await fetch(sent) };
+    }
+    return {
+        async send(fetch, request, context = {}) {
+            // A paid attempt (a challenge in context, or a Payment or x402 credential the caller
+            // attached) is never resent: its credential may already have settled, and replaying it
+            // could pay again.
+            const paid = context.challenge !== undefined ||
+                x402CredentialHeaders.some((name) => request.headers.has(name)) ||
+                [...request.headers.values()].some((value) => Credential.extractPaymentScheme(value) !== null);
+            const resendable = !paid && inScope(request.url).some((prover) => prover.retry);
+            const result = await sendOnce(fetch, request, context, resendable);
+            const { response } = result;
+            if (!resendable || response.status < 400 || response.status === 402)
+                return result;
+            // Each callback reads its own copy, so the returned response stays readable.
+            const copies = [];
+            let retry = false;
+            for (const prover of inScope(request.url)) {
+                if (!prover.retry)
+                    continue;
+                const copy = response.clone();
+                copies.push(copy);
+                if (await prover.retry(copy, context))
+                    retry = true;
+            }
+            if (!retry) {
+                release(copies);
+                return result;
+            }
+            release([response, ...copies]);
+            return sendOnce(fetch, request, context, false);
+        },
+        async challenge(response, context, url) {
+            for (const prover of inScope(url)) {
+                if (!prover.retry)
+                    continue;
+                const copy = response.clone();
+                try {
+                    await prover.retry(copy, context);
+                }
+                finally {
+                    release([copy]);
+                }
+            }
+        },
+    };
+}
+/** Releases unread response copies without waiting, so they neither buffer the body nor block a resend. */
+function release(responses) {
+    for (const unread of responses)
+        if (!unread.bodyUsed)
+            void unread.body?.cancel().catch(() => { });
+}
+/**
+ * Wraps a fetch implementation so every request is proved.
+ *
+ * Prefer `Mppx.create({ identity })`, which also passes the payment challenge to provers.
+ */
+export function wrapFetch(fetch, client, context) {
+    return async (input, init) => {
+        const request = new Request(input, init);
+        // A retry may answer a refreshed challenge: bind proofs to the challenge its credential
+        // carries, and let provers prepare for a refreshed 402 of the same method and intent.
+        const challenge = credentialChallenge(request.headers) ?? context?.challenge;
+        const { response } = await client.send(fetch, request, { ...context, challenge });
+        if (response.status === 402 && challenge)
+            // A 402 without a parseable Payment challenge is returned as is: the caller decides.
+            for (const next of challengesOf(response))
+                if (next.method === challenge.method && next.intent === challenge.intent)
+                    await client.challenge(response, { ...context, challenge: next }, request.url);
+        return response;
+    };
+}
+/** Returns the Payment challenges of a 402, or none when it carries none that parse. */
+function challengesOf(response) {
+    try {
+        return Challenge.fromResponseList(response);
+    }
+    catch {
+        return [];
+    }
+}
+/** Returns the challenge of a Payment credential in `headers`, if any. */
+function credentialChallenge(headers) {
+    for (const [, value] of headers) {
+        const payment = Credential.extractPaymentScheme(value);
+        if (!payment)
+            continue;
+        try {
+            return Credential.deserialize(payment).challenge;
+        }
+        catch { }
+    }
+    return undefined;
+}
+//# sourceMappingURL=Client.js.map

package/dist/identity/Server.d.ts

@@ -0,0 +1,46 @@
+import type * as Types from './Types.js';
+/**
+ * Accepts the first of several identity protocols that verifies.
+ *
+ * Every member runs. The result is `valid` if any member verifies, `invalid` if none verifies and
+ * any member was presented but failed, and `missing` otherwise, with every
+ * member's challenge headers. All members must run at the same stage.
+ *
+ * @example
+ * ```ts
+ * mppx.charge({ amount: '1', identity: [Identity.anyOf(tap, webBotAuth)] })
+ * ```
+ */
+export declare function anyOf(...verifiers: readonly [Types.Verifier, Types.Verifier, ...Types.Verifier[]]): Types.Verifier<{
+    index: number;
+    value: unknown;
+}>;
+/** The combined outcome of a route's verifiers at one stage. @internal */
+export type Outcome = {
+    status: 'valid';
+    values: ReadonlyMap<Types.Verifier, unknown>;
+} | {
+    status: 'missing' | 'invalid';
+    code: number;
+    headers: Headers;
+    reason: string;
+};
+/**
+ * Runs every verifier at one stage and combines their outcomes.
+ *
+ * Every verifier must be valid. Any `invalid` outcome rejects with 401 unless
+ * it sets its own code; otherwise any `missing` outcome rejects with 403. The
+ * headers of every rejected outcome are merged. Each verifier runs at most once
+ * per request and context, so replay-protected nonces are consumed once even
+ * when several handlers evaluate the same request.
+ */
+export declare function verify(request: Request, verifiers: readonly Types.Verifier[], context?: Types.Context): Promise<Outcome>;
+/** Builds the rejection response for a failed request-stage outcome. @internal */
+export declare function toResponse(outcome: Exclude<Outcome, {
+    status: 'valid';
+}>): Response;
+/** Creates a results lookup from verified values. @internal */
+export declare function results(values?: ReadonlyMap<Types.Verifier, unknown>): Types.Results;
+/** Returns the stage a verifier runs at. @internal */
+export declare function stageOf(verifier: Types.Verifier): Types.Stage;
+//# sourceMappingURL=Server.d.ts.map

package/dist/identity/Server.js

@@ -0,0 +1,145 @@
+const members = Symbol('mppx.identity.members');
+/**
+ * Accepts the first of several identity protocols that verifies.
+ *
+ * Every member runs. The result is `valid` if any member verifies, `invalid` if none verifies and
+ * any member was presented but failed, and `missing` otherwise, with every
+ * member's challenge headers. All members must run at the same stage.
+ *
+ * @example
+ * ```ts
+ * mppx.charge({ amount: '1', identity: [Identity.anyOf(tap, webBotAuth)] })
+ * ```
+ */
+export function anyOf(...verifiers) {
+    const stage = stageOf(verifiers[0]);
+    if (verifiers.some((verifier) => stageOf(verifier) !== stage))
+        throw new TypeError('Identity anyOf verifiers must run at the same stage.');
+    const verifier = {
+        [members]: verifiers,
+        stage,
+        async verify(request, context) {
+            // Every member runs, so each presented proof's replay nonce is consumed even when an
+            // earlier member already verified; the first valid member wins.
+            const all = [];
+            for (const member of verifiers)
+                all.push(await run(member, request, context));
+            const index = all.findIndex((outcome) => outcome.status === 'valid');
+            const matched = all[index];
+            if (matched?.status === 'valid')
+                return { status: 'valid', value: { index, value: matched.value } };
+            const outcomes = all;
+            const headers = mergeHeaders(outcomes);
+            const invalid = outcomes.find((outcome) => outcome.status === 'invalid');
+            if (invalid)
+                return { status: 'invalid', code: invalid.code, headers, reason: invalid.reason };
+            // Keep the first member's custom status so wrapping a verifier does not change its HTTP behavior.
+            const code = outcomes.find((outcome) => outcome.code !== undefined)?.code;
+            return {
+                status: 'missing',
+                ...(code !== undefined && { code }),
+                headers,
+                reason: 'None of the accepted identity proofs was presented.',
+            };
+        },
+    };
+    return verifier;
+}
+/**
+ * Runs every verifier at one stage and combines their outcomes.
+ *
+ * Every verifier must be valid. Any `invalid` outcome rejects with 401 unless
+ * it sets its own code; otherwise any `missing` outcome rejects with 403. The
+ * headers of every rejected outcome are merged. Each verifier runs at most once
+ * per request and context, so replay-protected nonces are consumed once even
+ * when several handlers evaluate the same request.
+ */
+export async function verify(request, verifiers, context = {}) {
+    const values = new Map();
+    const rejected = [];
+    for (const verifier of verifiers) {
+        const outcome = await run(verifier, request, context);
+        if (outcome.status !== 'valid') {
+            rejected.push(outcome);
+            continue;
+        }
+        // Record the matched member at every anyOf level, so results.get(leaf) works when nested.
+        let current = verifier;
+        let value = outcome.value;
+        for (;;) {
+            values.set(current, value);
+            const nested = current[members];
+            if (!nested)
+                break;
+            const matched = value;
+            current = nested[matched.index];
+            value = matched.value;
+        }
+    }
+    if (rejected.length === 0)
+        return { status: 'valid', values };
+    const headers = mergeHeaders(rejected);
+    const invalid = rejected.find((outcome) => outcome.status === 'invalid');
+    if (invalid)
+        return { status: 'invalid', code: invalid.code ?? 401, headers, reason: invalid.reason };
+    const missing = rejected[0];
+    return {
+        status: 'missing',
+        code: missing.code ?? 403,
+        headers,
+        reason: missing.reason ?? 'Identity verification is required.',
+    };
+}
+/** Builds the rejection response for a failed request-stage outcome. @internal */
+export function toResponse(outcome) {
+    const headers = new Headers(outcome.headers);
+    headers.set('Cache-Control', 'no-store');
+    return new Response(outcome.reason, { headers, status: outcome.code });
+}
+/** Creates a results lookup from verified values. @internal */
+export function results(values = new Map()) {
+    return Object.freeze({
+        get(verifier) {
+            return values.get(verifier);
+        },
+    });
+}
+/** Returns the stage a verifier runs at. @internal */
+export function stageOf(verifier) {
+    const stage = verifier.stage ?? 'request';
+    // An unknown stage would leave the verifier unchecked, so it is rejected (fail closed).
+    if (stage !== 'request' && stage !== 'payment')
+        throw new TypeError(`Unknown identity verifier stage "${String(stage)}".`);
+    return stage;
+}
+const cache = new WeakMap();
+function run(verifier, request, context) {
+    let byVerifier = cache.get(request);
+    if (!byVerifier)
+        cache.set(request, (byVerifier = new Map()));
+    let byContext = byVerifier.get(verifier);
+    if (!byContext)
+        byVerifier.set(verifier, (byContext = new Map()));
+    // Decisions can depend on the credential, so each credential object gets its own entry.
+    const key = context.challenge?.id ?? '';
+    let byCredential = byContext.get(key);
+    if (!byCredential)
+        byContext.set(key, (byCredential = new Map()));
+    let outcome = byCredential.get(context.credential);
+    if (!outcome) {
+        outcome = Promise.resolve(verifier.verify(request, context));
+        byCredential.set(context.credential, outcome);
+    }
+    return outcome;
+}
+function mergeHeaders(outcomes) {
+    const merged = new Headers();
+    for (const outcome of outcomes) {
+        if (outcome.status === 'valid' || !outcome.headers)
+            continue;
+        for (const [name, value] of new Headers(outcome.headers))
+            merged.append(name, value);
+    }
+    return merged;
+}
+//# sourceMappingURL=Server.js.map

package/dist/identity/Types.d.ts

@@ -0,0 +1,90 @@
+import type * as Challenge from '../Challenge.js';
+import type * as Credential from '../Credential.js';
+import type { MaybePromise } from '../internal/types.js';
+/**
+ * When a verifier runs on the server.
+ *
+ * `request` verifiers run before any payment challenge is issued and reject
+ * the request with their own status code. `payment` verifiers run when a
+ * challenge is issued (to add their own challenge headers to the 402) and
+ * again on the paid retry, before the credential is settled.
+ */
+export type Stage = 'request' | 'payment';
+/**
+ * Payment state passed to verifiers and provers.
+ *
+ * Request-stage verifiers receive an empty context. Payment-stage verifiers
+ * receive the challenge being issued, or the challenge and credential being
+ * answered on the paid retry.
+ */
+export type Context = {
+    /** The MPP challenge being issued or answered. */
+    challenge?: Challenge.Challenge | undefined;
+    /** The payment credential submitted with the request. */
+    credential?: Credential.Credential | undefined;
+};
+/**
+ * The outcome of one identity verifier.
+ *
+ * `missing` means the identity proof was not presented; its `headers` (for
+ * example a protocol challenge) are returned to the client. `invalid` means a
+ * proof was presented but must be rejected. `valid` carries the verified value.
+ */
+export type Verification<value = unknown> = {
+    status: 'missing';
+    /** HTTP status for a request-stage rejection. @default 403 */
+    code?: number | undefined;
+    /** Headers returned to the client, such as a protocol challenge. */
+    headers?: HeadersInit | undefined;
+    /** Human-readable reason. */
+    reason?: string | undefined;
+} | {
+    status: 'invalid';
+    /** HTTP status for a request-stage rejection. @default 401 */
+    code?: number | undefined;
+    /** Headers returned to the client, such as a protocol error object. */
+    headers?: HeadersInit | undefined;
+    /** Human-readable reason. */
+    reason: string;
+} | {
+    status: 'valid';
+    value: value;
+};
+/** Verifies one identity protocol on the server. */
+export type Verifier<value = unknown> = {
+    /** When the verifier runs. @default 'request' */
+    stage?: Stage | undefined;
+    /** Returns the protocol's verification outcome for the request. */
+    verify: (request: Request, context: Context) => MaybePromise<Verification<value>>;
+};
+/** Verified identity values, looked up by the verifier that produced them. */
+export type Results = {
+    /** Returns the verified value for a verifier, or `undefined` if it did not run or match. */
+    get<value>(verifier: Verifier<value>): value | undefined;
+};
+/**
+ * Values shared by every prover contributing to one HTTP attempt.
+ *
+ * Every retry gets a new context, so single-use nonces are never replayed.
+ */
+export type ProveContext = Context & {
+    /** Unix timestamp, in seconds, at which the attempt was created. */
+    readonly created: number;
+    /** Base64url-encoded random value identifying the attempt. */
+    readonly nonce: string;
+};
+/** Adds one identity protocol to outbound requests on the client. */
+export type Prover = {
+    /** Origins the prover may run for, such as `['https://shop.example']`, or `'*'` for any origin. */
+    scope: readonly string[] | '*';
+    /** Returns a new request carrying the protocol's identity material. */
+    prove: (request: Request, context: ProveContext) => MaybePromise<Request>;
+    /**
+     * Inspects a rejected or 402 response and prepares a proof for the next attempt.
+     *
+     * Return `true` to resend a rejected (non-402) request once. On a 402 the
+     * context carries the selected challenge and the payment retry always follows.
+     */
+    retry?: ((response: Response, context: Context) => MaybePromise<boolean | undefined>) | undefined;
+};
+//# sourceMappingURL=Types.d.ts.map

package/dist/identity/Types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Types.js.map

package/dist/{attestation → identity}/index.d.ts

@@ -1,6 +1,6 @@
 export * as Client from './Client.js';
 export * as Server from './Server.js';
+export { anyOf } from './Server.js';
 export * as Store from '../Store.js';
-export * from './Constants.js';
-export * from './Types.js';
+export type * from './Types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/{attestation → identity}/index.js

@@ -1,6 +1,5 @@
 export * as Client from './Client.js';
 export * as Server from './Server.js';
+export { anyOf } from './Server.js';
 export * as Store from '../Store.js';
-export * from './Constants.js';
-export * from './Types.js';
 //# sourceMappingURL=index.js.map

package/dist/identity/internal/SigningContext.d.ts

@@ -0,0 +1,6 @@
+/** Creates the attempt values shared by every prover on one HTTP attempt. */
+export declare function create(): {
+    readonly created: number;
+    readonly nonce: string;
+};
+//# sourceMappingURL=SigningContext.d.ts.map

package/dist/identity/internal/SigningContext.js

@@ -0,0 +1,11 @@
+import { Base64 } from 'ox';
+/** Creates the attempt values shared by every prover on one HTTP attempt. */
+export function create() {
+    const bytes = new Uint8Array(64);
+    crypto.getRandomValues(bytes);
+    return {
+        created: Math.floor(Date.now() / 1_000),
+        nonce: Base64.fromBytes(bytes, { pad: false, url: true }),
+    };
+}
+//# sourceMappingURL=SigningContext.js.map

package/dist/integrations/x402/Evm.d.ts

@@ -21,6 +21,7 @@ export declare function createHandler(parameters: {
     } | {
         status: 200;
         challenge?: import("../../Challenge.js").Challenge | undefined;
+        identity?: import("../../identity/Types.js").Results | undefined;
         withReceipt: import("../../server/Transport.js").WithReceipt<import("../../server/Transport.js").Http>;
     };
     skipHandlerResponse: Response | undefined;

package/dist/internal/version.d.ts

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

package/dist/mcp/client/McpClient.d.ts

@@ -69,6 +69,11 @@ export declare namespace wrap {
         paymentPreferences?: AcceptPayment.Config<FlattenMethods<methods>> | undefined;
         /** Array of methods to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
         methods: methods;
+        /**
+         * Realms allowed to request zero-amount Tempo proofs. An MCP server has no origin that could
+         * own a realm, so these proofs are refused unless their realm is listed here.
+         */
+        trustedTempoProofRealms?: readonly string[] | undefined;
     };
     type McpClient<client extends Pick<Client, 'callTool'> = Pick<Client, 'callTool'>, methods extends Methods = DefaultMethods> = Omit<client, 'callTool'> & {
         /** Call a tool with automatic payment handling. Preserves the MCP SDK signature. */

package/dist/mcp/client/McpClient.js

@@ -1,4 +1,5 @@
 import * as Challenge from '../../Challenge.js';
+import * as ProofRealm from '../../client/internal/ProofRealm.js';
 import * as Credential from '../../Credential.js';
 import * as Expires from '../../Expires.js';
 import * as AcceptPayment from '../../internal/AcceptPayment.js';
@@ -111,6 +112,7 @@ function createPaymentAwareCallTool(callTool, config) {
         }
         if (selected.challenge.expires)
             Expires.assert(selected.challenge.expires, selected.challenge.id);
+        ProofRealm.assertWithoutOrigin(selected.challenge, config.trustedTempoProofRealms);
         if (call.onPaymentRequired) {
             const approved = await call.onPaymentRequired(selected.challenge);
             if (!approved)

package/dist/proxy/Proxy.js

@@ -91,22 +91,23 @@ export function create(config) {
                 // so same-path paid routes can coexist without sharing credentials.
                 Route.matchPath(service.routes, upstreamPath, 
                 // skip free routes (e.g. `'GET /foo/bar': true`)
-                (endpoint) => endpoint !== true && matchesPaymentBinding(endpoint, fallbackBinding))
+                (endpoint) => Service.getHandler(endpoint) !== undefined &&
+                    matchesPaymentBinding(endpoint, fallbackBinding))
             : null;
         const matched = exactMatch ?? fallbackMatch;
         if (!matched)
             return new Response('Not Found', { status: 404 });
         const endpoint = matched.value;
         const ctx = { request, service, upstreamPath };
-        if (endpoint === true)
+        const handler = Service.getHandler(endpoint);
+        if (!handler)
             return proxyUpstream({
                 request,
                 service,
-                ctx,
+                ctx: { ...ctx, ...Service.getOptions(endpoint) },
                 proxy,
                 onUpstreamError: service.onUpstreamError ?? config.onUpstreamError,
             });
-        const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay;
         const scope = getConfiguredScope(handler) ??
             deriveRouteScope({
                 basePath: config.basePath,
@@ -276,6 +277,10 @@ function buildDiscoveryRoutes(services) {
             method: hasMethod ? tokens[0] : 'GET',
             path: `/${service.id}${path}`,
             payment: endpoint ? Service.paymentOf(endpoint) : null,
+            ...(typeof endpoint === 'object' && endpoint?.requestBody
+                ? { requestBody: endpoint.requestBody }
+                : {}),
+            ...(typeof endpoint === 'object' && endpoint?.summary ? { summary: endpoint.summary } : {}),
         };
     }));
 }
@@ -328,7 +333,7 @@ function getPaymentBinding(request) {
     return null;
 }
 function matchesPaymentBinding(endpoint, binding) {
-    if (endpoint === true)
+    if (!Service.getHandler(endpoint))
         return false;
     if (!binding)
         return true;

package/dist/proxy/Service.d.ts

@@ -30,13 +30,45 @@ export type Docs = {
  * An endpoint definition.
  *
  * - `IntentHandler` — payment required, calls the handler to issue a 402 challenge or verify payment.
- * - `{ pay, options }` — payment required with per-endpoint config overrides.
+ * - `EndpointConfig` — `{ pay, options, summary, requestBody }` (paid) or `{ free: true, options, summary, requestBody }` (free).
  * - `true` — free passthrough, no payment required, rewriteRequest is applied.
  */
-export type Endpoint = IntentHandler | {
+export type Endpoint = IntentHandler | EndpointConfig | true;
+/**
+ * An endpoint definition with per-endpoint config overrides and discovery metadata.
+ *
+ * @example
+ * ```ts
+ * routes: {
+ *   'POST /v1/search': {
+ *     pay: mppx.charge({ amount: '0.01' }),
+ *     summary: 'Search the web',
+ *     requestBody: {
+ *       content: { 'application/json': { schema: { type: 'object' } } },
+ *     },
+ *   },
+ *   'GET /v1/status': { free: true, summary: 'Service status' },
+ * }
+ * ```
+ */
+export type EndpointConfig = EndpointMetadata & ({
+    /** Payment handler. */
     pay: IntentHandler;
-    options: EndpointOptions;
-} | true;
+    free?: undefined;
+} | {
+    /** Free passthrough route, declared explicitly so a missing handler never means free. */
+    free: true;
+    pay?: undefined;
+});
+/** Per-endpoint config and discovery metadata shared by paid and free endpoint objects. */
+export type EndpointMetadata = {
+    /** Per-endpoint config overrides passed to request hooks via `ctx`. */
+    options?: EndpointOptions | undefined;
+    /** OpenAPI request body object emitted in `/openapi.json`. */
+    requestBody?: Record<string, unknown> | undefined;
+    /** Short summary emitted in `/openapi.json`. */
+    summary?: string | undefined;
+};
 /** Map of `"METHOD /pattern"` keys to endpoint definitions. */
 export type EndpointMap<routes extends string = string> = Partial<Record<routes, Endpoint>> & Record<string & {}, Endpoint>;
 /** Per-endpoint configuration overrides (e.g. `{ apiKey: 'sk-...' }`). */
@@ -149,6 +181,12 @@ export declare function toLlmsTxt(services: Service[], options?: {
 }): string;
 /** Extracts per-endpoint options from an endpoint definition. */
 export declare function getOptions(endpoint: Endpoint): EndpointOptions | undefined;
+/**
+ * Returns the payment handler of an endpoint, or `undefined` for a route declared free (`true` or
+ * `{ free: true }`). Throws for anything else, such as `{ pay: undefined }`, so a missing handler
+ * fails closed instead of proxying for free with the service's credentials.
+ */
+export declare function getHandler(endpoint: Endpoint): IntentHandler | 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

@@ -86,16 +86,32 @@ export function toLlmsTxt(services, options) {
 }
 /** Extracts per-endpoint options from an endpoint definition. */
 export function getOptions(endpoint) {
-    if (typeof endpoint === 'object' && endpoint !== null && 'options' in endpoint)
+    if (typeof endpoint === 'object' && endpoint !== null)
         return endpoint.options;
     return undefined;
 }
+/**
+ * Returns the payment handler of an endpoint, or `undefined` for a route declared free (`true` or
+ * `{ free: true }`). Throws for anything else, such as `{ pay: undefined }`, so a missing handler
+ * fails closed instead of proxying for free with the service's credentials.
+ */
+export function getHandler(endpoint) {
+    if (typeof endpoint === 'function')
+        return endpoint;
+    if (endpoint === true)
+        return undefined;
+    if (typeof endpoint === 'object' && endpoint !== null) {
+        if (typeof endpoint.pay === 'function')
+            return endpoint.pay;
+        if (endpoint.free === true && endpoint.pay === undefined)
+            return undefined;
+    }
+    throw new Error('Invalid proxy endpoint: expected a payment handler, `true` or `{ free: true }`.');
+}
 /** 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))
+    const handler = getHandler(endpoint);
+    if (!handler || !('_internal' in handler))
         return null;
     const metadata = handler._internal;
     if (!metadata)