@agent-score/commerce 1.0.0

package/dist/challenge/index.d.mts

@@ -0,0 +1,523 @@
+import { AgentMemoryHint } from '../core.mjs';
+export { buildAgentMemoryHint } from '../core.mjs';
+import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.mjs';
+
+interface TempoMethodEntry {
+    method: 'tempo/charge';
+    network: string;
+    chain_id: number;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+}
+interface X402MethodEntry {
+    method: 'x402/exact';
+    network: string;
+    chain_id?: number;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+}
+interface StripeMethodEntry {
+    method: 'stripe/charge';
+    rails: ('card' | 'link' | 'shared_payment_token')[];
+    profile_id: string | null;
+}
+type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | StripeMethodEntry;
+interface BuildAcceptedMethodsInput {
+    tempo?: {
+        recipient: string;
+        network?: string;
+        chainId?: number;
+        token?: string;
+        symbol?: string;
+        decimals?: number;
+    };
+    x402_base?: {
+        recipient: string;
+        network?: string;
+        chainId?: number;
+        token?: string;
+        symbol?: string;
+        decimals?: number;
+    };
+    x402_solana?: {
+        recipient: string;
+        network?: string;
+        token?: string;
+        symbol?: string;
+        decimals?: number;
+    };
+    stripe?: {
+        profileId?: string | null;
+        rails?: ('card' | 'link' | 'shared_payment_token')[];
+    };
+}
+/**
+ * Build the `accepted_methods[]` array for an enriched 402 body. Each rail entry is
+ * conditionally included based on whether the vendor passed it. Per-rail shapes follow
+ * the conventions established in martin-estate's reference 402.
+ */
+declare function buildAcceptedMethods(input: BuildAcceptedMethodsInput): AcceptedMethodEntry[];
+
+type IdentityMode = 'wallet' | 'operator_token';
+interface SignerMatchResultLike {
+    kind: 'pass' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | string;
+    expectedSigner?: string;
+    actualSigner?: string;
+    linkedWallets?: string[];
+}
+interface IdentityMetadataInput {
+    /** Current request's identity mode. */
+    mode: IdentityMode;
+    /** Claimed wallet address (when mode === 'wallet'). */
+    wallet?: string;
+    /** Result of a prior verifyWalletSignerMatch call. */
+    signerMatchResult?: SignerMatchResultLike;
+    /** Same-operator linked wallets (from assess response). */
+    linkedWallets?: string[];
+    /** Optional explicit constraint description (overrides the auto-generated one). */
+    signerConstraint?: string;
+}
+interface IdentityMetadataBlock {
+    identity_mode: IdentityMode;
+    required_signer?: string;
+    linked_wallets?: string[];
+    signer_constraint?: string;
+}
+/**
+ * Build the identity-metadata block for an enriched 402 body. Echoes the agent's
+ * identity context (wallet vs. operator-token mode) so the agent can self-correct
+ * before signing — specifically, on wallet-auth rails the agent MUST sign with one
+ * of the wallets in linked_wallets (all resolve to the same operator).
+ */
+declare function buildIdentityMetadata(input: IdentityMetadataInput): IdentityMetadataBlock;
+
+interface HowToPayRailEntry {
+    setup?: string[];
+    prerequisite?: string;
+    command: string;
+    alternative_command?: string;
+    what_it_does: string;
+}
+interface HowToPayStripeEntry {
+    prerequisite: string;
+    instructions: string;
+    setup_link_cli?: string[];
+    command_link_cli?: string[];
+    what_it_does_link_cli?: string;
+    note?: string;
+}
+interface HowToPayBlock {
+    tempo?: HowToPayRailEntry;
+    x402_base?: HowToPayRailEntry;
+    x402_solana?: HowToPayRailEntry;
+    stripe?: HowToPayStripeEntry;
+}
+interface BuildHowToPayInput {
+    /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
+    url: string;
+    /** JSON string of the body the agent should retry with — typically the original request body. */
+    retryBodyJson: string;
+    /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
+    totalUsd: string | number;
+    /** Per-rail config — each is optional. Pass only the rails you support. */
+    rails: {
+        tempo?: {
+            recipient: string;
+            networkName?: string;
+            chainId?: number;
+            recommend?: 'tempo' | 'agentscore-pay' | 'both';
+        };
+        x402_base?: {
+            recipient: string;
+            network?: string;
+        };
+        x402_solana?: {
+            recipient: string;
+            network?: string;
+        };
+        stripe?: {
+            profileId?: string | null;
+            productName?: string;
+        };
+    };
+    /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
+    opTokenPlaceholder?: string;
+    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
+    maxSpend?: string | number;
+}
+/**
+ * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
+ * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
+ * they support; the helper produces the right command for each.
+ *
+ * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
+ */
+declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
+
+/** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
+ *  that have been smoke-verified by the merchant against the protocol shape they emit.
+ *  Strings are display labels, not install commands — agents already get install commands
+ *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
+type CompatibleClients = Record<string, string[]>;
+interface BuildAgentInstructionsInput {
+    /** Per-rail commands. Build with `buildHowToPay`. */
+    howToPay: HowToPayBlock;
+    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
+    recommendedTools?: string[];
+    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
+    walletCompatibility?: string;
+    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
+    timeoutSeconds?: number;
+    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
+    warnings?: string[];
+    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
+    recommended?: string;
+    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
+     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
+     *  merchant has not tested). When omitted, the field is not emitted. */
+    compatibleClients?: CompatibleClients;
+    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
+    extra?: Record<string, unknown>;
+}
+interface AgentInstructions {
+    how_to_pay: HowToPayBlock;
+    recommended_tools: string[];
+    wallet_compatibility: string;
+    timeout_seconds: number;
+    warnings: string[];
+    recommended?: string;
+    compatible_clients?: CompatibleClients;
+    [key: string]: unknown;
+}
+/**
+ * Build the agent_instructions object for the 402 body. Combines how_to_pay with
+ * recommended tools, warnings, wallet-compatibility note, and timeout.
+ *
+ * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
+ * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base`/`x402_solana`
+ * are set. Stripe-only merchants get neither rail-specific warning. Vendors override
+ * `warnings`/`recommendedTools` for full control.
+ */
+declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
+
+/**
+ * Helpers for emitting the cross-merchant `agent_memory` hint on merchant 402 responses.
+ *
+ * The gate (`@agent-score/commerce/identity/*`) emits `agent_memory` on identity-related
+ * responses (sessions, credentials, missing_identity bootstraps). Merchants can ALSO
+ * include the hint in their own 402 challenge bodies on first-encounter requests so
+ * agents persist the cross-merchant pattern even when entering the ecosystem through a
+ * merchant-side endpoint rather than a direct AgentScore API call.
+ *
+ * Usage pattern:
+ *   - Merchant tracks per-operator (or per-IP / per-fingerprint) "have I seen this agent
+ *     before?" in their own DB
+ *   - On first encounter (no prior request from this operator/wallet/IP), include the hint
+ *     so the agent saves the pattern
+ *   - On subsequent encounters, skip — the agent already has it (or never will)
+ *
+ * The hint contents come from `buildAgentMemoryHint` (re-exported here for convenience).
+ * Keep it stateless: AgentScore's pattern doesn't depend on the merchant's identity, so
+ * every merchant emits the same shape.
+ */
+
+interface FirstEncounterAgentMemoryInput {
+    /**
+     * Whether this is a first encounter for this operator/wallet/IP at this merchant.
+     * Merchant-determined (DB lookup, cache flag, etc.). Pass `false` to suppress emission
+     * cleanly without wrapping the call in an `if`.
+     */
+    firstEncounter: boolean;
+}
+/**
+ * Returns the `agent_memory` hint when this is a first encounter, otherwise `undefined`.
+ * Use directly with the `agentMemory` field of `build402Body`:
+ *
+ * ```ts
+ * const body = build402Body({
+ *   acceptedMethods,
+ *   agentInstructions,
+ *   pricing,
+ *   agentMemory: firstEncounterAgentMemory({ firstEncounter: !this.hasSeenOperator(opToken) }),
+ * });
+ * ```
+ *
+ * Returning `undefined` means `build402Body` cleanly skips the field instead of emitting
+ * `agent_memory: null` (which would imply "I tried but failed" rather than "didn't apply").
+ */
+declare function firstEncounterAgentMemory(input: FirstEncounterAgentMemoryInput): AgentMemoryHint | undefined;
+
+/**
+ * Pricing block builder + canonical type.
+ *
+ * Composes the cents-denominated price components into the dollar-string shape that
+ * 402 challenge bodies advertise. Lifts the inline pattern from martin-estate's
+ * `purchase.ts` so every merchant — current and future commerce-platform plugins
+ * (Commerce7, WooCommerce, Shopify) — surfaces the same shape to agents.
+ *
+ * Shipping is included by default because most physical-goods merchants carry it; pass
+ * `shippingCents: 0` (or omit) for digital goods / services. Tax is optional for
+ * merchants outside taxable jurisdictions.
+ */
+interface PricingBlock {
+    /** Pre-tax, pre-shipping subtotal as a dollar-string (e.g. `"250.00"`). */
+    subtotal: string;
+    /** Tax amount as a dollar-string. Always present even if `"0.00"`. */
+    tax: string;
+    /** Shipping cost as a dollar-string. Always present even if `"0.00"`. */
+    shipping?: string;
+    /** Final total = subtotal + tax + shipping, dollar-string. */
+    total: string;
+    /** Tax rate as a decimal fraction (e.g. `0.0775` for 7.75%). Optional — omit for tax-free merchants. */
+    tax_rate?: number;
+    /** ISO-3166-2 state code or jurisdiction name used for tax calc. Optional. */
+    tax_state?: string;
+    /** ISO-4217 currency code. Default `"USD"`. */
+    currency?: string;
+}
+interface BuildPricingBlockInput {
+    /** Pre-tax, pre-shipping subtotal in the smallest currency unit (cents, satoshi, etc.). */
+    subtotalCents: number;
+    /** Tax amount in the smallest currency unit. Default `0`. */
+    taxCents?: number;
+    /** Shipping cost in the smallest currency unit. Default `0`. */
+    shippingCents?: number;
+    /** Override the computed total. By default `subtotalCents + taxCents + shippingCents`. */
+    totalCents?: number;
+    /** Tax rate as a decimal fraction (e.g. `0.0775`). */
+    taxRate?: number;
+    /** Tax jurisdiction (state code, country, etc.). */
+    taxState?: string;
+    /** ISO-4217 currency. Default `"USD"`. */
+    currency?: string;
+}
+/**
+ * Compose a `PricingBlock` from cents-denominated inputs. Handles the cents → dollar-string
+ * conversion (always 2 decimals) and computes the total when not explicitly provided.
+ *
+ * Example:
+ * ```ts
+ * const pricing = buildPricingBlock({
+ *   subtotalCents: 25000,
+ *   taxCents: 1875,
+ *   shippingCents: 999,
+ *   taxRate: 0.075,
+ *   taxState: 'CA',
+ * });
+ * // → { subtotal: '250.00', tax: '18.75', shipping: '9.99', total: '278.74', tax_rate: 0.075, tax_state: 'CA' }
+ * ```
+ *
+ * Pass `shippingCents: 0` for digital goods if you want the field present (it's then `"0.00"`);
+ * omit entirely if you don't want shipping in the response shape at all.
+ */
+declare function buildPricingBlock(input: BuildPricingBlockInput): PricingBlock;
+
+interface Build402BodyInput {
+    /** From buildAcceptedMethods — list of MPP method entries. */
+    acceptedMethods: AcceptedMethodEntry[];
+    /** From buildAgentInstructions — wraps how_to_pay + warnings + recommended_tools. */
+    agentInstructions?: AgentInstructions;
+    /** From buildIdentityMetadata — wallet-mode echoer. Spread into the body when present. */
+    identityMetadata?: IdentityMetadataBlock;
+    /** Cross-merchant agent_memory hint (from gate). */
+    agentMemory?: unknown;
+    /** Pricing breakdown. */
+    pricing?: PricingBlock;
+    /** Total amount in USD as a string (e.g., '250.00'). */
+    amountUsd?: string;
+    /** Currency code. Default 'USD'. */
+    currency?: string;
+    /** Order id for retry correlation. */
+    orderId?: string | null;
+    /** Product info — surfaced on the 402 so agents can confirm what they're buying. */
+    product?: {
+        id: string;
+        name: string;
+    };
+    /** The body the agent should retry with after payment (e.g., the original request body). */
+    retryBody?: unknown;
+    /** Recommended rail — agent's default if multiple are listed. */
+    recommended?: string;
+    /** x402-compliance fields (paired with the PAYMENT-REQUIRED header from `payment/wwwauthenticate`). */
+    x402?: {
+        accepts: unknown[];
+        version?: 1 | 2;
+    };
+    /** Vendor-specific extra fields merged at the top level. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Assemble the full enriched 402 response body. Combines accepted_methods, agent_instructions,
+ * identity metadata, pricing, x402 compliance fields, and any vendor-specific extras into a
+ * single object suitable for `JSON.stringify`. Vendors pass only what they have; the builder
+ * conditionally includes each section.
+ *
+ * Pair this with a Response that sets:
+ *   - 'content-type: application/json'
+ *   - 'www-authenticate: <wwwAuthenticateHeader([...])>' from `payment/wwwauthenticate`
+ *   - 'PAYMENT-REQUIRED: <paymentRequiredHeader({...})>' for x402 clients
+ */
+declare function build402Body(input: Build402BodyInput): Record<string, unknown>;
+
+/**
+ * Canonical order-receipt shape returned to agents on the 200 after a successful settlement.
+ *
+ * Merchants own their order schema, but converging on this shape across every AgentScore-gated
+ * merchant (Martin Estate today; Commerce7 / WooCommerce / Shopify plugins tomorrow) means
+ * agents can render and post-process orders consistently. Lift this type, fill the fields you
+ * care about, and ignore (or extend via `extras`) what you don't.
+ *
+ * All money fields are dollar-strings (e.g. `"250.00"`). Use `buildPricingBlock` from
+ * `@agent-score/commerce/challenge` to compose the pricing fields from cents.
+ */
+
+interface OrderReceipt {
+    /** Stable order id — UUID, slug, or platform-native (Commerce7 order id, etc.). */
+    id: string;
+    /** ISO-8601 timestamp of order creation. */
+    created_at: string;
+    /** Quantity purchased. */
+    quantity?: number;
+    /** Product info — the agent confirmed they were buying this in the 402, surface again on receipt. */
+    product?: {
+        id?: string;
+        name?: string;
+        slug?: string;
+    };
+    /** Pricing block — same shape as the 402 advertised. Use `buildPricingBlock` to compose. */
+    pricing?: PricingBlock;
+    /** Buyer email if provided. */
+    email?: string;
+    /** Payment status — typically `"completed"`, `"pending"`, `"failed"`. */
+    payment_status?: string;
+    /** Fulfillment status — typically `"pending"`, `"shipped"`, `"delivered"`, `"cancelled"`. */
+    fulfillment_status?: string;
+    /** Carrier tracking number when fulfillment_status >= shipped. */
+    tracking_number?: string | null;
+    /** Shipping address — physical-goods merchants. Omit for digital goods. */
+    shipping?: {
+        name?: string;
+        address_1?: string;
+        address_2?: string | null;
+        city?: string;
+        state?: string;
+        zip?: string;
+        country?: string;
+    };
+    /** Optional gift note / order memo. */
+    gift_note?: string | null;
+    /** Vendor-specific extras merged at the top level (loyalty points, warranty, etc.). */
+    extras?: Record<string, unknown>;
+    /** Next-steps block guiding the agent on what to do post-purchase. */
+    next_steps?: {
+        user_message?: string;
+        order_status_url?: string;
+        fulfillment_eta?: string;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * `respond402` — single-call 402 emit for merchants who use both `mppx` (for tempo + stripe
+ * MPP rails) AND x402 (for Base + Solana).
+ *
+ * The seam is fiddly enough to get wrong by hand:
+ *   - mppx's `compose()(req)` returns a 402 Response with WWW-Authenticate directives
+ *     whose ids mppx's server-side validator REMEMBERS — they round-trip in client
+ *     credentials. Overwriting that header (e.g. with `buildPaymentHeaders` output)
+ *     breaks the round-trip.
+ *   - x402 needs the binary-friendly `PAYMENT-REQUIRED` header (base64-encoded JSON
+ *     of `{x402Version, accepts, resource}`) — mppx doesn't emit it.
+ *   - Merchants want a richer JSON body (pricing, identity metadata, agent_instructions,
+ *     agent_memory, retry_body, accepted_methods cross-reference) than the bare mppx body.
+ *
+ * `respond402` composes all three in one call:
+ *   - PRESERVES mppx's WWW-Authenticate verbatim
+ *   - ADDS PAYMENT-REQUIRED when x402 entries are present
+ *   - REPLACES the body with the rich body via `build402Body`
+ *
+ * Usage:
+ * ```ts
+ * const result = await m.compose(['tempo/charge', {...}], ['stripe/charge', {...}])(c.req.raw);
+ * if (result.status === 402) {
+ *   return commerce.respond402({
+ *     mppxChallenge: result.challenge,
+ *     x402: { version: 2, accepts: x402Accepts, resource: { url: c.req.url, mimeType: 'application/json' } },
+ *     body: { acceptedMethods, agentInstructions, identityMetadata, pricing, agentMemory, retryBody, ... },
+ *   });
+ * }
+ * ```
+ */
+
+interface Respond402Input {
+    /** The 402 Response returned by `mppx.compose()(req)`. Its WWW-Authenticate header
+     *  is preserved verbatim — mppx's server-side validator matches credentials to the
+     *  directive ids it generated, so overwriting breaks the round-trip. */
+    mppxChallenge: Response;
+    /** Inputs to `build402Body` — the rich JSON body sent to the agent. */
+    body: Build402BodyInput;
+    /** When set, layers on the x402 PAYMENT-REQUIRED header (base64-encoded JSON).
+     *  Omit for merchants that don't accept x402 (Base/Solana) — mppx-only setups. */
+    x402?: PaymentRequiredHeaderInput;
+}
+declare function respond402(input: Respond402Input): Response;
+
+/**
+ * Build a structured 4xx validation-error body that pairs cleanly with the
+ * existing 402 / 403 builders. Every commerce merchant returning helpful
+ * `bad_request` / `not_found` / `out_of_stock` / etc. errors converges on the
+ * same shape: `{ error: {code, message}, ...optional_hints, next_steps? }`.
+ *
+ * This builder doesn't choose the HTTP status — vendors wrap the returned
+ * body in their framework's response (`c.json(body, 400)` in Hono,
+ * `Response.json(body, {status: 400})` for the Web Fetch path, etc.). Status
+ * stays the merchant's call because the same shape works for 400/404/409/422.
+ */
+interface BuildValidationErrorInput {
+    /** Machine-readable error code (e.g. 'bad_request', 'not_found', 'out_of_stock'). */
+    code: string;
+    /** Human-readable message — surfaced directly to the user via the agent. */
+    message: string;
+    /** Optional schema description of required body fields, keyed by field name. Surfaced
+     *  so agents can self-correct without fetching docs. */
+    requiredFields?: Record<string, string>;
+    /** Optional concrete example body. Pairs with `requiredFields` for max self-serve. */
+    exampleBody?: unknown;
+    /** Optional next-step hint block (`{action, user_message?, ...vendor_extras}`). */
+    nextSteps?: Record<string, unknown>;
+    /** Vendor-specific top-level fields merged into the body (e.g. `available`,
+     *  `blocked_states`, `max_length`). */
+    extra?: Record<string, unknown>;
+}
+interface ValidationErrorBody {
+    error: {
+        code: string;
+        message: string;
+    };
+    required_fields?: Record<string, string>;
+    example_body?: unknown;
+    next_steps?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Compose a 4xx body that vendors return via their framework's response helper.
+ * Combine with the merchant's chosen HTTP status (400 for body shape errors,
+ * 404 for missing entities, 409 for stock conflicts, 403 for policy denials, etc.).
+ *
+ * Example:
+ * ```ts
+ * return c.json(buildValidationError({
+ *   code: 'bad_request',
+ *   message: 'product_id, email, and shipping are required',
+ *   requiredFields: { product_id: 'uuid', email: 'string', shipping: 'object' },
+ *   nextSteps: { action: 'retry_with_complete_body' },
+ * }), 400);
+ * ```
+ */
+declare function buildValidationError(input: BuildValidationErrorInput): ValidationErrorBody;
+
+export { type AcceptedMethodEntry, type AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildAgentInstructionsInput, type BuildHowToPayInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type CompatibleClients, type FirstEncounterAgentMemoryInput, type HowToPayBlock, type HowToPayRailEntry, type HowToPayStripeEntry, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildAgentInstructions, buildHowToPay, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };