mppx 0.9.3 → 0.10.1

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

@@ -1,10 +1,12 @@
-import type { EndpointSpec } from './helpers.js';
+import type { CheckResult, EndpointSpec } from './helpers.js';
 export declare function fetchDiscoveryDoc(baseUrl: string): Promise<{
     doc: unknown;
     raw: string;
 } | {
     error: string;
 }>;
+/** Checks that the server publishes nonempty text documentation at /llms.txt. */
+export declare function validateLlmsDoc(baseUrl: string): Promise<CheckResult>;
 export declare function extractEndpointsFromDiscovery(doc: Record<string, unknown>): EndpointSpec[];
 export declare function extractRequestBodyFromDiscovery(doc: Record<string, unknown>, endpoint: EndpointSpec): string | undefined;
 export declare function buildUrl(baseUrl: string, endpoint: EndpointSpec, query?: string[]): string;

package/dist/cli/validate/discovery.js

@@ -1,4 +1,4 @@
-import { fetchWithTimeout, HTTP_METHODS } from './helpers.js';
+import { check, fetchWithTimeout, HTTP_METHODS } from './helpers.js';
 export async function fetchDiscoveryDoc(baseUrl) {
     // Trailing slash makes URL treat baseUrl as a directory, so relative resolution appends rather than replaces the last segment.
     const url = new URL('openapi.json', baseUrl.replace(/\/?$/, '/')).href;
@@ -18,6 +18,33 @@ export async function fetchDiscoveryDoc(baseUrl) {
         return { error: error.message };
     }
 }
+/** Checks that the server publishes nonempty text documentation at /llms.txt. */
+export async function validateLlmsDoc(baseUrl) {
+    const url = new URL('/llms.txt', baseUrl).href;
+    const label = 'llms.txt found and nonempty';
+    try {
+        const response = await fetchWithTimeout(url, {});
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const body = (await response.text()).trim();
+        if (!body)
+            throw new Error('Empty document');
+        const contentType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+        if ((contentType && !contentType.startsWith('text/')) ||
+            contentType === 'text/html' ||
+            /^<(?:!doctype html|html|head|body)\b/i.test(body))
+            throw new Error('Expected text documentation, received non-text or HTML content');
+        return check(label, url);
+    }
+    catch (error) {
+        return {
+            label,
+            detail: `${url}: ${error.message}`,
+            severity: 'suggested',
+            hint: 'Serve nonempty text documentation at /llms.txt.',
+        };
+    }
+}
 // Extracts testable endpoints from an OpenAPI doc. Prefers endpoints with
 // explicit x-payment-info (the server declares them as paid). Falls back to
 // endpoints that list a 402 response (weaker signal, but still worth testing).

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

@@ -2,7 +2,7 @@ export type CheckResult = {
     label: string;
     detail?: string | undefined;
     hint?: string | undefined;
-    severity: 'pass' | 'fail' | 'warn' | 'skip';
+    severity: 'pass' | 'fail' | 'warn' | 'suggested' | 'skip';
 };
 export type EndpointSpec = {
     method: string;
@@ -33,10 +33,11 @@ export type Counts = {
     passed: number;
     failed: number;
     warnings: number;
+    suggested: number;
     skipped: number;
 };
 export declare function printResults(results: CheckResult[], counts: Counts): void;
-export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs?: number): Promise<Response>;
+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>;
 export declare function isValidAddress(addr: unknown): boolean;

package/dist/cli/validate/helpers.js

@@ -28,6 +28,7 @@ const SEVERITY_ICONS = {
     pass: pc.green('✓'),
     fail: pc.red('✗'),
     warn: pc.yellow('⚠'),
+    suggested: pc.cyan('◇'),
     skip: pc.dim('○'),
 };
 export function printCheck(result) {
@@ -50,6 +51,8 @@ export function printResults(results, counts) {
             counts.failed++;
         else if (result.severity === 'warn')
             counts.warnings++;
+        else if (result.severity === 'suggested')
+            counts.suggested++;
         else if (result.severity === 'skip')
             counts.skipped++;
     }

package/dist/cli/validate/index.js

@@ -53,7 +53,7 @@ const validate = Cli.create('validate', {
         // Streaming human-readable output
         const baseUrl = c.args.url.replace(/\/$/, '').replace(/\/openapi\.json$/i, '');
         console.log(`\n${pc.bold('mppx validate')} ${pc.dim(baseUrl)}\n`);
-        const counts = { passed: 0, failed: 0, warnings: 0, skipped: 0 };
+        const counts = { passed: 0, failed: 0, warnings: 0, suggested: 0, skipped: 0 };
         let sawMppEndpoint = false;
         let sawNonMppPaymentEndpoint = false;
         let sawMalformedChallenge = false;
@@ -165,6 +165,8 @@ function printSummary(counts, flags, endpointsLength) {
         parts.push(pc.red(`${counts.failed} failed`));
     if (counts.warnings > 0)
         parts.push(pc.yellow(`${counts.warnings} warning(s)`));
+    if (counts.suggested > 0)
+        parts.push(pc.cyan(`${counts.suggested} suggested`));
     if (counts.skipped > 0)
         parts.push(pc.yellow(`${counts.skipped} skipped`));
     console.log(`${pc.bold('Summary:')} ${parts.join(', ')}`);

package/dist/cli/validate/payment.js

@@ -11,8 +11,9 @@ import * as Constants from '../../Constants.js';
 import * as Receipt from '../../Receipt.js';
 import { tempo as tempoMethods } from '../../tempo/client/index.js';
 import { chainId as tempoChainIds } from '../../tempo/internal/defaults.js';
+import { isTempoSessionChallenge } from '../../tempo/session/client/Transports.js';
 import { resolveAccount, resolveAccountName } from '../account.js';
-import { loadConfig, preparePayment, resolvePlugin } from '../internal.js';
+import { assertSamePaymentRequest, flattenConfigMethods, loadConfig, preparePayment, resolvePlugin, } from '../internal.js';
 import { fetchTokenInfo, confirm, pc } from '../utils.js';
 import { buildUrl } from './discovery.js';
 import { check, fail, fetchWithTimeout, formatBytes, isValidIntegerAmount, parseHeaders, skip, warn, } from './helpers.js';
@@ -156,6 +157,8 @@ export async function validatePaymentFlow(baseUrl, endpoint, verbose, options) {
     const tempoTestnetChallenge = challenges.find((ch) => {
         if (ch.method !== Constants.Methods.tempo)
             return false;
+        if (flattenConfigMethods(loaded?.config)?.some((method) => method.name === ch.method && method.intent === ch.intent))
+            return false;
         const req = ch.request;
         const md = req.methodDetails;
         return typeof md?.chainId === 'number' && md.chainId !== tempoChainIds.mainnet;
@@ -174,7 +177,7 @@ export async function validatePaymentFlow(baseUrl, endpoint, verbose, options) {
                 const credentialContext = await preparePayment(tempoTestnetChallenge, loaded?.config.extensions);
                 const cred = await mppx.createCredential(fakeResp, credentialContext);
                 results.push(check('Payment: submitted', 'ephemeral testnet wallet'));
-                await sendAndValidateResponse(results, url, endpoint, cred, fetchHeaders, fetchBody, verbose, tempoModerato);
+                await sendAndValidateResponse(results, url, endpoint, cred, fetchHeaders, fetchBody, verbose, tempoModerato, Challenge.credentialHeader(tempoTestnetChallenge));
             }
             catch (error) {
                 results.push(fail('Payment: create credential', error.message));
@@ -256,31 +259,42 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
         : undefined;
     const decimals = methodDetails?.decimals ?? request.decimals ?? 6;
     const currency = request.currency;
-    // Resolve wallet
-    let walletAddress;
-    try {
-        walletAddress = await resolveWalletAddress();
-    }
-    catch { }
-    if (!walletAddress) {
-        results.push(skip(tag, 'no wallet configured. Run "mppx account create" to create one.'));
+    const { plugin, method: directMethod } = resolvePlugin(challenge, loaded?.config);
+    if (!plugin && !directMethod) {
+        results.push(skip(tag, methodSetupHint(challenge)));
         return;
     }
+    // Direct methods own their payer; the CLI wallet may be unrelated or absent.
+    let walletAddress;
+    if (!directMethod) {
+        try {
+            walletAddress = await resolveWalletAddress();
+        }
+        catch { }
+        if (!walletAddress) {
+            results.push(skip(tag, 'no wallet configured. Run "mppx account create" to create one.'));
+            return;
+        }
+    }
     // Pre-flight balance check and chain resolution
     let paymentChain;
-    if (challenge.method === Constants.Methods.tempo)
-        paymentChain = tempoMainnetChain;
+    if (challenge.method === Constants.Methods.tempo) {
+        const chainId = methodDetails?.chainId ??
+            (directMethod ? undefined : tempoMainnetChain.id);
+        if (chainId !== undefined)
+            paymentChain = chainId === tempoModerato.id ? tempoModerato : resolveEvmChain(chainId);
+    }
     else if (challenge.method === Constants.Methods.evm) {
         const chainId = methodDetails?.chainId;
         if (chainId)
             paymentChain = resolveEvmChain(chainId);
     }
     let tokenSymbol;
-    if (requiredAmount && currency && paymentChain) {
+    if (walletAddress && requiredAmount && currency && paymentChain) {
         try {
             let balance;
             if (challenge.method === Constants.Methods.tempo) {
-                const client = createClient({ chain: tempoMainnetChain, transport: http() });
+                const client = createClient({ chain: paymentChain, transport: http() });
                 const info = await fetchTokenInfo(client, currency, walletAddress);
                 balance = info.balance;
                 tokenSymbol = info.symbol;
@@ -309,8 +323,10 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
     const chainName = paymentChain?.name;
     const paymentDesc = `${amountDisplay}${tokenDisplay ? ` ${tokenDisplay}` : ''}${chainName ? ` on ${chainName}` : ''}`;
     if (!options.silent)
-        console.log(pc.dim(`    Attempting payment with wallet ${walletAddress}`));
-    if (paymentChain?.testnet) {
+        console.log(pc.dim(walletAddress
+            ? `    Attempting payment with wallet ${walletAddress}`
+            : '    Attempting payment with configured method'));
+    if (!directMethod && paymentChain?.testnet) {
         if (!options.silent)
             console.log(pc.dim(`    Auto-approved: ${paymentDesc} (testnet)`));
     }
@@ -329,14 +345,6 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
         if (!options.silent)
             console.log(pc.dim(`    Auto-approved: ${paymentDesc}`));
     }
-    // Resolve plugin and pay
-    const resolved = resolvePlugin(challenge, loaded?.config);
-    const plugin = resolved.plugin;
-    const directMethod = resolved.method;
-    if (!plugin && !directMethod) {
-        results.push(skip(tag, methodSetupHint(challenge)));
-        return;
-    }
     let methods;
     let createCredentialFn;
     let credentialContext;
@@ -359,14 +367,58 @@ async function attemptCryptoPayment(challenge, tag, ctx) {
     else {
         methods = [directMethod];
     }
+    if (directMethod && isTempoSessionChallenge(challenge)) {
+        let initial = true;
+        const mppx = Mppx.create({
+            methods: [directMethod],
+            polyfill: false,
+            async onChallenge(retry, { createCredential }) {
+                const context = await preparePayment(retry, loaded?.config.extensions);
+                assertSamePaymentRequest(challenge, retry);
+                const credential = await createCredential(context);
+                results.push(check(`${tag}: submitted`));
+                return credential;
+            },
+            fetch: async (input, init) => {
+                if (initial) {
+                    initial = false;
+                    return new Response(null, {
+                        status: 402,
+                        headers: {
+                            [Constants.Headers.wwwAuthenticate]: Challenge.serialize(challenge),
+                        },
+                    });
+                }
+                return fetchWithTimeout(input, init ?? {}, 30_000);
+            },
+        });
+        try {
+            const response = await mppx.fetch(url, {
+                method: endpoint.method,
+                headers: fetchHeaders,
+                body: fetchBody ?? null,
+            });
+            await validatePaymentResponse(results, response, verbose, paymentChain);
+        }
+        catch (error) {
+            results.push(fail(tag, error.message));
+        }
+        return;
+    }
     const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext);
     if (!credential)
         return;
     plugin?.prepareCredentialRequest?.({ challenge, credential, headers: fetchHeaders });
-    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, paymentChain);
+    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, paymentChain, Challenge.credentialHeader(challenge));
 }
 async function attemptStripePayment(challenge, tag, ctx) {
-    const { results, url, endpoint, fetchHeaders, fetchBody, verbose, loaded, options, isStripeTestKey, stripeKey, } = ctx;
+    const { results, url, endpoint, fetchHeaders, fetchBody, verbose, loaded, options, stripeKey } = ctx;
+    const { plugin, method: directMethod } = resolvePlugin(challenge, loaded?.config);
+    if (!plugin && !directMethod) {
+        results.push(skip(tag, 'no Stripe payment method available'));
+        return;
+    }
+    const isStripeTestKey = Boolean(plugin && !loaded?.config.plugins?.includes(plugin) && ctx.isStripeTestKey);
     const request = challenge.request;
     const requiredAmount = isValidIntegerAmount(request.amount)
         ? BigInt(request.amount)
@@ -395,42 +447,40 @@ async function attemptStripePayment(challenge, tag, ctx) {
         if (!options.silent)
             console.log(pc.dim(`    Auto-approved: ${paymentDesc}`));
     }
-    // Resolve plugin
-    const resolved = resolvePlugin(challenge, loaded?.config);
-    const plugin = resolved.plugin;
-    if (!plugin) {
-        results.push(skip(tag, 'no Stripe plugin available'));
-        return;
-    }
     let methods;
     let createCredentialFn;
     let credentialContext;
-    try {
-        const methodOpts = { paymentMethod: 'pm_card_visa' };
-        if (stripeKey)
-            methodOpts.secretKey = stripeKey;
-        const pluginResult = await plugin.setup({
-            challenge,
-            options: {},
-            methodOpts,
-        });
-        methods = pluginResult.methods;
-        createCredentialFn = pluginResult.createCredential;
-        credentialContext = pluginResult.credentialContext;
+    if (plugin) {
+        try {
+            const methodOpts = { paymentMethod: 'pm_card_visa' };
+            if (stripeKey)
+                methodOpts.secretKey = stripeKey;
+            const pluginResult = await plugin.setup({
+                challenge,
+                options: {},
+                methodOpts,
+            });
+            methods = pluginResult.methods;
+            createCredentialFn = pluginResult.createCredential;
+            credentialContext = pluginResult.credentialContext;
+        }
+        catch (error) {
+            results.push(skip(tag, error.message));
+            return;
+        }
     }
-    catch (error) {
-        results.push(skip(tag, error.message));
-        return;
+    else {
+        methods = [directMethod];
     }
     const credential = await createAndSend(challenge, methods, createCredentialFn, tag, results, loaded?.config.extensions, credentialContext);
     if (!credential)
         return;
-    plugin.prepareCredentialRequest?.({ challenge, credential, headers: fetchHeaders });
+    plugin?.prepareCredentialRequest?.({ challenge, credential, headers: fetchHeaders });
     // Stripe testmode: detect livemode rejection gracefully
     if (isStripeTestKey) {
         const resp = await fetchWithTimeout(url, {
             method: endpoint.method,
-            headers: { ...fetchHeaders, [Constants.Headers.authorization]: credential },
+            headers: { ...fetchHeaders, [Challenge.credentialHeader(challenge)]: credential },
             body: fetchBody ?? null,
         }, 30_000);
         if (resp.status >= 200 && resp.status < 300) {
@@ -441,7 +491,7 @@ async function attemptStripePayment(challenge, tag, ctx) {
         }
         return;
     }
-    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, undefined);
+    await sendAndValidateResponse(results, url, endpoint, credential, fetchHeaders, fetchBody, verbose, undefined, Challenge.credentialHeader(challenge));
 }
 async function createAndSend(challenge, methods, createCredentialFn, tag, results, extensions, initialCredentialContext) {
     const fakeResponse = new Response(null, {
@@ -472,12 +522,12 @@ async function createAndSend(challenge, methods, createCredentialFn, tag, result
         return undefined;
     }
 }
-async function sendAndValidateResponse(results, url, endpoint, credential, baseHeaders, fetchBody, verbose, explorerChain) {
+async function sendAndValidateResponse(results, url, endpoint, credential, baseHeaders, fetchBody, verbose, explorerChain, credentialHeader = Constants.Headers.authorization) {
     let paymentResponse;
     try {
         paymentResponse = await fetchWithTimeout(url, {
             method: endpoint.method,
-            headers: { ...baseHeaders, [Constants.Headers.authorization]: credential },
+            headers: { ...baseHeaders, [credentialHeader]: credential },
             body: fetchBody ?? null,
         }, 30_000);
     }
@@ -485,6 +535,9 @@ async function sendAndValidateResponse(results, url, endpoint, credential, baseH
         results.push(fail('Payment: send credential', error.message));
         return results;
     }
+    return validatePaymentResponse(results, paymentResponse, verbose, explorerChain);
+}
+async function validatePaymentResponse(results, paymentResponse, verbose, explorerChain) {
     if (paymentResponse.status === 402) {
         const body = await paymentResponse.text().catch(() => '');
         let detail = 'Payment rejected';

package/dist/client/Mppx.d.ts

@@ -24,6 +24,30 @@ export type PreparedPayment<methods extends readonly Method.AnyClient[] = readon
     /** Attaches a credential using the protocol that produced the selected challenge. */
     setCredential: (request: Transport.RequestOf<transport>, credential: string) => Transport.RequestOf<transport>;
 }>;
+/** An HTTP request prepared together with its response and optional payment. */
+export type PreparedRequest<methods extends readonly Method.AnyClient[], requirePayment extends boolean = false> = Readonly<{
+    /** Exact request that produced {@link response}. */
+    request: Request;
+    /** Response returned for {@link request}. */
+    response: Response;
+    /** Redirects followed before receiving {@link response}. */
+    redirects: readonly PreparedRequest.Redirect[];
+    /** Selected payment when the response requires payment. */
+    payment: requirePayment extends true ? PreparedRequest.Payment<methods> : PreparedRequest.Payment<methods> | undefined;
+}>;
+export declare namespace PreparedRequest {
+    /** A request-bound payment that can be inspected or paid. */
+    type Payment<methods extends readonly Method.AnyClient[]> = Readonly<PreparedPayment<methods, Transport.Transport<RequestInit, Response>> & {
+        /** Creates and sends a credential to the prepared request without following redirects. */
+        pay: (context?: AnyContextFor<methods> | undefined) => Promise<Response>;
+    }>;
+    /** A redirect followed while discovering a payment challenge. */
+    type Redirect = Readonly<{
+        from: string;
+        status: number;
+        to: string;
+    }>;
+}
 /**
  * Client-side payment handler.
  */
@@ -50,6 +74,18 @@ export type Mppx<methods extends Methods = Methods, transport extends Transport.
      * ```
      */
     preparePayment: (response: Transport.ResponseOf<transport>, options?: preparePayment.Options<FlattenMethods<methods>, transport> | undefined) => Promise<PreparedPayment<FlattenMethods<methods>, transport>>;
+    /**
+     * Follows safe pre-payment redirects and returns the response with its exact request. When the
+     * response requires payment, prepares its selected challenge without creating a credential.
+     * Credential-bearing requests never follow redirects. Requires a runtime that exposes manual
+     * redirect responses; browsers return opaque redirects and are not supported.
+     */
+    prepareRequest: transport extends Transport.Transport<RequestInit, Response> ? {
+        <const requirePayment extends boolean>(input: RequestInfo | URL, init: RequestInit | undefined, options: prepareRequest.Options<FlattenMethods<methods>, requirePayment> & {
+            requirePayment: requirePayment;
+        }): Promise<PreparedRequest<FlattenMethods<methods>, requirePayment>>;
+        (input: RequestInfo | URL, init?: RequestInit | undefined, options?: prepareRequest.Options<FlattenMethods<methods>> | undefined): Promise<PreparedRequest<FlattenMethods<methods>>>;
+    } : never;
     /** Creates a credential from a payment-required response by routing to the correct method. */
     createCredential: (response: Transport.ResponseOf<transport>, context?: AnyContextFor<FlattenMethods<methods>> | undefined, options?: createCredential.Options<FlattenMethods<methods>, transport> | undefined) => Promise<string>;
     /** Register a client event handler by canonical event name. */
@@ -89,6 +125,15 @@ export declare namespace preparePayment {
     /** Options for selecting a payment without creating its credential. */
     type Options<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], transport extends Transport.AnyTransport = Transport.Transport> = createCredential.Options<methods, transport>;
 }
+export declare namespace prepareRequest {
+    /** Options for preparing a request-bound payment. */
+    type Options<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], requirePayment extends boolean = false> = Omit<preparePayment.Options<methods, Transport.Transport<RequestInit, Response>>, 'request'> & {
+        /** Maximum redirects followed before rejecting the request. @default 20 */
+        maxRedirects?: number | undefined;
+        /** Throw when the response does not require payment. @default false */
+        requirePayment?: requirePayment | undefined;
+    };
+}
 export declare namespace createCredential {
     type Options<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[], transport extends Transport.AnyTransport = Transport.Transport> = {
         /** Request-local Accept-Payment override for manual rawFetch + createCredential flows. */