@agent-score/commerce 1.0.0 → 1.0.1

package/dist/index.mjs

@@ -1,3 +1,82 @@
+// src/_denial.ts
+var FIXABLE_DENIAL_REASONS = /* @__PURE__ */ new Set([
+  "kyc_required",
+  "kyc_pending",
+  "kyc_failed"
+]);
+function isFixableDenial(reasons) {
+  if (!reasons || reasons.length === 0) return false;
+  return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));
+}
+function denialReasonStatus(reason) {
+  if (reason.code === "token_expired" || reason.code === "invalid_credential") return 401;
+  if (reason.code === "api_error") return 503;
+  return 403;
+}
+function buildSignerMismatchBody(input) {
+  const { result } = input;
+  if (result.kind === "pass" || result.kind === "api_error") return null;
+  const learnMoreUrl = input.learnMoreUrl ?? "https://docs.agentscore.sh/guides/agent-identity";
+  if (result.kind === "wallet_signer_mismatch") {
+    const linkedWallets = result.linkedWallets ?? [];
+    const userMessage = input.userMessage ?? (linkedWallets.length > 0 ? `Sign the payment with one of the wallets linked to this operator: ${linkedWallets.join(", ")}. Then retry.` : "Sign the payment with the same wallet you claimed via X-Wallet-Address, or switch to X-Operator-Token for rail-independent identity.");
+    return {
+      error: {
+        code: "wallet_signer_mismatch",
+        message: "Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator."
+      },
+      claimed_operator: result.claimedOperator,
+      actual_signer_operator: result.actualSignerOperator ?? null,
+      expected_signer: result.expectedSigner,
+      actual_signer: result.actualSigner,
+      linked_wallets: linkedWallets,
+      next_steps: {
+        action: "regenerate_payment_from_linked_wallet",
+        user_message: userMessage,
+        learn_more_url: learnMoreUrl
+      }
+    };
+  }
+  return {
+    error: {
+      code: "wallet_auth_requires_wallet_signing",
+      message: "Wallet-auth requires a payment rail that carries a wallet signature (Tempo MPP, x402). Stripe SPT and card rails have no wallet signer; switch to X-Operator-Token to use those."
+    },
+    next_steps: {
+      action: "switch_to_operator_token",
+      user_message: input.userMessage ?? "Drop the X-Wallet-Address header and retry with X-Operator-Token (works on every payment rail).",
+      learn_more_url: learnMoreUrl
+    }
+  };
+}
+function buildContactSupportNextSteps(supportEmail, message) {
+  return {
+    action: "contact_support",
+    support_email: supportEmail,
+    user_message: message ?? `If you believe this denial is in error, contact support at ${supportEmail} with your order details.`
+  };
+}
+function verificationAgentInstructions(input = {}) {
+  const baseSteps = [
+    "Present the verify_url directly to the user \u2014 it is a complete, ready-to-open URL with the session token already embedded (e.g. https://agentscore.sh/verify?session=sess_...). Do NOT modify or construct the URL yourself.",
+    `Immediately begin polling poll_url every ${input.pollIntervalSeconds ?? 5} seconds with header X-Poll-Secret set to poll_secret. The user will complete verification in their browser while you poll in the background.`,
+    "The user visits the URL, signs in, completes identity verification (photo ID + selfie via Stripe Identity), and closes the tab. They do NOT need to copy or paste anything back to you.",
+    'When your poll returns status "verified", extract operator_token from the response. This is a one-time value \u2014 save it immediately. Subsequent polls return status "consumed" without the token.',
+    input.retryStep ?? "Retry the original merchant request with header X-Operator-Token set to the operator_token value."
+  ];
+  return {
+    action: "poll_for_credential",
+    user_action: input.userAction ?? "The user must visit verify_url to complete identity verification before this request can proceed",
+    steps: input.extraSteps ? [...baseSteps, ...input.extraSteps] : baseSteps,
+    poll_interval_seconds: input.pollIntervalSeconds ?? 5,
+    poll_secret_header: "X-Poll-Secret",
+    retry_token_header: "X-Operator-Token",
+    timeout_seconds: input.timeoutSeconds ?? 3600,
+    ...input.orderTtl ? { order_ttl: input.orderTtl } : {},
+    ...input.extra ?? {}
+  };
+}
+
 // src/core.ts
 var CANONICAL_AGENTSCORE_API = "https://api.agentscore.sh";
 var WALLET_SIGNER_MISMATCH_INSTRUCTIONS = JSON.stringify({
@@ -100,87 +179,48 @@ function readX402PaymentHeader(request) {
   return request.headers.get("payment-signature") ?? request.headers.get("x-payment") ?? void 0;
 }
 
-// src/_denial.ts
-var FIXABLE_DENIAL_REASONS = /* @__PURE__ */ new Set([
-  "kyc_required",
-  "kyc_pending",
-  "kyc_failed",
-  "jurisdiction_restricted"
-]);
-function isFixableDenial(reasons) {
-  if (!reasons || reasons.length === 0) return true;
-  return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));
-}
-function denialReasonStatus(reason) {
-  if (reason.code === "token_expired" || reason.code === "invalid_credential") return 401;
-  if (reason.code === "api_error") return 503;
-  return 403;
-}
-function buildSignerMismatchBody(input) {
-  const { result } = input;
-  if (result.kind === "pass" || result.kind === "api_error") return null;
-  const learnMoreUrl = input.learnMoreUrl ?? "https://docs.agentscore.sh/guides/agent-identity";
-  if (result.kind === "wallet_signer_mismatch") {
-    const linkedWallets = result.linkedWallets ?? [];
-    const userMessage = input.userMessage ?? (linkedWallets.length > 0 ? `Sign the payment with one of the wallets linked to this operator: ${linkedWallets.join(", ")}. Then retry.` : "Sign the payment with the same wallet you claimed via X-Wallet-Address, or switch to X-Operator-Token for rail-independent identity.");
-    return {
-      error: {
-        code: "wallet_signer_mismatch",
-        message: "Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator."
-      },
-      claimed_operator: result.claimedOperator,
-      actual_signer_operator: result.actualSignerOperator ?? null,
-      expected_signer: result.expectedSigner,
-      actual_signer: result.actualSigner,
-      linked_wallets: linkedWallets,
-      next_steps: {
-        action: "regenerate_payment_from_linked_wallet",
-        user_message: userMessage,
-        learn_more_url: learnMoreUrl
-      }
-    };
-  }
-  return {
-    error: {
-      code: "wallet_auth_requires_wallet_signing",
-      message: "Wallet-auth requires a payment rail that carries a wallet signature (Tempo MPP, x402). Stripe SPT and card rails have no wallet signer; switch to X-Operator-Token to use those."
-    },
-    next_steps: {
-      action: "switch_to_operator_token",
-      user_message: input.userMessage ?? "Drop the X-Wallet-Address header and retry with X-Operator-Token (works on every payment rail).",
-      learn_more_url: learnMoreUrl
-    }
-  };
-}
-function buildContactSupportNextSteps(supportEmail, message) {
-  return {
-    action: "contact_support",
-    support_email: supportEmail,
-    user_message: message ?? `If you believe this denial is in error, contact support at ${supportEmail} with your order details.`
-  };
-}
-function verificationAgentInstructions(input = {}) {
-  const baseSteps = [
-    "Present the verify_url directly to the user \u2014 it is a complete, ready-to-open URL with the session token already embedded (e.g. https://agentscore.sh/verify?session=sess_...). Do NOT modify or construct the URL yourself.",
-    `Immediately begin polling poll_url every ${input.pollIntervalSeconds ?? 5} seconds with header X-Poll-Secret set to poll_secret. The user will complete verification in their browser while you poll in the background.`,
-    "The user visits the URL, signs in, completes identity verification (photo ID + selfie via Stripe Identity), and closes the tab. They do NOT need to copy or paste anything back to you.",
-    'When your poll returns status "verified", extract operator_token from the response. This is a one-time value \u2014 save it immediately. Subsequent polls return status "consumed" without the token.',
-    input.retryStep ?? "Retry the original merchant request with header X-Operator-Token set to the operator_token value."
-  ];
-  return {
-    action: "poll_for_credential",
-    user_action: input.userAction ?? "The user must visit verify_url to complete identity verification before this request can proceed",
-    steps: input.extraSteps ? [...baseSteps, ...input.extraSteps] : baseSteps,
-    poll_interval_seconds: input.pollIntervalSeconds ?? 5,
-    poll_secret_header: "X-Poll-Secret",
-    retry_token_header: "X-Operator-Token",
-    timeout_seconds: input.timeoutSeconds ?? 3600,
-    ...input.orderTtl ? { order_ttl: input.orderTtl } : {},
-    ...input.extra ?? {}
-  };
-}
-
 // src/_response.ts
+var WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_support",
+  steps: [
+    "The wallet's operator failed an UNFIXABLE compliance check (sanctions, age, or jurisdiction). `reasons` lists which: `sanctions_flagged` / `age_insufficient` / `jurisdiction_restricted`. KYC re-verification won't change the outcome \u2014 the policy denial is structural.",
+    "Surface the denial to the user with the merchant's support contact. Do not retry the same merchant request; do not hand the user a verify_url (verification won't fix this code path).",
+    "Fixable compliance reasons (`kyc_required`, `kyc_pending`, `kyc_failed`) do NOT land on this code \u2014 the gate auto-mints a verification session for those and returns `identity_verification_required` with poll endpoints, same shape as `missing_identity`. `jurisdiction_restricted` IS in the unfixable bucket because the API only emits it after KYC is verified (the user's KYC'd country is in the blocked list \u2014 re-doing KYC won't change the country)."
+  ],
+  user_message: "This purchase is denied by the merchant's compliance policy and cannot be resolved by re-verifying. Contact the merchant's support if you believe this is in error."
+});
+var PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "The merchant's AgentScore tier does not include the assess feature, so agent identity cannot be evaluated. This is a merchant-side configuration gap \u2014 there is no agent-side recovery.",
+    "Contact the merchant (their support channel \u2014 typically listed in /llms.txt or the OpenAPI servers metadata) and request they upgrade their AgentScore plan."
+  ],
+  user_message: "This merchant's identity gate is misconfigured (AgentScore tier doesn't support assess). Contact the merchant \u2014 there's nothing to fix on the agent side."
+});
+var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "Share verify_url with the user \u2014 they complete identity verification on AgentScore.",
+    "If session_id + poll_secret are present in the body, poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <opc_...>`."
+  ],
+  user_message: "Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry."
+});
+var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "The operator token is expired or revoked. AgentScore auto-mints a fresh verification session \u2014 complete it to receive a new opc_...",
+    "Share verify_url with the user, then poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a fresh one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <new_opc_...>`."
+  ],
+  user_message: "Operator token is expired or revoked. A new verification session has been minted \u2014 visit verify_url to refresh."
+});
+var DEFAULT_AGENT_INSTRUCTIONS = {
+  wallet_not_trusted: WALLET_NOT_TRUSTED_INSTRUCTIONS,
+  payment_required: PAYMENT_REQUIRED_INSTRUCTIONS,
+  identity_verification_required: IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS,
+  token_expired: TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS
+};
 var DEFAULT_MESSAGES = {
   missing_identity: "No identity provided. Send X-Wallet-Address (wallet) or X-Operator-Token (credential).",
   identity_verification_required: "Identity verification is required to access this resource. Visit verify_url to complete KYC.",
@@ -217,7 +257,8 @@ function denialReasonToBody(reason) {
   if (reason.session_id) body.session_id = reason.session_id;
   if (reason.poll_secret) body.poll_secret = reason.poll_secret;
   if (reason.poll_url) body.poll_url = reason.poll_url;
-  if (reason.agent_instructions) body.agent_instructions = reason.agent_instructions;
+  const instructions = reason.agent_instructions ?? DEFAULT_AGENT_INSTRUCTIONS[reason.code];
+  if (instructions) body.agent_instructions = instructions;
   if (reason.agent_memory) body.agent_memory = reason.agent_memory;
   if (reason.claimed_operator) body.claimed_operator = reason.claimed_operator;
   if (reason.code === "wallet_signer_mismatch") body.actual_signer_operator = reason.actual_signer_operator ?? null;