@402flow/sdk 0.1.0-alpha.13 → 0.1.0-alpha.15

package/dist/index.js

@@ -1,7 +1,19 @@
+/**
+ * Core public client surface for @402flow/sdk.
+ *
+ * The SDK exposes two primary integration styles:
+ * 1. fetchPaid() for the fastest end-to-end paid request path
+ * 2. preparePaidRequest() plus executePreparedRequest() when the caller wants
+ *    an explicit check/revise/execute loop
+ */
 import { createHash } from 'node:crypto';
 import { detectChallengeFromResponse, } from './challenge-detection.js';
-import { sdkPaymentDecisionRequestSchema, sdkPaymentDecisionResponseSchema, sdkReceiptResponseSchema, } from './contracts.js';
+import { monetaryAmountToMinorUnits, paidRequestChallengeSchema, paidRequestHttpRequestSchema, sdkPaymentDecisionRequestSchema, sdkPaymentDecisionResponseSchema, sdkReceiptResponseSchema, } from './contracts.js';
 import { sdkClientVersion, sdkClientVersionHeaderName, } from './version.js';
+/**
+ * Thrown for all non-success paid outcomes. The original typed failure payload is
+ * preserved on details so callers can branch on kind without reparsing responses.
+ */
 export class FetchPaidError extends Error {
     details;
     kind;
@@ -33,6 +45,7 @@ export class FetchPaidError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/** Type guard for callers that catch unknown errors around fetchPaid flows. */
 export function isFetchPaidError(error) {
     return error instanceof FetchPaidError;
 }
@@ -128,7 +141,30 @@ function tryParseJson(value) {
         return undefined;
     }
 }
-function getReplayableRequestBody(body) {
+function describeRequestBodyType(body) {
+    if (body === undefined || body === null) {
+        return 'empty';
+    }
+    if (typeof body === 'string') {
+        return 'string';
+    }
+    if (body instanceof URLSearchParams) {
+        return 'URLSearchParams';
+    }
+    if (typeof body === 'object' && 'constructor' in body) {
+        const constructorName = body.constructor?.name;
+        if (typeof constructorName === 'string' && constructorName.length > 0) {
+            return constructorName;
+        }
+    }
+    return typeof body;
+}
+/** Returns true when a request body can be replayed exactly across paid flows. */
+export function isReplayableRequestBody(body) {
+    return typeof body === 'string' || body instanceof URLSearchParams;
+}
+/** Serialize a paid-flow request body into the exact replayable wire representation. */
+export function toReplayableRequestBody(body) {
     if (body === undefined || body === null) {
         return undefined;
     }
@@ -138,7 +174,30 @@ function getReplayableRequestBody(body) {
     if (body instanceof URLSearchParams) {
         return body.toString();
     }
-    throw new Error('Paid requests currently support replayable string and URLSearchParams bodies when routed through the control plane.');
+    throw new Error(`Paid requests require replayable string or URLSearchParams bodies. Received ${describeRequestBodyType(body)}. Convert JSON payloads with createJsonRequestBody(...) or form payloads with createFormUrlEncodedBody(...).`);
+}
+/** Helper for callers that want an explicit JSON-string body for paid flows. */
+export function createJsonRequestBody(payload) {
+    return JSON.stringify(payload);
+}
+/** Helper for callers that want a replayable form body for paid flows. */
+export function createFormUrlEncodedBody(values) {
+    const params = new URLSearchParams();
+    for (const [key, rawValue] of Object.entries(values)) {
+        if (Array.isArray(rawValue)) {
+            for (const entry of rawValue) {
+                params.append(key, String(entry));
+            }
+            continue;
+        }
+        params.append(key, String(rawValue));
+    }
+    return params;
+}
+// Preparation and paid execution may need to replay the exact request body, so
+// only body types that can be losslessly serialized are accepted here.
+function getReplayableRequestBody(body) {
+    return toReplayableRequestBody(body);
 }
 function hashRequestBody(body) {
     if (!body) {
@@ -163,6 +222,604 @@ function parseRuntimeTokenResponse(payload) {
         expiresAt,
     };
 }
+function createPreparedHttpRequest(input, init) {
+    const requestBody = getReplayableRequestBody(init.body);
+    return paidRequestHttpRequestSchema.parse({
+        url: input,
+        method: (init.method ?? 'GET').toUpperCase(),
+        headers: normalizeHeaders(init.headers),
+        body: requestBody,
+        bodyHash: hashRequestBody(requestBody),
+    });
+}
+function createPreparationAttribution(source, authority, note) {
+    return {
+        source,
+        authority,
+        ...(note ? { note } : {}),
+    };
+}
+function readExternalMetadata(options) {
+    return options.externalMetadata;
+}
+function readSchemaType(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const firstString = value.find((entry) => typeof entry === 'string' && entry.length > 0);
+        if (firstString) {
+            return firstString;
+        }
+    }
+    return undefined;
+}
+function readMerchantFieldsFromObjectSchema(objectSchema) {
+    const properties = isRecord(objectSchema.properties)
+        ? objectSchema.properties
+        : undefined;
+    const required = Array.isArray(objectSchema.required)
+        ? new Set(objectSchema.required.filter((entry) => typeof entry === 'string' && entry.length > 0))
+        : new Set();
+    const fields = new Map();
+    for (const [name, schema] of Object.entries(properties ?? {})) {
+        const propertySchema = isRecord(schema) ? schema : {};
+        fields.set(name.toLowerCase(), {
+            name,
+            ...(readSchemaType(propertySchema.type) ? { type: readSchemaType(propertySchema.type) } : {}),
+            ...(readStringValue(propertySchema.description)
+                ? { description: readStringValue(propertySchema.description) }
+                : {}),
+            ...(required.has(name) ? { required: true } : {}),
+        });
+    }
+    for (const fieldName of required) {
+        if (!fields.has(fieldName.toLowerCase())) {
+            fields.set(fieldName.toLowerCase(), {
+                name: fieldName,
+                required: true,
+            });
+        }
+    }
+    return Array.from(fields.values());
+}
+function inferFieldTypeFromValue(value) {
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (value === null) {
+        return undefined;
+    }
+    switch (typeof value) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return Number.isInteger(value) ? 'integer' : 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'object':
+            return 'object';
+        default:
+            return undefined;
+    }
+}
+function inferFieldsFromQueryParamExample(queryParams) {
+    return Object.entries(queryParams).map(([name, value]) => ({
+        name,
+        ...(inferFieldTypeFromValue(value) ? { type: inferFieldTypeFromValue(value) } : {}),
+        required: true,
+    }));
+}
+async function resolveJsonSchemaRef(schema, fetchImpl) {
+    const ref = readStringValue(schema.$ref);
+    if (!ref) {
+        return schema;
+    }
+    try {
+        const url = new URL(ref);
+        if (!['http:', 'https:'].includes(url.protocol)) {
+            return undefined;
+        }
+        const response = await fetchImpl(url.toString());
+        if (!response.ok) {
+            return undefined;
+        }
+        const parsed = await response.json();
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readMerchantPreparationMetadataFromInputSchema(inputSchema, requestBodyExample, queryParamExample, fetchImpl) {
+    const bodyType = readStringValue(inputSchema.bodyType)
+        ?? (isRecord(inputSchema.properties)
+            && isRecord(inputSchema.properties.bodyType)
+            ? readStringValue(inputSchema.properties.bodyType.const)
+            : undefined);
+    const bodySchema = isRecord(inputSchema.body)
+        ? inputSchema.body
+        : isRecord(inputSchema.properties)
+            && isRecord(inputSchema.properties.body)
+            ? inputSchema.properties.body
+            : undefined;
+    const queryParamSchema = isRecord(inputSchema.queryParams)
+        ? inputSchema.queryParams
+        : isRecord(inputSchema.properties)
+            && isRecord(inputSchema.properties.queryParams)
+            ? inputSchema.properties.queryParams
+            : undefined;
+    const requestBodyFields = bodySchema
+        ? readMerchantFieldsFromObjectSchema(bodySchema)
+        : undefined;
+    const resolvedQueryParamSchema = queryParamSchema
+        ? await resolveJsonSchemaRef(queryParamSchema, fetchImpl)
+        : undefined;
+    const requestQueryParams = resolvedQueryParamSchema
+        ? readMerchantFieldsFromObjectSchema(resolvedQueryParamSchema)
+        : queryParamExample
+            ? inferFieldsFromQueryParamExample(queryParamExample)
+            : undefined;
+    const hasBodyFields = requestBodyFields && requestBodyFields.length > 0;
+    const hasQueryFields = requestQueryParams && requestQueryParams.length > 0;
+    if (!bodyType && !requestBodyExample && !hasBodyFields && !hasQueryFields) {
+        return undefined;
+    }
+    return {
+        ...(bodyType ? { requestBodyType: bodyType } : {}),
+        ...(requestBodyExample ? { requestBodyExample } : {}),
+        ...(hasBodyFields
+            ? { requestBodyFields }
+            : {}),
+        ...(hasQueryFields
+            ? { requestQueryParams }
+            : {}),
+        notes: ['Request hints derived from merchant challenge metadata.'],
+    };
+}
+async function readMerchantPreparationMetadata(challenge, fetchImpl) {
+    if (!challenge) {
+        return undefined;
+    }
+    const paymentRequiredPayload = tryParsePaymentRequiredHeader(challenge.headers['payment-required']);
+    const payload = unwrapChallengePayload(paymentRequiredPayload ?? challenge.body);
+    if (!isRecord(payload)) {
+        return undefined;
+    }
+    const accepts = Array.isArray(payload.accepts) ? payload.accepts : [];
+    for (const accept of accepts) {
+        if (!isRecord(accept) || !isRecord(accept.extra) || !isRecord(accept.extra.outputSchema)) {
+            continue;
+        }
+        const outputSchema = accept.extra.outputSchema;
+        const metadata = isRecord(outputSchema.input)
+            ? await readMerchantPreparationMetadataFromInputSchema(outputSchema.input, undefined, undefined, fetchImpl)
+            : undefined;
+        if (metadata) {
+            return metadata;
+        }
+    }
+    const bazaar = isRecord(payload.extensions) && isRecord(payload.extensions.bazaar)
+        ? payload.extensions.bazaar
+        : undefined;
+    const bazaarInfoInput = isRecord(bazaar?.info) && isRecord(bazaar.info.input)
+        ? bazaar.info.input
+        : undefined;
+    const bazaarRequestBodyExample = isRecord(bazaarInfoInput?.body)
+        ? JSON.stringify(bazaarInfoInput.body)
+        : undefined;
+    const bazaarQueryParamExample = isRecord(bazaarInfoInput?.queryParams)
+        ? bazaarInfoInput.queryParams
+        : undefined;
+    const bazaarInputSchema = isRecord(bazaar?.schema)
+        && isRecord(bazaar.schema.properties)
+        && isRecord(bazaar.schema.properties.input)
+        ? bazaar.schema.properties.input
+        : undefined;
+    if (bazaarInputSchema) {
+        return readMerchantPreparationMetadataFromInputSchema(bazaarInputSchema, bazaarRequestBodyExample, bazaarQueryParamExample, fetchImpl);
+    }
+    return undefined;
+}
+function pickPreparedHintValue(options, merchantChallengeMetadata, key) {
+    if (merchantChallengeMetadata?.[key]) {
+        return {
+            value: merchantChallengeMetadata[key],
+            attribution: createPreparationAttribution('merchant_challenge', 'authoritative'),
+        };
+    }
+    const externalMetadata = readExternalMetadata(options);
+    if (externalMetadata?.[key]) {
+        return {
+            value: externalMetadata[key],
+            attribution: createPreparationAttribution('external_metadata', 'advisory'),
+        };
+    }
+    return undefined;
+}
+function mergePreparedHintFields(options, merchantChallengeMetadata, key) {
+    const fields = new Map();
+    for (const field of merchantChallengeMetadata?.[key] ?? []) {
+        fields.set(field.name.toLowerCase(), {
+            ...field,
+            attribution: createPreparationAttribution('merchant_challenge', 'authoritative'),
+        });
+    }
+    for (const field of readExternalMetadata(options)?.[key] ?? []) {
+        const normalizedName = field.name.toLowerCase();
+        if (fields.has(normalizedName)) {
+            continue;
+        }
+        fields.set(normalizedName, {
+            ...field,
+            attribution: createPreparationAttribution('external_metadata', 'advisory'),
+        });
+    }
+    return Array.from(fields.values());
+}
+async function buildPreparedRequestHints(options, fetchImpl, challenge) {
+    // Hint assembly merges optional caller metadata with merchant-authoritative
+    // challenge metadata while preserving attribution for every returned field.
+    const merchantChallengeMetadata = await readMerchantPreparationMetadata(challenge, fetchImpl);
+    const externalMetadata = readExternalMetadata(options);
+    return {
+        ...(pickPreparedHintValue(options, merchantChallengeMetadata, 'description')
+            ? {
+                description: pickPreparedHintValue(options, merchantChallengeMetadata, 'description'),
+            }
+            : {}),
+        ...(pickPreparedHintValue(options, merchantChallengeMetadata, 'requestBodyType')
+            ? {
+                requestBodyType: pickPreparedHintValue(options, merchantChallengeMetadata, 'requestBodyType'),
+            }
+            : {}),
+        ...(pickPreparedHintValue(options, merchantChallengeMetadata, 'requestBodyExample')
+            ? {
+                requestBodyExample: pickPreparedHintValue(options, merchantChallengeMetadata, 'requestBodyExample'),
+            }
+            : {}),
+        requestBodyFields: mergePreparedHintFields(options, merchantChallengeMetadata, 'requestBodyFields'),
+        requestQueryParams: mergePreparedHintFields(options, merchantChallengeMetadata, 'requestQueryParams'),
+        requestPathParams: mergePreparedHintFields(options, merchantChallengeMetadata, 'requestPathParams'),
+        notes: [
+            ...(merchantChallengeMetadata?.notes ?? []).map((value) => ({
+                value,
+                attribution: createPreparationAttribution('merchant_challenge', 'authoritative'),
+            })),
+            ...(externalMetadata?.notes ?? []).map((value) => ({
+                value,
+                attribution: createPreparationAttribution('external_metadata', 'advisory'),
+            })),
+        ],
+    };
+}
+function isJsonContentType(value) {
+    return value?.toLowerCase().includes('application/json') ?? false;
+}
+function matchesExpectedFieldType(value, expectedType) {
+    switch (expectedType?.toLowerCase()) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'integer':
+        case 'int':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'object':
+            return isRecord(value);
+        case 'array':
+            return Array.isArray(value);
+        default:
+            return true;
+    }
+}
+function buildPreparedValidationIssues(request, hints) {
+    // Validation is intentionally narrow: it checks only request-shape issues the
+    // SDK can defend from available hints, not task-specific semantic correctness.
+    const issues = [];
+    const contentType = request.headers?.['content-type'];
+    const requestBodyType = hints.requestBodyType?.value.toLowerCase();
+    const requiredBodyFields = hints.requestBodyFields.filter((field) => field.required);
+    if (requestBodyType === 'json'
+        && request.body !== undefined
+        && !isJsonContentType(contentType)) {
+        issues.push({
+            location: 'headers',
+            field: 'content-type',
+            code: 'unsupported_content_type',
+            message: 'Request body is expected to be JSON but content-type is not application/json.',
+            source: hints.requestBodyType?.attribution.source ?? 'external_metadata',
+            blocking: true,
+            severity: 'error',
+            suggestedFix: 'Send the request with content-type: application/json.',
+        });
+    }
+    if (hints.requestBodyFields.length > 0) {
+        if (request.body === undefined) {
+            for (const field of requiredBodyFields) {
+                issues.push({
+                    location: 'body',
+                    field: field.name,
+                    code: 'missing_required_field',
+                    message: `Required request body field "${field.name}" is missing.`,
+                    source: field.attribution.source,
+                    blocking: true,
+                    severity: 'error',
+                    suggestedFix: `Add the required body field "${field.name}" before execution.`,
+                });
+            }
+        }
+        else {
+            const parsedBody = tryParseJson(request.body);
+            if (parsedBody === undefined) {
+                issues.push({
+                    location: 'body',
+                    field: 'body',
+                    code: 'malformed_candidate_value',
+                    message: 'Request body must be valid JSON to satisfy the declared body fields.',
+                    source: hints.requestBodyType?.attribution.source
+                        ?? hints.requestBodyFields[0]?.attribution.source
+                        ?? 'external_metadata',
+                    blocking: true,
+                    severity: 'error',
+                    suggestedFix: 'Send a valid JSON object body that satisfies the declared fields.',
+                });
+            }
+            else if (!isRecord(parsedBody)) {
+                issues.push({
+                    location: 'body',
+                    field: 'body',
+                    code: 'request_shape_conflicts_with_hint',
+                    message: 'Request body must be a JSON object to satisfy the declared body fields.',
+                    source: hints.requestBodyFields[0]?.attribution.source
+                        ?? hints.requestBodyType?.attribution.source
+                        ?? 'external_metadata',
+                    blocking: true,
+                    severity: 'error',
+                    suggestedFix: 'Send a JSON object body whose keys match the declared fields.',
+                });
+            }
+            else {
+                for (const field of requiredBodyFields) {
+                    if (!(field.name in parsedBody)) {
+                        issues.push({
+                            location: 'body',
+                            field: field.name,
+                            code: 'missing_required_field',
+                            message: `Required request body field "${field.name}" is missing.`,
+                            source: field.attribution.source,
+                            blocking: true,
+                            severity: 'error',
+                            suggestedFix: `Add the required body field "${field.name}" before execution.`,
+                        });
+                    }
+                }
+                for (const field of hints.requestBodyFields) {
+                    if (!(field.name in parsedBody)) {
+                        continue;
+                    }
+                    if (!matchesExpectedFieldType(parsedBody[field.name], field.type)) {
+                        issues.push({
+                            location: 'body',
+                            field: field.name,
+                            code: 'malformed_candidate_value',
+                            message: `Request body field "${field.name}" does not match the expected type${field.type ? ` "${field.type}"` : ''}.`,
+                            source: field.attribution.source,
+                            blocking: true,
+                            severity: 'error',
+                            suggestedFix: `Set "${field.name}" to a value compatible with the declared type${field.type ? ` "${field.type}"` : ''}.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const url = new URL(request.url);
+    for (const field of hints.requestQueryParams.filter((entry) => entry.required)) {
+        if (!url.searchParams.has(field.name)) {
+            issues.push({
+                location: 'query',
+                field: field.name,
+                code: 'missing_required_query_param',
+                message: `Required query parameter "${field.name}" is missing.`,
+                source: field.attribution.source,
+                blocking: true,
+                severity: 'error',
+                suggestedFix: `Add the required query parameter "${field.name}" before execution.`,
+            });
+        }
+    }
+    for (const field of hints.requestPathParams.filter((entry) => entry.required)) {
+        if (url.pathname.includes(`{${field.name}}`)
+            || url.pathname.includes(`:${field.name}`)) {
+            issues.push({
+                location: 'path',
+                field: field.name,
+                code: 'missing_required_path_param',
+                message: `Required path parameter "${field.name}" is still unresolved in the request URL.`,
+                source: field.attribution.source,
+                blocking: true,
+                severity: 'error',
+                suggestedFix: `Replace the unresolved path placeholder for "${field.name}" before execution.`,
+            });
+        }
+    }
+    const seen = new Set();
+    return issues.filter((issue) => {
+        const key = [
+            issue.location,
+            issue.field.toLowerCase(),
+            issue.code,
+            issue.source,
+        ].join(':');
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function derivePreparedNextAction(kind, validationIssues) {
+    if (kind === 'passthrough') {
+        return 'treat_as_passthrough';
+    }
+    if (validationIssues.some((issue) => issue.blocking)) {
+        return 'revise_request';
+    }
+    return 'execute';
+}
+function readStringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readIntegerValue(value) {
+    if (typeof value === 'number' && Number.isInteger(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    return undefined;
+}
+function readPrecisionFromAmount(amount) {
+    if (!amount) {
+        return undefined;
+    }
+    const [, fractionalPart = ''] = amount.split('.');
+    return fractionalPart.length;
+}
+function formatMinorUnitsAsAmount(amountMinor, precision) {
+    if (precision === 0) {
+        return amountMinor;
+    }
+    const normalizedMinor = amountMinor.replace(/^0+(?=\d)/, '') || '0';
+    const paddedMinor = normalizedMinor.padStart(precision + 1, '0');
+    const wholePart = paddedMinor.slice(0, -precision) || '0';
+    const fractionalPart = paddedMinor.slice(-precision);
+    return `${wholePart}.${fractionalPart}`;
+}
+function tryParsePaymentRequiredHeader(value) {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(Buffer.from(value, 'base64').toString('utf8'));
+    }
+    catch {
+        // Fall through.
+    }
+    return tryParseJson(value);
+}
+function unwrapChallengePayload(payload) {
+    if (!isRecord(payload)) {
+        return undefined;
+    }
+    if (isRecord(payload.challenge)) {
+        return payload.challenge;
+    }
+    return payload;
+}
+function parseAuthenticateHeaderParameters(header) {
+    if (!header) {
+        return new Map();
+    }
+    const matches = header.matchAll(/([a-zA-Z0-9_-]+)="([^"]+)"/g);
+    const parameters = new Map();
+    for (const match of matches) {
+        const [, key, value] = match;
+        if (key && value) {
+            parameters.set(key.toLowerCase(), value);
+        }
+    }
+    return parameters;
+}
+function buildPreparedPaymentRequirement(challenge) {
+    // Payment terms are normalized into one portable structure so callers do not
+    // need protocol-specific parsing logic in their agent or application layer.
+    const provenance = createPreparationAttribution('merchant_challenge', 'authoritative');
+    const paymentRequiredPayload = tryParsePaymentRequiredHeader(challenge.headers['payment-required']);
+    const payload = unwrapChallengePayload(paymentRequiredPayload ?? challenge.body);
+    if (isRecord(payload)) {
+        const resource = isRecord(payload.resource) ? payload.resource : undefined;
+        const accepts = Array.isArray(payload.accepts) ? payload.accepts : undefined;
+        const primaryAccept = accepts?.find((candidate) => isRecord(candidate));
+        if (primaryAccept && isRecord(primaryAccept)) {
+            const amountMinor = readStringValue(primaryAccept.amount)
+                ?? readStringValue(primaryAccept.maxAmountRequired);
+            const precision = readIntegerValue(primaryAccept.precision)
+                ?? (isRecord(primaryAccept.extra)
+                    ? readIntegerValue(primaryAccept.extra.precision)
+                        ?? readIntegerValue(primaryAccept.extra.decimals)
+                    : undefined);
+            const amount = amountMinor && precision !== undefined
+                ? formatMinorUnitsAsAmount(amountMinor, precision)
+                : undefined;
+            return {
+                protocol: challenge.protocol,
+                ...(readStringValue(resource?.description)
+                    ? { description: readStringValue(resource?.description) }
+                    : {}),
+                ...(readStringValue(primaryAccept.asset)
+                    ? { asset: readStringValue(primaryAccept.asset) }
+                    : {}),
+                ...(readStringValue(primaryAccept.network)
+                    ? { network: readStringValue(primaryAccept.network) }
+                    : {}),
+                ...(readStringValue(primaryAccept.payTo)
+                    ? { payee: readStringValue(primaryAccept.payTo) }
+                    : {}),
+                ...(readStringValue(primaryAccept.amount)
+                    ? { amountType: 'exact' }
+                    : readStringValue(primaryAccept.maxAmountRequired)
+                        ? { amountType: 'max' }
+                        : {}),
+                ...(amount ? { amount } : {}),
+                ...(amountMinor ? { amountMinor } : {}),
+                ...(precision !== undefined ? { precision } : {}),
+                provenance,
+            };
+        }
+    }
+    const explicitAmount = readStringValue(challenge.headers['x-payment-amount']);
+    const explicitPrecision = readIntegerValue(challenge.headers['x-payment-precision'])
+        ?? readPrecisionFromAmount(explicitAmount);
+    if (explicitAmount || challenge.headers['www-authenticate']) {
+        const authenticateParameters = parseAuthenticateHeaderParameters(challenge.headers['www-authenticate']);
+        const amount = explicitAmount ?? authenticateParameters.get('amount');
+        const precision = explicitPrecision ?? readPrecisionFromAmount(amount);
+        const asset = readStringValue(challenge.headers['x-payment-asset'])
+            ?? authenticateParameters.get('asset');
+        const payee = readStringValue(challenge.headers['x-payment-payee'])
+            ?? authenticateParameters.get('payee');
+        const network = readStringValue(challenge.headers['x-payment-network'])
+            ?? authenticateParameters.get('network');
+        const amountMinor = amount && precision !== undefined
+            ? monetaryAmountToMinorUnits(amount, precision)
+            : undefined;
+        return {
+            protocol: challenge.protocol,
+            ...(asset ? { asset } : {}),
+            ...(network ? { network } : {}),
+            ...(payee ? { payee } : {}),
+            ...(amount ? { amount } : {}),
+            ...(amountMinor ? { amountMinor } : {}),
+            ...(precision !== undefined ? { precision } : {}),
+            ...(amount ? { amountType: 'exact' } : {}),
+            provenance,
+        };
+    }
+    return {
+        protocol: challenge.protocol,
+        provenance,
+    };
+}
+/**
+ * Client bound to one organization/agent identity and one 402flow control plane.
+ *
+ * Most integrations either call fetchPaid() directly or use the explicit
+ * preparePaidRequest() -> executePreparedRequest() flow.
+ */
 export class AgentPayClient {
     controlPlaneBaseUrl;
     auth;
@@ -181,6 +838,82 @@ export class AgentPayClient {
         this.fetchImpl = options.fetch ?? fetch;
         this.headers = options.headers;
     }
+    /**
+     * Probe or reuse a merchant challenge and return a normalized preparation
+     * result the caller can inspect before paying.
+     */
+    async preparePaidRequest(input, init = {}, options = {}) {
+        const request = createPreparedHttpRequest(input, init);
+        if (options.challenge) {
+            const hints = await buildPreparedRequestHints(options, this.fetchImpl, options.challenge);
+            const validationIssues = buildPreparedValidationIssues(request, hints);
+            return {
+                kind: 'ready',
+                protocol: options.challenge.protocol,
+                request,
+                challenge: paidRequestChallengeSchema.parse(options.challenge),
+                ...(buildPreparedPaymentRequirement(options.challenge)
+                    ? {
+                        paymentRequirement: buildPreparedPaymentRequirement(options.challenge),
+                    }
+                    : {}),
+                hints,
+                validationIssues,
+                nextAction: derivePreparedNextAction('ready', validationIssues),
+            };
+        }
+        const initialResponse = await this.fetchImpl(input, init);
+        const challenge = await detectChallengeFromResponse(initialResponse);
+        const probe = {
+            responseStatus: initialResponse.status,
+            confirmedAt: new Date().toISOString(),
+        };
+        const hints = await buildPreparedRequestHints(options, this.fetchImpl, challenge);
+        const validationIssues = buildPreparedValidationIssues(request, hints);
+        if (!challenge) {
+            return {
+                kind: 'passthrough',
+                protocol: 'none',
+                request,
+                hints,
+                probe,
+                validationIssues,
+                nextAction: derivePreparedNextAction('passthrough', validationIssues),
+            };
+        }
+        return {
+            kind: 'ready',
+            protocol: challenge.protocol,
+            request,
+            challenge: paidRequestChallengeSchema.parse(challenge),
+            ...(buildPreparedPaymentRequirement(challenge)
+                ? { paymentRequirement: buildPreparedPaymentRequirement(challenge) }
+                : {}),
+            hints,
+            probe,
+            validationIssues,
+            nextAction: derivePreparedNextAction('ready', validationIssues),
+        };
+    }
+    /**
+     * Execute the exact request that was previously prepared, without re-probing
+     * the merchant first.
+     */
+    async executePreparedRequest(prepared, request = {}) {
+        return this.fetchPaid(prepared.request.url, {
+            method: prepared.request.method,
+            ...(prepared.request.headers ? { headers: prepared.request.headers } : {}),
+            ...(prepared.request.body !== undefined ? { body: prepared.request.body } : {}),
+        }, {
+            ...request,
+            challenge: prepared.challenge,
+        });
+    }
+    /**
+     * Fast-path helper that probes when needed, asks the control plane for a paid
+     * execution decision, and returns either passthrough or success. All non-success
+     * paid outcomes are thrown as FetchPaidError.
+     */
     async fetchPaid(input, init = {}, request) {
         let challenge = request.challenge;
         if (!challenge) {
@@ -198,6 +931,7 @@ export class AgentPayClient {
         const decision = await this.requestPaymentDecision(decisionRequest, challenge.protocol);
         return this.mapDecisionToPaidResponse(decision, challenge.protocol);
     }
+    /** Lookup a durable receipt by id through the control plane. */
     async lookupReceipt(receiptId) {
         const response = await this.controlPlaneFetch(`/api/sdk/receipts/${receiptId}`, {
             method: 'GET',
@@ -209,20 +943,13 @@ export class AgentPayClient {
         return sdkReceiptResponseSchema.parse(await response.json());
     }
     createDecisionRequest(input, init, request, challenge) {
-        const requestBody = getReplayableRequestBody(init.body);
         const { challenge: _challenge, idempotencyKey, ...requestContext } = request;
         return sdkPaymentDecisionRequestSchema.parse({
             context: {
                 ...this.identity,
                 ...requestContext,
             },
-            request: {
-                url: input,
-                method: (init.method ?? 'GET').toUpperCase(),
-                headers: normalizeHeaders(init.headers),
-                body: requestBody,
-                bodyHash: hashRequestBody(requestBody),
-            },
+            request: createPreparedHttpRequest(input, init),
             challenge: {
                 protocol: challenge.protocol,
                 headers: challenge.headers,
@@ -232,6 +959,9 @@ export class AgentPayClient {
         });
     }
     async requestPaymentDecision(decisionRequest, protocol) {
+        // The control plane is the single source of truth for payment policy and
+        // receipt persistence. Any response that does not match the SDK contract is
+        // downgraded to request_failed.
         const decisionResponse = await this.controlPlaneFetch('/api/sdk/payment-decisions', {
             method: 'POST',
             headers: {
@@ -277,6 +1007,8 @@ export class AgentPayClient {
         });
     }
     mapDecisionToPaidResponse(decision, protocol) {
+        // Only allow returns normally. Every other durable or non-durable paid outcome
+        // is surfaced as a typed FetchPaidError so caller control flow stays explicit.
         switch (decision.outcome) {
             case 'allow': {
                 const response = {
@@ -413,6 +1145,8 @@ export class AgentPayClient {
         return runtimeToken.token;
     }
     async controlPlaneFetch(path, init, authorizationHeader) {
+        // Every control-plane call carries the SDK version header so incompatible
+        // client/server contract mismatches can fail fast.
         return this.fetchImpl(`${this.controlPlaneBaseUrl}${path}`, {
             ...init,
             headers: {
@@ -424,9 +1158,11 @@ export class AgentPayClient {
         });
     }
 }
+/** Small factory wrapper for callers that prefer a function export. */
 export function createAgentPayClient(options) {
     return new AgentPayClient(options);
 }
+export * from './agent-harness.js';
 export * from './contracts.js';
 export { detectChallengeFromResponse } from './challenge-detection.js';
 export { sdkClientVersion, sdkClientVersionHeaderName } from './version.js';