@agentx402-ai/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The AgentKV Authors
+
+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,16 @@
+# @agentx402-ai/core
+
+Shared x402/EIP-712 platform SDK plumbing — auth, payment, usage, error, and retry handling —
+extracted from `@agentkv/client` for reuse across future `agentx402` service SDKs.
+
+## Error handling
+
+`@agentkv/client` re-exports this package's `AgentXError` as `AgentKVError`, so both names refer
+to the same class object and `instanceof AgentKVError` holds across the workspace. This relies on
+a single resolved copy of `@agentx402-ai/core` — if a downstream project ever resolves two
+incompatible majors of it (e.g. one dependency pinning `^0.1.0` and another `^1.0.0`), each copy's
+`AgentXError` is a distinct class, and `instanceof` checks silently fail across them.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,337 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentKVError: () => AgentXError,
+  AgentXError: () => AgentXError,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  EIP712_DOMAIN_NAME: () => EIP712_DOMAIN_NAME,
+  EIP712_DOMAIN_VERSION: () => EIP712_DOMAIN_VERSION,
+  MAX_AUTH_WINDOW_SEC: () => MAX_AUTH_WINDOW_SEC,
+  SpendCapError: () => SpendCapError,
+  buildBearerHeaders: () => buildBearerHeaders,
+  buildIdentityHeaders: () => buildIdentityHeaders,
+  buildPaymentHeader: () => buildPaymentHeader,
+  chainIdFromCaip2: () => chainIdFromCaip2,
+  challengePriceUsd: () => challengePriceUsd,
+  decodeBase64Utf8: () => decodeBase64Utf8,
+  fetchWithRetry: () => fetchWithRetry,
+  freshNonce: () => freshNonce,
+  nonceFromIdempotencyKey: () => nonceFromIdempotencyKey,
+  nowSec: () => nowSec,
+  retryDelay: () => retryDelay
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var AgentXError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "AgentKVError";
+  }
+  code;
+  status;
+};
+var SpendCapError = class extends AgentXError {
+  constructor(message) {
+    super(message, "spend_cap_exceeded");
+    this.name = "SpendCapError";
+  }
+};
+
+// src/idempotency.ts
+var import_viem = require("viem");
+function freshNonce() {
+  return (0, import_viem.toHex)(crypto.getRandomValues(new Uint8Array(32)));
+}
+function nonceFromIdempotencyKey(key) {
+  return (0, import_viem.keccak256)((0, import_viem.stringToHex)(key));
+}
+
+// src/payment.ts
+var import_http = require("@x402/core/http");
+var import_evm = require("@x402/evm");
+var import_viem2 = require("viem");
+var EIP712_DOMAIN_NAME = "AgentKV";
+var EIP712_DOMAIN_VERSION = "1";
+var MAX_AUTH_WINDOW_SEC = 3600;
+function chainIdFromCaip2(network) {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "eip155") {
+    throw new Error(`unsupported CAIP-2 network: ${network}`);
+  }
+  const id = Number(parts[1]);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(`invalid CAIP-2 chain id: ${network}`);
+  }
+  return id;
+}
+function decodeBase64Utf8(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder("utf-8").decode(bytes);
+}
+var REQUEST_TYPES = {
+  Request: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    // host binds the signature to one deployment (prevents cross-deployment replay) —
+    // must match the backend's EIP-712 type definitions exactly, or every identity op fails to verify.
+    { name: "host", type: "string" },
+    { name: "nonce", type: "bytes32" },
+    { name: "timestamp", type: "uint256" }
+  ]
+};
+function buildBearerHeaders(accountKey) {
+  return { Authorization: `Bearer ${accountKey}` };
+}
+function nowSec() {
+  return Math.floor(Date.now() / 1e3);
+}
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function decodeChallenge(paymentRequiredHeader) {
+  let json;
+  try {
+    json = decodeBase64Utf8(paymentRequiredHeader);
+  } catch {
+    throw new Error("PAYMENT-REQUIRED header is not valid base64");
+  }
+  const parsed = JSON.parse(json);
+  if (!parsed || !Array.isArray(parsed.accepts)) {
+    throw new Error("invalid PAYMENT-REQUIRED challenge: missing accepts array");
+  }
+  return parsed;
+}
+function selectRequirement(accepts, amountAtomic) {
+  const exact = accepts.filter((a) => a.scheme === "exact");
+  if (exact.length === 0)
+    throw new Error("no acceptable x402 exact-scheme requirement in challenge");
+  if (amountAtomic !== void 0) {
+    return { ...exact[0], amount: String(amountAtomic) };
+  }
+  if (exact.length > 1)
+    throw new Error(
+      "ambiguous PAYMENT-REQUIRED challenge: multiple exact requirements; specify an amount"
+    );
+  return exact[0];
+}
+function assertNetworkParity(req, expectedNetwork) {
+  if (req.network !== expectedNetwork) {
+    throw new AgentXError(
+      `payment challenge network "${req.network}" does not match client network "${expectedNetwork}"`,
+      "network_mismatch",
+      0
+    );
+  }
+  const asset = (0, import_evm.getDefaultAsset)(expectedNetwork);
+  if ((0, import_viem2.getAddress)(req.asset) !== (0, import_viem2.getAddress)(asset.address)) {
+    throw new AgentXError(
+      `payment challenge asset "${req.asset}" is not the canonical USDC for ${expectedNetwork}`,
+      "asset_mismatch",
+      0
+    );
+  }
+}
+function challengePriceUsd(paymentRequiredHeader, amountAtomic, expectedNetwork) {
+  const { accepts } = decodeChallenge(paymentRequiredHeader);
+  const req = selectRequirement(accepts, amountAtomic);
+  if (expectedNetwork) assertNetworkParity(req, expectedNetwork);
+  return Number(req.amount) / 1e6;
+}
+async function buildPaymentHeader(account, paymentRequiredHeader, opts) {
+  const { x402Version, accepts } = decodeChallenge(paymentRequiredHeader);
+  const req = selectRequirement(accepts, opts?.amountAtomic);
+  if (opts?.expectedNetwork) assertNetworkParity(req, opts.expectedNetwork);
+  if (opts?.expectedPayTo && (0, import_viem2.getAddress)(req.payTo) !== (0, import_viem2.getAddress)(opts.expectedPayTo)) {
+    throw new AgentXError(
+      `payment challenge payTo "${req.payTo}" does not match expected "${opts.expectedPayTo}"`,
+      "payto_mismatch",
+      0
+    );
+  }
+  const chainId = chainIdFromCaip2(req.network);
+  const asset = (0, import_evm.getDefaultAsset)(req.network);
+  const nonce = opts?.nonce ?? freshNonce();
+  const now = nowSec();
+  const window = Math.min(req.maxTimeoutSeconds ?? 300, MAX_AUTH_WINDOW_SEC);
+  const validBefore = String(now + window);
+  const authorization = {
+    from: (0, import_viem2.getAddress)(account.address),
+    to: (0, import_viem2.getAddress)(req.payTo),
+    value: req.amount,
+    validAfter: "0",
+    validBefore,
+    nonce
+  };
+  const signature = await account.signTypedData({
+    domain: {
+      name: asset.name,
+      version: asset.version,
+      chainId,
+      verifyingContract: (0, import_viem2.getAddress)(req.asset)
+    },
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: (0, import_viem2.getAddress)(account.address),
+      to: (0, import_viem2.getAddress)(req.payTo),
+      value: BigInt(req.amount),
+      validAfter: BigInt(0),
+      validBefore: BigInt(validBefore),
+      nonce
+    }
+  });
+  const paymentPayload = {
+    x402Version,
+    accepted: req,
+    payload: {
+      authorization,
+      signature
+    }
+  };
+  return (0, import_http.encodePaymentSignatureHeader)(paymentPayload);
+}
+async function buildIdentityHeaders(account, args) {
+  const nonce = freshNonce();
+  const timestamp = nowSec();
+  const signature = await account.signTypedData({
+    domain: {
+      name: EIP712_DOMAIN_NAME,
+      version: EIP712_DOMAIN_VERSION,
+      chainId: chainIdFromCaip2(args.network)
+    },
+    types: REQUEST_TYPES,
+    primaryType: "Request",
+    message: {
+      method: args.method,
+      path: args.path,
+      host: args.host,
+      nonce,
+      timestamp: BigInt(timestamp)
+    }
+  });
+  return {
+    "X-AgentKV-Signature": signature,
+    "X-AgentKV-Nonce": nonce,
+    "X-AgentKV-Timestamp": String(timestamp)
+  };
+}
+
+// src/retry.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+function combineSignals(signals) {
+  const present = signals.filter((s) => !!s);
+  if (present.length === 0) return void 0;
+  if (present.length === 1) return present[0];
+  if (typeof AbortSignal.any === "function") return AbortSignal.any(present);
+  const ctrl = new AbortController();
+  for (const s of present) {
+    if (s.aborted) {
+      ctrl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+  }
+  return ctrl.signal;
+}
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
+async function fetchWithRetry(url, build, maxRetries, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const init = await build();
+      const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : void 0;
+      const signal = combineSignals([init.signal ?? void 0, opts.signal, timeoutSignal]);
+      const res = await doFetch(url, { ...init, signal });
+      const transient = res.status >= 500 && res.status <= 599 || res.status === 429;
+      if (transient && attempt < maxRetries) {
+        await drainBody(res);
+        await retryDelay(attempt, res);
+        continue;
+      }
+      return res;
+    } catch (err) {
+      if (opts.signal?.aborted) {
+        throw err instanceof Error ? err : new AgentXError(String(err), "aborted", 0);
+      }
+      if (attempt < maxRetries) {
+        await retryDelay(attempt);
+        continue;
+      }
+      throw err instanceof Error ? err : new AgentXError(String(err), "network_error", 0);
+    }
+  }
+}
+function retryDelay(attempt, res) {
+  const base = Math.min(500, 50 * 2 ** attempt);
+  let ms = Math.round(base * (0.5 + Math.random() * 0.5));
+  const retryAfter = res?.headers.get("Retry-After");
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) {
+      ms = Math.min(2e3, secs * 1e3);
+    } else {
+      const when = Date.parse(retryAfter);
+      if (Number.isFinite(when)) ms = Math.min(2e3, Math.max(0, when - Date.now()));
+    }
+  }
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentKVError,
+  AgentXError,
+  DEFAULT_TIMEOUT_MS,
+  EIP712_DOMAIN_NAME,
+  EIP712_DOMAIN_VERSION,
+  MAX_AUTH_WINDOW_SEC,
+  SpendCapError,
+  buildBearerHeaders,
+  buildIdentityHeaders,
+  buildPaymentHeader,
+  chainIdFromCaip2,
+  challengePriceUsd,
+  decodeBase64Utf8,
+  fetchWithRetry,
+  freshNonce,
+  nonceFromIdempotencyKey,
+  nowSec,
+  retryDelay
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/idempotency.ts","../src/payment.ts","../src/retry.ts"],"sourcesContent":["// core/src/index.ts\n//\n// @agentx402-ai/core: shared auth/pay/usage/error/retry plumbing that a future\n// second service package can reuse without re-declaring the error base class,\n// EIP-712/x402 signing helpers, or the retry mechanics.\n\nexport * from \"./errors\";\nexport * from \"./idempotency\";\nexport * from \"./payment\";\nexport * from \"./retry\";\nexport * from \"./usage\";\n","// core/src/errors.ts\n//\n// The SINGLE error base class object for the installed workspace. `@agentkv/client`\n// (and any future second service package) must DEPEND ON and RE-EXPORT this class —\n// never re-declare it — or `err instanceof AgentKVError` breaks for anything caught\n// across a package boundary (two distinct class objects in node_modules).\n\n/** Base error carrying a machine code (mapped to CLI exit codes / MCP errors). */\nexport class AgentXError extends Error {\n  constructor(\n    message: string,\n    readonly code: string,\n    readonly status?: number,\n  ) {\n    super(message);\n    // Keep the original runtime `.name` string (\"AgentKVError\") so any existing\n    // logging/serialization that reads `err.name` sees no observable change from\n    // the pre-extraction class — only the exported IDENTIFIER is renamed.\n    this.name = \"AgentKVError\";\n  }\n}\n\n/**\n * Back-compat alias: the base class shipped as `AgentKVError` before this\n * extraction. Re-export the SAME reference under the old name (not a second\n * `class AgentKVError extends AgentXError {}` declaration) so\n * `new AgentKVError(...) instanceof AgentKVError` and\n * `new AgentKVError(...) instanceof AgentXError` both hold, and so callers that\n * imported `AgentKVError` before this refactor keep compiling and matching.\n */\nexport { AgentXError as AgentKVError };\n\n/** Thrown when a paying call would exceed a configured spend cap. */\nexport class SpendCapError extends AgentXError {\n  constructor(message: string) {\n    super(message, \"spend_cap_exceeded\");\n    this.name = \"SpendCapError\";\n  }\n}\n","// core/src/idempotency.ts\n//\n// Nonce helpers shared by the identity-signing and x402-payment paths.\n\nimport { keccak256, stringToHex, toHex } from \"viem\";\n\n/** A fresh random bytes32 nonce (0x-prefixed, 64 hex chars). */\nexport function freshNonce(): `0x${string}` {\n  return toHex(crypto.getRandomValues(new Uint8Array(32)));\n}\n\n/**\n * Derive a deterministic bytes32 EIP-3009 nonce from a caller idempotency key,\n * so retrying a logical write reuses the same authorization and the server's\n * idempotency record is hit (exactly-once across caller retries).\n */\nexport function nonceFromIdempotencyKey(key: string): `0x${string}` {\n  return keccak256(stringToHex(key));\n}\n","// core/src/payment.ts\n//\n// Payment/identity header builders, plus the `Signer` interface and EIP-712 domain\n// constants they depend on. These travel together because\n// `buildPaymentHeader`/`buildIdentityHeaders` are not truly standalone from them —\n// splitting the functions from their domain constants would force a circular\n// client<->core dependency.\n\nimport { encodePaymentSignatureHeader } from \"@x402/core/http\";\nimport type { PaymentPayload, PaymentRequirements } from \"@x402/core/types\";\nimport { getDefaultAsset } from \"@x402/evm\";\nimport { getAddress } from \"viem\";\nimport { AgentXError } from \"./errors\";\nimport { freshNonce } from \"./idempotency\";\n\n/** Minimal signer the client needs: a viem account satisfies this structurally. */\nexport interface Signer {\n  address: `0x${string}`;\n  // viem's signTypedData is generic; accept it structurally.\n  signTypedData(args: any): Promise<`0x${string}`>;\n}\n\n/** EIP-712 domain name shared with the server's EIP-712 verifier. */\nexport const EIP712_DOMAIN_NAME = \"AgentKV\";\n\n/** EIP-712 domain version shared with the server's EIP-712 verifier. */\nexport const EIP712_DOMAIN_VERSION = \"1\";\n\n/**\n * Hard cap on the signed EIP-3009 authorization window, regardless of the server-supplied\n * `maxTimeoutSeconds`. A signed authorization is a bearer instrument; a hostile challenge\n * asking for a multi-year window must not yield one that stays spendable indefinitely.\n */\nexport const MAX_AUTH_WINDOW_SEC = 3600;\n\n/** Maps a CAIP-2 network id (e.g. \"eip155:8453\") to its numeric chainId. */\nexport function chainIdFromCaip2(network: string): number {\n  const parts = network.split(\":\");\n  if (parts.length !== 2 || parts[0] !== \"eip155\") {\n    throw new Error(`unsupported CAIP-2 network: ${network}`);\n  }\n  const id = Number(parts[1]);\n  if (!Number.isInteger(id) || id <= 0) {\n    throw new Error(`invalid CAIP-2 chain id: ${network}`);\n  }\n  return id;\n}\n\n/**\n * Decode a base64 header as UTF-8 (atob → char-code bytes → TextDecoder(\"utf-8\")).\n * The backend encodes both PAYMENT-REQUIRED and PAYMENT-RESPONSE with base64/UTF-8 and\n * documents this exact mirror decode; a bare `atob()` decodes Latin-1, which corrupts\n * any non-ASCII code point (e.g. a future \"USD₮\" asset name). Byte-identical for ASCII.\n */\nexport function decodeBase64Utf8(b64: string): string {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);\n  return new TextDecoder(\"utf-8\").decode(bytes);\n}\n\n/** EIP-712 typed-data shape shared with the server's EIP-712 verifier. */\nconst REQUEST_TYPES = {\n  Request: [\n    { name: \"method\", type: \"string\" },\n    { name: \"path\", type: \"string\" },\n    // host binds the signature to one deployment (prevents cross-deployment replay) —\n    // must match the backend's EIP-712 type definitions exactly, or every identity op fails to verify.\n    { name: \"host\", type: \"string\" },\n    { name: \"nonce\", type: \"bytes32\" },\n    { name: \"timestamp\", type: \"uint256\" },\n  ],\n} as const;\n\n/** Identity headers sent on free/credit operations. */\nexport interface IdentityHeaders {\n  \"X-AgentKV-Signature\": string;\n  \"X-AgentKV-Nonce\": string;\n  \"X-AgentKV-Timestamp\": string;\n}\n\n/**\n * Bearer auth header for account-key mode. The opaque `ak_…` token IS the\n * capability: the server hashes it to name the account's storage and debits its\n * prepaid credits. NO x402, NO EIP-712 — this header replaces both. The raw key\n * travels in the clear over TLS exactly like any bearer token; never log it.\n */\nexport function buildBearerHeaders(accountKey: string): Record<string, string> {\n  return { Authorization: `Bearer ${accountKey}` };\n}\n\n/** Current unix time in whole seconds. */\nexport function nowSec(): number {\n  return Math.floor(Date.now() / 1000);\n}\n\n/** EIP-712 typed-data types for EIP-3009 transferWithAuthorization. */\nconst TRANSFER_WITH_AUTHORIZATION_TYPES = {\n  TransferWithAuthorization: [\n    { name: \"from\", type: \"address\" },\n    { name: \"to\", type: \"address\" },\n    { name: \"value\", type: \"uint256\" },\n    { name: \"validAfter\", type: \"uint256\" },\n    { name: \"validBefore\", type: \"uint256\" },\n    { name: \"nonce\", type: \"bytes32\" },\n  ],\n} as const;\n\n/** Each PAYMENT-REQUIRED accept is a full v2 PaymentRequirements. */\ntype ChallengeAccept = PaymentRequirements;\n\n/** Decoded PAYMENT-REQUIRED challenge body. */\ninterface PaymentRequiredChallenge {\n  x402Version: number;\n  accepts: ChallengeAccept[];\n}\n\n/**\n * Decode and validate a base64-encoded PAYMENT-REQUIRED challenge header.\n */\nfunction decodeChallenge(paymentRequiredHeader: string): PaymentRequiredChallenge {\n  let json: string;\n  try {\n    json = decodeBase64Utf8(paymentRequiredHeader);\n  } catch {\n    throw new Error(\"PAYMENT-REQUIRED header is not valid base64\");\n  }\n  const parsed = JSON.parse(json) as PaymentRequiredChallenge;\n  if (!parsed || !Array.isArray(parsed.accepts)) {\n    throw new Error(\"invalid PAYMENT-REQUIRED challenge: missing accepts array\");\n  }\n  return parsed;\n}\n\n/** Pick the exact-scheme requirement, by amount when several tiers are offered. */\nfunction selectRequirement(accepts: ChallengeAccept[], amountAtomic?: number): ChallengeAccept {\n  const exact = accepts.filter((a) => a.scheme === \"exact\");\n  if (exact.length === 0)\n    throw new Error(\"no acceptable x402 exact-scheme requirement in challenge\");\n  if (amountAtomic !== undefined) {\n    // Use the first exact requirement as the asset/payTo/network/domain template and\n    // override the amount — supports any top-off / deposit amount, not just advertised tiers.\n    return { ...exact[0], amount: String(amountAtomic) };\n  }\n  if (exact.length > 1)\n    throw new Error(\n      \"ambiguous PAYMENT-REQUIRED challenge: multiple exact requirements; specify an amount\",\n    );\n  return exact[0];\n}\n\n/**\n * Enforce that a server-supplied challenge targets the client's configured network AND its\n * canonical USDC contract. Money movement must never be dictated solely by the server: a\n * compromised or spoofed worker could otherwise return a challenge for a different chain\n * (e.g. hand a Base-configured client an Arbitrum challenge, draining the SAME EOA's\n * Arbitrum USDC) or a non-canonical token address, and the client would sign it. This is\n * the payment-path mirror of the host-binding on identity signatures and the domain pin.\n */\nfunction assertNetworkParity(req: ChallengeAccept, expectedNetwork: string): void {\n  if (req.network !== expectedNetwork) {\n    throw new AgentXError(\n      `payment challenge network \"${req.network}\" does not match client network \"${expectedNetwork}\"`,\n      \"network_mismatch\",\n      0,\n    );\n  }\n  const asset = getDefaultAsset(expectedNetwork as `${string}:${string}`);\n  if (getAddress(req.asset) !== getAddress(asset.address)) {\n    throw new AgentXError(\n      `payment challenge asset \"${req.asset}\" is not the canonical USDC for ${expectedNetwork}`,\n      \"asset_mismatch\",\n      0,\n    );\n  }\n}\n\n/** Decode a challenge and return the chosen requirement's price in USD. */\nexport function challengePriceUsd(\n  paymentRequiredHeader: string,\n  amountAtomic?: number,\n  expectedNetwork?: string,\n): number {\n  const { accepts } = decodeChallenge(paymentRequiredHeader);\n  const req = selectRequirement(accepts, amountAtomic);\n  if (expectedNetwork) assertNetworkParity(req, expectedNetwork);\n  return Number(req.amount) / 1_000_000;\n}\n\n/**\n * Build the base64 PAYMENT-SIGNATURE header from a PAYMENT-REQUIRED challenge.\n *\n * Decodes the v2 challenge, selects the matching `exact`-scheme requirement\n * (by `opts.amountAtomic` when several tiers are offered), and signs an EIP-3009\n * transferWithAuthorization payload (validAfter=0, validBefore=now+window) with\n * the viem account. `opts.nonce` pins a deterministic EIP-3009 nonce so retries\n * reuse the same authorization.\n *\n * Returns the base64-encoded JSON payload as the PAYMENT-SIGNATURE value.\n */\nexport async function buildPaymentHeader(\n  account: Signer,\n  paymentRequiredHeader: string,\n  opts?: {\n    nonce?: `0x${string}`;\n    amountAtomic?: number;\n    expectedNetwork?: string;\n    /** Pin the recipient: reject the challenge unless its `payTo` equals this address (high-value ops). */\n    expectedPayTo?: string;\n  },\n): Promise<string> {\n  const { x402Version, accepts } = decodeChallenge(paymentRequiredHeader);\n\n  const req = selectRequirement(accepts, opts?.amountAtomic);\n\n  // Pin the money-moving challenge to the client's configured network + canonical asset\n  // BEFORE signing anything (a signed EIP-3009 authorization is a bearer instrument).\n  if (opts?.expectedNetwork) assertNetworkParity(req, opts.expectedNetwork);\n  // Optional recipient pin: the client can't know the \"correct\" payTo in general (the amount\n  // ceiling is the primary defense), but for high-value ops a caller may pin an expected one.\n  if (opts?.expectedPayTo && getAddress(req.payTo) !== getAddress(opts.expectedPayTo)) {\n    throw new AgentXError(\n      `payment challenge payTo \"${req.payTo}\" does not match expected \"${opts.expectedPayTo}\"`,\n      \"payto_mismatch\",\n      0,\n    );\n  }\n\n  const chainId = chainIdFromCaip2(req.network);\n  // Look up EIP-712 domain info for the token (name/version).\n  // Cast to the x402 Network template-literal type.\n  const asset = getDefaultAsset(req.network as `${string}:${string}`);\n\n  const nonce = opts?.nonce ?? freshNonce();\n  const now = nowSec();\n  // Clamp the signed window: never sign an authorization valid longer than MAX_AUTH_WINDOW_SEC,\n  // regardless of the server-supplied maxTimeoutSeconds.\n  const window = Math.min(req.maxTimeoutSeconds ?? 300, MAX_AUTH_WINDOW_SEC);\n  const validBefore = String(now + window);\n\n  const authorization = {\n    from: getAddress(account.address),\n    to: getAddress(req.payTo),\n    value: req.amount,\n    validAfter: \"0\",\n    validBefore,\n    nonce,\n  };\n\n  const signature = await account.signTypedData({\n    domain: {\n      name: asset.name,\n      version: asset.version,\n      chainId,\n      verifyingContract: getAddress(req.asset),\n    },\n    types: TRANSFER_WITH_AUTHORIZATION_TYPES,\n    primaryType: \"TransferWithAuthorization\",\n    message: {\n      from: getAddress(account.address),\n      to: getAddress(req.payTo),\n      value: BigInt(req.amount),\n      validAfter: BigInt(0),\n      validBefore: BigInt(validBefore),\n      nonce,\n    },\n  });\n\n  // v2 PaymentPayload: the chosen requirement + the signed EIP-3009 authorization,\n  // encoded with the SDK so the server's decodePaymentSignatureHeader round-trips.\n  const paymentPayload: PaymentPayload = {\n    x402Version,\n    accepted: req,\n    payload: {\n      authorization,\n      signature,\n    },\n  };\n\n  return encodePaymentSignatureHeader(paymentPayload);\n}\n\n/**\n * Build EIP-712 identity headers for a free/credit op (delete, balance).\n * Signs the Request typed data with a fresh nonce + timestamp so the server\n * can recover the wallet address and enforce replay protection.\n */\nexport async function buildIdentityHeaders(\n  account: Signer,\n  args: { method: string; path: string; host: string; network: string },\n): Promise<IdentityHeaders> {\n  const nonce = freshNonce();\n  const timestamp = nowSec();\n  const signature = await account.signTypedData({\n    domain: {\n      name: EIP712_DOMAIN_NAME,\n      version: EIP712_DOMAIN_VERSION,\n      chainId: chainIdFromCaip2(args.network),\n    },\n    types: REQUEST_TYPES,\n    primaryType: \"Request\",\n    message: {\n      method: args.method,\n      path: args.path,\n      host: args.host,\n      nonce,\n      timestamp: BigInt(timestamp),\n    },\n  });\n\n  return {\n    \"X-AgentKV-Signature\": signature,\n    \"X-AgentKV-Nonce\": nonce,\n    \"X-AgentKV-Timestamp\": String(timestamp),\n  };\n}\n","// core/src/retry.ts\n//\n// Pure retry helpers factored out of `AgentKV#fetchWithRetry` / `AgentKV#retryDelay`.\n// The original methods only ever read `this.maxRetries` (a plain number) and called\n// `this.retryDelay` — no other instance state — so they extract cleanly into pure\n// functions parameterized by `maxRetries`. `AgentKV` now delegates to these via thin\n// private wrappers so every existing call site (`this.fetchWithRetry(...)`) is unchanged.\n\nimport { AgentXError } from \"./errors\";\n\n/** Default per-attempt request timeout (ms). A hung-open connection would otherwise wedge an op forever. */\nexport const DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Tuning knobs for {@link fetchWithRetry}. All optional; sensible defaults. */\nexport interface RetryOptions {\n  /** Per-ATTEMPT timeout in ms (via `AbortSignal.timeout`). Default 30_000. Pass 0 to disable. */\n  timeoutMs?: number;\n  /** Injectable `fetch` for proxies / instrumentation / tests. Defaults to the global `fetch`. */\n  fetchImpl?: typeof fetch;\n  /** Caller `AbortSignal` to cancel the whole operation (abort is surfaced immediately, never retried). */\n  signal?: AbortSignal;\n}\n\n/** Combine 0+ AbortSignals into one that aborts when any input does. Undefined if none supplied. */\nfunction combineSignals(signals: (AbortSignal | undefined)[]): AbortSignal | undefined {\n  const present = signals.filter((s): s is AbortSignal => !!s);\n  if (present.length === 0) return undefined;\n  if (present.length === 1) return present[0];\n  // AbortSignal.any is Node >=20.3 / modern browsers; fall back to a manual combiner for Node 20.0–20.2.\n  if (typeof AbortSignal.any === \"function\") return AbortSignal.any(present);\n  const ctrl = new AbortController();\n  for (const s of present) {\n    if (s.aborted) {\n      ctrl.abort(s.reason);\n      break;\n    }\n    s.addEventListener(\"abort\", () => ctrl.abort(s.reason), { once: true });\n  }\n  return ctrl.signal;\n}\n\n/** Release a transient response's body so its socket returns to the pool before we retry. */\nasync function drainBody(res: Response): Promise<void> {\n  try {\n    await res.body?.cancel();\n  } catch {\n    // best-effort — a body that can't be cancelled is not worth failing the retry over.\n  }\n}\n\n/**\n * Issue a request with bounded retry on TRANSIENT failures only: a thrown\n * fetch (network error / lost response / per-attempt timeout) or a 5xx/429\n * response. `build()` is re-invoked per attempt so a caller can re-sign\n * per-attempt state (e.g. a fresh identity nonce) while a stable Idempotency-Key\n * (and pinned EIP-3009 nonce on paid ops) makes a retry of an already-processed\n * request dedupe server-side — so a lost response that the server already charged\n * is recovered without a second charge. NOT retried: any 2xx/4xx (incl. a 402\n * credit->pay handoff, 401, 404) — returned as-is; and a caller-initiated abort,\n * which is surfaced immediately. Honors `Retry-After` (delta-seconds or HTTP-date).\n * Each attempt is bounded by `opts.timeoutMs` (default 30s).\n */\nexport async function fetchWithRetry(\n  url: string,\n  build: () => RequestInit | Promise<RequestInit>,\n  maxRetries: number,\n  opts: RetryOptions = {},\n): Promise<Response> {\n  const doFetch = opts.fetchImpl ?? fetch;\n  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  for (let attempt = 0; ; attempt++) {\n    try {\n      const init = await build();\n      const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;\n      const signal = combineSignals([init.signal ?? undefined, opts.signal, timeoutSignal]);\n      const res = await doFetch(url, { ...init, signal });\n      // Retry TRANSIENT statuses: 5xx, and 429 (rate limited).\n      const transient = (res.status >= 500 && res.status <= 599) || res.status === 429;\n      if (transient && attempt < maxRetries) {\n        await drainBody(res);\n        await retryDelay(attempt, res);\n        continue;\n      }\n      return res;\n    } catch (err) {\n      // A caller-initiated cancel is intentional, not transient — surface it immediately.\n      if (opts.signal?.aborted) {\n        throw err instanceof Error ? err : new AgentXError(String(err), \"aborted\", 0);\n      }\n      if (attempt < maxRetries) {\n        await retryDelay(attempt);\n        continue;\n      }\n      throw err instanceof Error ? err : new AgentXError(String(err), \"network_error\", 0);\n    }\n  }\n}\n\n/**\n * Short, bounded backoff between retries. Base is 50ms, 100ms, ... capped at 500ms, with\n * full jitter (each delay uniformly in [50%, 100%] of the base) to avoid a synchronized\n * retry herd under a 5xx/429 storm. If the response carries a `Retry-After` — delta-seconds\n * OR an HTTP-date — honor it up to a 2s cap so a re-sent paid authorization still stays\n * comfortably within its validBefore window (jitter is skipped when the server dictates a delay).\n */\nexport function retryDelay(attempt: number, res?: Response): Promise<void> {\n  const base = Math.min(500, 50 * 2 ** attempt);\n  let ms = Math.round(base * (0.5 + Math.random() * 0.5));\n  const retryAfter = res?.headers.get(\"Retry-After\");\n  if (retryAfter) {\n    const secs = Number(retryAfter);\n    if (Number.isFinite(secs) && secs >= 0) {\n      ms = Math.min(2000, secs * 1000); // delta-seconds form\n    } else {\n      const when = Date.parse(retryAfter); // HTTP-date form\n      if (Number.isFinite(when)) ms = Math.min(2000, Math.max(0, when - Date.now()));\n    }\n  }\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"],"mappings":"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","names":["import_viem"]}

package/dist/index.d.cts

@@ -0,0 +1,152 @@
+/** Base error carrying a machine code (mapped to CLI exit codes / MCP errors). */
+declare class AgentXError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(message: string, code: string, status?: number | undefined);
+}
+
+/** Thrown when a paying call would exceed a configured spend cap. */
+declare class SpendCapError extends AgentXError {
+    constructor(message: string);
+}
+
+/** A fresh random bytes32 nonce (0x-prefixed, 64 hex chars). */
+declare function freshNonce(): `0x${string}`;
+/**
+ * Derive a deterministic bytes32 EIP-3009 nonce from a caller idempotency key,
+ * so retrying a logical write reuses the same authorization and the server's
+ * idempotency record is hit (exactly-once across caller retries).
+ */
+declare function nonceFromIdempotencyKey(key: string): `0x${string}`;
+
+/** Minimal signer the client needs: a viem account satisfies this structurally. */
+interface Signer {
+    address: `0x${string}`;
+    signTypedData(args: any): Promise<`0x${string}`>;
+}
+/** EIP-712 domain name shared with the server's EIP-712 verifier. */
+declare const EIP712_DOMAIN_NAME = "AgentKV";
+/** EIP-712 domain version shared with the server's EIP-712 verifier. */
+declare const EIP712_DOMAIN_VERSION = "1";
+/**
+ * Hard cap on the signed EIP-3009 authorization window, regardless of the server-supplied
+ * `maxTimeoutSeconds`. A signed authorization is a bearer instrument; a hostile challenge
+ * asking for a multi-year window must not yield one that stays spendable indefinitely.
+ */
+declare const MAX_AUTH_WINDOW_SEC = 3600;
+/** Maps a CAIP-2 network id (e.g. "eip155:8453") to its numeric chainId. */
+declare function chainIdFromCaip2(network: string): number;
+/**
+ * Decode a base64 header as UTF-8 (atob → char-code bytes → TextDecoder("utf-8")).
+ * The backend encodes both PAYMENT-REQUIRED and PAYMENT-RESPONSE with base64/UTF-8 and
+ * documents this exact mirror decode; a bare `atob()` decodes Latin-1, which corrupts
+ * any non-ASCII code point (e.g. a future "USD₮" asset name). Byte-identical for ASCII.
+ */
+declare function decodeBase64Utf8(b64: string): string;
+/** Identity headers sent on free/credit operations. */
+interface IdentityHeaders {
+    "X-AgentKV-Signature": string;
+    "X-AgentKV-Nonce": string;
+    "X-AgentKV-Timestamp": string;
+}
+/**
+ * Bearer auth header for account-key mode. The opaque `ak_…` token IS the
+ * capability: the server hashes it to name the account's storage and debits its
+ * prepaid credits. NO x402, NO EIP-712 — this header replaces both. The raw key
+ * travels in the clear over TLS exactly like any bearer token; never log it.
+ */
+declare function buildBearerHeaders(accountKey: string): Record<string, string>;
+/** Current unix time in whole seconds. */
+declare function nowSec(): number;
+/** Decode a challenge and return the chosen requirement's price in USD. */
+declare function challengePriceUsd(paymentRequiredHeader: string, amountAtomic?: number, expectedNetwork?: string): number;
+/**
+ * Build the base64 PAYMENT-SIGNATURE header from a PAYMENT-REQUIRED challenge.
+ *
+ * Decodes the v2 challenge, selects the matching `exact`-scheme requirement
+ * (by `opts.amountAtomic` when several tiers are offered), and signs an EIP-3009
+ * transferWithAuthorization payload (validAfter=0, validBefore=now+window) with
+ * the viem account. `opts.nonce` pins a deterministic EIP-3009 nonce so retries
+ * reuse the same authorization.
+ *
+ * Returns the base64-encoded JSON payload as the PAYMENT-SIGNATURE value.
+ */
+declare function buildPaymentHeader(account: Signer, paymentRequiredHeader: string, opts?: {
+    nonce?: `0x${string}`;
+    amountAtomic?: number;
+    expectedNetwork?: string;
+    /** Pin the recipient: reject the challenge unless its `payTo` equals this address (high-value ops). */
+    expectedPayTo?: string;
+}): Promise<string>;
+/**
+ * Build EIP-712 identity headers for a free/credit op (delete, balance).
+ * Signs the Request typed data with a fresh nonce + timestamp so the server
+ * can recover the wallet address and enforce replay protection.
+ */
+declare function buildIdentityHeaders(account: Signer, args: {
+    method: string;
+    path: string;
+    host: string;
+    network: string;
+}): Promise<IdentityHeaders>;
+
+/** Default per-attempt request timeout (ms). A hung-open connection would otherwise wedge an op forever. */
+declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Tuning knobs for {@link fetchWithRetry}. All optional; sensible defaults. */
+interface RetryOptions {
+    /** Per-ATTEMPT timeout in ms (via `AbortSignal.timeout`). Default 30_000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable `fetch` for proxies / instrumentation / tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Caller `AbortSignal` to cancel the whole operation (abort is surfaced immediately, never retried). */
+    signal?: AbortSignal;
+}
+/**
+ * Issue a request with bounded retry on TRANSIENT failures only: a thrown
+ * fetch (network error / lost response / per-attempt timeout) or a 5xx/429
+ * response. `build()` is re-invoked per attempt so a caller can re-sign
+ * per-attempt state (e.g. a fresh identity nonce) while a stable Idempotency-Key
+ * (and pinned EIP-3009 nonce on paid ops) makes a retry of an already-processed
+ * request dedupe server-side — so a lost response that the server already charged
+ * is recovered without a second charge. NOT retried: any 2xx/4xx (incl. a 402
+ * credit->pay handoff, 401, 404) — returned as-is; and a caller-initiated abort,
+ * which is surfaced immediately. Honors `Retry-After` (delta-seconds or HTTP-date).
+ * Each attempt is bounded by `opts.timeoutMs` (default 30s).
+ */
+declare function fetchWithRetry(url: string, build: () => RequestInit | Promise<RequestInit>, maxRetries: number, opts?: RetryOptions): Promise<Response>;
+/**
+ * Short, bounded backoff between retries. Base is 50ms, 100ms, ... capped at 500ms, with
+ * full jitter (each delay uniformly in [50%, 100%] of the base) to avoid a synchronized
+ * retry herd under a 5xx/429 storm. If the response carries a `Retry-After` — delta-seconds
+ * OR an HTTP-date — honor it up to a 2s cap so a re-sent paid authorization still stays
+ * comfortably within its validBefore window (jitter is skipped when the server dictates a delay).
+ */
+declare function retryDelay(attempt: number, res?: Response): Promise<void>;
+
+/**
+ * Machine-readable usage envelope the backend attaches to a paid op's success
+ * body. Mirrors the backend's canonical `UsageBlock` FIELD-FOR-FIELD — client and
+ * backend are separate packages that can't share an import, so keep this in
+ * lockstep by hand with the backend's shape. Kept in @agentx402-ai/core so a second
+ * service SDK can reuse the same shape without re-declaring it.
+ */
+interface UsageBlock {
+    service: string;
+    op: string;
+    /**
+     * USD ACTUALLY charged for THIS op on the taken path (NOT the list price).
+     * The credit path spends at the 10x discount, so it does NOT equal
+     * `list_price_usd`. A cache hit is a free serve -> `price_usd: 0`.
+     */
+    price_usd: number;
+    /**
+     * Pay-per-op LIST price in USD — the un-discounted reference rate a
+     * budgeting agent compares `price_usd` against.
+     */
+    list_price_usd: number;
+    /** Prepaid credits debited from the ledger for this op (0 on the x402 pay-per-op path). */
+    credits_charged: number;
+    cache_hit?: boolean;
+}
+
+export { AgentXError as AgentKVError, AgentXError, DEFAULT_TIMEOUT_MS, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, type IdentityHeaders, MAX_AUTH_WINDOW_SEC, type RetryOptions, type Signer, SpendCapError, type UsageBlock, buildBearerHeaders, buildIdentityHeaders, buildPaymentHeader, chainIdFromCaip2, challengePriceUsd, decodeBase64Utf8, fetchWithRetry, freshNonce, nonceFromIdempotencyKey, nowSec, retryDelay };

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/** Base error carrying a machine code (mapped to CLI exit codes / MCP errors). */
+declare class AgentXError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(message: string, code: string, status?: number | undefined);
+}
+
+/** Thrown when a paying call would exceed a configured spend cap. */
+declare class SpendCapError extends AgentXError {
+    constructor(message: string);
+}
+
+/** A fresh random bytes32 nonce (0x-prefixed, 64 hex chars). */
+declare function freshNonce(): `0x${string}`;
+/**
+ * Derive a deterministic bytes32 EIP-3009 nonce from a caller idempotency key,
+ * so retrying a logical write reuses the same authorization and the server's
+ * idempotency record is hit (exactly-once across caller retries).
+ */
+declare function nonceFromIdempotencyKey(key: string): `0x${string}`;
+
+/** Minimal signer the client needs: a viem account satisfies this structurally. */
+interface Signer {
+    address: `0x${string}`;
+    signTypedData(args: any): Promise<`0x${string}`>;
+}
+/** EIP-712 domain name shared with the server's EIP-712 verifier. */
+declare const EIP712_DOMAIN_NAME = "AgentKV";
+/** EIP-712 domain version shared with the server's EIP-712 verifier. */
+declare const EIP712_DOMAIN_VERSION = "1";
+/**
+ * Hard cap on the signed EIP-3009 authorization window, regardless of the server-supplied
+ * `maxTimeoutSeconds`. A signed authorization is a bearer instrument; a hostile challenge
+ * asking for a multi-year window must not yield one that stays spendable indefinitely.
+ */
+declare const MAX_AUTH_WINDOW_SEC = 3600;
+/** Maps a CAIP-2 network id (e.g. "eip155:8453") to its numeric chainId. */
+declare function chainIdFromCaip2(network: string): number;
+/**
+ * Decode a base64 header as UTF-8 (atob → char-code bytes → TextDecoder("utf-8")).
+ * The backend encodes both PAYMENT-REQUIRED and PAYMENT-RESPONSE with base64/UTF-8 and
+ * documents this exact mirror decode; a bare `atob()` decodes Latin-1, which corrupts
+ * any non-ASCII code point (e.g. a future "USD₮" asset name). Byte-identical for ASCII.
+ */
+declare function decodeBase64Utf8(b64: string): string;
+/** Identity headers sent on free/credit operations. */
+interface IdentityHeaders {
+    "X-AgentKV-Signature": string;
+    "X-AgentKV-Nonce": string;
+    "X-AgentKV-Timestamp": string;
+}
+/**
+ * Bearer auth header for account-key mode. The opaque `ak_…` token IS the
+ * capability: the server hashes it to name the account's storage and debits its
+ * prepaid credits. NO x402, NO EIP-712 — this header replaces both. The raw key
+ * travels in the clear over TLS exactly like any bearer token; never log it.
+ */
+declare function buildBearerHeaders(accountKey: string): Record<string, string>;
+/** Current unix time in whole seconds. */
+declare function nowSec(): number;
+/** Decode a challenge and return the chosen requirement's price in USD. */
+declare function challengePriceUsd(paymentRequiredHeader: string, amountAtomic?: number, expectedNetwork?: string): number;
+/**
+ * Build the base64 PAYMENT-SIGNATURE header from a PAYMENT-REQUIRED challenge.
+ *
+ * Decodes the v2 challenge, selects the matching `exact`-scheme requirement
+ * (by `opts.amountAtomic` when several tiers are offered), and signs an EIP-3009
+ * transferWithAuthorization payload (validAfter=0, validBefore=now+window) with
+ * the viem account. `opts.nonce` pins a deterministic EIP-3009 nonce so retries
+ * reuse the same authorization.
+ *
+ * Returns the base64-encoded JSON payload as the PAYMENT-SIGNATURE value.
+ */
+declare function buildPaymentHeader(account: Signer, paymentRequiredHeader: string, opts?: {
+    nonce?: `0x${string}`;
+    amountAtomic?: number;
+    expectedNetwork?: string;
+    /** Pin the recipient: reject the challenge unless its `payTo` equals this address (high-value ops). */
+    expectedPayTo?: string;
+}): Promise<string>;
+/**
+ * Build EIP-712 identity headers for a free/credit op (delete, balance).
+ * Signs the Request typed data with a fresh nonce + timestamp so the server
+ * can recover the wallet address and enforce replay protection.
+ */
+declare function buildIdentityHeaders(account: Signer, args: {
+    method: string;
+    path: string;
+    host: string;
+    network: string;
+}): Promise<IdentityHeaders>;
+
+/** Default per-attempt request timeout (ms). A hung-open connection would otherwise wedge an op forever. */
+declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Tuning knobs for {@link fetchWithRetry}. All optional; sensible defaults. */
+interface RetryOptions {
+    /** Per-ATTEMPT timeout in ms (via `AbortSignal.timeout`). Default 30_000. Pass 0 to disable. */
+    timeoutMs?: number;
+    /** Injectable `fetch` for proxies / instrumentation / tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Caller `AbortSignal` to cancel the whole operation (abort is surfaced immediately, never retried). */
+    signal?: AbortSignal;
+}
+/**
+ * Issue a request with bounded retry on TRANSIENT failures only: a thrown
+ * fetch (network error / lost response / per-attempt timeout) or a 5xx/429
+ * response. `build()` is re-invoked per attempt so a caller can re-sign
+ * per-attempt state (e.g. a fresh identity nonce) while a stable Idempotency-Key
+ * (and pinned EIP-3009 nonce on paid ops) makes a retry of an already-processed
+ * request dedupe server-side — so a lost response that the server already charged
+ * is recovered without a second charge. NOT retried: any 2xx/4xx (incl. a 402
+ * credit->pay handoff, 401, 404) — returned as-is; and a caller-initiated abort,
+ * which is surfaced immediately. Honors `Retry-After` (delta-seconds or HTTP-date).
+ * Each attempt is bounded by `opts.timeoutMs` (default 30s).
+ */
+declare function fetchWithRetry(url: string, build: () => RequestInit | Promise<RequestInit>, maxRetries: number, opts?: RetryOptions): Promise<Response>;
+/**
+ * Short, bounded backoff between retries. Base is 50ms, 100ms, ... capped at 500ms, with
+ * full jitter (each delay uniformly in [50%, 100%] of the base) to avoid a synchronized
+ * retry herd under a 5xx/429 storm. If the response carries a `Retry-After` — delta-seconds
+ * OR an HTTP-date — honor it up to a 2s cap so a re-sent paid authorization still stays
+ * comfortably within its validBefore window (jitter is skipped when the server dictates a delay).
+ */
+declare function retryDelay(attempt: number, res?: Response): Promise<void>;
+
+/**
+ * Machine-readable usage envelope the backend attaches to a paid op's success
+ * body. Mirrors the backend's canonical `UsageBlock` FIELD-FOR-FIELD — client and
+ * backend are separate packages that can't share an import, so keep this in
+ * lockstep by hand with the backend's shape. Kept in @agentx402-ai/core so a second
+ * service SDK can reuse the same shape without re-declaring it.
+ */
+interface UsageBlock {
+    service: string;
+    op: string;
+    /**
+     * USD ACTUALLY charged for THIS op on the taken path (NOT the list price).
+     * The credit path spends at the 10x discount, so it does NOT equal
+     * `list_price_usd`. A cache hit is a free serve -> `price_usd: 0`.
+     */
+    price_usd: number;
+    /**
+     * Pay-per-op LIST price in USD — the un-discounted reference rate a
+     * budgeting agent compares `price_usd` against.
+     */
+    list_price_usd: number;
+    /** Prepaid credits debited from the ledger for this op (0 on the x402 pay-per-op path). */
+    credits_charged: number;
+    cache_hit?: boolean;
+}
+
+export { AgentXError as AgentKVError, AgentXError, DEFAULT_TIMEOUT_MS, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, type IdentityHeaders, MAX_AUTH_WINDOW_SEC, type RetryOptions, type Signer, SpendCapError, type UsageBlock, buildBearerHeaders, buildIdentityHeaders, buildPaymentHeader, chainIdFromCaip2, challengePriceUsd, decodeBase64Utf8, fetchWithRetry, freshNonce, nonceFromIdempotencyKey, nowSec, retryDelay };

package/dist/index.js

@@ -0,0 +1,293 @@
+// src/errors.ts
+var AgentXError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "AgentKVError";
+  }
+  code;
+  status;
+};
+var SpendCapError = class extends AgentXError {
+  constructor(message) {
+    super(message, "spend_cap_exceeded");
+    this.name = "SpendCapError";
+  }
+};
+
+// src/idempotency.ts
+import { keccak256, stringToHex, toHex } from "viem";
+function freshNonce() {
+  return toHex(crypto.getRandomValues(new Uint8Array(32)));
+}
+function nonceFromIdempotencyKey(key) {
+  return keccak256(stringToHex(key));
+}
+
+// src/payment.ts
+import { encodePaymentSignatureHeader } from "@x402/core/http";
+import { getDefaultAsset } from "@x402/evm";
+import { getAddress } from "viem";
+var EIP712_DOMAIN_NAME = "AgentKV";
+var EIP712_DOMAIN_VERSION = "1";
+var MAX_AUTH_WINDOW_SEC = 3600;
+function chainIdFromCaip2(network) {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "eip155") {
+    throw new Error(`unsupported CAIP-2 network: ${network}`);
+  }
+  const id = Number(parts[1]);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(`invalid CAIP-2 chain id: ${network}`);
+  }
+  return id;
+}
+function decodeBase64Utf8(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder("utf-8").decode(bytes);
+}
+var REQUEST_TYPES = {
+  Request: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    // host binds the signature to one deployment (prevents cross-deployment replay) —
+    // must match the backend's EIP-712 type definitions exactly, or every identity op fails to verify.
+    { name: "host", type: "string" },
+    { name: "nonce", type: "bytes32" },
+    { name: "timestamp", type: "uint256" }
+  ]
+};
+function buildBearerHeaders(accountKey) {
+  return { Authorization: `Bearer ${accountKey}` };
+}
+function nowSec() {
+  return Math.floor(Date.now() / 1e3);
+}
+var TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" }
+  ]
+};
+function decodeChallenge(paymentRequiredHeader) {
+  let json;
+  try {
+    json = decodeBase64Utf8(paymentRequiredHeader);
+  } catch {
+    throw new Error("PAYMENT-REQUIRED header is not valid base64");
+  }
+  const parsed = JSON.parse(json);
+  if (!parsed || !Array.isArray(parsed.accepts)) {
+    throw new Error("invalid PAYMENT-REQUIRED challenge: missing accepts array");
+  }
+  return parsed;
+}
+function selectRequirement(accepts, amountAtomic) {
+  const exact = accepts.filter((a) => a.scheme === "exact");
+  if (exact.length === 0)
+    throw new Error("no acceptable x402 exact-scheme requirement in challenge");
+  if (amountAtomic !== void 0) {
+    return { ...exact[0], amount: String(amountAtomic) };
+  }
+  if (exact.length > 1)
+    throw new Error(
+      "ambiguous PAYMENT-REQUIRED challenge: multiple exact requirements; specify an amount"
+    );
+  return exact[0];
+}
+function assertNetworkParity(req, expectedNetwork) {
+  if (req.network !== expectedNetwork) {
+    throw new AgentXError(
+      `payment challenge network "${req.network}" does not match client network "${expectedNetwork}"`,
+      "network_mismatch",
+      0
+    );
+  }
+  const asset = getDefaultAsset(expectedNetwork);
+  if (getAddress(req.asset) !== getAddress(asset.address)) {
+    throw new AgentXError(
+      `payment challenge asset "${req.asset}" is not the canonical USDC for ${expectedNetwork}`,
+      "asset_mismatch",
+      0
+    );
+  }
+}
+function challengePriceUsd(paymentRequiredHeader, amountAtomic, expectedNetwork) {
+  const { accepts } = decodeChallenge(paymentRequiredHeader);
+  const req = selectRequirement(accepts, amountAtomic);
+  if (expectedNetwork) assertNetworkParity(req, expectedNetwork);
+  return Number(req.amount) / 1e6;
+}
+async function buildPaymentHeader(account, paymentRequiredHeader, opts) {
+  const { x402Version, accepts } = decodeChallenge(paymentRequiredHeader);
+  const req = selectRequirement(accepts, opts?.amountAtomic);
+  if (opts?.expectedNetwork) assertNetworkParity(req, opts.expectedNetwork);
+  if (opts?.expectedPayTo && getAddress(req.payTo) !== getAddress(opts.expectedPayTo)) {
+    throw new AgentXError(
+      `payment challenge payTo "${req.payTo}" does not match expected "${opts.expectedPayTo}"`,
+      "payto_mismatch",
+      0
+    );
+  }
+  const chainId = chainIdFromCaip2(req.network);
+  const asset = getDefaultAsset(req.network);
+  const nonce = opts?.nonce ?? freshNonce();
+  const now = nowSec();
+  const window = Math.min(req.maxTimeoutSeconds ?? 300, MAX_AUTH_WINDOW_SEC);
+  const validBefore = String(now + window);
+  const authorization = {
+    from: getAddress(account.address),
+    to: getAddress(req.payTo),
+    value: req.amount,
+    validAfter: "0",
+    validBefore,
+    nonce
+  };
+  const signature = await account.signTypedData({
+    domain: {
+      name: asset.name,
+      version: asset.version,
+      chainId,
+      verifyingContract: getAddress(req.asset)
+    },
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: getAddress(account.address),
+      to: getAddress(req.payTo),
+      value: BigInt(req.amount),
+      validAfter: BigInt(0),
+      validBefore: BigInt(validBefore),
+      nonce
+    }
+  });
+  const paymentPayload = {
+    x402Version,
+    accepted: req,
+    payload: {
+      authorization,
+      signature
+    }
+  };
+  return encodePaymentSignatureHeader(paymentPayload);
+}
+async function buildIdentityHeaders(account, args) {
+  const nonce = freshNonce();
+  const timestamp = nowSec();
+  const signature = await account.signTypedData({
+    domain: {
+      name: EIP712_DOMAIN_NAME,
+      version: EIP712_DOMAIN_VERSION,
+      chainId: chainIdFromCaip2(args.network)
+    },
+    types: REQUEST_TYPES,
+    primaryType: "Request",
+    message: {
+      method: args.method,
+      path: args.path,
+      host: args.host,
+      nonce,
+      timestamp: BigInt(timestamp)
+    }
+  });
+  return {
+    "X-AgentKV-Signature": signature,
+    "X-AgentKV-Nonce": nonce,
+    "X-AgentKV-Timestamp": String(timestamp)
+  };
+}
+
+// src/retry.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+function combineSignals(signals) {
+  const present = signals.filter((s) => !!s);
+  if (present.length === 0) return void 0;
+  if (present.length === 1) return present[0];
+  if (typeof AbortSignal.any === "function") return AbortSignal.any(present);
+  const ctrl = new AbortController();
+  for (const s of present) {
+    if (s.aborted) {
+      ctrl.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => ctrl.abort(s.reason), { once: true });
+  }
+  return ctrl.signal;
+}
+async function drainBody(res) {
+  try {
+    await res.body?.cancel();
+  } catch {
+  }
+}
+async function fetchWithRetry(url, build, maxRetries, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const init = await build();
+      const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : void 0;
+      const signal = combineSignals([init.signal ?? void 0, opts.signal, timeoutSignal]);
+      const res = await doFetch(url, { ...init, signal });
+      const transient = res.status >= 500 && res.status <= 599 || res.status === 429;
+      if (transient && attempt < maxRetries) {
+        await drainBody(res);
+        await retryDelay(attempt, res);
+        continue;
+      }
+      return res;
+    } catch (err) {
+      if (opts.signal?.aborted) {
+        throw err instanceof Error ? err : new AgentXError(String(err), "aborted", 0);
+      }
+      if (attempt < maxRetries) {
+        await retryDelay(attempt);
+        continue;
+      }
+      throw err instanceof Error ? err : new AgentXError(String(err), "network_error", 0);
+    }
+  }
+}
+function retryDelay(attempt, res) {
+  const base = Math.min(500, 50 * 2 ** attempt);
+  let ms = Math.round(base * (0.5 + Math.random() * 0.5));
+  const retryAfter = res?.headers.get("Retry-After");
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) {
+      ms = Math.min(2e3, secs * 1e3);
+    } else {
+      const when = Date.parse(retryAfter);
+      if (Number.isFinite(when)) ms = Math.min(2e3, Math.max(0, when - Date.now()));
+    }
+  }
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  AgentXError as AgentKVError,
+  AgentXError,
+  DEFAULT_TIMEOUT_MS,
+  EIP712_DOMAIN_NAME,
+  EIP712_DOMAIN_VERSION,
+  MAX_AUTH_WINDOW_SEC,
+  SpendCapError,
+  buildBearerHeaders,
+  buildIdentityHeaders,
+  buildPaymentHeader,
+  chainIdFromCaip2,
+  challengePriceUsd,
+  decodeBase64Utf8,
+  fetchWithRetry,
+  freshNonce,
+  nonceFromIdempotencyKey,
+  nowSec,
+  retryDelay
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/idempotency.ts","../src/payment.ts","../src/retry.ts"],"sourcesContent":["// core/src/errors.ts\n//\n// The SINGLE error base class object for the installed workspace. `@agentkv/client`\n// (and any future second service package) must DEPEND ON and RE-EXPORT this class —\n// never re-declare it — or `err instanceof AgentKVError` breaks for anything caught\n// across a package boundary (two distinct class objects in node_modules).\n\n/** Base error carrying a machine code (mapped to CLI exit codes / MCP errors). */\nexport class AgentXError extends Error {\n  constructor(\n    message: string,\n    readonly code: string,\n    readonly status?: number,\n  ) {\n    super(message);\n    // Keep the original runtime `.name` string (\"AgentKVError\") so any existing\n    // logging/serialization that reads `err.name` sees no observable change from\n    // the pre-extraction class — only the exported IDENTIFIER is renamed.\n    this.name = \"AgentKVError\";\n  }\n}\n\n/**\n * Back-compat alias: the base class shipped as `AgentKVError` before this\n * extraction. Re-export the SAME reference under the old name (not a second\n * `class AgentKVError extends AgentXError {}` declaration) so\n * `new AgentKVError(...) instanceof AgentKVError` and\n * `new AgentKVError(...) instanceof AgentXError` both hold, and so callers that\n * imported `AgentKVError` before this refactor keep compiling and matching.\n */\nexport { AgentXError as AgentKVError };\n\n/** Thrown when a paying call would exceed a configured spend cap. */\nexport class SpendCapError extends AgentXError {\n  constructor(message: string) {\n    super(message, \"spend_cap_exceeded\");\n    this.name = \"SpendCapError\";\n  }\n}\n","// core/src/idempotency.ts\n//\n// Nonce helpers shared by the identity-signing and x402-payment paths.\n\nimport { keccak256, stringToHex, toHex } from \"viem\";\n\n/** A fresh random bytes32 nonce (0x-prefixed, 64 hex chars). */\nexport function freshNonce(): `0x${string}` {\n  return toHex(crypto.getRandomValues(new Uint8Array(32)));\n}\n\n/**\n * Derive a deterministic bytes32 EIP-3009 nonce from a caller idempotency key,\n * so retrying a logical write reuses the same authorization and the server's\n * idempotency record is hit (exactly-once across caller retries).\n */\nexport function nonceFromIdempotencyKey(key: string): `0x${string}` {\n  return keccak256(stringToHex(key));\n}\n","// core/src/payment.ts\n//\n// Payment/identity header builders, plus the `Signer` interface and EIP-712 domain\n// constants they depend on. These travel together because\n// `buildPaymentHeader`/`buildIdentityHeaders` are not truly standalone from them —\n// splitting the functions from their domain constants would force a circular\n// client<->core dependency.\n\nimport { encodePaymentSignatureHeader } from \"@x402/core/http\";\nimport type { PaymentPayload, PaymentRequirements } from \"@x402/core/types\";\nimport { getDefaultAsset } from \"@x402/evm\";\nimport { getAddress } from \"viem\";\nimport { AgentXError } from \"./errors\";\nimport { freshNonce } from \"./idempotency\";\n\n/** Minimal signer the client needs: a viem account satisfies this structurally. */\nexport interface Signer {\n  address: `0x${string}`;\n  // viem's signTypedData is generic; accept it structurally.\n  signTypedData(args: any): Promise<`0x${string}`>;\n}\n\n/** EIP-712 domain name shared with the server's EIP-712 verifier. */\nexport const EIP712_DOMAIN_NAME = \"AgentKV\";\n\n/** EIP-712 domain version shared with the server's EIP-712 verifier. */\nexport const EIP712_DOMAIN_VERSION = \"1\";\n\n/**\n * Hard cap on the signed EIP-3009 authorization window, regardless of the server-supplied\n * `maxTimeoutSeconds`. A signed authorization is a bearer instrument; a hostile challenge\n * asking for a multi-year window must not yield one that stays spendable indefinitely.\n */\nexport const MAX_AUTH_WINDOW_SEC = 3600;\n\n/** Maps a CAIP-2 network id (e.g. \"eip155:8453\") to its numeric chainId. */\nexport function chainIdFromCaip2(network: string): number {\n  const parts = network.split(\":\");\n  if (parts.length !== 2 || parts[0] !== \"eip155\") {\n    throw new Error(`unsupported CAIP-2 network: ${network}`);\n  }\n  const id = Number(parts[1]);\n  if (!Number.isInteger(id) || id <= 0) {\n    throw new Error(`invalid CAIP-2 chain id: ${network}`);\n  }\n  return id;\n}\n\n/**\n * Decode a base64 header as UTF-8 (atob → char-code bytes → TextDecoder(\"utf-8\")).\n * The backend encodes both PAYMENT-REQUIRED and PAYMENT-RESPONSE with base64/UTF-8 and\n * documents this exact mirror decode; a bare `atob()` decodes Latin-1, which corrupts\n * any non-ASCII code point (e.g. a future \"USD₮\" asset name). Byte-identical for ASCII.\n */\nexport function decodeBase64Utf8(b64: string): string {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);\n  return new TextDecoder(\"utf-8\").decode(bytes);\n}\n\n/** EIP-712 typed-data shape shared with the server's EIP-712 verifier. */\nconst REQUEST_TYPES = {\n  Request: [\n    { name: \"method\", type: \"string\" },\n    { name: \"path\", type: \"string\" },\n    // host binds the signature to one deployment (prevents cross-deployment replay) —\n    // must match the backend's EIP-712 type definitions exactly, or every identity op fails to verify.\n    { name: \"host\", type: \"string\" },\n    { name: \"nonce\", type: \"bytes32\" },\n    { name: \"timestamp\", type: \"uint256\" },\n  ],\n} as const;\n\n/** Identity headers sent on free/credit operations. */\nexport interface IdentityHeaders {\n  \"X-AgentKV-Signature\": string;\n  \"X-AgentKV-Nonce\": string;\n  \"X-AgentKV-Timestamp\": string;\n}\n\n/**\n * Bearer auth header for account-key mode. The opaque `ak_…` token IS the\n * capability: the server hashes it to name the account's storage and debits its\n * prepaid credits. NO x402, NO EIP-712 — this header replaces both. The raw key\n * travels in the clear over TLS exactly like any bearer token; never log it.\n */\nexport function buildBearerHeaders(accountKey: string): Record<string, string> {\n  return { Authorization: `Bearer ${accountKey}` };\n}\n\n/** Current unix time in whole seconds. */\nexport function nowSec(): number {\n  return Math.floor(Date.now() / 1000);\n}\n\n/** EIP-712 typed-data types for EIP-3009 transferWithAuthorization. */\nconst TRANSFER_WITH_AUTHORIZATION_TYPES = {\n  TransferWithAuthorization: [\n    { name: \"from\", type: \"address\" },\n    { name: \"to\", type: \"address\" },\n    { name: \"value\", type: \"uint256\" },\n    { name: \"validAfter\", type: \"uint256\" },\n    { name: \"validBefore\", type: \"uint256\" },\n    { name: \"nonce\", type: \"bytes32\" },\n  ],\n} as const;\n\n/** Each PAYMENT-REQUIRED accept is a full v2 PaymentRequirements. */\ntype ChallengeAccept = PaymentRequirements;\n\n/** Decoded PAYMENT-REQUIRED challenge body. */\ninterface PaymentRequiredChallenge {\n  x402Version: number;\n  accepts: ChallengeAccept[];\n}\n\n/**\n * Decode and validate a base64-encoded PAYMENT-REQUIRED challenge header.\n */\nfunction decodeChallenge(paymentRequiredHeader: string): PaymentRequiredChallenge {\n  let json: string;\n  try {\n    json = decodeBase64Utf8(paymentRequiredHeader);\n  } catch {\n    throw new Error(\"PAYMENT-REQUIRED header is not valid base64\");\n  }\n  const parsed = JSON.parse(json) as PaymentRequiredChallenge;\n  if (!parsed || !Array.isArray(parsed.accepts)) {\n    throw new Error(\"invalid PAYMENT-REQUIRED challenge: missing accepts array\");\n  }\n  return parsed;\n}\n\n/** Pick the exact-scheme requirement, by amount when several tiers are offered. */\nfunction selectRequirement(accepts: ChallengeAccept[], amountAtomic?: number): ChallengeAccept {\n  const exact = accepts.filter((a) => a.scheme === \"exact\");\n  if (exact.length === 0)\n    throw new Error(\"no acceptable x402 exact-scheme requirement in challenge\");\n  if (amountAtomic !== undefined) {\n    // Use the first exact requirement as the asset/payTo/network/domain template and\n    // override the amount — supports any top-off / deposit amount, not just advertised tiers.\n    return { ...exact[0], amount: String(amountAtomic) };\n  }\n  if (exact.length > 1)\n    throw new Error(\n      \"ambiguous PAYMENT-REQUIRED challenge: multiple exact requirements; specify an amount\",\n    );\n  return exact[0];\n}\n\n/**\n * Enforce that a server-supplied challenge targets the client's configured network AND its\n * canonical USDC contract. Money movement must never be dictated solely by the server: a\n * compromised or spoofed worker could otherwise return a challenge for a different chain\n * (e.g. hand a Base-configured client an Arbitrum challenge, draining the SAME EOA's\n * Arbitrum USDC) or a non-canonical token address, and the client would sign it. This is\n * the payment-path mirror of the host-binding on identity signatures and the domain pin.\n */\nfunction assertNetworkParity(req: ChallengeAccept, expectedNetwork: string): void {\n  if (req.network !== expectedNetwork) {\n    throw new AgentXError(\n      `payment challenge network \"${req.network}\" does not match client network \"${expectedNetwork}\"`,\n      \"network_mismatch\",\n      0,\n    );\n  }\n  const asset = getDefaultAsset(expectedNetwork as `${string}:${string}`);\n  if (getAddress(req.asset) !== getAddress(asset.address)) {\n    throw new AgentXError(\n      `payment challenge asset \"${req.asset}\" is not the canonical USDC for ${expectedNetwork}`,\n      \"asset_mismatch\",\n      0,\n    );\n  }\n}\n\n/** Decode a challenge and return the chosen requirement's price in USD. */\nexport function challengePriceUsd(\n  paymentRequiredHeader: string,\n  amountAtomic?: number,\n  expectedNetwork?: string,\n): number {\n  const { accepts } = decodeChallenge(paymentRequiredHeader);\n  const req = selectRequirement(accepts, amountAtomic);\n  if (expectedNetwork) assertNetworkParity(req, expectedNetwork);\n  return Number(req.amount) / 1_000_000;\n}\n\n/**\n * Build the base64 PAYMENT-SIGNATURE header from a PAYMENT-REQUIRED challenge.\n *\n * Decodes the v2 challenge, selects the matching `exact`-scheme requirement\n * (by `opts.amountAtomic` when several tiers are offered), and signs an EIP-3009\n * transferWithAuthorization payload (validAfter=0, validBefore=now+window) with\n * the viem account. `opts.nonce` pins a deterministic EIP-3009 nonce so retries\n * reuse the same authorization.\n *\n * Returns the base64-encoded JSON payload as the PAYMENT-SIGNATURE value.\n */\nexport async function buildPaymentHeader(\n  account: Signer,\n  paymentRequiredHeader: string,\n  opts?: {\n    nonce?: `0x${string}`;\n    amountAtomic?: number;\n    expectedNetwork?: string;\n    /** Pin the recipient: reject the challenge unless its `payTo` equals this address (high-value ops). */\n    expectedPayTo?: string;\n  },\n): Promise<string> {\n  const { x402Version, accepts } = decodeChallenge(paymentRequiredHeader);\n\n  const req = selectRequirement(accepts, opts?.amountAtomic);\n\n  // Pin the money-moving challenge to the client's configured network + canonical asset\n  // BEFORE signing anything (a signed EIP-3009 authorization is a bearer instrument).\n  if (opts?.expectedNetwork) assertNetworkParity(req, opts.expectedNetwork);\n  // Optional recipient pin: the client can't know the \"correct\" payTo in general (the amount\n  // ceiling is the primary defense), but for high-value ops a caller may pin an expected one.\n  if (opts?.expectedPayTo && getAddress(req.payTo) !== getAddress(opts.expectedPayTo)) {\n    throw new AgentXError(\n      `payment challenge payTo \"${req.payTo}\" does not match expected \"${opts.expectedPayTo}\"`,\n      \"payto_mismatch\",\n      0,\n    );\n  }\n\n  const chainId = chainIdFromCaip2(req.network);\n  // Look up EIP-712 domain info for the token (name/version).\n  // Cast to the x402 Network template-literal type.\n  const asset = getDefaultAsset(req.network as `${string}:${string}`);\n\n  const nonce = opts?.nonce ?? freshNonce();\n  const now = nowSec();\n  // Clamp the signed window: never sign an authorization valid longer than MAX_AUTH_WINDOW_SEC,\n  // regardless of the server-supplied maxTimeoutSeconds.\n  const window = Math.min(req.maxTimeoutSeconds ?? 300, MAX_AUTH_WINDOW_SEC);\n  const validBefore = String(now + window);\n\n  const authorization = {\n    from: getAddress(account.address),\n    to: getAddress(req.payTo),\n    value: req.amount,\n    validAfter: \"0\",\n    validBefore,\n    nonce,\n  };\n\n  const signature = await account.signTypedData({\n    domain: {\n      name: asset.name,\n      version: asset.version,\n      chainId,\n      verifyingContract: getAddress(req.asset),\n    },\n    types: TRANSFER_WITH_AUTHORIZATION_TYPES,\n    primaryType: \"TransferWithAuthorization\",\n    message: {\n      from: getAddress(account.address),\n      to: getAddress(req.payTo),\n      value: BigInt(req.amount),\n      validAfter: BigInt(0),\n      validBefore: BigInt(validBefore),\n      nonce,\n    },\n  });\n\n  // v2 PaymentPayload: the chosen requirement + the signed EIP-3009 authorization,\n  // encoded with the SDK so the server's decodePaymentSignatureHeader round-trips.\n  const paymentPayload: PaymentPayload = {\n    x402Version,\n    accepted: req,\n    payload: {\n      authorization,\n      signature,\n    },\n  };\n\n  return encodePaymentSignatureHeader(paymentPayload);\n}\n\n/**\n * Build EIP-712 identity headers for a free/credit op (delete, balance).\n * Signs the Request typed data with a fresh nonce + timestamp so the server\n * can recover the wallet address and enforce replay protection.\n */\nexport async function buildIdentityHeaders(\n  account: Signer,\n  args: { method: string; path: string; host: string; network: string },\n): Promise<IdentityHeaders> {\n  const nonce = freshNonce();\n  const timestamp = nowSec();\n  const signature = await account.signTypedData({\n    domain: {\n      name: EIP712_DOMAIN_NAME,\n      version: EIP712_DOMAIN_VERSION,\n      chainId: chainIdFromCaip2(args.network),\n    },\n    types: REQUEST_TYPES,\n    primaryType: \"Request\",\n    message: {\n      method: args.method,\n      path: args.path,\n      host: args.host,\n      nonce,\n      timestamp: BigInt(timestamp),\n    },\n  });\n\n  return {\n    \"X-AgentKV-Signature\": signature,\n    \"X-AgentKV-Nonce\": nonce,\n    \"X-AgentKV-Timestamp\": String(timestamp),\n  };\n}\n","// core/src/retry.ts\n//\n// Pure retry helpers factored out of `AgentKV#fetchWithRetry` / `AgentKV#retryDelay`.\n// The original methods only ever read `this.maxRetries` (a plain number) and called\n// `this.retryDelay` — no other instance state — so they extract cleanly into pure\n// functions parameterized by `maxRetries`. `AgentKV` now delegates to these via thin\n// private wrappers so every existing call site (`this.fetchWithRetry(...)`) is unchanged.\n\nimport { AgentXError } from \"./errors\";\n\n/** Default per-attempt request timeout (ms). A hung-open connection would otherwise wedge an op forever. */\nexport const DEFAULT_TIMEOUT_MS = 30_000;\n\n/** Tuning knobs for {@link fetchWithRetry}. All optional; sensible defaults. */\nexport interface RetryOptions {\n  /** Per-ATTEMPT timeout in ms (via `AbortSignal.timeout`). Default 30_000. Pass 0 to disable. */\n  timeoutMs?: number;\n  /** Injectable `fetch` for proxies / instrumentation / tests. Defaults to the global `fetch`. */\n  fetchImpl?: typeof fetch;\n  /** Caller `AbortSignal` to cancel the whole operation (abort is surfaced immediately, never retried). */\n  signal?: AbortSignal;\n}\n\n/** Combine 0+ AbortSignals into one that aborts when any input does. Undefined if none supplied. */\nfunction combineSignals(signals: (AbortSignal | undefined)[]): AbortSignal | undefined {\n  const present = signals.filter((s): s is AbortSignal => !!s);\n  if (present.length === 0) return undefined;\n  if (present.length === 1) return present[0];\n  // AbortSignal.any is Node >=20.3 / modern browsers; fall back to a manual combiner for Node 20.0–20.2.\n  if (typeof AbortSignal.any === \"function\") return AbortSignal.any(present);\n  const ctrl = new AbortController();\n  for (const s of present) {\n    if (s.aborted) {\n      ctrl.abort(s.reason);\n      break;\n    }\n    s.addEventListener(\"abort\", () => ctrl.abort(s.reason), { once: true });\n  }\n  return ctrl.signal;\n}\n\n/** Release a transient response's body so its socket returns to the pool before we retry. */\nasync function drainBody(res: Response): Promise<void> {\n  try {\n    await res.body?.cancel();\n  } catch {\n    // best-effort — a body that can't be cancelled is not worth failing the retry over.\n  }\n}\n\n/**\n * Issue a request with bounded retry on TRANSIENT failures only: a thrown\n * fetch (network error / lost response / per-attempt timeout) or a 5xx/429\n * response. `build()` is re-invoked per attempt so a caller can re-sign\n * per-attempt state (e.g. a fresh identity nonce) while a stable Idempotency-Key\n * (and pinned EIP-3009 nonce on paid ops) makes a retry of an already-processed\n * request dedupe server-side — so a lost response that the server already charged\n * is recovered without a second charge. NOT retried: any 2xx/4xx (incl. a 402\n * credit->pay handoff, 401, 404) — returned as-is; and a caller-initiated abort,\n * which is surfaced immediately. Honors `Retry-After` (delta-seconds or HTTP-date).\n * Each attempt is bounded by `opts.timeoutMs` (default 30s).\n */\nexport async function fetchWithRetry(\n  url: string,\n  build: () => RequestInit | Promise<RequestInit>,\n  maxRetries: number,\n  opts: RetryOptions = {},\n): Promise<Response> {\n  const doFetch = opts.fetchImpl ?? fetch;\n  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  for (let attempt = 0; ; attempt++) {\n    try {\n      const init = await build();\n      const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;\n      const signal = combineSignals([init.signal ?? undefined, opts.signal, timeoutSignal]);\n      const res = await doFetch(url, { ...init, signal });\n      // Retry TRANSIENT statuses: 5xx, and 429 (rate limited).\n      const transient = (res.status >= 500 && res.status <= 599) || res.status === 429;\n      if (transient && attempt < maxRetries) {\n        await drainBody(res);\n        await retryDelay(attempt, res);\n        continue;\n      }\n      return res;\n    } catch (err) {\n      // A caller-initiated cancel is intentional, not transient — surface it immediately.\n      if (opts.signal?.aborted) {\n        throw err instanceof Error ? err : new AgentXError(String(err), \"aborted\", 0);\n      }\n      if (attempt < maxRetries) {\n        await retryDelay(attempt);\n        continue;\n      }\n      throw err instanceof Error ? err : new AgentXError(String(err), \"network_error\", 0);\n    }\n  }\n}\n\n/**\n * Short, bounded backoff between retries. Base is 50ms, 100ms, ... capped at 500ms, with\n * full jitter (each delay uniformly in [50%, 100%] of the base) to avoid a synchronized\n * retry herd under a 5xx/429 storm. If the response carries a `Retry-After` — delta-seconds\n * OR an HTTP-date — honor it up to a 2s cap so a re-sent paid authorization still stays\n * comfortably within its validBefore window (jitter is skipped when the server dictates a delay).\n */\nexport function retryDelay(attempt: number, res?: Response): Promise<void> {\n  const base = Math.min(500, 50 * 2 ** attempt);\n  let ms = Math.round(base * (0.5 + Math.random() * 0.5));\n  const retryAfter = res?.headers.get(\"Retry-After\");\n  if (retryAfter) {\n    const secs = Number(retryAfter);\n    if (Number.isFinite(secs) && secs >= 0) {\n      ms = Math.min(2000, secs * 1000); // delta-seconds form\n    } else {\n      const when = Date.parse(retryAfter); // HTTP-date form\n      if (Number.isFinite(when)) ms = Math.min(2000, Math.max(0, when - Date.now()));\n    }\n  }\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentx402-ai/core",
+  "version": "0.1.0",
+  "description": "Shared auth/pay/usage/error/retry plumbing extracted from @agentkv/client, for reuse across agentx402 service SDKs",
+  "license": "MIT",
+  "author": "The AgentKV Authors <contact@agentx402.ai>",
+  "homepage": "https://github.com/agentx402-ai/agentkv#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentx402-ai/agentkv.git",
+    "directory": "core"
+  },
+  "bugs": {
+    "url": "https://github.com/agentx402-ai/agentkv/issues"
+  },
+  "keywords": [
+    "agentx402",
+    "x402",
+    "eip-3009",
+    "eip-712",
+    "viem",
+    "sdk-core"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "tsc --noEmit && vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@x402/core": "^2.16.0",
+    "@x402/evm": "^2.16.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}