@agent-score/commerce 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentScore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# @agent-score/commerce
+
+[![npm version](https://img.shields.io/npm/v/@agent-score/commerce.svg)](https://www.npmjs.com/package/@agent-score/commerce)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The full merchant-side SDK for [AgentScore](https://agentscore.sh) — agent commerce in one install. Ships identity gating, payment rail helpers, 402 challenge builders, MPP discovery, and Stripe multichain support. Built and maintained by AgentScore; works with any 402/MPP merchant in the ecosystem, AgentScore-gated or not.
+
+## Install
+
+```bash
+npm install @agent-score/commerce
+# or
+bun add @agent-score/commerce
+```
+
+Framework + protocol packages are optional peer deps — install only what you use:
+
+```bash
+npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your stack needs
+```
+
+## What's in the package
+
+| Subpath | What it provides |
+|---|---|
+| `/identity/{hono,express,fastify,nextjs,web}` | Trust gate middleware: KYC, sanctions, age, jurisdiction. `agentscoreGate(...)`, `getAgentScoreData(c)`, `captureWallet(...)`, `verifyWalletSignerMatch(...)`. Plus shared denial helpers: `denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`. |
+| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim — emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (returns `{address, network}`); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call). |
+| `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
+| `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions`, `buildPricingBlock`, `firstEncounterAgentMemory`, `OrderReceipt`; `respond402` — 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`, `getDepositAddress`, `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. |
+
+## Quick start
+
+### Identity gate (Hono)
+
+```typescript
+import { Hono } from "hono";
+import {
+  agentscoreGate,
+  captureWallet,
+  getAgentScoreData,
+  verifyWalletSignerMatch,
+} from "@agent-score/commerce/identity/hono";
+
+const app = new Hono();
+
+const _gate = agentscoreGate({
+  apiKey: process.env.AGENTSCORE_API_KEY!,
+  requireKyc: true,
+  minAge: 21,
+  allowedJurisdictions: ["US"],
+  createSessionOnMissing: { apiKey: process.env.AGENTSCORE_API_KEY!, context: "wine-purchase" },
+});
+
+// Run the gate CONDITIONALLY — only when a payment credential is already attached.
+// Anonymous discovery (no payment header) flows through to the handler so any spec-
+// compliant x402 wallet can read the 402 challenge with rails + pricing without first
+// proving identity. Identity is verified at settle time on the retry leg.
+app.use("/purchase", async (c, next) => {
+  const hasPaymentHeader = Boolean(
+    c.req.header("payment-signature") ||
+    c.req.header("x-payment") ||
+    c.req.header("authorization")?.startsWith("Payment "),
+  );
+  if (!hasPaymentHeader) { await next(); return; }
+  return _gate(c, next);
+});
+
+app.post("/purchase", async (c) => {
+  const data = getAgentScoreData(c);
+  // ... settle payment ...
+  // After payment, capture the signer wallet for cross-merchant attribution
+  await captureWallet(c, { walletAddress: signer, network: "evm", idempotencyKey: paymentIntentId });
+  return c.json({ ok: true });
+});
+```
+
+### Payment helpers
+
+```typescript
+import {
+  buildPaymentDirective,
+  extractPaymentSigner,
+  networks,
+  paymentRequiredHeader,
+  wwwAuthenticateHeader,
+} from "@agent-score/commerce/payment";
+
+// Build paymentauth.org directives by symbolic rail name (decimals + currency from registry)
+const directives = [
+  buildPaymentDirective({ rail: "tempo-mainnet",       id: "chg_t", realm: "ex.com", recipient: TEMPO_ADDR, amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "x402-base-mainnet",   id: "chg_b", realm: "ex.com", recipient: BASE_ADDR,  amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "x402-solana-mainnet", id: "chg_s", realm: "ex.com", recipient: SOL_ADDR,   amountUsd: 0.01 }),
+];
+const wwwAuth = wwwAuthenticateHeader(directives);
+
+// Recover the on-chain signer from the inbound credential — returns {address, network}
+const signer = await extractPaymentSigner(req, req.headers.get("x-payment") ?? undefined);
+```
+
+### x402 + MPP server setup
+
+```typescript
+import { createX402Server, createMppxServer } from "@agent-score/commerce/payment";
+
+const x402 = await createX402Server({
+  facilitator: "coinbase",  // or "http", or pass a custom facilitator instance
+  rails: ["x402-base-mainnet", "x402-solana-mainnet", "x402-base-mainnet-upto"],
+});
+
+const mppx = await createMppxServer({
+  rails: {
+    tempo: { recipient: process.env.TEMPO_RECIPIENT! },
+    stripe: { profileId: process.env.STRIPE_PROFILE_ID!, secretKey: process.env.STRIPE_SECRET_KEY! },
+  },
+  secretKey: process.env.MPP_SECRET_KEY!,
+});
+```
+
+### 402 builders
+
+```typescript
+import {
+  build402Body,
+  buildAcceptedMethods,
+  buildAgentInstructions,
+  buildHowToPay,
+  buildIdentityMetadata,
+} from "@agent-score/commerce/challenge";
+
+const acceptedMethods = buildAcceptedMethods({
+  tempo: { recipient: TEMPO_ADDR },
+  x402_base: { recipient: BASE_ADDR },
+  x402_solana: { recipient: SOL_ADDR },
+  stripe: { profileId: STRIPE_PROFILE_ID },
+});
+
+const howToPay = buildHowToPay({
+  url: req.url,
+  retryBodyJson: JSON.stringify(body),
+  totalUsd: "10.00",
+  rails: { tempo: { recipient: TEMPO_ADDR }, x402_base: { recipient: BASE_ADDR } },
+});
+
+const responseBody = build402Body({
+  acceptedMethods,
+  agentInstructions: buildAgentInstructions({ howToPay }),
+  identityMetadata: buildIdentityMetadata({ mode: "wallet", wallet: claimedAddress }),
+  pricing: buildPricingBlock({ subtotalCents: 1000, taxCents: 80, shippingCents: 999, taxRate: 0.08, taxState: "CA" }),
+  amountUsd: "10.80",
+  retryBody: body,
+  // First-encounter merchants attach the cross-merchant agent_memory hint so agents persist the AgentScore pattern.
+  agentMemory: firstEncounterAgentMemory({ firstEncounter: !merchant.hasSeenOperator(opToken) }),
+});
+```
+
+`buildPricingBlock` handles cents → dollar-string conversion (with optional shipping). `firstEncounterAgentMemory` returns the canonical hint or `undefined` based on a per-merchant first-seen flag. `OrderReceipt` is a TS interface for the post-settlement 200 response shape.
+
+### Idempotency-key + multi-rail header bundle
+
+```typescript
+import { buildIdempotencyKey, buildPaymentHeaders } from "@agent-score/commerce/payment";
+
+// Stable per-payment key — Stripe PI id wins, falls back to pi-{orderId}-{amountCents}.
+const idempotencyKey = buildIdempotencyKey({ paymentIntentId, orderId, amountCents });
+
+// One-call WWW-Authenticate + PAYMENT-REQUIRED bundle from a single rails declaration.
+const headers = buildPaymentHeaders({
+  orderId,
+  realm: "agents.merchant.example",
+  rails: [
+    { rail: "tempo-mainnet", amountUsd: "10.00", recipient: TEMPO_ADDR },
+    { rail: "x402-base-mainnet", amountUsd: "10.00", recipient: BASE_ADDR },
+    { rail: "stripe", amountUsd: "10.00", networkId: STRIPE_PROFILE_ID },
+  ],
+  x402: { accepts: x402Accepts, version: 2 },
+});
+return new Response(JSON.stringify(responseBody), { status: 402, headers });
+```
+
+### Identity publishing (cross-vendor standards)
+
+```typescript
+import { buildA2AAgentCard, buildUCPProfile } from "@agent-score/commerce";
+
+// Google A2A v1.0 Signed Agent Card — publish at /.well-known/agent-card.json
+const card = buildA2AAgentCard({ name, url, capabilities, data: assess });
+
+// Google Universal Commerce Protocol — publish at /.well-known/ucp
+const profile = buildUCPProfile({ name, services, payment_handlers, signing_keys, data: assess });
+```
+
+ACP (Stripe + OpenAI Agentic Commerce Protocol) is a transactional checkout protocol with no identity-publishing surface — ACP merchants integrate via the existing `build402Body` + `buildPaymentHeaders` + Stripe SPT rail.
+
+### Stripe multichain (peer dep on `stripe`)
+
+```typescript
+import {
+  createMultichainPaymentIntent,
+  createPiCache,
+  getDepositAddress,
+  simulateCryptoDeposit,
+  simulateDepositIfTestMode,
+} from "@agent-score/commerce/stripe-multichain";
+
+const result = await createMultichainPaymentIntent({
+  stripe: stripeClient,
+  amount: 1000,
+  networks: ["tempo", "base", "solana"],
+  metadata: { order_id: orderId },
+  idempotencyKey: orderId,
+});
+const baseAddress = getDepositAddress(result, "base");
+const solanaAddress = getDepositAddress(result, "solana");
+
+// PI / deposit-address cache. Redis-backed when REDIS_URL is set, in-memory otherwise —
+// multi-task deployments need Redis so a deposit lands on whichever task settles it.
+const piCache = createPiCache({ redisUrl: process.env.REDIS_URL });
+for (const addr of Object.values(result.depositAddresses)) {
+  await piCache.cacheAddress(addr);
+  piCache.cachePaymentIntent(addr, result.paymentIntentId);
+}
+piCache.cacheNetworkAddresses(result.paymentIntentId, result.depositAddresses);
+
+// Testnet helper — gates on sk_test_ and looks up the PI for you. No-op on live keys.
+await simulateDepositIfTestMode({
+  getPaymentIntentId: piCache.getPaymentIntentId,
+  depositAddress: baseAddress!,
+  network: "base",
+  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
+});
+```
+
+### Drop-in 402 + settle (x402)
+
+```typescript
+import {
+  processX402Settle,
+  validateX402NetworkConfig,
+  verifyX402Request,
+} from "@agent-score/commerce/payment";
+import { respond402 } from "@agent-score/commerce/challenge";
+
+// Boot-time guard — raises if a configured network isn't supported.
+validateX402NetworkConfig({ baseNetwork: X402_BASE, svmNetwork: X402_SVM });
+
+app.post("/purchase", async (c) => {
+  // Path A — agent presented an x402 X-Payment header
+  if (c.req.header("payment-signature") || c.req.header("x-payment")) {
+    const verified = await verifyX402Request({
+      request: c.req.raw,
+      isCachedAddress: piCache.hasAddress,
+      acceptedNetworks: { base: X402_BASE, svm: X402_SVM },
+    });
+    if (!verified.ok) return c.json(verified.body, verified.status);
+
+    const settle = await processX402Settle({
+      x402Server,
+      payload: verified.payload,
+      resourceConfig: { scheme: "exact", network: verified.signedNetwork, price: `$${total}`, payTo: verified.signedPayTo, maxTimeoutSeconds: 300 },
+      resourceMeta: { url: c.req.url, mimeType: "application/json" },
+    });
+    if (!settle.success) return c.json({ error: { code: "payment_proof_invalid", phase: settle.phase } }, 400);
+
+    const headers: Record<string, string> = {};
+    if (settle.paymentResponseHeader) headers["payment-response"] = settle.paymentResponseHeader;
+    return c.json({ ok: true }, { headers });
+  }
+
+  // Path B — cold call (or Authorization: Payment for mppx). After mppx.compose() returns 402,
+  // respond402 PRESERVES mppx's WWW-Authenticate and ADDS x402's PAYMENT-REQUIRED.
+  return respond402({
+    mppxChallenge: mppxResult.challenge as Response,
+    body: { acceptedMethods, agentInstructions, pricing, amountUsd: total, retryBody: body },
+    x402: { x402Version: 2, accepts: x402Accepts, resource: { url: c.req.url, mimeType: "application/json" } },
+  });
+});
+```
+
+## Examples
+
+The [examples/](./examples) directory has 6 runnable single-file Hono apps covering common merchant scenarios — copy-paste templates, not frameworks. See [examples/README.md](./examples/README.md) for the full table.
+
+## Vendor profile examples
+
+| Vendor type | Subpaths used | Example install line |
+|---|---|---|
+| Wine merchant (full compliance + multi-rail) | `/identity/*`, `/payment`, `/discovery`, `/challenge`, `/stripe-multichain` | `npm install @agent-score/commerce stripe` |
+| API provider (per-call billing, no compliance) | `/payment`, `/discovery` | `npm install @agent-score/commerce` |
+| Tempo-only merchant | `/payment` | `npm install @agent-score/commerce mppx` |
+| Crypto-native, no Stripe | `/identity/*`, `/payment`, `/challenge` | `npm install @agent-score/commerce @x402/core` |
+
+The SDK is genuinely a toolkit — vendors compose only what they need. Helpers don't bundle assumptions about which rails or protocols you support, and don't recommend one rail over another.
+
+## Stability
+
+`@agent-score/commerce@1.0.0` ships with the full merchant SDK surface stable. Helpers are protocol translations + configurable opinions — most evolution is additive (new optional params, new helpers, new networks/rails). Major bumps are reserved for genuine protocol-mapping bugs.
+
+## Documentation
+
+Full integration docs at [docs.agentscore.sh/integrations/node-commerce](https://docs.agentscore.sh/integrations/node-commerce).
+
+## License
+
+[MIT](LICENSE)

package/dist/_response-DmziuJz6.d.mts

@@ -0,0 +1,137 @@
+import { VerifyWalletSignerResult, DenialReason } from './core.mjs';
+
+/**
+ * Universal denial helpers shared across every adapter.
+ *
+ * What lives here:
+ *   - `FIXABLE_DENIAL_REASONS` / `isFixableDenial` — classifier for compliance reasons that can
+ *     be resolved by re-completing KYC (vs sanctions / age failures which are permanent).
+ *   - `denialReasonStatus` — picks the right HTTP status code per denial code (401 for credential
+ *     problems, 503 for transient API errors, 403 for everything else).
+ *   - `buildSignerMismatchBody` — produces the standard 403 body for a `verifyWalletSignerMatch`
+ *     non-pass result.
+ *   - `buildContactSupportNextSteps` — standard `next_steps.action: "contact_support"` shape for
+ *     unfixable compliance denials.
+ *   - `verificationAgentInstructions` — the canned `agent_instructions` block for
+ *     identity-verification 403s. Vendors can override individual fields.
+ *
+ * Adapters use `denialReasonStatus` inside their default `onDenied` so vendors get the right
+ * status code for free. The body builders are exported from each adapter so vendors who write
+ * a custom `onDenied` can compose them without copy-paste.
+ */
+
+/**
+ * Compliance denial reasons that can be resolved by re-completing KYC. Sanctions hits and
+ * age-not-verified are NOT in this set — they're permanent policy failures on an
+ * otherwise-verified identity and require contact-support, not retry.
+ */
+declare const FIXABLE_DENIAL_REASONS: ReadonlySet<string>;
+/**
+ * Returns true when a `wallet_not_trusted` denial's reasons are all "fixable" (the user can
+ * re-verify and retry). False when any reason is permanent (sanctions, age).
+ *
+ * Empty reasons array is treated as fixable on the assumption that an empty-reason denial
+ * means a generic policy fail that's worth retrying — vendors can override by checking the
+ * specific reasons themselves.
+ */
+declare function isFixableDenial(reasons: readonly string[] | undefined): boolean;
+/**
+ * The right HTTP status code for a denial. `defaultOnDenied` in every adapter uses this so
+ * vendors get correct status codes without writing per-code branches.
+ *
+ *   - 401 for credential problems the agent can recover from (`token_expired`, `invalid_credential`)
+ *   - 503 for transient `api_error`
+ *   - 403 for everything else (identity required, compliance fail, signer mismatch, etc.)
+ */
+declare function denialReasonStatus(reason: DenialReason): 401 | 403 | 503;
+interface SignerMismatchBodyInput {
+    /** Result from `verifyWalletSignerMatch`. The function only emits a body for non-pass results. */
+    result: VerifyWalletSignerResult;
+    /** Optional override for the human-facing `next_steps.user_message`. */
+    userMessage?: string;
+    /** Optional override for `next_steps.learn_more_url`. Default: AgentScore agent-identity guide. */
+    learnMoreUrl?: string;
+}
+/**
+ * Standard 403 body for a non-pass `verifyWalletSignerMatch` result. Returns null for `pass` /
+ * `api_error` so vendors can call it unconditionally:
+ *
+ *   const result = await verifyWalletSignerMatch(c);
+ *   const mismatchBody = buildSignerMismatchBody({ result });
+ *   if (mismatchBody) return c.json(mismatchBody, 403);
+ *
+ * Body shape mirrors the gate's denial bodies: top-level error.code, all signer-match fields
+ * (`claimed_operator`, `actual_signer_operator`, `expected_signer`, `actual_signer`,
+ * `linked_wallets`), plus a `next_steps` action describing the recovery path.
+ */
+declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record<string, unknown> | null;
+/**
+ * Standard `next_steps` block for unfixable compliance denials (sanctions, age, etc.). Vendors
+ * spread this into a 403 body alongside the usual `error`/`reasons` fields.
+ *
+ *   return c.json({
+ *     error: { code: 'compliance_denied', message: '...' },
+ *     reasons,
+ *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *   }, 403);
+ */
+declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {
+    action: 'contact_support';
+    support_email: string;
+    user_message: string;
+};
+interface VerificationAgentInstructionsInput {
+    /** Override the user-facing message. */
+    userAction?: string;
+    /** Replace the generic "Retry the original merchant request..." step with a merchant-specific
+     *  one (e.g. "Retry POST /purchase with X-Operator-Token AND include order_id..."). When set,
+     *  this REPLACES baseSteps[4] rather than appending — use it instead of `extraSteps[0]` when
+     *  your retry instruction is a refinement of the canonical retry, not an additional step. */
+    retryStep?: string;
+    /** Append additional steps after the retry step. Use this for genuinely additional steps
+     *  (e.g. "After payment the same call returns 200 with the order"), not for re-stating the
+     *  retry — use `retryStep` for that. */
+    extraSteps?: string[];
+    /** Override the poll cadence. Default 5 seconds. */
+    pollIntervalSeconds?: number;
+    /** Override how long the agent should keep polling. Default 3600 seconds (1 hour). */
+    timeoutSeconds?: number;
+    /** Optional `order_ttl` note describing how long pending orders survive. */
+    orderTtl?: string;
+    /** Arbitrary additional fields merged into the instructions object. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The canonical `agent_instructions` block for identity-verification 403s. Tells the agent how to
+ * present the verify_url, poll for the operator_token, and retry the original request. Universal
+ * across every AgentScore-gated merchant — overrides let vendors add merchant-specific steps
+ * (e.g. "include order_id when retrying").
+ */
+declare function verificationAgentInstructions(input?: VerificationAgentInstructionsInput): {
+    action: 'poll_for_credential';
+    user_action: string;
+    steps: string[];
+    poll_interval_seconds: number;
+    poll_secret_header: 'X-Poll-Secret';
+    retry_token_header: 'X-Operator-Token';
+    timeout_seconds: number;
+    order_ttl?: string;
+    [key: string]: unknown;
+};
+
+/**
+ * Shared DenialReason → response body serialization for all adapters.
+ *
+ * Keeps Hono / Express / Fastify / Web / Next.js defaults aligned — a field added
+ * here shows up in every adapter's 403 body automatically, and there's one place
+ * to test the marshaling.
+ *
+ * Body shape: `{ error: { code, message }, ... }` — matches the canonical AgentScore
+ * core API response shape (`core/api/src/lib/auth.ts`, `lib/rate-limit.ts`, etc.) and
+ * martin-estate's pre-commerce shape, so downstream agents see one consistent
+ * `error.code` + `error.message` pair regardless of which layer produced the denial.
+ */
+
+declare function denialReasonToBody(reason: DenialReason): Record<string, unknown>;
+
+export { FIXABLE_DENIAL_REASONS as F, buildSignerMismatchBody as a, buildContactSupportNextSteps as b, denialReasonToBody as c, denialReasonStatus as d, isFixableDenial as i, verificationAgentInstructions as v };

package/dist/_response-rbK0zM7y.d.ts

@@ -0,0 +1,137 @@
+import { VerifyWalletSignerResult, DenialReason } from './core.js';
+
+/**
+ * Universal denial helpers shared across every adapter.
+ *
+ * What lives here:
+ *   - `FIXABLE_DENIAL_REASONS` / `isFixableDenial` — classifier for compliance reasons that can
+ *     be resolved by re-completing KYC (vs sanctions / age failures which are permanent).
+ *   - `denialReasonStatus` — picks the right HTTP status code per denial code (401 for credential
+ *     problems, 503 for transient API errors, 403 for everything else).
+ *   - `buildSignerMismatchBody` — produces the standard 403 body for a `verifyWalletSignerMatch`
+ *     non-pass result.
+ *   - `buildContactSupportNextSteps` — standard `next_steps.action: "contact_support"` shape for
+ *     unfixable compliance denials.
+ *   - `verificationAgentInstructions` — the canned `agent_instructions` block for
+ *     identity-verification 403s. Vendors can override individual fields.
+ *
+ * Adapters use `denialReasonStatus` inside their default `onDenied` so vendors get the right
+ * status code for free. The body builders are exported from each adapter so vendors who write
+ * a custom `onDenied` can compose them without copy-paste.
+ */
+
+/**
+ * Compliance denial reasons that can be resolved by re-completing KYC. Sanctions hits and
+ * age-not-verified are NOT in this set — they're permanent policy failures on an
+ * otherwise-verified identity and require contact-support, not retry.
+ */
+declare const FIXABLE_DENIAL_REASONS: ReadonlySet<string>;
+/**
+ * Returns true when a `wallet_not_trusted` denial's reasons are all "fixable" (the user can
+ * re-verify and retry). False when any reason is permanent (sanctions, age).
+ *
+ * Empty reasons array is treated as fixable on the assumption that an empty-reason denial
+ * means a generic policy fail that's worth retrying — vendors can override by checking the
+ * specific reasons themselves.
+ */
+declare function isFixableDenial(reasons: readonly string[] | undefined): boolean;
+/**
+ * The right HTTP status code for a denial. `defaultOnDenied` in every adapter uses this so
+ * vendors get correct status codes without writing per-code branches.
+ *
+ *   - 401 for credential problems the agent can recover from (`token_expired`, `invalid_credential`)
+ *   - 503 for transient `api_error`
+ *   - 403 for everything else (identity required, compliance fail, signer mismatch, etc.)
+ */
+declare function denialReasonStatus(reason: DenialReason): 401 | 403 | 503;
+interface SignerMismatchBodyInput {
+    /** Result from `verifyWalletSignerMatch`. The function only emits a body for non-pass results. */
+    result: VerifyWalletSignerResult;
+    /** Optional override for the human-facing `next_steps.user_message`. */
+    userMessage?: string;
+    /** Optional override for `next_steps.learn_more_url`. Default: AgentScore agent-identity guide. */
+    learnMoreUrl?: string;
+}
+/**
+ * Standard 403 body for a non-pass `verifyWalletSignerMatch` result. Returns null for `pass` /
+ * `api_error` so vendors can call it unconditionally:
+ *
+ *   const result = await verifyWalletSignerMatch(c);
+ *   const mismatchBody = buildSignerMismatchBody({ result });
+ *   if (mismatchBody) return c.json(mismatchBody, 403);
+ *
+ * Body shape mirrors the gate's denial bodies: top-level error.code, all signer-match fields
+ * (`claimed_operator`, `actual_signer_operator`, `expected_signer`, `actual_signer`,
+ * `linked_wallets`), plus a `next_steps` action describing the recovery path.
+ */
+declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record<string, unknown> | null;
+/**
+ * Standard `next_steps` block for unfixable compliance denials (sanctions, age, etc.). Vendors
+ * spread this into a 403 body alongside the usual `error`/`reasons` fields.
+ *
+ *   return c.json({
+ *     error: { code: 'compliance_denied', message: '...' },
+ *     reasons,
+ *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *   }, 403);
+ */
+declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {
+    action: 'contact_support';
+    support_email: string;
+    user_message: string;
+};
+interface VerificationAgentInstructionsInput {
+    /** Override the user-facing message. */
+    userAction?: string;
+    /** Replace the generic "Retry the original merchant request..." step with a merchant-specific
+     *  one (e.g. "Retry POST /purchase with X-Operator-Token AND include order_id..."). When set,
+     *  this REPLACES baseSteps[4] rather than appending — use it instead of `extraSteps[0]` when
+     *  your retry instruction is a refinement of the canonical retry, not an additional step. */
+    retryStep?: string;
+    /** Append additional steps after the retry step. Use this for genuinely additional steps
+     *  (e.g. "After payment the same call returns 200 with the order"), not for re-stating the
+     *  retry — use `retryStep` for that. */
+    extraSteps?: string[];
+    /** Override the poll cadence. Default 5 seconds. */
+    pollIntervalSeconds?: number;
+    /** Override how long the agent should keep polling. Default 3600 seconds (1 hour). */
+    timeoutSeconds?: number;
+    /** Optional `order_ttl` note describing how long pending orders survive. */
+    orderTtl?: string;
+    /** Arbitrary additional fields merged into the instructions object. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The canonical `agent_instructions` block for identity-verification 403s. Tells the agent how to
+ * present the verify_url, poll for the operator_token, and retry the original request. Universal
+ * across every AgentScore-gated merchant — overrides let vendors add merchant-specific steps
+ * (e.g. "include order_id when retrying").
+ */
+declare function verificationAgentInstructions(input?: VerificationAgentInstructionsInput): {
+    action: 'poll_for_credential';
+    user_action: string;
+    steps: string[];
+    poll_interval_seconds: number;
+    poll_secret_header: 'X-Poll-Secret';
+    retry_token_header: 'X-Operator-Token';
+    timeout_seconds: number;
+    order_ttl?: string;
+    [key: string]: unknown;
+};
+
+/**
+ * Shared DenialReason → response body serialization for all adapters.
+ *
+ * Keeps Hono / Express / Fastify / Web / Next.js defaults aligned — a field added
+ * here shows up in every adapter's 403 body automatically, and there's one place
+ * to test the marshaling.
+ *
+ * Body shape: `{ error: { code, message }, ... }` — matches the canonical AgentScore
+ * core API response shape (`core/api/src/lib/auth.ts`, `lib/rate-limit.ts`, etc.) and
+ * martin-estate's pre-commerce shape, so downstream agents see one consistent
+ * `error.code` + `error.message` pair regardless of which layer produced the denial.
+ */
+
+declare function denialReasonToBody(reason: DenialReason): Record<string, unknown>;
+
+export { FIXABLE_DENIAL_REASONS as F, buildSignerMismatchBody as a, buildContactSupportNextSteps as b, denialReasonToBody as c, denialReasonStatus as d, isFixableDenial as i, verificationAgentInstructions as v };

package/dist/api/index.d.mts

@@ -0,0 +1 @@
+export { AGENTSCORE_TEST_ADDRESSES, AgentScore, AgentScoreError, isAgentScoreTestAddress } from '@agent-score/sdk';

package/dist/api/index.d.ts

@@ -0,0 +1 @@
+export { AGENTSCORE_TEST_ADDRESSES, AgentScore, AgentScoreError, isAgentScoreTestAddress } from '@agent-score/sdk';

package/dist/api/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/api/index.ts
+var api_exports = {};
+__export(api_exports, {
+  AGENTSCORE_TEST_ADDRESSES: () => import_sdk.AGENTSCORE_TEST_ADDRESSES,
+  AgentScore: () => import_sdk.AgentScore,
+  AgentScoreError: () => import_sdk.AgentScoreError,
+  isAgentScoreTestAddress: () => import_sdk.isAgentScoreTestAddress
+});
+module.exports = __toCommonJS(api_exports);
+var import_sdk = require("@agent-score/sdk");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AGENTSCORE_TEST_ADDRESSES,
+  AgentScore,
+  AgentScoreError,
+  isAgentScoreTestAddress
+});
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/index.ts"],"sourcesContent":["/**\n * AgentScore SDK re-export — vendors install only `@agent-score/commerce` and reach\n * everything from the underlying `@agent-score/sdk` here. Don't add `@agent-score/sdk`\n * as a separate dep; the two can drift versions and cause subtle type mismatches.\n *\n * Use this for: programmatic API calls (sessions, credentials, reputation) and the\n * test-mode address fixtures for integration tests.\n */\nexport {\n  AGENTSCORE_TEST_ADDRESSES,\n  AgentScore,\n  AgentScoreError,\n  isAgentScoreTestAddress,\n} from '@agent-score/sdk';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,iBAKO;","names":[]}

package/dist/api/index.mjs

@@ -0,0 +1,14 @@
+// src/api/index.ts
+import {
+  AGENTSCORE_TEST_ADDRESSES,
+  AgentScore,
+  AgentScoreError,
+  isAgentScoreTestAddress
+} from "@agent-score/sdk";
+export {
+  AGENTSCORE_TEST_ADDRESSES,
+  AgentScore,
+  AgentScoreError,
+  isAgentScoreTestAddress
+};
+//# sourceMappingURL=index.mjs.map

package/dist/api/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/index.ts"],"sourcesContent":["/**\n * AgentScore SDK re-export — vendors install only `@agent-score/commerce` and reach\n * everything from the underlying `@agent-score/sdk` here. Don't add `@agent-score/sdk`\n * as a separate dep; the two can drift versions and cause subtle type mismatches.\n *\n * Use this for: programmatic API calls (sessions, credentials, reputation) and the\n * test-mode address fixtures for integration tests.\n */\nexport {\n  AGENTSCORE_TEST_ADDRESSES,\n  AgentScore,\n  AgentScoreError,\n  isAgentScoreTestAddress,\n} from '@agent-score/sdk';\n"],"mappings":";AAQA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}