@agent-score/commerce 2.6.0 → 2.6.1

package/README.md

@@ -29,7 +29,7 @@ npm install hono mppx @x402/core @x402/evm @solana/mpp @solana/kit stripe   # wh
 | `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (opt-in v1↔v2 amount-field shim: adds both `amount` and `maxAmountRequired` to an entry. The 402 builders do NOT apply it by default, strict x402 v2 settlement matches the agent's echoed requirement by exact comparison, so an extra field the server's rebuilt requirement lacks breaks settle; use only when you know a client is hardcoded to read `maxAmountRequired`), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (Request-based; recovers signer from x402 EIP-3009 `payload.authorization.from` OR MPP `Authorization: Payment <base64>` `did:pkh:eip155:<chain>:<addr>` / `did:pkh:solana:<genesis>:<addr>` source DID, including Solana `TransferChecked` authority fallback when `@solana/kit` is installed), `extractPaymentSignerFromAuth` (header-string variant for callers that already have the `Authorization` value in hand), `detectRailFromHeaders` (returns `"x402"` / `"mpp"` / `null` from inbound headers); `createX402Server`, `createMppxServer` (the solana rail's `ataCreationRequired` defaults to `true` so Solana settles work on `@solana/mpp >= 0.6.0` out of the box, opt out only if every recipient's ATA is guaranteed to pre-exist; see `SolanaMppRailSpec.ataCreationRequired` for economics), `buildDefaultCheckoutRails({tempo?, x402Base?, solanaMpp?, stripe?})` (canonical 4-rail `rails` dict factory: flipping `network` alone derives the right `token` + `chainId`, Base Sepolia → Sepolia USDC + chainId 84532, Solana devnet → devnet USDC mint. Solana's `network` accepts both CAIP-2 and the raw `@solana/mpp` form `mainnet-beta` / `devnet` / `localnet`. Explicit overrides always win), `buildMppxComposeRails({amountUsd, tempoRecipient?, solanaRecipient?, ...})` (per-call intent factory replacing the hand-rolled `[['tempo/charge',{...}],['solana/charge',{...}],['stripe/charge',{...}]]` array; auto-handles USD→atomic conversion for Solana; auto-drops `stripe/charge` when `amountUsd < 0.50` since Stripe's fixed ~$0.30 fee makes sub-50-cent charges unprofitable, sub-50-cent APIs pass `includeStripe: false` explicitly to silence the warning); drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call), `classifyX402SettleResult` (maps the tagged settle result to a recommended HTTP status / code / nextSteps so merchants get a controlled envelope without coupling to facilitator-specific error text), `classifyOrchestrationError` (same `ClassifiedX402Error` shape but for uncaught exceptions thrown elsewhere in the orchestration; returns `null` for unknown errors so merchants rethrow instead of swallowing); `zeroAmountCarveOut` (skip CDP / mppx upstream verify+settle for $0 settles where the upstream rejects value=0 payloads; parses the credential, lifts signer + network, returns a `ZeroSettleResult` shaped identically to the success path so callers branch on rail, not on result shape); `usdToAtomic` (BigInt-based USD → atomic value, ROUND_HALF_UP, for Tempo / Solana / Base USDC amount construction). |
 | `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers, e.g. `awal x402 details`), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `buildSkillMd` (Claude-Skill-compatible `/skill.md` agent-discovery manifest; strictly agent-facing data only, no internal posture), `buildRedemptionSkillMd` (delivery-neutral redemption-code template, printed mailers, emailed codes, API trial credits all covered; `endpointPath`/`deliveryIntro`/`bodyShape`/`bodyRules`/`extraRecoveryRows` overrides for non-goods shapes), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware emitting `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks), `buildMerchantIndexJson` (canonical `/` discovery body), `standardEndpointDescriptions({kind})` (canonical method+path → description map for goods vs api merchants; optional `includeOrderStatusRoute` for goods), `buildSuccessNextSteps` (universal Passport-active success block), `buildAgentscoreOnboardingSteps` (canonical skill.md onboarding for goods or API merchants). Plus the UCP/JWKS publish surface: `buildSignedUcpResponse`, `buildSignedJwksResponse`, `wellKnownPreflightResponse`, `defaultA2aServices`, `bootstrapUcpSigningKey`, and the framework-neutral `SignedDiscoveryResponse` + per-framework wrappers `signedResponse{Hono,Express,Fastify,Nextjs,Web}`. |
 | `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions` (auto-emits per-rail `compatible_clients`: smoke-verified CLIs the agent should use; vendor override supported; pure helper `compatibleClientsByRails(rails)` returns the same map for vendors building custom 402s), `buildPricingBlock`, `firstEncounterAgentMemory`, `Receipt` (canonical 200-receipt shape returned post-settle, universal: goods merchants fill the shipping/fulfillment/product slots, API merchants populate only the universal fields); `respond402`, a drop-in 402 emit that preserves mppx's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `buildValidationError`: structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
-| `/stripe-multichain` | `createMultichainPaymentIntent` (returns `{ paymentIntentId, depositAddresses }`, read `depositAddresses[network]` directly), `createPayToAddressFromStripePI({request, amountCents, stripe, piCache, networks?, staticRecipients?, metadata?, orderId?, preferredNetwork?})`, per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `piCache.hasAddress` check OR a `staticRecipients` match, the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `staticRecipients`, caches the merged map, registers static addresses with `piCache.cacheAddress` so verify-leg lookups pass. `mintMultichainRecipients({...same opts})`, structured variant that returns `{ recipients: Record<string,string>, paymentIntentId?, reusedFromCredential }`; prefer this when your `mintRecipients` hook needs the full per-rail map (typical multi-rail merchant). Use `staticRecipients: { solana: '<wallet>' }` for low-margin endpoints where the per-call ATA rent on Solana (~$0.50 against MPP spec §13.6) would dominate revenue, the SDK skips Stripe minting for that network, the static recipient is reused forever, and a one-time pre-funding of its USDC ATA from any external wallet makes every settle pay only the ~$0.001 per-tx fee. `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
+| `/stripe-multichain` | `createMultichainPaymentIntent` (returns `{ paymentIntentId, depositAddresses }`, read `depositAddresses[network]` directly), `createPayToAddressFromStripePI({request, amountCents, stripe, piCache, networks?, staticRecipients?, metadata?, orderId?, preferredNetwork?})`, per-order payTo resolver: on the settle leg, reuses the buyer's signed-against payTo from the MPP credential (after `piCache.hasAddress` check OR a `staticRecipients` match, the static address is always-accepted because the merchant owns it); on the discovery leg, mints a fresh PI for the rails NOT covered by `staticRecipients`, caches the merged map, registers static addresses with `piCache.cacheAddress` so verify-leg lookups pass. `mintMultichainRecipients({...same opts})`, structured variant that returns `{ recipients: Record<string,string>, paymentIntentId?, reusedFromCredential }`; prefer this when your `mintRecipients` hook needs the full per-rail map (typical multi-rail merchant). Solana MPP requires a static recipient: pass `staticRecipients: { solana: '<wallet>' }` and pre-fund its USDC ATA once from any external wallet. Rotating (per-order, Stripe-minted) Solana recipients do not settle, since the settlement transaction does not create the recipient's token account; the SDK logs a warning when one is minted. The static recipient is reused forever, each settle pays only the ~$0.001 per-tx fee, and this also sidesteps the per-call ATA rent (~$0.50 against MPP spec §13.6). `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
 | `/api` | Everything from `@agent-score/sdk` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `isAgentScoreTestAddress`. **Don't add `@agent-score/sdk` as a separate dep**; the two can drift versions and cause subtle type mismatches. |
 | `/middleware/{hono,express,fastify,nextjs,web}` | Framework-specific rate-limit middleware. Hono / Express / Fastify expose middleware factories (`rateLimitHono`, `rateLimitExpress`, `rateLimitFastify`); Next.js exposes `withRateLimit(opts, handler)`; Web Fetch exposes `createRateLimit(opts) => guard(req)`. Shared options: `windowSeconds` (default 60), `maxRequests` (default 60), `keyResolver` (default first hop of `x-forwarded-for`), `redisUrl` (lazy-imports `ioredis` when set, in-memory `Map` fallback otherwise), `keyPrefix`. `ioredis` is an optional peer dep, install it only if you want distributed limiting. |
 | `@agent-score/commerce` (top-level) | `Checkout` orchestrator + `CheckoutContext` + `CheckoutGateConfig` + `CheckoutValidationError` + `DiscoveryProbeConfig` + `MountUcpRoutesOptions` + `SettleOutcome` + `MppxComposeOutcome` + `PricingResult` (the 2.0 high-level surface: one config object, hooks for preValidate/computePricing/onSettled/mintRecipients/composeMppx, auto-derived x402+mppx servers, per-framework adapters `handleHono`/`handleExpress`/`handleFastify`/`handleNextjs`/`handleWeb`, signed UCP routes via `mountUcpRoutes{Hono,Express,Fastify}`); `pricingResult` (factory: cents-denominated → typed `PricingResult` with embedded `PricingBlock`); `validationResponse{Hono,Express,Fastify,Nextjs,Web}` (per-framework 4xx envelope wrappers); `loadUCPSigningKeyFromEnv` (cached env-driven loader for the UCP signing key, reads `UCP_SIGNING_KEY_JWK_PRIVATE` JSON JWK, detects alg from shape, falls back to ephemeral when unset, sanitizes errors so key bytes never reach logs, concurrent-safe via Promise-pinned cache); `hashOperatorToken` (sha256 hex of plaintext `opc_...`, for merchants persisting `operator_token_id` to their own DB without ever storing the plaintext); `extractOwnerScope(headers) → { walletAddress?, operatorTokenHash? }` (canonical owner-identity extractor for caller-scoped resource queries, reads `X-Wallet-Address` / `X-Operator-Token`, hashes the token so plaintext never leaves the request); `hasPaymentHeader` / `hasX402Header` / `hasMppxHeader` (request discriminators, any-credential vs x402 vs MPP); `defaultReadOnlyOnDenied(reason)` (canonical `onDenied` for read-only resource gates: 401 + `Cache-Control: no-store` while still spreading `denialReasonToBody`); plus the cross-vendor publishers `buildA2AAgentCard` + `buildUCPProfile` (return unsigned payloads: vendor signs + publishes). |

package/dist/core.js

@@ -227,7 +227,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/core.mjs

@@ -209,7 +209,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/express.js

@@ -920,7 +920,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/express.mjs

@@ -892,7 +892,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/fastify.js

@@ -921,7 +921,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/fastify.mjs

@@ -892,7 +892,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/hono.js

@@ -901,7 +901,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/hono.mjs

@@ -873,7 +873,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/nextjs.js

@@ -922,7 +922,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/nextjs.mjs

@@ -897,7 +897,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/web.js

@@ -898,7 +898,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/identity/web.mjs

@@ -873,7 +873,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();

package/dist/index.js

@@ -22662,7 +22662,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
-  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.6.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();
@@ -24636,6 +24636,27 @@ async function dynamicImport(moduleName) {
   }
 }
 
+// src/forwarded_proto.ts
+function applyForwardedProto(url2, forwardedProto) {
+  const proto = typeof forwardedProto === "string" ? forwardedProto.split(",")[0]?.trim() : void 0;
+  if (!proto) return url2;
+  try {
+    const u = new URL(url2);
+    u.protocol = `${proto}:`;
+    return u.toString();
+  } catch {
+    return url2;
+  }
+}
+function readForwardedProto(headers) {
+  if (typeof headers.get === "function") {
+    return headers.get("x-forwarded-proto") ?? void 0;
+  }
+  const rec = headers;
+  const raw = rec["x-forwarded-proto"] ?? rec["X-Forwarded-Proto"];
+  return Array.isArray(raw) ? raw[0] : raw;
+}
+
 // src/payment/constants.ts
 var STRIPE_MIN_CHARGE_USD = 0.5;
 
@@ -26423,17 +26444,7 @@ function validationResponseWeb(input) {
   return validationResponseHono(input);
 }
 function resolveResourceUrl(request) {
-  const fwd = request.headers["x-forwarded-proto"] ?? request.headers["X-Forwarded-Proto"];
-  const proto = typeof fwd === "string" ? fwd.split(",")[0]?.trim() : void 0;
-  if (proto) {
-    try {
-      const u = new URL(request.url);
-      u.protocol = `${proto}:`;
-      return u.toString();
-    } catch {
-    }
-  }
-  return request.url;
+  return applyForwardedProto(request.url, readForwardedProto(request.headers));
 }
 function stripContentType(headers) {
   const out = {};
@@ -27029,7 +27040,11 @@ function computeFirstCheckout(opts) {
     for (const [k, v] of Object.entries(mppChallengeHeaders)) headers.set(k, v);
     headers.set(
       "PAYMENT-REQUIRED",
-      paymentRequiredHeader2({ x402Version: 2, accepts: accepted, resource: { url: opts.url } })
+      paymentRequiredHeader2({
+        x402Version: 2,
+        accepts: accepted,
+        resource: { url: applyForwardedProto(req.url, readForwardedProto(req.headers)) }
+      })
     );
     return new Response(JSON.stringify(body402), { status: 402, headers });
   }
@@ -27088,7 +27103,7 @@ function computeFirstCheckout(opts) {
         maxTimeoutSeconds: 300
       },
       resourceMeta: {
-        url: req.url,
+        url: applyForwardedProto(req.url, readForwardedProto(req.headers)),
         description: `Agent purchase via x402-exact (${opts.name})`,
         mimeType: "application/json"
       }