@agent-score/commerce 1.8.1 → 2.0.0

package/dist/challenge/index.d.ts

@@ -1,9 +1,10 @@
-import { A as AgentInstructions } from '../agent_instructions-DiMSGkdm.js';
-export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.js';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from '../rail_spec-XP0wKgJV.js';
+import { A as AgentInstructions, P as PricingBlock } from '../pricing-CQ9DIFaw.js';
+export { C as CompatibleClients, H as HowToPayBlock, a as HowToPayRailEntry, b as HowToPayRails, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as buildPricingBlock, g as compatibleClientsByRails } from '../pricing-CQ9DIFaw.js';
 import { AgentMemoryHint } from '../core.js';
 export { buildAgentMemoryHint } from '../core.js';
-import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.js';
-import '../signer-CFVQsWjL.js';
+import { p as paymentRequiredHeader } from '../wwwauthenticate-D_FMnPgU.js';
+import '../signer-3FAit11j.js';
 
 interface TempoMethodEntry {
     method: 'tempo/charge';
@@ -30,7 +31,6 @@ interface SolanaMppMethodEntry {
     symbol: string;
     decimals: number;
     pay_to: string;
-    fee_payer_key?: string;
 }
 interface StripeMethodEntry {
     method: 'stripe/charge';
@@ -38,42 +38,19 @@ interface StripeMethodEntry {
     profile_id: string | null;
 }
 type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | SolanaMppMethodEntry | 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;
-    };
-    solana_mpp?: {
-        recipient: string;
-        network?: string;
-        token?: string;
-        symbol?: string;
-        decimals?: number;
-        feePayerKey?: string;
-    };
-    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
- * a canonical 402 shape across rails.
+ * Build the `accepted_methods[]` array for an enriched 402 body. Each rail entry
+ * is conditionally included when the vendor passes a `*RailSpec` for that rail.
+ * Each spec's `recipient` is resolved via `resolveRecipient` so per-order
+ * factories (e.g. Stripe-multichain mints fresh deposits per PaymentIntent)
+ * flow through identically to static-treasury strings.
  */
-declare function buildAcceptedMethods(input: BuildAcceptedMethodsInput): AcceptedMethodEntry[];
+declare function buildAcceptedMethods({ tempo, x402_base, solana_mpp, stripe, }: {
+    tempo?: TempoRailSpec;
+    x402_base?: X402BaseRailSpec;
+    solana_mpp?: SolanaMppRailSpec;
+    stripe?: StripeRailSpec;
+}): Promise<AcceptedMethodEntry[]>;
 
 type IdentityMode = 'wallet' | 'operator_token';
 interface SignerMatchResultLike {
@@ -82,18 +59,6 @@ interface SignerMatchResultLike {
     actualSigner?: string;
     linkedWallets?: string[];
 }
-interface IdentityMetadataInput {
-    /** Current request's identity mode. */
-    mode: IdentityMode;
-    /** Claimed wallet address (when mode === 'wallet'). */
-    wallet?: string;
-    /** Projected signer_match verdict (from `getSignerVerdict(ctx).signer_match`). */
-    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;
@@ -106,7 +71,13 @@ interface IdentityMetadataBlock {
  * 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;
+declare function buildIdentityMetadata({ mode, wallet, signerMatchResult, linkedWallets, signerConstraint, }: {
+    mode: IdentityMode;
+    wallet?: string;
+    signerMatchResult?: SignerMatchResultLike;
+    linkedWallets?: string[];
+    signerConstraint?: string;
+}): IdentityMetadataBlock;
 
 /**
  * Helpers for emitting the cross-merchant `agent_memory` hint on merchant 402 responses.
@@ -129,14 +100,6 @@ declare function buildIdentityMetadata(input: IdentityMetadataInput): IdentityMe
  * 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`:
@@ -150,77 +113,27 @@ interface FirstEncounterAgentMemoryInput {
  * });
  * ```
  *
- * 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").
+ * `firstEncounter` is merchant-determined (DB lookup, cache flag, etc.); pass `false` to
+ * suppress emission cleanly without wrapping the call in an `if`. 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;
+declare function firstEncounterAgentMemory({ firstEncounter, }: {
+    firstEncounter: boolean;
+}): AgentMemoryHint | undefined;
 
 /**
- * Pricing block builder + canonical type.
- *
- * Composes the cents-denominated price components into the dollar-string shape that
- * 402 challenge bodies advertise. Standardizes the pricing block 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' }
- * ```
+ * 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.
  *
- * 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.
+ * 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 buildPricingBlock(input: BuildPricingBlockInput): PricingBlock;
-
-interface Build402BodyInput {
+declare function build402Body({ acceptedMethods, agentInstructions, identityMetadata, agentMemory, pricing, amountUsd, currency, orderId, product, retryBody, recommended, x402, extra, }: {
     /** From buildAcceptedMethods — list of MPP method entries. */
     acceptedMethods: AcceptedMethodEntry[];
     /** From buildAgentInstructions — wraps how_to_pay + warnings + recommended_tools. */
@@ -250,58 +163,58 @@ interface Build402BodyInput {
     x402?: {
         accepts: unknown[];
         version?: 1 | 2;
+        /** x402 spec `extensions` field. Per-endpoint declared extensions (e.g.
+         *  `bazaar` discovery schema from `createBazaarDiscovery({...})`). Surfaces
+         *  on the 402 body as `extensions` so spec-compliant crawlers can read it. */
+        extensions?: Record<string, unknown>;
     };
     /** 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>;
+}): Record<string, unknown>;
 
 /**
- * Canonical order-receipt shape returned to agents on the 200 after a successful settlement.
+ * Canonical receipt shape returned to agents on the 200 after settlement.
+ *
+ * Universal across vendor types: goods merchants populate the shipping +
+ * fulfillment slots, API merchants populate only the core fields (id,
+ * created_at, pricing, payment_status, next_steps). All goods-only fields are
+ * optional.
  *
- * Merchants own their order schema, but converging on this shape across AgentScore-gated
- * merchants 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.
+ * Merchants own their order schema, but converging on this shape across
+ * AgentScore-gated merchants means agents can render and post-process receipts
+ * consistently regardless of whether the seller ships product or returns API
+ * output. 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.
+ * 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.). */
+interface Receipt {
+    /** Stable receipt id; order UUID for goods, request id for API merchants. */
     id: string;
-    /** ISO-8601 timestamp of order creation. */
+    /** ISO-8601 timestamp of settlement. */
     created_at: string;
-    /** Quantity purchased. */
+    /** Goods: units purchased. API: usage count (calls, tokens, requests). */
     quantity?: number;
-    /** Product info — the agent confirmed they were buying this in the 402, surface again on receipt. */
+    /** Goods-shaped product info. Omit for API merchants (per-call billing has no product concept). */
     product?: {
         id?: string;
         name?: string;
         slug?: string;
     };
-    /** Pricing block — same shape as the 402 advertised. Use `buildPricingBlock` to compose. */
+    /** 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; typically `"completed"`, `"pending"`, `"failed"`. */
     payment_status?: string;
-    /** Fulfillment status — typically `"pending"`, `"shipped"`, `"delivered"`, `"cancelled"`. */
+    /** Goods-only. Typically `"pending"`, `"shipped"`, `"delivered"`, `"cancelled"`. */
     fulfillment_status?: string;
-    /** Carrier tracking number when fulfillment_status >= shipped. */
+    /** Goods-only. Carrier tracking number when fulfillment_status >= shipped. */
     tracking_number?: string | null;
-    /** Shipping address — physical-goods merchants. Omit for digital goods. */
+    /** Goods-only. Omit for digital goods, services, or API receipts. */
     shipping?: {
         name?: string;
         address_1?: string;
@@ -311,12 +224,13 @@ interface OrderReceipt {
         zip?: string;
         country?: string;
     };
-    /** Optional gift note / order memo. */
+    /** Goods-only. Omit for API receipts. */
     gift_note?: string | null;
-    /** Vendor-specific extras merged at the top level (loyalty points, warranty, etc.). */
+    /** Vendor-specific extras merged at the top level (loyalty points, warranty, per-call usage breakdown, etc.). */
     extras?: Record<string, unknown>;
-    /** Next-steps block guiding the agent on what to do post-purchase. */
+    /** Next-steps block guiding the agent post-settlement. Matches the shape returned by `buildSuccessNextSteps` so vendors can spread that helper's output verbatim. `order_status_url` works for both: goods → order detail route, API → usage / billing dashboard. `fulfillment_eta` is goods-only. */
     next_steps?: {
+        action?: string;
         user_message?: string;
         order_status_url?: string;
         fulfillment_eta?: string;
@@ -331,43 +245,46 @@ interface OrderReceipt {
  * 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.
+ *     credentials. Overwriting that header 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`
+ * `respond402` composes all three and returns a framework-neutral `Respond402Result`
+ * (body + headers + status) that the merchant wraps in their framework's response shape.
  *
  * 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, ... },
+ * const challenge = await m.compose(['tempo/charge', {...}], ['stripe/charge', {...}])(c.req.raw);
+ * if (challenge.status === 402) {
+ *   const result = respond402({
+ *     mppxChallengeHeaders: Object.fromEntries(challenge.headers),
+ *     body: build402Body({ ... }),
+ *     x402: { x402Version: 2, accepts: x402Accepts, resource: { url: c.req.url, mimeType: 'application/json' } },
  *   });
+ *   return new Response(JSON.stringify(result.body), { status: result.status, headers: result.headers });
  * }
  * ```
  */
 
-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;
+/** Framework-neutral 402 response shape — body + headers + status. */
+interface Respond402Result {
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+    status: 402;
+}
+declare function respond402({ mppxChallengeHeaders, body, x402, }: {
+    /** Headers from mppx's 402 Response (`Object.fromEntries(challenge.headers)`). The
+     *  `WWW-Authenticate` directives are preserved verbatim — mppx's server-side validator
+     *  matches credentials to the ids it generated. */
+    mppxChallengeHeaders: Record<string, string>;
+    /** The already-built 402 body — call `build402Body({...})` to construct it. */
+    body: Record<string, unknown>;
     /** 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;
+    x402?: Parameters<typeof paymentRequiredHeader>[0];
+}): Respond402Result;
 
 /**
  * Build a structured 4xx validation-error body that pairs cleanly with the
@@ -380,22 +297,6 @@ declare function respond402(input: Respond402Input): Response;
  * `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;
@@ -421,6 +322,13 @@ interface ValidationErrorBody {
  * }), 400);
  * ```
  */
-declare function buildValidationError(input: BuildValidationErrorInput): ValidationErrorBody;
+declare function buildValidationError({ code, message, requiredFields, exampleBody, nextSteps, extra, }: {
+    code: string;
+    message: string;
+    requiredFields?: Record<string, string>;
+    exampleBody?: unknown;
+    nextSteps?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+}): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type IdentityMetadataBlock, type IdentityMode, PricingBlock, type Receipt, type Respond402Result, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildValidationError, firstEncounterAgentMemory, respond402 };