@agent-score/commerce 1.1.0 → 1.3.0

package/dist/discovery/index.mjs

@@ -83,15 +83,15 @@ var rails = {
     decimals: USDC.base.sepolia.decimals,
     asset: USDC.base.sepolia.address
   },
-  "x402-solana-mainnet": {
-    method: "x402",
+  "mpp-solana-mainnet": {
+    method: "solana",
     network: networks.solana.mainnet.caip2,
     currency: USDC.solana.mainnet.mint,
     decimals: USDC.solana.mainnet.decimals,
     asset: USDC.solana.mainnet.mint
   },
-  "x402-solana-devnet": {
-    method: "x402",
+  "mpp-solana-devnet": {
+    method: "solana",
     network: networks.solana.devnet.caip2,
     currency: USDC.solana.devnet.mint,
     decimals: USDC.solana.devnet.decimals,
@@ -280,6 +280,14 @@ function buildWellKnownMpp(input) {
   };
 }
 
+// src/discovery/well_known_x402.ts
+function buildWellKnownX402(input) {
+  return {
+    version: 1,
+    resources: input.resources.map((r) => `${r.method.toUpperCase()} ${r.path}`)
+  };
+}
+
 // src/discovery/llms_txt.ts
 function llmsTxtIdentitySection(input = {}) {
   if (!input.agentscore) {
@@ -294,19 +302,13 @@ Compliance: ${[
     compliance.allowed_jurisdictions?.length ? `${compliance.allowed_jurisdictions.join("/")} only` : null,
     compliance.require_sanctions_clear ? "sanctions clear" : null
   ].filter(Boolean).join(", ")}.` : "";
-  return `## Choose your identity header
-
-AgentScore provides cross-merchant identity \u2014 one KYC works for every AgentScore-gated endpoint, no re-verification per site. Pick the right header based on how you plan to pay:
-
-- **Wallet-auth** (preferred for agents with a stable crypto wallet): send \`X-Wallet-Address: 0x...\`. Only works on rails that carry a wallet signature \u2014 Tempo MPP and x402 EIP-3009. The wallet you claim MUST sign the payment; we verify that the payment signer resolves to the same operator as the claimed wallet. No TTL, no rotation.
-- **Operator-token** (works for every rail): send \`X-Operator-Token: opc_...\`. Required when paying with Stripe SPT or card (those rails have no wallet signer). Reusable across every AgentScore merchant until the token expires.
-- **Neither**: you'll get 403 with \`verify_url\` + \`poll_secret\` \u2014 complete the session flow once, then reuse the credential (or any wallet that pays under it) forever.
-
-If you reach another AgentScore-gated endpoint in the future, the same credential and/or any linked wallet already works \u2014 skip the session flow.
+  return `## Identity
 
-## Memory contract
+AgentScore identity is reusable across every AgentScore-gated merchant \u2014 one KYC, no re-verification per site. Pick a header:
 
-First-encounter 403 responses (and the POST /v1/sessions success body) include an \`agent_memory\` block describing how AgentScore identity works across merchants. LLM-hosted agents should persist its contents (the pattern, never secrets) so subsequent AgentScore-gated endpoints become returning-customer encounters.${complianceNote}`;
+- **\`X-Wallet-Address: 0x...\` or base58** \u2014 works on signing rails (Tempo, x402, Solana MPP). The wallet you claim must sign the payment.
+- **\`X-Operator-Token: opc_...\`** \u2014 works on every rail, including Stripe SPT. Reusable across AgentScore merchants until expiry.
+- **Neither** \u2014 you get a 403 with \`verify_url\`. Complete the session flow once and reuse the resulting \`opc_...\` everywhere.${complianceNote}`;
 }
 function llmsTxtPaymentSection(input) {
   return input.verbose ? llmsTxtPaymentSectionVerbose(input) : llmsTxtPaymentSectionCompact(input);
@@ -326,8 +328,8 @@ function llmsTxtPaymentSectionCompact(input) {
   if (hasRailFamily(rails2, "x402-base-")) {
     lines.push("- **x402 USDC on Base** (EIP-3009) \u2014 `agentscore-pay pay POST " + input.appUrl + ` --chain base -H "X-Operator-Token: opc_..." -d '{...}'\``);
   }
-  if (hasRailFamily(rails2, "x402-solana-")) {
-    lines.push("- **x402 USDC on Solana** (SPL Token) \u2014 `agentscore-pay pay POST " + input.appUrl + ` --chain solana -H "X-Operator-Token: opc_..." -d '{...}'\``);
+  if (hasRailFamily(rails2, "mpp-solana-")) {
+    lines.push("- **USDC on Solana** \u2014 `agentscore-pay pay POST " + input.appUrl + ` --chain solana -H "X-Operator-Token: opc_..." -d '{...}'\``);
   }
   if (rails2.includes("stripe-spt")) {
     lines.push("- **Stripe Shared Payment Token** \u2014 agent mints SPT (own Stripe account scoped to networkId, OR `link-cli spend-request create --credential-type shared_payment_token --network-id <profileId> ...`)");
@@ -343,72 +345,62 @@ function llmsTxtPaymentSectionVerbose(input) {
   const tempoChain = input.tempoChainId ?? 4217;
   const hasTempo = hasRailFamily(rails2, "tempo-");
   const hasBase = hasRailFamily(rails2, "x402-base-");
-  const hasSolana = hasRailFamily(rails2, "x402-solana-");
+  const hasSolana = hasRailFamily(rails2, "mpp-solana-");
   const hasStripe = rails2.includes("stripe-spt");
   const baseNetworkName = isTestnetRail(rails2, "x402-base-") ? "Base Sepolia" : "Base";
-  const solanaNetworkName = isTestnetRail(rails2, "x402-solana-") ? "Solana devnet" : "Solana";
+  const solanaNetworkName = isTestnetRail(rails2, "mpp-solana-") ? "Solana devnet" : "Solana";
   const lines = ["## Payment", ""];
-  lines.push("This is an agent-first API. All payments are initiated and completed by agents. The 402 challenge advertises:");
+  lines.push("Accepted rails:");
   lines.push("");
-  if (hasTempo) lines.push("- **Tempo USDC via MPP** (on-chain stablecoin)");
-  if (hasBase || hasSolana) {
-    const chains = [hasBase && `${baseNetworkName} (EIP-3009)`, hasSolana && `${solanaNetworkName} (SPL Token)`].filter(Boolean).join(" and ");
-    lines.push(`- **x402 USDC** on ${chains}, via the Coinbase facilitator`);
-  }
-  if (hasStripe) lines.push("- **Stripe Shared Payment Token** (agent mints SPT on their Stripe account scoped to our networkId in the challenge, submits it in the credential)");
+  if (hasTempo) lines.push("- **USDC on Tempo**");
+  if (hasBase) lines.push(`- **USDC on ${baseNetworkName}**`);
+  if (hasSolana) lines.push(`- **USDC on ${solanaNetworkName}**`);
+  if (hasStripe) lines.push("- **Stripe Shared Payment Token**");
   lines.push("");
   if (hasTempo) {
-    lines.push("### How to pay with Tempo");
+    lines.push("### Pay with Tempo");
     lines.push("");
-    lines.push("1. Install the Tempo CLI: curl -fsSL https://tempo.xyz/install | bash");
-    lines.push("2. Log in to your Tempo Wallet: tempo wallet login (passkey auth in browser)");
-    lines.push(`3. Confirm your balance: tempo wallet whoami (need USDC.e on ${tempoNetwork}, chain ${tempoChain})`);
-    lines.push("4. If balance is zero, fund it: tempo wallet fund");
-    lines.push("");
-    lines.push("Then use `tempo request` to make the paid purchase:");
+    lines.push("```bash");
+    lines.push("curl -fsSL https://tempo.xyz/install | bash");
+    lines.push("tempo wallet login");
+    lines.push(`tempo wallet whoami     # need USDC.e on ${tempoNetwork} (chain ${tempoChain})`);
+    lines.push("tempo wallet fund       # if zero");
     lines.push("");
     lines.push("tempo request -X POST \\");
-    lines.push('  -H "X-Operator-Token: opc_your_credential" \\');
-    lines.push('  -H "Content-Type: application/json" \\');
+    lines.push('  -H "X-Operator-Token: opc_..." \\');
     lines.push("  --json '{...}' \\");
     lines.push("  --max-spend N \\");
     lines.push(`  ${input.appUrl}`);
-    lines.push("");
-    lines.push(`\`tempo request\` handles the full MPP handshake: sends the POST, receives the 402 challenge, signs the payment on ${tempoNetwork}, submits the credential, and returns the completed order.`);
+    lines.push("```");
     lines.push("");
   }
   if (hasBase || hasSolana) {
     const chainsLabel = [hasBase && baseNetworkName, hasSolana && solanaNetworkName].filter(Boolean).join(" or ");
     const flags = [hasBase && "`--chain base`", hasSolana && "`--chain solana`"].filter(Boolean).join(" or ");
-    lines.push(`### How to pay with x402 (${chainsLabel})`);
+    lines.push(`### Pay with ${chainsLabel}`);
     lines.push("");
-    lines.push("1. Install the agentscore-pay CLI: npm install -g @agent-score/pay  (or: brew install agentscore/tap/agentscore-pay)");
-    lines.push(`2. Create a wallet on your chain of choice: agentscore-pay wallet create ${flags}`);
-    lines.push(`3. Fund the printed address with USDC on ${chainsLabel}`);
-    lines.push(`4. Confirm balance: agentscore-pay balance ${flags}`);
-    lines.push("");
-    lines.push("Then submit the paid purchase:");
+    lines.push("```bash");
+    lines.push("npm install -g @agent-score/pay");
+    lines.push(`agentscore-pay wallet create ${flags}`);
+    lines.push(`agentscore-pay balance ${flags}   # fund the printed address with USDC`);
     lines.push("");
     lines.push(`agentscore-pay pay POST ${input.appUrl} \\`);
     lines.push(`  ${hasBase ? "--chain base" : "--chain solana"} \\`);
-    lines.push('  -H "X-Operator-Token: opc_your_credential" \\');
-    lines.push('  -H "Content-Type: application/json" \\');
+    lines.push('  -H "X-Operator-Token: opc_..." \\');
     lines.push("  -d '{...}' \\");
     lines.push("  --max-spend N");
-    lines.push("");
-    const handshakeChains = [hasBase && "EIP-3009 (Base)", hasSolana && "SPL Token (Solana)"].filter(Boolean).join(" or ");
-    lines.push(`The CLI handles the full x402 handshake: hits the URL, parses the 402 challenge, signs the ${handshakeChains} transaction, submits via X-Payment header, and returns the completed order.`);
+    lines.push("```");
     lines.push("");
   }
   if (hasStripe) {
-    lines.push("### How to pay with Stripe SPT");
+    lines.push("### Pay with Stripe SPT");
     lines.push("");
-    lines.push("Mint a SharedPaymentToken scoped to the profile_id advertised in `accepted_methods.stripe.profile_id`, then submit via `Authorization: Payment` MPP header with `method=stripe/charge`. Either bring your own Stripe account or use `link-cli spend-request create --credential-type shared_payment_token --network-id <profileId> ...` for users with Stripe Link wallets.");
+    lines.push("Mint a SharedPaymentToken scoped to the `profile_id` from the 402 body, then submit via `Authorization: Payment` with `method=stripe/charge`. Either your own Stripe account or `link-cli spend-request create --credential-type shared_payment_token --network-id <profileId> ...` for Stripe Link wallets.");
     lines.push("");
   }
-  lines.push("IMPORTANT: Do NOT use `tempo wallet transfer` or send USDC manually to the x402 deposit addresses \u2014 those bypass the payment handshake and your order will stay in pending_identity.");
+  lines.push("IMPORTANT: Use the CLIs above. Raw on-chain transfers (e.g. `tempo wallet transfer`, sending USDC manually to deposit addresses) bypass the protocol handshake and the order will not complete.");
   if (hasBase || hasSolana) {
-    lines.push("IMPORTANT: x402 payments must be the exact amount specified in the 402 challenge. Overpayments and underpayments cannot be matched and funds may be unrecoverable.");
+    lines.push("IMPORTANT: Pay the exact amount in the 402 challenge. Overpayments and underpayments cannot be matched.");
   }
   lines.push("");
   return lines.join("\n");
@@ -449,7 +441,16 @@ function agentscoreSecuritySchemes() {
       in: "header",
       name: "X-Wallet-Address",
       description: "Wallet-path identity (0x... or base58). Only works on rails that carry a wallet signature (Tempo MPP, x402 EIP-3009, x402 SPL Token). The wallet you claim MUST sign the payment."
-    }
+    },
+    siwx: siwxSecurityScheme()
+  };
+}
+function siwxSecurityScheme() {
+  return {
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "SIWX",
+    description: "Sign-In With X wallet authentication. Agent signs a challenge with their wallet (any supported chain) and presents the proof in the Authorization header. Used for identity-gated free endpoints; payment-required endpoints declare x-payment-info instead."
   };
 }
 function agentscoreDenialSchemas() {
@@ -522,6 +523,12 @@ function agentscorePaymentRequiredSchema() {
     }
   };
 }
+function xPaymentInfoExtension(input) {
+  return { "x-payment-info": { price: input.price, protocols: input.protocols } };
+}
+function xGuidanceExtension(text) {
+  return { "x-guidance": text };
+}
 function agentscoreOpenApiSnippets(opts = {}) {
   const out = {};
   if (opts.security !== false) {
@@ -540,7 +547,10 @@ function agentscoreOpenApiSnippets(opts = {}) {
 var defaultDiscoveryPaths = /* @__PURE__ */ new Set([
   "/openapi.json",
   "/llms.txt",
+  "/skill.md",
+  "/SKILL.md",
   "/.well-known/mpp.json",
+  "/.well-known/x402",
   "/.well-known/agent-card.json",
   "/.well-known/ucp",
   "/favicon.png",
@@ -606,6 +616,204 @@ function wrapNoindexResponse(path, response, options) {
   });
 }
 var applyNoindexHeader = wrapNoindexResponse;
+
+// src/challenge/agent_instructions.ts
+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(rails2) {
+  const out = {};
+  for (const r of rails2) out[r] = [...RAIL_CLIENTS[r]];
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+
+// src/discovery/skill_md.ts
+var RAIL_LABELS = {
+  tempo_mpp: "MPP on Tempo",
+  x402_base: "x402 on Base",
+  solana_mpp: "MPP on Solana",
+  stripe: "Stripe Shared Payment Token"
+};
+var RAIL_NOTES = {
+  tempo_mpp: "USDC. Use `agentscore-pay --chain tempo` (or `tempo request`); MPP credential goes in `Authorization: Payment`.",
+  x402_base: "USDC (EIP-3009). Use `agentscore-pay`; X-Payment header carries the signed credential.",
+  solana_mpp: "USDC (SPL). Use `agentscore-pay --chain solana`; MPP credential goes in `Authorization: Payment`.",
+  stripe: "Card via Link wallet. Use `@stripe/link-cli` \u2014 `agentscore-pay` emits the handoff hint when this rail is picked."
+};
+var NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var NAME_MAX = 64;
+var DESCRIPTION_MAX = 1024;
+var COMPATIBILITY_MAX = 500;
+function validateInput(input) {
+  if (!input.name || input.name.length === 0 || input.name.length > NAME_MAX) {
+    throw new Error(`buildSkillMd: name must be 1-${NAME_MAX} characters (got ${input.name?.length ?? 0})`);
+  }
+  if (!NAME_RE.test(input.name)) {
+    throw new Error(
+      `buildSkillMd: name "${input.name}" is invalid \u2014 must be lowercase alphanumeric and hyphens, no leading/trailing/consecutive hyphens (agentskills.io spec)`
+    );
+  }
+  if (!input.description || input.description.length === 0) {
+    throw new Error("buildSkillMd: description is required and must be non-empty (agentskills.io spec)");
+  }
+  if (input.description.length > DESCRIPTION_MAX) {
+    throw new Error(
+      `buildSkillMd: description must be \u2264${DESCRIPTION_MAX} characters (got ${input.description.length})`
+    );
+  }
+  if (input.compatibility && input.compatibility.length > COMPATIBILITY_MAX) {
+    throw new Error(
+      `buildSkillMd: compatibility must be \u2264${COMPATIBILITY_MAX} characters (got ${input.compatibility.length})`
+    );
+  }
+}
+function quoteYaml(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+}
+function tableCell(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+function frontmatter(input) {
+  const lines = ["---"];
+  lines.push(`name: ${input.name}`);
+  lines.push(`description: ${quoteYaml(input.description)}`);
+  if (input.license) lines.push(`license: ${quoteYaml(input.license)}`);
+  if (input.compatibility) lines.push(`compatibility: ${quoteYaml(input.compatibility)}`);
+  if (input.allowedTools) lines.push(`allowed-tools: ${quoteYaml(input.allowedTools)}`);
+  const meta = [];
+  meta.push(["version", String(input.version ?? "1")]);
+  meta.push(["homepage", input.homepage]);
+  for (const [k, v] of Object.entries(input.metadata ?? {})) {
+    if (k === "version" || k === "homepage") continue;
+    meta.push([k, String(v)]);
+  }
+  lines.push("metadata:");
+  for (const [k, v] of meta) {
+    lines.push(`  ${k}: ${quoteYaml(v)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+function importantFiles(input) {
+  const skillUrl = `${input.homepage.replace(/\/$/, "")}/skill.md`;
+  const rows = [
+    "| File | URL |",
+    "|------|-----|",
+    `| **SKILL.md** (this file) | \`${skillUrl}\` |`
+  ];
+  for (const f of input.files ?? []) {
+    rows.push(`| ${tableCell(f.label)} | \`${tableCell(f.url)}\` |`);
+  }
+  return ["## Important Files", "", ...rows].join("\n");
+}
+function paymentSection(input) {
+  const override = input.compatibleClients;
+  const defaults = compatibleClientsByRails(input.acceptedRails) ?? {};
+  const clients = {};
+  for (const r of input.acceptedRails) {
+    clients[r] = override?.[r] ?? defaults[r] ?? [];
+  }
+  const rows = ["| Rail | Notes | Compatible clients |", "|---|---|---|"];
+  for (const r of input.acceptedRails) {
+    const list = (clients[r] ?? []).join(", ") || "\u2014";
+    rows.push(`| **${RAIL_LABELS[r]}** | ${RAIL_NOTES[r]} | ${list} |`);
+  }
+  return [
+    "## Payment",
+    "",
+    "Each gated route returns a 402 with `WWW-Authenticate` + `PAYMENT-REQUIRED` body listing the rails below with current pricing. Pick whichever your wallet is funded for.",
+    "",
+    ...rows
+  ].join("\n");
+}
+function identitySection(input) {
+  const id = input.identity;
+  if (!id) return "";
+  const reqs = [];
+  if (id.kycRequired) reqs.push("KYC verified Passport");
+  if (id.minAge) reqs.push(`age ${id.minAge}+`);
+  if (id.allowedJurisdictions?.length) reqs.push(`${id.allowedJurisdictions.join("/")} only`);
+  if (id.sanctionsClear) reqs.push("sanctions clear");
+  if (reqs.length === 0) return "";
+  const bootstrap = input.identityBootstrapUrl ? `
+
+If you don't have a Passport, fetch \`${input.identityBootstrapUrl}\` and follow the onboarding there first. Bring back the \`opc_...\` operator token in \`X-Operator-Token\` on every gated request.` : "";
+  return [
+    "## Identity Prerequisite",
+    "",
+    `This merchant uses AgentScore identity. Required: ${reqs.join(", ")}.${bootstrap}`,
+    "",
+    "Denial bodies carry an `agent_instructions` block describing the recovery action \u2014 read the `action` field and follow it. See the identity-bootstrap skill for the canonical denial-code \u2192 action table."
+  ].join("\n");
+}
+function shippingSection(input) {
+  const s = input.shipping;
+  if (!s || !s.allowedCountries?.length && !s.blockedStates?.length) return "";
+  const lines = ["## Shipping", ""];
+  if (s.allowedCountries?.length) {
+    lines.push(`Ships to: ${s.allowedCountries.join(", ")}.`);
+  }
+  if (s.blockedStates?.length) {
+    if (lines.length > 2) lines.push("");
+    lines.push(`Blocked US states: ${s.blockedStates.join(", ")}.`);
+  }
+  return lines.join("\n");
+}
+function endpointsSection(input) {
+  if (input.endpoints.length === 0) return "";
+  const rows = ["| Method | Path | Auth | Purpose |", "|---|---|---|---|"];
+  for (const e of input.endpoints) {
+    rows.push(
+      `| ${e.method} | \`${tableCell(e.path)}\` | ${e.authRequired ? "identity required" : "anonymous"} | ${tableCell(e.description)} |`
+    );
+  }
+  return ["## Endpoints", "", ...rows].join("\n");
+}
+function onboardingSection(input) {
+  if (!input.onboardingSteps?.length) return "";
+  const rows = input.onboardingSteps.map((step, i) => `${i + 1}. ${step}`);
+  return ["## Onboarding Flow", "", ...rows].join("\n");
+}
+function triggersSection(input) {
+  if (input.triggers.length === 0) return "";
+  const rows = input.triggers.map((t) => `- ${t}`);
+  return ["## Triggers", "", "Use this skill when the user wants to:", "", ...rows].join("\n");
+}
+function supportSection(input) {
+  if (!input.supportLinks?.length) return "";
+  const rows = input.supportLinks.map((l) => `- **${l.label}**: ${l.url}`);
+  return ["## Support", "", ...rows].join("\n");
+}
+function refreshFooter(input) {
+  if (input.refreshFooter === false) return "";
+  return "_Re-fetch this file periodically to pick up new endpoints, rails, or policies._";
+}
+function titleBlock(input) {
+  const parts = [`# ${input.merchantName}`];
+  if (input.tagline) parts.push(`_${input.tagline}_`);
+  if (input.intro) parts.push(input.intro);
+  return parts.join("\n\n");
+}
+function buildSkillMd(input) {
+  validateInput(input);
+  const sections = [
+    frontmatter(input),
+    titleBlock(input),
+    importantFiles(input),
+    identitySection(input),
+    paymentSection(input),
+    shippingSection(input),
+    onboardingSection(input),
+    endpointsSection(input),
+    triggersSection(input),
+    supportSection(input),
+    refreshFooter(input)
+  ].filter((s) => s !== "");
+  return sections.join("\n\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
 export {
   agentscoreDenialSchemas,
   agentscoreOpenApiSnippets,
@@ -614,7 +822,10 @@ export {
   applyNoindexHeader,
   buildDiscoveryProbeResponse,
   buildLlmsTxt,
+  buildSkillMd,
   buildWellKnownMpp,
+  buildWellKnownX402,
+  compatibleClientsByRails,
   createBazaarDiscovery,
   defaultDiscoveryPaths,
   isDiscoveryPath,
@@ -625,6 +836,9 @@ export {
   noindexNonDiscoveryPathsExpress,
   noindexNonDiscoveryPathsFastify,
   sampleX402AcceptForNetwork,
-  wrapNoindexResponse
+  siwxSecurityScheme,
+  wrapNoindexResponse,
+  xGuidanceExtension,
+  xPaymentInfoExtension
 };
 //# sourceMappingURL=index.mjs.map