@agent-score/commerce 1.0.2 → 1.1.0

package/dist/core.mjs

@@ -1,3 +1,13 @@
+// src/core.ts
+import {
+  AgentScore,
+  InvalidCredentialError,
+  PaymentRequiredError,
+  QuotaExceededError,
+  TimeoutError as SdkTimeoutError,
+  TokenExpiredError
+} from "@agent-score/sdk";
+
 // src/_denial.ts
 var FIXABLE_DENIAL_REASONS = /* @__PURE__ */ new Set([
   "kyc_required",
@@ -9,6 +19,61 @@ function isFixableDenial(reasons) {
   return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));
 }
 
+// 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 account does not have the assess endpoint enabled, 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) so they can resolve the configuration on their side."
+  ],
+  user_message: "This merchant's identity gate is misconfigured. 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 API_ERROR_INSTRUCTIONS = JSON.stringify({
+  action: "retry_with_backoff",
+  steps: [
+    "Verification is temporarily unavailable. Retry the request after 5\u201330 seconds with exponential backoff.",
+    "This is NOT a compliance denial \u2014 the user does not need to re-verify their identity. Send the same identity headers (X-Wallet-Address or X-Operator-Token) on retry.",
+    "If the request continues to fail after 3+ retries (~60 seconds total), surface the error to the user with the merchant's support contact."
+  ],
+  user_message: "Verification is temporarily unavailable. Please try again in a moment \u2014 this is a transient issue, not a problem with your account."
+});
+var QUOTA_EXCEEDED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "AgentScore identity verification is unavailable for this merchant. This is a merchant-side issue and is NOT recoverable via retry.",
+    "Do not retry: the same 503 will be returned until the merchant resolves the issue on their side.",
+    "Surface to the user with the merchant's support contact. The merchant (not the agent) needs to act."
+  ],
+  user_message: "This merchant's identity verification is temporarily unavailable. Try again later, or contact the merchant directly."
+});
+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."
+});
+
 // src/address.ts
 var SOLANA_BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 var isSolanaAddress = (address) => SOLANA_BASE58_RE.test(address) && !address.startsWith("0x");
@@ -137,9 +202,23 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"1.0.2"}`;
+  const defaultUa = `@agent-score/commerce@${"1.1.0"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
-  const API_TIMEOUT_MS = 1e4;
+  const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
+  const sessionSdkCache = /* @__PURE__ */ new Map();
+  function getSessionSdk(sessionApiKey, sessionBaseUrl) {
+    const key = `${sessionApiKey}|${sessionBaseUrl ?? ""}`;
+    let s = sessionSdkCache.get(key);
+    if (!s) {
+      s = new AgentScore({
+        apiKey: sessionApiKey,
+        baseUrl: sessionBaseUrl ?? baseUrl,
+        userAgent: userAgentHeader
+      });
+      sessionSdkCache.set(key, s);
+    }
+    return s;
+  }
   const cache = new TTLCache(cacheSeconds * 1e3);
   async function tryMintSessionDenial(ctx) {
     if (!createSessionOnMissing) return void 0;
@@ -156,20 +235,11 @@ function createAgentScoreCore(options) {
           console.warn("[gate] createSessionOnMissing.getSessionOptions hook failed:", err instanceof Error ? err.message : err);
         }
       }
-      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? "https://api.agentscore.sh");
-      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": createSessionOnMissing.apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(sessionBody),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      const sessionSdk = getSessionSdk(createSessionOnMissing.apiKey, createSessionOnMissing.baseUrl);
+      const data = await sessionSdk.createSession({
+        ...sessionBody.context !== void 0 ? { context: sessionBody.context } : {},
+        ...sessionBody.product_name !== void 0 ? { product_name: sessionBody.product_name } : {}
       });
-      if (!sessionRes.ok) return void 0;
-      const data = await sessionRes.json();
       if (typeof data.session_id !== "string" || typeof data.poll_secret !== "string" || typeof data.verify_url !== "string") {
         console.warn("[gate] /v1/sessions returned 200 without required fields \u2014 falling back to bare denial");
         return void 0;
@@ -233,7 +303,13 @@ function createAgentScoreCore(options) {
     const cached = cache.get(cacheKey);
     if (cached) {
       if (cached.allow) {
-        return { kind: "allow", data: cached.raw };
+        const cachedRaw = cached.raw;
+        const cachedQuota = cachedRaw?.quota;
+        return {
+          kind: "allow",
+          data: cachedRaw,
+          ...cachedQuota !== void 0 && { quota: cachedQuota }
+        };
       }
       if (isFixableDenial(cached.reasons)) {
         const sessionReason = await tryMintSessionDenial(ctx);
@@ -250,130 +326,119 @@ function createAgentScoreCore(options) {
         }
       };
     }
+    const policy = {};
+    if (requireKyc != null) policy.require_kyc = requireKyc;
+    if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
+    if (minAge != null) policy.min_age = minAge;
+    if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
+    if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
+    let data;
     try {
-      const body = {};
-      if (identity.address) body.address = identity.address;
-      if (identity.operatorToken) body.operator_token = identity.operatorToken;
-      if (gateChain) body.chain = gateChain;
-      const policy = {};
-      if (requireKyc != null) policy.require_kyc = requireKyc;
-      if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
-      if (minAge != null) policy.min_age = minAge;
-      if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
-      if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
-      if (Object.keys(policy).length > 0) body.policy = policy;
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (response.status === 402) {
+      const opts = {
+        chain: gateChain,
+        ...Object.keys(policy).length > 0 ? { policy } : {}
+      };
+      const result = identity.address ? await sdk.assess(identity.address, { ...opts, operatorToken: identity.operatorToken }) : await sdk.assess(null, { ...opts, operatorToken: identity.operatorToken });
+      data = result;
+    } catch (err) {
+      if (err instanceof PaymentRequiredError) {
         if (failOpen) return { kind: "allow" };
         return { kind: "deny", reason: { code: "payment_required" } };
       }
-      if (response.status === 401) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code === "token_expired") {
-            return {
-              kind: "deny",
-              reason: {
-                code,
-                data: errData,
-                ...typeof errData.verify_url === "string" ? { verify_url: errData.verify_url } : {},
-                ...typeof errData.session_id === "string" ? { session_id: errData.session_id } : {},
-                ...typeof errData.poll_secret === "string" ? { poll_secret: errData.poll_secret } : {},
-                ...typeof errData.poll_url === "string" ? { poll_url: errData.poll_url } : {},
-                ...errData.next_steps ? { agent_instructions: JSON.stringify(errData.next_steps) } : {},
-                ...errData.agent_memory ? { agent_memory: errData.agent_memory } : {}
-              }
-            };
-          }
-          if (code === "invalid_credential") {
-            return {
-              kind: "deny",
-              reason: {
-                code: "invalid_credential",
-                agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
-                agent_memory: agentMemoryHint
-              }
-            };
-          }
-          if (code) {
-            console.warn(`[gate] /v1/assess returned 401 ${code} \u2014 no specific handler, surfacing as api_error.`);
+      if (err instanceof TokenExpiredError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "token_expired",
+            data: err.details,
+            ...err.verifyUrl ? { verify_url: err.verifyUrl } : {},
+            ...err.sessionId ? { session_id: err.sessionId } : {},
+            ...err.pollSecret ? { poll_secret: err.pollSecret } : {},
+            ...err.pollUrl ? { poll_url: err.pollUrl } : {},
+            ...err.nextSteps ? { agent_instructions: JSON.stringify(err.nextSteps) } : {},
+            ...err.agentMemory ? { agent_memory: err.agentMemory } : {}
           }
-        } catch (err) {
-          console.warn("[gate] /v1/assess 401 body parse failed:", err instanceof Error ? err.message : err);
-        }
+        };
       }
-      if (response.status >= 400 && response.status < 500 && response.status !== 402) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code && code !== "token_expired" && code !== "invalid_credential") {
-            console.warn(
-              `[gate] /v1/assess returned ${response.status} ${code} \u2014 surfacing as api_error. Validate input shape before invoking the gate to avoid this.`
-            );
+      if (err instanceof InvalidCredentialError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "invalid_credential",
+            agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
+            agent_memory: agentMemoryHint
           }
-        } catch {
-        }
+        };
       }
-      if (!response.ok) {
-        throw new Error(`AgentScore API returned ${response.status}`);
+      if (err instanceof QuotaExceededError) {
+        console.warn("[gate] /v1/assess returned 429 quota_exceeded");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
       }
-      const data = await response.json();
-      const decision = data.decision;
-      const decisionReasons = data.decision_reasons ?? [];
-      const allow = decision === "allow" || decision == null;
-      cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
-      if (allow) {
-        return { kind: "allow", data };
+      if (err instanceof SdkTimeoutError) {
+        console.warn("[gate] /v1/assess timed out:", err.message);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
       }
-      if (isFixableDenial(decisionReasons)) {
-        const sessionReason = await tryMintSessionDenial(ctx);
-        if (sessionReason) return { kind: "deny", reason: sessionReason };
+      const status = err?.status;
+      const errName = err instanceof Error ? err.name : "";
+      if (status === 429) {
+        console.warn("[gate] /v1/assess returned 429 (untyped \u2014 defensive)");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
+      }
+      if (errName === "TimeoutError" || errName === "AbortError") {
+        console.warn("[gate] /v1/assess timed out (by Error.name):", err instanceof Error ? err.message : err);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
       }
+      const errCode = err?.code;
+      const msg = err instanceof Error ? err.message : String(err);
+      const detail = errCode ? `${errCode}: ${msg}` : msg;
+      console.warn(`[gate] /v1/assess call failed \u2014 surfacing as api_error: ${detail}`);
+      if (failOpen) return { kind: "allow", degraded: true, infraReason: "api_error" };
+      return { kind: "deny", reason: { code: "api_error" } };
+    }
+    const decision = data.decision;
+    const decisionReasons = data.decision_reasons ?? [];
+    const allow = decision === "allow" || decision == null;
+    cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
+    if (allow) {
+      const quota = data.quota;
       return {
-        kind: "deny",
-        reason: {
-          code: "wallet_not_trusted",
-          decision: decision ?? void 0,
-          reasons: decisionReasons,
-          verify_url: data.verify_url,
-          data
-        }
+        kind: "allow",
+        data,
+        ...quota !== void 0 && { quota }
       };
-    } catch (err) {
-      console.warn("[gate] /v1/assess call failed \u2014 surfacing as api_error:", err instanceof Error ? err.message : err);
-      if (failOpen) return { kind: "allow" };
-      return { kind: "deny", reason: { code: "api_error" } };
     }
+    if (isFixableDenial(decisionReasons)) {
+      const sessionReason = await tryMintSessionDenial(ctx);
+      if (sessionReason) return { kind: "deny", reason: sessionReason };
+    }
+    return {
+      kind: "deny",
+      reason: {
+        code: "wallet_not_trusted",
+        decision: decision ?? void 0,
+        reasons: decisionReasons,
+        verify_url: data.verify_url,
+        data
+      }
+    };
   }
   async function captureWallet(options2) {
     try {
-      const body = {
-        operator_token: options2.operatorToken,
-        wallet_address: options2.walletAddress,
-        network: options2.network
-      };
-      if (options2.idempotencyKey) body.idempotency_key = options2.idempotencyKey;
-      await fetch(`${baseUrl}/v1/credentials/wallets`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      await sdk.associateWallet({
+        operatorToken: options2.operatorToken,
+        walletAddress: options2.walletAddress,
+        network: options2.network,
+        ...options2.idempotencyKey ? { idempotencyKey: options2.idempotencyKey } : {}
       });
     } catch (err) {
       console.warn("[agentscore-commerce] captureWallet failed:", err instanceof Error ? err.message : err);
@@ -398,19 +463,7 @@ function createAgentScoreCore(options) {
       return { ok: true, ...extractFromCached(resolveCached.raw) };
     }
     try {
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ address: walletAddress }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (!response.ok) return { ok: false };
-      const data = await response.json();
+      const data = await sdk.assess(walletAddress);
       cache.set(`resolve:${wallet}`, { allow: true, raw: data });
       return { ok: true, ...extractFromCached(data) };
     } catch (err) {
@@ -419,28 +472,37 @@ function createAgentScoreCore(options) {
     }
   }
   function reportSignerEvent(kind) {
-    try {
-      const pending = fetch(`${baseUrl}/v1/telemetry/signer-match`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ kind }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (pending && typeof pending.catch === "function") {
-        pending.catch((err) => {
-          console.warn("[agentscore-commerce] signer-match telemetry failed:", err instanceof Error ? err.message : err);
-        });
-      }
-    } catch {
+    void sdk.telemetrySignerMatch({ kind });
+  }
+  function projectSignerMatch(sm, claimedNorm, signerNorm) {
+    const kind = sm.kind;
+    if (kind === "pass") {
+      return {
+        kind: "pass",
+        claimedOperator: sm.claimed_operator ?? null,
+        signerOperator: sm.signer_operator ?? null
+      };
+    }
+    if (kind === "wallet_auth_requires_wallet_signing") {
+      return {
+        kind: "wallet_auth_requires_wallet_signing",
+        claimedWallet: sm.claimed_wallet ?? claimedNorm,
+        agentInstructions: sm.agent_instructions ?? WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS
+      };
     }
+    const linked = sm.linked_wallets;
+    return {
+      kind: "wallet_signer_mismatch",
+      claimedOperator: sm.claimed_operator ?? null,
+      actualSignerOperator: sm.signer_operator ?? null,
+      expectedSigner: sm.expected_signer ?? claimedNorm,
+      actualSigner: sm.actual_signer ?? signerNorm,
+      linkedWallets: Array.isArray(linked) ? linked.filter((w) => typeof w === "string") : [],
+      agentInstructions: sm.agent_instructions ?? WALLET_SIGNER_MISMATCH_INSTRUCTIONS
+    };
   }
   async function verifyWalletSignerMatch(options2) {
-    const { claimedWallet, signer } = options2;
+    const { claimedWallet, signer, network } = options2;
     if (!signer) {
       reportSignerEvent("wallet_auth_requires_wallet_signing");
       return {
@@ -455,6 +517,35 @@ function createAgentScoreCore(options) {
       reportSignerEvent("pass");
       return { kind: "pass", claimedOperator: null, signerOperator: null };
     }
+    const cachedEntry = cache.get(claimedNorm);
+    const cachedMatch = cachedEntry?.signerMatchBySigner?.get(signerNorm);
+    if (cachedMatch) {
+      return projectSignerMatch(cachedMatch, claimedNorm, signerNorm);
+    }
+    const inferredNetwork = network ?? (signerNorm.startsWith("0x") ? "evm" : "solana");
+    let assessResponse;
+    try {
+      assessResponse = await sdk.assess(claimedNorm, {
+        resolveSigner: { address: signerNorm, network: inferredNetwork }
+      });
+    } catch (err) {
+      console.warn("[gate] verifyWalletSignerMatch assess failed:", err instanceof Error ? err.message : err);
+      reportSignerEvent("api_error");
+      return { kind: "api_error", claimedWallet: claimedNorm };
+    }
+    const signerMatch = assessResponse.signer_match;
+    if (signerMatch && typeof signerMatch === "object") {
+      if (cachedEntry) {
+        const map = cachedEntry.signerMatchBySigner ?? /* @__PURE__ */ new Map();
+        map.set(signerNorm, signerMatch);
+        cachedEntry.signerMatchBySigner = map;
+      } else {
+        const entry = { allow: true, raw: assessResponse };
+        entry.signerMatchBySigner = /* @__PURE__ */ new Map([[signerNorm, signerMatch]]);
+        cache.set(claimedNorm, entry);
+      }
+      return projectSignerMatch(signerMatch, claimedNorm, signerNorm);
+    }
     const [claimedResolve, signerResolve] = await Promise.all([
       resolveWalletToOperator(claimedNorm),
       resolveWalletToOperator(signerNorm)
@@ -476,8 +567,6 @@ function createAgentScoreCore(options) {
       actualSignerOperator: signerOperator,
       expectedSigner: claimedNorm,
       actualSigner: signerNorm,
-      // Populated from /v1/assess.linked_wallets on the claimed wallet — the full set of
-      // wallets the agent CAN sign with to satisfy the claim (same-operator rule).
       linkedWallets: claimedResolve.linkedWallets,
       agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS
     };