@agent-score/commerce 1.1.0 → 1.3.0

package/dist/challenge/index.d.ts

@@ -1,3 +1,5 @@
+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 { AgentMemoryHint } from '../core.js';
 export { buildAgentMemoryHint } from '../core.js';
 import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.js';
@@ -20,12 +22,21 @@ interface X402MethodEntry {
     decimals: number;
     pay_to: string;
 }
+interface SolanaMppMethodEntry {
+    method: 'solana/charge';
+    network: string;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+    fee_payer_key?: string;
+}
 interface StripeMethodEntry {
     method: 'stripe/charge';
     rails: ('card' | 'link' | 'shared_payment_token')[];
     profile_id: string | null;
 }
-type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | StripeMethodEntry;
+type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | SolanaMppMethodEntry | StripeMethodEntry;
 interface BuildAcceptedMethodsInput {
     tempo?: {
         recipient: string;
@@ -43,12 +54,13 @@ interface BuildAcceptedMethodsInput {
         symbol?: string;
         decimals?: number;
     };
-    x402_solana?: {
+    solana_mpp?: {
         recipient: string;
         network?: string;
         token?: string;
         symbol?: string;
         decimals?: number;
+        feePayerKey?: string;
     };
     stripe?: {
         profileId?: string | null;
@@ -95,115 +107,6 @@ interface IdentityMetadataBlock {
  */
 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.
  *
@@ -366,10 +269,9 @@ 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.
+ * 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.
  *
  * All money fields are dollar-strings (e.g. `"250.00"`). Use `buildPricingBlock` from
  * `@agent-score/commerce/challenge` to compose the pricing fields from cents.
@@ -520,4 +422,4 @@ interface ValidationErrorBody {
  */
 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 };
+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 };

package/dist/challenge/index.js

@@ -28,6 +28,7 @@ __export(challenge_exports, {
   buildIdentityMetadata: () => buildIdentityMetadata,
   buildPricingBlock: () => buildPricingBlock,
   buildValidationError: () => buildValidationError,
+  compatibleClientsByRails: () => compatibleClientsByRails,
   firstEncounterAgentMemory: () => firstEncounterAgentMemory,
   respond402: () => respond402
 });
@@ -58,14 +59,15 @@ function buildAcceptedMethods(input) {
       pay_to: input.x402_base.recipient
     });
   }
-  if (input.x402_solana) {
+  if (input.solana_mpp) {
     out.push({
-      method: "x402/exact",
-      network: input.x402_solana.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
-      token: input.x402_solana.token ?? "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
-      symbol: input.x402_solana.symbol ?? "USDC",
-      decimals: input.x402_solana.decimals ?? 6,
-      pay_to: input.x402_solana.recipient
+      method: "solana/charge",
+      network: input.solana_mpp.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+      token: input.solana_mpp.token ?? "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      symbol: input.solana_mpp.symbol ?? "USDC",
+      decimals: input.solana_mpp.decimals ?? 6,
+      pay_to: input.solana_mpp.recipient,
+      ...input.solana_mpp.feePayerKey ? { fee_payer_key: input.solana_mpp.feePayerKey } : {}
     });
   }
   if (input.stripe) {
@@ -125,7 +127,7 @@ function buildHowToPay(input) {
       prerequisite: `Run \`tempo wallet whoami\` and confirm USDC.e balance on ${networkName} (chain ${chainId}) is at least $${maxSpend}. If the tempo CLI is not installed, run the setup commands above first.`,
       command: recommend === "agentscore-pay" ? payCommand : tempoCommand,
       ...recommend === "both" ? { alternative_command: payCommand } : recommend === "agentscore-pay" ? { alternative_command: tempoCommand } : {},
-      what_it_does: `Hits this endpoint, receives this same 402, signs the MPP challenge on ${networkName}, and submits the credential back via Authorization: Payment. Either client (tempo request or agentscore-pay pay --chain tempo) works \u2014 both run the full MPP handshake.`
+      what_it_does: `Pays via Tempo USDC on ${networkName}.`
     };
   }
   if (input.rails.x402_base) {
@@ -134,16 +136,16 @@ function buildHowToPay(input) {
       setup: PAY_SETUP_BASE,
       prerequisite: `Run \`agentscore-pay balance --chain base\` and confirm USDC balance on Base (${network}) is at least $${maxSpend}. If the CLI is not installed, run the setup commands above first.`,
       command: `agentscore-pay pay POST ${input.url} --chain base -H 'X-Operator-Token: ${opToken}' -H 'Content-Type: application/json' -d '${input.retryBodyJson}' --max-spend ${maxSpend}`,
-      what_it_does: "Hits this endpoint, receives this same 402, signs an EIP-3009 USDC TransferWithAuthorization on Base, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + returns 200 with the completed order."
+      what_it_does: "Pays via USDC on Base."
     };
   }
-  if (input.rails.x402_solana) {
-    const network = input.rails.x402_solana.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-    block.x402_solana = {
+  if (input.rails.solana_mpp) {
+    const network = input.rails.solana_mpp.network ?? "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    block.solana_mpp = {
       setup: PAY_SETUP_SOLANA,
       prerequisite: `Run \`agentscore-pay balance --chain solana\` and confirm USDC balance on Solana (${network}) is at least $${maxSpend}. If the CLI is not installed, run the setup commands above first.`,
       command: `agentscore-pay pay POST ${input.url} --chain solana -H 'X-Operator-Token: ${opToken}' -H 'Content-Type: application/json' -d '${input.retryBodyJson}' --max-spend ${maxSpend}`,
-      what_it_does: "Hits this endpoint, receives this same 402, signs an SPL Token TransferChecked transaction on Solana, submits via X-Payment header. Server verifies + settles via the Coinbase facilitator + returns 200 with the completed order."
+      what_it_does: "Pays via USDC on Solana."
     };
   }
   if (input.rails.stripe) {
@@ -166,7 +168,7 @@ function buildHowToPay(input) {
         `SPEND_ID=$(link-cli spend-request create --payment-method-id <csmrpd_id_from_payment_methods_list> --credential-type shared_payment_token --network-id ${stripeCfg.profileId} --amount ${amountCents} --context "${sptContext}" --request-approval --output-json | jq -r .id)`,
         `link-cli mpp pay ${input.url} --spend-request-id $SPEND_ID --method POST --data '${input.retryBodyJson}' --header 'X-Operator-Token: ${opToken}' --output-json`
       ];
-      stripe.what_it_does_link_cli = "For users who have a Stripe Link wallet: step 1 mints a one-time-use SharedPaymentToken scoped to this purchase and pushes a notification to the user for approval (blocks until approved); step 2 submits the SPT via the MPP handshake along with your AgentScore operator credential.";
+      stripe.what_it_does_link_cli = "Mints a one-time-use SharedPaymentToken scoped to this purchase (user approves in Link wallet), then submits it as the payment credential.";
     } else if (linkCliBlocked) {
       stripe.note = `link-cli SPT path not available for this purchase \u2014 Stripe link-cli caps spend requests at $500.00 ($50000 cents); your total is $${totalNum}. Use your own Stripe account with the SharedPaymentToken API instead.`;
     }
@@ -176,31 +178,42 @@ function buildHowToPay(input) {
 }
 
 // src/challenge/agent_instructions.ts
-var TEMPO_WARNING = "Do NOT use `tempo wallet transfer` to pay to the address above. That moves USDC on-chain but does not notify this server, leaving your order in pending_identity state. Use `tempo request` instead \u2014 it performs the full MPP handshake (signs, submits Authorization: Payment, waits for server confirmation).";
-var X402_WARNING = "Do NOT send USDC manually to the x402 deposit addresses (e.g. via a bare wallet `transfer`). Use `agentscore-pay pay` so the X-Payment credential is signed and submitted; otherwise the order stays in pending_identity even though the deposit lands.";
-var TEMPO_TOOL = "`tempo request` for Tempo USDC (installs via `tempo add request`)";
-var AGENTSCORE_PAY_TOOL = "`agentscore-pay` (npm: `@agent-score/pay`) \u2014 single CLI for x402 on Base + Solana, also speaks tempo MPP via `--chain tempo`";
-var DEFAULT_WALLET_COMPATIBILITY = "No specific wallet stack required. The 402 challenge is rail-neutral: any client that can produce a valid MPP credential (Authorization: Payment) or x402 X-Payment header is accepted. The CLI commands above are the easiest path; sign-it-yourself is fine too.";
+var TEMPO_WARNING = "Do NOT use `tempo wallet transfer`. That moves USDC on-chain without completing the protocol handshake, so the order will not complete. Use `tempo request` instead.";
+var X402_WARNING = "Do NOT send USDC manually to the deposit addresses. Use `agentscore-pay pay` so the credential is signed and submitted; otherwise the order will not complete even though the deposit lands.";
+var TEMPO_TOOL = "`tempo request` for Tempo USDC";
+var AGENTSCORE_PAY_TOOL = "`agentscore-pay` \u2014 Base + Solana + Tempo from one CLI";
+var DEFAULT_WALLET_COMPATIBILITY = "Any client that can produce a valid MPP credential (Authorization: Payment) or x402 X-Payment header. Use the CLI commands above; sign-it-yourself is also fine.";
 function defaultRecommendedTools(howToPay) {
   const tools = [];
   if (howToPay.tempo) tools.push(TEMPO_TOOL);
-  if (howToPay.tempo || howToPay.x402_base || howToPay.x402_solana) tools.push(AGENTSCORE_PAY_TOOL);
+  if (howToPay.tempo || howToPay.x402_base || howToPay.solana_mpp) tools.push(AGENTSCORE_PAY_TOOL);
   return tools;
 }
 function defaultWarnings(howToPay) {
   const w = [];
   if (howToPay.tempo) w.push(TEMPO_WARNING);
-  if (howToPay.x402_base || howToPay.x402_solana) w.push(X402_WARNING);
+  if (howToPay.x402_base) w.push(X402_WARNING);
   return w;
 }
-function defaultCompatibleClients(howToPay) {
+var RAIL_CLIENTS = {
+  tempo_mpp: ["agentscore-pay", "tempo request", "x402-proxy"],
+  x402_base: ["agentscore-pay", "x402-proxy", "purl (omit --network flag)"],
+  solana_mpp: ["agentscore-pay"],
+  stripe: ["link-cli"]
+};
+function compatibleClientsByRails(rails) {
   const out = {};
-  if (howToPay.tempo) out.tempo_mpp = ["agentscore-pay", "tempo request", "x402-proxy"];
-  if (howToPay.x402_base) out.x402_base = ["agentscore-pay", "x402-proxy", "purl (omit --network flag)"];
-  if (howToPay.x402_solana) out.x402_solana = ["agentscore-pay"];
-  if (howToPay.stripe) out.stripe = ["link-cli"];
+  for (const r of rails) out[r] = [...RAIL_CLIENTS[r]];
   return Object.keys(out).length === 0 ? void 0 : out;
 }
+function defaultCompatibleClients(howToPay) {
+  const rails = [];
+  if (howToPay.tempo) rails.push("tempo_mpp");
+  if (howToPay.x402_base) rails.push("x402_base");
+  if (howToPay.solana_mpp) rails.push("solana_mpp");
+  if (howToPay.stripe) rails.push("stripe");
+  return compatibleClientsByRails(rails);
+}
 function buildAgentInstructions(input) {
   const compatibleClients = input.compatibleClients ?? defaultCompatibleClients(input.howToPay);
   return {
@@ -208,7 +221,7 @@ function buildAgentInstructions(input) {
     recommended_tools: input.recommendedTools ?? defaultRecommendedTools(input.howToPay),
     wallet_compatibility: input.walletCompatibility ?? DEFAULT_WALLET_COMPATIBILITY,
     timeout_seconds: input.timeoutSeconds ?? 300,
-    warnings: input.warnings ?? defaultWarnings(input.howToPay),
+    warnings: input.warnings ?? [...defaultWarnings(input.howToPay), ...input.extraWarnings ?? []],
     ...input.recommended ? { recommended: input.recommended } : {},
     ...compatibleClients ? { compatible_clients: compatibleClients } : {},
     ...input.extra ?? {}
@@ -406,6 +419,7 @@ function buildValidationError(input) {
   buildIdentityMetadata,
   buildPricingBlock,
   buildValidationError,
+  compatibleClientsByRails,
   firstEncounterAgentMemory,
   respond402
 });