@agent-score/commerce 2.1.0 → 2.1.1

package/dist/index.js

@@ -20825,6 +20825,7 @@ __export(index_exports, {
   buildMppxComposeRails: () => buildMppxComposeRails,
   buildSignerMismatchBody: () => buildSignerMismatchBody,
   buildUCPProfile: () => buildUCPProfile,
+  buildVerificationRequiredBody: () => buildVerificationRequiredBody,
   computeFirstCheckout: () => computeFirstCheckout,
   createDefaultOnDenied: () => createDefaultOnDenied,
   createQuoteCache: () => createQuoteCache,
@@ -21049,6 +21050,20 @@ var RESERVED_FIELDS = /* @__PURE__ */ new Set([
   "actual_signer",
   "linked_wallets"
 ]);
+function buildVerificationRequiredBody(reason, opts = {}) {
+  const body = denialReasonToBody(reason);
+  body.error = {
+    code: "operator_verification_required",
+    message: opts.message ?? "Identity verification is required."
+  };
+  if (opts.agentInstructions !== void 0) {
+    body.agent_instructions = opts.agentInstructions;
+  }
+  if (opts.extra) {
+    for (const [k, v] of Object.entries(opts.extra)) body[k] = v;
+  }
+  return body;
+}
 function denialReasonToBody(reason) {
   const message = reason.message ?? DEFAULT_MESSAGES[reason.code];
   const body = { error: { code: reason.code, message } };
@@ -21206,7 +21221,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"2.1.0"}`;
+  const defaultUa = `@agent-score/commerce@${"2.1.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();
@@ -21664,9 +21679,140 @@ var A2A_DEFAULT_TRANSPORT = DEFAULT_TRANSPORT;
 init_ucp();
 init_ucp_jwks();
 
-// src/checkout.ts
+// src/errors.ts
+var CheckoutValidationError = class extends Error {
+  code;
+  action;
+  status;
+  extra;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "CheckoutValidationError";
+    this.code = opts.code;
+    this.action = opts.action ?? "fix_request";
+    this.status = opts.status ?? 400;
+    this.extra = opts.extra;
+  }
+};
+
+// src/identity/policy.ts
+function buildGateFromPolicy(policy, base) {
+  if (!policy || !policy.enforcement) return null;
+  return {
+    apiKey: base.apiKey,
+    ...base.baseUrl !== void 0 && { baseUrl: base.baseUrl },
+    ...policy.requireKyc !== void 0 && { requireKyc: policy.requireKyc },
+    ...policy.requireSanctionsClear !== void 0 && {
+      requireSanctionsClear: policy.requireSanctionsClear
+    },
+    ...policy.minAge !== void 0 && { minAge: policy.minAge },
+    ...policy.allowedJurisdictions !== void 0 && {
+      allowedJurisdictions: [...policy.allowedJurisdictions]
+    }
+  };
+}
+async function runGateWithEnforcement(enforcement, runGate) {
+  if (!runGate || !enforcement) return { status: "anonymous" };
+  const outcome = await runGate();
+  if (outcome.ok) return { status: "verified" };
+  if (enforcement === "hard") {
+    return {
+      status: "denied",
+      denialStatus: outcome.status,
+      denialBody: outcome.body,
+      ...outcome.reason !== void 0 && { denialReason: outcome.reason }
+    };
+  }
+  return {
+    status: "unverified",
+    denialStatus: outcome.status,
+    denialBody: outcome.body,
+    ...outcome.reason !== void 0 && { denialReason: outcome.reason }
+  };
+}
+function shippingCountryAllowed(country, policy) {
+  if (!policy?.allowedShippingCountries || policy.allowedShippingCountries.length === 0) return true;
+  const allowed = new Set(policy.allowedShippingCountries.map((c) => c.toUpperCase()));
+  return allowed.has(country.toUpperCase());
+}
+function shippingStateAllowed(state, country, policy) {
+  if (!policy?.allowedShippingStates || policy.allowedShippingStates.length === 0) return true;
+  if (country.toUpperCase() !== "US") return true;
+  const allowed = new Set(policy.allowedShippingStates.map((s) => s.toUpperCase()));
+  return allowed.has(state.toUpperCase());
+}
+function validateShippingAgainstPolicy(opts) {
+  const code = opts.errorCode ?? "unsupported_jurisdiction";
+  const action = opts.errorAction ?? "change_shipping_state";
+  const item = opts.productName ? `'${opts.productName}'` : "this item";
+  if (!shippingCountryAllowed(opts.country, opts.policy)) {
+    throw new CheckoutValidationError({
+      code,
+      message: opts.countryMessage ?? `We can't ship ${item} to ${opts.country.toUpperCase() || "<unset>"}.`,
+      action
+    });
+  }
+  if (!shippingStateAllowed(opts.state, opts.country, opts.policy)) {
+    throw new CheckoutValidationError({
+      code,
+      message: opts.stateMessage ?? `We can't ship ${item} to ${opts.state.toUpperCase() || "<unset>"}.`,
+      action
+    });
+  }
+}
+
+// src/identity/tokens.ts
 var import_node_crypto = require("crypto");
 
+// src/payment/payment_header.ts
+function toTitleCase(name) {
+  return name.replace(/(^|-)([a-z])/g, (_m, sep, c) => sep + c.toUpperCase());
+}
+function readHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const rec = headers;
+  const v = rec[name] ?? rec[name.toLowerCase()] ?? rec[toTitleCase(name)];
+  if (typeof v === "string") return v;
+  if (Array.isArray(v) && typeof v[0] === "string") return v[0];
+  return null;
+}
+function asHeaders(input) {
+  return typeof input.headers === "object" && input instanceof Request ? input.headers : input;
+}
+function hasPaymentHeader(input) {
+  const headers = asHeaders(input);
+  return Boolean(
+    readHeader(headers, "payment-signature") || readHeader(headers, "x-payment") || readHeader(headers, "authorization")?.startsWith("Payment ")
+  );
+}
+function hasX402Header(input) {
+  const headers = asHeaders(input);
+  return Boolean(readHeader(headers, "payment-signature") || readHeader(headers, "x-payment"));
+}
+function hasMppxHeader(input) {
+  const headers = asHeaders(input);
+  return Boolean(readHeader(headers, "authorization")?.startsWith("Payment "));
+}
+
+// src/identity/tokens.ts
+function hashOperatorToken(plaintext) {
+  return (0, import_node_crypto.createHash)("sha256").update(plaintext, "utf8").digest("hex");
+}
+function extractOwnerScope(input) {
+  const headers = asHeaders(input);
+  const walletAddress = readHeader(headers, "x-wallet-address");
+  const operatorToken = readHeader(headers, "x-operator-token");
+  return {
+    ...walletAddress ? { walletAddress } : {},
+    ...operatorToken ? { operatorTokenHash: hashOperatorToken(operatorToken) } : {}
+  };
+}
+
+// src/checkout.ts
+var import_node_crypto2 = require("crypto");
+
 // src/_mppx_receipt.ts
 function extractMppxReceiptHeaderFromRaw(raw) {
   if (!raw || typeof raw !== "object" || !("withReceipt" in raw)) return null;
@@ -22073,6 +22219,12 @@ function buildValidationError({
   return body;
 }
 
+// src/payment/constants.ts
+var STRIPE_MIN_CHARGE_USD = 0.5;
+
+// src/payment/mppx_server.ts
+var import_node_async_hooks = require("async_hooks");
+
 // src/stripe-multichain/mppx_stripe.ts
 async function createMppxStripe({
   profileId,
@@ -22253,6 +22405,31 @@ function wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl) {
     }
   };
 }
+var mppxCapture = new import_node_async_hooks.AsyncLocalStorage();
+var consoleErrorPatched = false;
+function ensureConsoleErrorPatch() {
+  if (consoleErrorPatched) return;
+  consoleErrorPatched = true;
+  const original = console.error.bind(console);
+  console.error = function captureMppxInternal(...args) {
+    if (args[0] === "mppx: internal verification error" && args[1] !== void 0) {
+      const ctx = mppxCapture.getStore();
+      if (ctx) {
+        const e = args[1];
+        const reason = typeof e?.shortMessage === "string" ? e.shortMessage : typeof e?.message === "string" ? e.message : String(args[1]);
+        const details = e?.details;
+        ctx.reason = typeof details === "string" && details.length > 0 ? `${reason} (${details})` : reason;
+      }
+    }
+    return original(...args);
+  };
+}
+async function runWithMppxFailureCapture(fn) {
+  ensureConsoleErrorPatch();
+  const ctx = { reason: null };
+  const result = await mppxCapture.run(ctx, fn);
+  return { result, failureReason: ctx.reason };
+}
 
 // src/payment/x402_server.ts
 init_networks();
@@ -22394,40 +22571,28 @@ function lazyMppxServer(opts) {
   };
 }
 
-// src/checkout.ts
-init_network_kind();
-
-// src/payment/payment_header.ts
-function toTitleCase(name) {
-  return name.replace(/(^|-)([a-z])/g, (_m, sep, c) => sep + c.toUpperCase());
-}
-function readHeader(headers, name) {
-  if (typeof headers.get === "function") {
-    return headers.get(name);
+// src/payment/mppx_failures.ts
+var TEMPO_KEY_NOT_REGISTERED = {
+  code: "tempo_key_not_registered",
+  status: 401,
+  message: "Tempo rejected the transaction: signer wallet is not registered with Tempo's keychain.",
+  nextSteps: {
+    action: "register_tempo_key",
+    user_message: "Your wallet is not enrolled with Tempo. Run `tempo wallet login` to complete the one-time WebAuthn enrollment (or use `tempo request` directly), then retry. To skip enrollment, switch to the Base or Solana rail on this 402."
+  },
+  extra: { upstream_error: "KeyNotFound", chain: "tempo" }
+};
+function classifyMppxFailure(reason) {
+  if (!reason) return null;
+  const lower = reason.toLowerCase();
+  if (lower.includes("keychain validation failed") || lower.includes("keynotfound")) {
+    return TEMPO_KEY_NOT_REGISTERED;
   }
-  const rec = headers;
-  const v = rec[name] ?? rec[name.toLowerCase()] ?? rec[toTitleCase(name)];
-  if (typeof v === "string") return v;
-  if (Array.isArray(v) && typeof v[0] === "string") return v[0];
   return null;
 }
-function asHeaders(input) {
-  return typeof input.headers === "object" && input instanceof Request ? input.headers : input;
-}
-function hasPaymentHeader(input) {
-  const headers = asHeaders(input);
-  return Boolean(
-    readHeader(headers, "payment-signature") || readHeader(headers, "x-payment") || readHeader(headers, "authorization")?.startsWith("Payment ")
-  );
-}
-function hasX402Header(input) {
-  const headers = asHeaders(input);
-  return Boolean(readHeader(headers, "payment-signature") || readHeader(headers, "x-payment"));
-}
-function hasMppxHeader(input) {
-  const headers = asHeaders(input);
-  return Boolean(readHeader(headers, "authorization")?.startsWith("Payment "));
-}
+
+// src/checkout.ts
+init_network_kind();
 
 // src/payment/x402_settle.ts
 function classifyX402SettleResult(result) {
@@ -22750,20 +22915,6 @@ function getIdentityStatus(ctx) {
   if (decision === "allow") return "verified";
   return "unverified";
 }
-var CheckoutValidationError = class extends Error {
-  code;
-  action;
-  status;
-  extra;
-  constructor(opts) {
-    super(opts.message);
-    this.name = "CheckoutValidationError";
-    this.code = opts.code;
-    this.action = opts.action ?? "fix_request";
-    this.status = opts.status ?? 400;
-    this.extra = opts.extra;
-  }
-};
 function resolveIdentityMetadata(ctx) {
   const h = normalizeHeadersToLowercase(ctx.request.headers);
   const wallet = h["x-wallet-address"];
@@ -23100,7 +23251,14 @@ var Checkout = class {
       }
     }
     ctx.pricing = await this.computePricing(ctx);
-    await this.resolveRecipientsForCtx(ctx);
+    try {
+      await this.resolveRecipientsForCtx(ctx);
+    } catch (err) {
+      if (err instanceof Error && err.name === "CheckoutValidationError") {
+        return this.validationErrorResult(ctx, err);
+      }
+      throw err;
+    }
     const x402ServerOk = this.x402ServerAvailable() && this.x402BaseNetwork !== null;
     if (hasX402Header(request.headers) && x402ServerOk) {
       const zero = await this.handleZeroSettle(ctx, "x402-base");
@@ -23171,8 +23329,16 @@ var Checkout = class {
       ...gate.failOpen !== void 0 && { failOpen: gate.failOpen },
       ...gate.cacheSeconds !== void 0 && { cacheSeconds: gate.cacheSeconds },
       ...gate.chain !== void 0 && { chain: gate.chain },
-      ...gate.createSessionOnMissing !== void 0 && {
-        createSessionOnMissing: gate.createSessionOnMissing
+      // Auto-default `createSessionOnMissing` from gate config when the merchant
+      // didn't supply one. Matches python-commerce's behavior — every gated route
+      // gets the bootstrap session-mint UX out of the box. Merchants who need
+      // custom session context or onBeforeSession side effects (goods merchants
+      // pre-minting an order_id) supply their own config instead.
+      createSessionOnMissing: gate.createSessionOnMissing ?? {
+        apiKey: gate.apiKey,
+        ...gate.baseUrl !== void 0 && { baseUrl: gate.baseUrl },
+        ...gate.context !== void 0 && { context: gate.context },
+        ...gate.merchantName !== void 0 && { productName: gate.merchantName }
       },
       ...policyOverride ?? {}
     };
@@ -23269,7 +23435,7 @@ var Checkout = class {
     return await this.buildSuccess(ctx, outcome);
   }
   async mintRefId(request) {
-    if (this.mintReferenceId === void 0) return (0, import_node_crypto.randomUUID)();
+    if (this.mintReferenceId === void 0) return (0, import_node_crypto2.randomUUID)();
     const seedCtx = { request, referenceId: "", pricing: null, recipients: {}, state: {} };
     return await this.mintReferenceId(seedCtx);
   }
@@ -23372,7 +23538,9 @@ var Checkout = class {
     if (this.composeMppx === void 0) {
       throw new Error("Checkout.handleMppx: composeMppx hook not configured");
     }
-    const composed = await this.composeMppx(ctx);
+    const { result: composed, failureReason } = await runWithMppxFailureCapture(
+      async () => this.composeMppx(ctx)
+    );
     if (composed.status === 200) {
       const paymentReceiptHeader = composed.paymentReceiptHeader ?? extractMppxReceiptHeaderFromRaw(composed.raw);
       const directMethod = composed.raw?.receipt?.method;
@@ -23391,6 +23559,22 @@ var Checkout = class {
       };
       return await this.buildSuccess(ctx, outcome);
     }
+    const classified = classifyMppxFailure(failureReason);
+    if (classified !== null) {
+      return {
+        status: classified.status,
+        body: buildValidationError({
+          code: classified.code,
+          message: classified.message,
+          nextSteps: classified.nextSteps,
+          ...classified.extra && { extra: classified.extra }
+        }),
+        headers: { ...composed.headers ?? {} },
+        referenceId: ctx.referenceId,
+        settled: false,
+        settlePhase: "verify_failed"
+      };
+    }
     return {
       status: 400,
       body: buildValidationError({
@@ -23409,7 +23593,11 @@ var Checkout = class {
       throw new Error("Checkout.emit402: pricing not computed");
     }
     await this.resolveRecipientsForCtx(ctx);
-    const emitRails = applyRecipientOverrides(this.rails, ctx.recipients);
+    let emitRails = applyRecipientOverrides(this.rails, ctx.recipients);
+    if (ctx.pricing.amountUsd < STRIPE_MIN_CHARGE_USD && emitRails.stripe !== void 0) {
+      const { stripe: _stripe, ...rest } = emitRails;
+      emitRails = rest;
+    }
     const accepted = await buildAcceptedMethods({
       tempo: pickRail(emitRails, "tempo"),
       x402_base: pickRail(emitRails, "x402_base"),
@@ -23812,87 +24000,6 @@ Checkout.prototype.mountUcpRoutesFastify = function(app, opts) {
   app.options(jwksPath, preflight);
 };
 
-// src/identity/policy.ts
-function buildGateFromPolicy(policy, base) {
-  if (!policy || !policy.enforcement) return null;
-  return {
-    apiKey: base.apiKey,
-    ...base.baseUrl !== void 0 && { baseUrl: base.baseUrl },
-    ...policy.requireKyc !== void 0 && { requireKyc: policy.requireKyc },
-    ...policy.requireSanctionsClear !== void 0 && {
-      requireSanctionsClear: policy.requireSanctionsClear
-    },
-    ...policy.minAge !== void 0 && { minAge: policy.minAge },
-    ...policy.allowedJurisdictions !== void 0 && {
-      allowedJurisdictions: [...policy.allowedJurisdictions]
-    }
-  };
-}
-async function runGateWithEnforcement(enforcement, runGate) {
-  if (!runGate || !enforcement) return { status: "anonymous" };
-  const outcome = await runGate();
-  if (outcome.ok) return { status: "verified" };
-  if (enforcement === "hard") {
-    return {
-      status: "denied",
-      denialStatus: outcome.status,
-      denialBody: outcome.body,
-      ...outcome.reason !== void 0 && { denialReason: outcome.reason }
-    };
-  }
-  return {
-    status: "unverified",
-    denialStatus: outcome.status,
-    denialBody: outcome.body,
-    ...outcome.reason !== void 0 && { denialReason: outcome.reason }
-  };
-}
-function shippingCountryAllowed(country, policy) {
-  if (!policy?.allowedShippingCountries || policy.allowedShippingCountries.length === 0) return true;
-  const allowed = new Set(policy.allowedShippingCountries.map((c) => c.toUpperCase()));
-  return allowed.has(country.toUpperCase());
-}
-function shippingStateAllowed(state, country, policy) {
-  if (!policy?.allowedShippingStates || policy.allowedShippingStates.length === 0) return true;
-  if (country.toUpperCase() !== "US") return true;
-  const allowed = new Set(policy.allowedShippingStates.map((s) => s.toUpperCase()));
-  return allowed.has(state.toUpperCase());
-}
-function validateShippingAgainstPolicy(opts) {
-  const code = opts.errorCode ?? "unsupported_jurisdiction";
-  const action = opts.errorAction ?? "change_shipping_state";
-  const item = opts.productName ? `'${opts.productName}'` : "this item";
-  if (!shippingCountryAllowed(opts.country, opts.policy)) {
-    throw new CheckoutValidationError({
-      code,
-      message: opts.countryMessage ?? `We can't ship ${item} to ${opts.country.toUpperCase() || "<unset>"}.`,
-      action
-    });
-  }
-  if (!shippingStateAllowed(opts.state, opts.country, opts.policy)) {
-    throw new CheckoutValidationError({
-      code,
-      message: opts.stateMessage ?? `We can't ship ${item} to ${opts.state.toUpperCase() || "<unset>"}.`,
-      action
-    });
-  }
-}
-
-// src/identity/tokens.ts
-var import_node_crypto2 = require("crypto");
-function hashOperatorToken(plaintext) {
-  return (0, import_node_crypto2.createHash)("sha256").update(plaintext, "utf8").digest("hex");
-}
-function extractOwnerScope(input) {
-  const headers = asHeaders(input);
-  const walletAddress = readHeader(headers, "x-wallet-address");
-  const operatorToken = readHeader(headers, "x-operator-token");
-  return {
-    ...walletAddress ? { walletAddress } : {},
-    ...operatorToken ? { operatorTokenHash: hashOperatorToken(operatorToken) } : {}
-  };
-}
-
 // src/payment/index.ts
 init_directive();
 init_networks();
@@ -23969,6 +24076,7 @@ async function loadSolanaFeePayer(opts) {
 
 // src/payment/compose_rails.ts
 init_usdc();
+var warnedStripeBelowMinimum = false;
 function buildMppxComposeRails(opts) {
   const rails2 = [];
   if (opts.tempoRecipient) {
@@ -23990,7 +24098,17 @@ function buildMppxComposeRails(opts) {
     }]);
   }
   if (opts.includeStripe !== false) {
-    rails2.push(["stripe/charge", { amount: opts.amountUsd, currency: "usd", decimals: 2 }]);
+    const amountUsdNumeric = Number(opts.amountUsd);
+    if (Number.isFinite(amountUsdNumeric) && amountUsdNumeric < STRIPE_MIN_CHARGE_USD) {
+      if (!warnedStripeBelowMinimum) {
+        warnedStripeBelowMinimum = true;
+        console.warn(
+          `[buildMppxComposeRails] Dropping stripe/charge rail: amountUsd=${opts.amountUsd} is below Stripe's $${STRIPE_MIN_CHARGE_USD.toFixed(2)} USD minimum. Stripe's fixed ~$0.30 fee makes sub-50-cent charges unprofitable (and many accounts reject PI creation with amount_too_small below this floor). Pass includeStripe: false to suppress this warning.`
+        );
+      }
+    } else {
+      rails2.push(["stripe/charge", { amount: opts.amountUsd, currency: "usd", decimals: 2 }]);
+    }
   }
   return rails2;
 }
@@ -24181,10 +24299,11 @@ function computeFirstCheckout(opts) {
     const tempoRecipient = recipients.tempo;
     const x402BaseRecipient = recipients.x402_base;
     const solanaRecipient = recipients.solana_mpp;
+    const includeStripeInDiscovery = opts.rails.stripe !== void 0 && Number(totalUsd) >= STRIPE_MIN_CHARGE_USD;
     const accepted = await buildAcceptedMethods({
       ...tempoRecipient && opts.rails.tempo && { tempo: { ...opts.rails.tempo, recipient: tempoRecipient } },
       ...solanaRecipient && opts.rails.solana_mpp && { solana_mpp: { ...opts.rails.solana_mpp, recipient: solanaRecipient } },
-      ...opts.rails.stripe && { stripe: opts.rails.stripe }
+      ...includeStripeInDiscovery && { stripe: opts.rails.stripe }
     });
     if (x402BaseRecipient && opts.rails.x402_base) {
       try {
@@ -24608,6 +24727,7 @@ function defaultReadOnlyOnDenied(reason) {
   buildMppxComposeRails,
   buildSignerMismatchBody,
   buildUCPProfile,
+  buildVerificationRequiredBody,
   computeFirstCheckout,
   createDefaultOnDenied,
   createQuoteCache,