yeetful 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.0
+
+- **New: `yeetful/agent` — the agent expense account.** `yeetful({ wallet, grant })`
+  returns a grant-aware paid `fetch` that enforces an allowlist + per-call/per-day/
+  lifetime USD caps + expiry **before** signing any x402 payment, pays via the
+  existing client, and emits a `Receipt` per call. Throws a typed `GrantError`
+  (`NOT_ALLOWED` / `OVER_PER_CALL` / `BUDGET_EXCEEDED` / `EXPIRED` / `REVOKED`) and
+  exposes `spentTodayUsd()` / `remainingTodayUsd()` / `spentTotalUsd()`.
+- Repositioned the package around spend-controlled x402 for AI agents; the
+  existing `client` / `server` / `next` / `express` entries are unchanged.
+
+## 0.1.0
+
+- Initial release: drop-in x402 client + server (`gate`/`withPayment`/
+  `paymentRequired`) + facilitator helpers.

package/README.md

@@ -1,24 +1,17 @@
 # yeetful
 
-**Drop-in [x402](https://www.x402.org) payments for your APIs and clients.** Gate any HTTP route behind a stablecoin micropayment in a few lines — no accounts, no API keys, no webhooks. Built for [Yeetful](https://yeetful.com), MIT-licensed, works anywhere TypeScript does.
+**Spend-controlled [x402](https://www.x402.org) for AI agents.** Give an agent an *expense account* — an allowlist of endpoints plus per-call / per-day budgets — and let it pay any x402 service with no API keys. Enforcement is local and instant; every call emits a receipt. Built for [Yeetful](https://yeetful.com), MIT-licensed, works anywhere TypeScript does.
 
 ```bash
 npm install yeetful viem
 ```
 
-```ts
-// Server — gate a route for 1¢ USDC
-import { withPayment } from 'yeetful/next'
+## Agent expense account
 
-export const GET = withPayment(
-  { price: '0.01', recipient: '0xYourAddress', network: 'base' },
-  async () => Response.json({ secret: 'gm' })
-)
-```
+Wrap your agent's calls in one grant-aware `pay()`. It refuses anything off the allowlist or over budget **before** signing a payment — your guardrail against runaway loops, bugs, and prompt-injected tool calls.
 
 ```ts
-// Client — auto-pay when a server returns 402
-import { createPaymentClient } from 'yeetful/client'
+import { yeetful, GrantError } from 'yeetful/agent'
 import { createWalletClient, http } from 'viem'
 import { base } from 'viem/chains'
 import { privateKeyToAccount } from 'viem/accounts'
@@ -29,6 +22,51 @@ const wallet = createWalletClient({
   transport: http(),
 })
 
+const pay = yeetful({
+  wallet,
+  grant: {
+    allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
+    perCallUsd: 0.05,
+    perDayUsd: 2,
+    expiresAt: '2026-12-31',
+  },
+  onReceipt: (r) => console.log(r.host, `$${r.amountUsd}`, r.txHash ?? r.note),
+})
+
+try {
+  const res = await pay('https://tripadvisor.x402.paysponge.com/api/v1/location/search?searchQuery=tokyo')
+  console.log(await res.json())
+  console.log(`spent today: $${pay.spentTodayUsd()} / left: $${pay.remainingTodayUsd()}`)
+} catch (e) {
+  // GrantError.code: NOT_ALLOWED | OVER_PER_CALL | BUDGET_EXCEEDED | EXPIRED | REVOKED
+  if (e instanceof GrantError) console.error(`blocked: ${e.code}`)
+}
+```
+
+One grant authorizes **many** endpoints (the allowlist). Use `onReceipt` to stream the audit trail to your dashboard or the Yeetful control plane.
+
+> **Local vs. hard enforcement.** This SDK enforces the grant in-process — ideal for governing *your own* agents (runaway loops, bugs, injected tool calls). For adversarial guarantees, back the grant with an on-chain Coinbase **Spend Permission** so the wallet contract caps spend regardless of the SDK.
+
+---
+
+## Low-level x402 primitives
+
+The agent wrapper is built on a full x402 toolkit you can use directly:
+
+```ts
+// Server — gate a route for 1¢ USDC
+import { withPayment } from 'yeetful/next'
+
+export const GET = withPayment(
+  { price: '0.01', recipient: '0xYourAddress', network: 'base' },
+  async () => Response.json({ secret: 'gm' })
+)
+```
+
+```ts
+// Client — auto-pay when a server returns 402 (no grant enforcement)
+import { createPaymentClient } from 'yeetful/client'
+
 const pay = createPaymentClient({ wallet })
 const res = await pay('https://api.example.com/premium')
 console.log(await res.json()) // → { secret: 'gm' }

package/dist/agent.cjs

@@ -0,0 +1,258 @@
+'use strict';
+
+// src/utils.ts
+var utf8Encoder = new TextEncoder();
+var utf8Decoder = new TextDecoder();
+function encodePayment(value) {
+  const bytes = utf8Encoder.encode(JSON.stringify(value));
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function decodePayment(b64) {
+  let bytes;
+  if (typeof Buffer !== "undefined") {
+    bytes = new Uint8Array(Buffer.from(b64, "base64"));
+  } else {
+    const binary = atob(b64);
+    bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  }
+  return JSON.parse(utf8Decoder.decode(bytes));
+}
+function randomNonce() {
+  const bytes = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(bytes);
+  return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/client.ts
+function createPaymentClient(options) {
+  const baseFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  return async function payFetch(input, init = {}) {
+    const first = await baseFetch(input, init);
+    if (first.status !== 402) return first;
+    const requirements = await parsePaymentRequired(first);
+    const requirement = selectRequirement(requirements.accepts, options);
+    if (!requirement) {
+      throw new PaymentError("No acceptable payment requirement matched client constraints", requirements);
+    }
+    if (options.onPaymentRequired) {
+      const approved = await options.onPaymentRequired(requirement);
+      if (!approved) throw new PaymentError("Payment rejected by user", requirements);
+    }
+    const payment = await signPayment(options.wallet, requirement);
+    const headers = new Headers(init.headers);
+    headers.set("X-PAYMENT", encodePayment(payment));
+    return baseFetch(input, { ...init, headers });
+  };
+}
+var PaymentError = class extends Error {
+  requirements;
+  constructor(message, requirements) {
+    super(message);
+    this.name = "PaymentError";
+    this.requirements = requirements;
+  }
+};
+async function parsePaymentRequired(res) {
+  try {
+    return await res.clone().json();
+  } catch {
+    throw new PaymentError("402 response did not contain a valid x402 discovery body");
+  }
+}
+function selectRequirement(accepts, opts) {
+  const filtered = accepts.filter((a) => a.scheme === "exact").filter((a) => !opts.allowedNetworks || opts.allowedNetworks.includes(a.network)).filter((a) => !opts.maxAmountAtomic || BigInt(a.maxAmountRequired) <= opts.maxAmountAtomic);
+  return filtered.sort(
+    (a, b) => BigInt(a.maxAmountRequired) < BigInt(b.maxAmountRequired) ? -1 : 1
+  )[0];
+}
+async function signPayment(wallet, requirement) {
+  const account = wallet.account;
+  if (!account) throw new PaymentError("Wallet has no account attached");
+  const now = Math.floor(Date.now() / 1e3);
+  const validAfter = BigInt(now - 60);
+  const validBefore = BigInt(now + (requirement.maxTimeoutSeconds ?? 600));
+  const nonce = randomNonce();
+  const tokenName = requirement.extra?.name ?? "USD Coin";
+  const tokenVersion = requirement.extra?.version ?? "2";
+  const signature = await wallet.signTypedData({
+    account,
+    domain: {
+      name: tokenName,
+      version: tokenVersion,
+      chainId: chainIdForNetwork(requirement.network),
+      verifyingContract: requirement.asset
+    },
+    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" }
+      ]
+    },
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: account.address,
+      to: requirement.payTo,
+      value: BigInt(requirement.maxAmountRequired),
+      validAfter,
+      validBefore,
+      nonce
+    }
+  });
+  return {
+    x402Version: 1,
+    scheme: "exact",
+    network: requirement.network,
+    payload: {
+      signature,
+      authorization: {
+        from: account.address,
+        to: requirement.payTo,
+        value: requirement.maxAmountRequired,
+        validAfter: validAfter.toString(),
+        validBefore: validBefore.toString(),
+        nonce
+      }
+    }
+  };
+}
+function chainIdForNetwork(network) {
+  switch (network) {
+    case "base":
+      return 8453;
+    case "base-sepolia":
+      return 84532;
+    case "ethereum":
+      return 1;
+    case "optimism":
+      return 10;
+    case "arbitrum":
+      return 42161;
+    case "polygon":
+      return 137;
+  }
+}
+
+// src/agent.ts
+var GrantError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "GrantError";
+  }
+  code;
+};
+function expiryMs(expiresAt) {
+  if (expiresAt == null) return Infinity;
+  if (expiresAt instanceof Date) return expiresAt.getTime();
+  if (typeof expiresAt === "number") return expiresAt;
+  const t = new Date(expiresAt).getTime();
+  return Number.isNaN(t) ? Infinity : t;
+}
+function utcDayIndex(ms) {
+  return Math.floor(ms / 864e5);
+}
+function hostOf(input) {
+  const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function txHashOf(res) {
+  const header = res.headers.get("x-payment-response");
+  if (!header) return void 0;
+  try {
+    return decodePayment(header).transaction;
+  } catch {
+    return void 0;
+  }
+}
+function yeetful(options) {
+  const { wallet, grant, onReceipt, onEvent } = options;
+  const log = onEvent ?? (() => {
+  });
+  let spentToday = 0;
+  let spentTotal = 0;
+  let dayIndex = utcDayIndex(Date.now());
+  const emit = (r) => {
+    void Promise.resolve(onReceipt?.(r)).catch(() => {
+    });
+  };
+  const deny = (host, code, msg) => {
+    emit({ host, amountUsd: 0, ok: false, note: code, ts: Date.now() });
+    log(`\u2717 ${host} \u2014 ${code}: ${msg}`);
+    throw new GrantError(code, msg);
+  };
+  const pay = async function pay2(input, init = {}) {
+    const today = utcDayIndex(Date.now());
+    if (today !== dayIndex) {
+      dayIndex = today;
+      spentToday = 0;
+    }
+    const host = hostOf(input);
+    if ((grant.status ?? "active") === "revoked") deny(host, "REVOKED", "grant is revoked");
+    if (Date.now() > expiryMs(grant.expiresAt)) deny(host, "EXPIRED", "grant has expired");
+    if (!grant.allow.map((h) => h.toLowerCase()).includes(host)) {
+      deny(host, "NOT_ALLOWED", `${host} is not in this grant's allowlist`);
+    }
+    let pricedUsd = 0;
+    const client = createPaymentClient({
+      wallet,
+      fetch: options.fetch,
+      allowedNetworks: options.allowedNetworks,
+      // Per-call enforcement lives in the hook (not maxAmountAtomic) so an
+      // over-cap call surfaces a clean GrantError instead of a filtered no-match.
+      onPaymentRequired: (req) => {
+        const price = Number(req.maxAmountRequired) / 1e6;
+        if (price > grant.perCallUsd) {
+          deny(host, "OVER_PER_CALL", `$${price.toFixed(4)} exceeds per-call cap $${grant.perCallUsd}`);
+        }
+        if (spentToday + price > grant.perDayUsd) {
+          deny(host, "BUDGET_EXCEEDED", `$${(spentToday + price).toFixed(2)} exceeds today's cap $${grant.perDayUsd}`);
+        }
+        if (grant.totalUsd != null && spentTotal + price > grant.totalUsd) {
+          deny(host, "BUDGET_EXCEEDED", `$${(spentTotal + price).toFixed(2)} exceeds lifetime cap $${grant.totalUsd}`);
+        }
+        pricedUsd = price;
+        return true;
+      }
+    });
+    let res;
+    try {
+      res = await client(input, init);
+    } catch (err) {
+      if (err instanceof GrantError) throw err;
+      const note = err instanceof PaymentError ? "payment-failed" : "error";
+      emit({ host, amountUsd: 0, ok: false, note, ts: Date.now() });
+      throw err;
+    }
+    if (pricedUsd > 0) {
+      spentToday += pricedUsd;
+      spentTotal += pricedUsd;
+    }
+    const txHash = txHashOf(res);
+    emit({ host, amountUsd: pricedUsd, ok: true, txHash, note: "settled", ts: Date.now() });
+    log(`\u2713 ${host} \u2014 $${pricedUsd.toFixed(4)} \xB7 today $${spentToday.toFixed(2)}/$${grant.perDayUsd}`);
+    return res;
+  };
+  pay.spentTodayUsd = () => spentToday;
+  pay.remainingTodayUsd = () => Math.max(0, grant.perDayUsd - spentToday);
+  pay.spentTotalUsd = () => spentTotal;
+  return pay;
+}
+
+exports.GrantError = GrantError;
+exports.yeetful = yeetful;
+//# sourceMappingURL=agent.cjs.map
+//# sourceMappingURL=agent.cjs.map

package/dist/agent.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/client.ts","../src/agent.ts"],"names":["pay"],"mappings":"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","file":"agent.cjs","sourcesContent":["import type { X402Network } from './types.js'\n\nconst USDC_BY_NETWORK: Record<X402Network, `0x${string}`> = {\n  base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',\n  'base-sepolia': '0x036CbD53842c5426634e7929541eC2318f3dCF7e',\n  ethereum: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',\n  optimism: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85',\n  arbitrum: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',\n  polygon: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',\n}\n\nexport const USDC_DECIMALS = 6\n\n/** Returns the canonical USDC contract address for a supported network. */\nexport function usdcAddress(network: X402Network): `0x${string}` {\n  return USDC_BY_NETWORK[network]\n}\n\n/**\n * Convert a human-friendly USD amount (e.g. \"0.01\") into atomic USDC units.\n * Fixed-point to avoid float drift — safer than Number math for payments.\n */\nexport function usdToAtomic(amount: string | number, decimals = USDC_DECIMALS): string {\n  const str = typeof amount === 'number' ? amount.toString() : amount\n  if (!/^\\d+(\\.\\d+)?$/.test(str)) {\n    throw new Error(`Invalid amount: ${str}`)\n  }\n  const [whole, frac = ''] = str.split('.')\n  const padded = frac.slice(0, decimals).padEnd(decimals, '0')\n  return (BigInt(whole ?? '0') * 10n ** BigInt(decimals) + BigInt(padded || '0')).toString()\n}\n\nconst utf8Encoder = new TextEncoder()\nconst utf8Decoder = new TextDecoder()\n\n/** Base64 encode a JSON value — works in Node 18+ and browsers. */\nexport function encodePayment(value: unknown): string {\n  const bytes = utf8Encoder.encode(JSON.stringify(value))\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(bytes).toString('base64')\n  }\n  let binary = ''\n  for (const byte of bytes) binary += String.fromCharCode(byte)\n  return btoa(binary)\n}\n\n/** Base64 decode a payment header value back into JSON. */\nexport function decodePayment<T = unknown>(b64: string): T {\n  let bytes: Uint8Array\n  if (typeof Buffer !== 'undefined') {\n    bytes = new Uint8Array(Buffer.from(b64, 'base64'))\n  } else {\n    const binary = atob(b64)\n    bytes = new Uint8Array(binary.length)\n    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)\n  }\n  return JSON.parse(utf8Decoder.decode(bytes)) as T\n}\n\n/** Generate a random 32-byte nonce as a 0x-prefixed hex string. */\nexport function randomNonce(): `0x${string}` {\n  const bytes = new Uint8Array(32)\n  globalThis.crypto.getRandomValues(bytes)\n  return ('0x' + Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')) as `0x${string}`\n}\n","import type { Address, Hex, WalletClient } from 'viem'\nimport type {\n  PaymentPayload,\n  PaymentRequiredResponse,\n  PaymentRequirement,\n  X402Network,\n} from './types.js'\nimport { encodePayment, randomNonce } from './utils.js'\n\nexport interface ClientOptions {\n  /** A viem WalletClient able to sign EIP-712 typed data. */\n  wallet: WalletClient\n  /** Underlying fetch to wrap (defaults to global fetch). */\n  fetch?: typeof fetch\n  /**\n   * Hook called before signing. Return `false` to reject the payment.\n   * Useful for showing a confirmation UI to the user.\n   */\n  onPaymentRequired?: (requirement: PaymentRequirement) => boolean | Promise<boolean>\n  /** Only allow payments up to this atomic-units cap. Safety belt. */\n  maxAmountAtomic?: bigint\n  /** Restrict to specific networks (defaults to all). */\n  allowedNetworks?: X402Network[]\n}\n\n/**\n * Create a fetch wrapper that transparently handles x402 payments.\n *\n * On a 402 response, it picks the cheapest acceptable requirement,\n * signs an EIP-3009 authorization with the provided wallet, and retries\n * the request with an `X-PAYMENT` header.\n *\n * @example\n * ```ts\n * const pay = createPaymentClient({ wallet })\n * const res = await pay('https://api.example.com/premium')\n * ```\n */\nexport function createPaymentClient(options: ClientOptions) {\n  const baseFetch = options.fetch ?? globalThis.fetch.bind(globalThis)\n\n  return async function payFetch(\n    input: string | URL | Request,\n    init: RequestInit = {},\n  ): Promise<Response> {\n    const first = await baseFetch(input, init)\n    if (first.status !== 402) return first\n\n    const requirements = await parsePaymentRequired(first)\n    const requirement = selectRequirement(requirements.accepts, options)\n    if (!requirement) {\n      throw new PaymentError('No acceptable payment requirement matched client constraints', requirements)\n    }\n\n    if (options.onPaymentRequired) {\n      const approved = await options.onPaymentRequired(requirement)\n      if (!approved) throw new PaymentError('Payment rejected by user', requirements)\n    }\n\n    const payment = await signPayment(options.wallet, requirement)\n    const headers = new Headers(init.headers)\n    headers.set('X-PAYMENT', encodePayment(payment))\n\n    return baseFetch(input, { ...init, headers })\n  }\n}\n\nexport class PaymentError extends Error {\n  readonly requirements?: PaymentRequiredResponse\n  constructor(message: string, requirements?: PaymentRequiredResponse) {\n    super(message)\n    this.name = 'PaymentError'\n    this.requirements = requirements\n  }\n}\n\nasync function parsePaymentRequired(res: Response): Promise<PaymentRequiredResponse> {\n  try {\n    return (await res.clone().json()) as PaymentRequiredResponse\n  } catch {\n    throw new PaymentError('402 response did not contain a valid x402 discovery body')\n  }\n}\n\nfunction selectRequirement(\n  accepts: PaymentRequirement[],\n  opts: ClientOptions,\n): PaymentRequirement | undefined {\n  const filtered = accepts\n    .filter((a) => a.scheme === 'exact')\n    .filter((a) => !opts.allowedNetworks || opts.allowedNetworks.includes(a.network))\n    .filter((a) => !opts.maxAmountAtomic || BigInt(a.maxAmountRequired) <= opts.maxAmountAtomic)\n\n  return filtered.sort((a, b) =>\n    BigInt(a.maxAmountRequired) < BigInt(b.maxAmountRequired) ? -1 : 1,\n  )[0]\n}\n\n/** Sign an EIP-3009 `TransferWithAuthorization` for the given requirement. */\nexport async function signPayment(\n  wallet: WalletClient,\n  requirement: PaymentRequirement,\n): Promise<PaymentPayload> {\n  const account = wallet.account\n  if (!account) throw new PaymentError('Wallet has no account attached')\n\n  const now = Math.floor(Date.now() / 1000)\n  const validAfter = BigInt(now - 60)\n  const validBefore = BigInt(now + (requirement.maxTimeoutSeconds ?? 600))\n  const nonce = randomNonce()\n\n  const tokenName =\n    (requirement.extra?.name as string | undefined) ?? 'USD Coin'\n  const tokenVersion =\n    (requirement.extra?.version as string | undefined) ?? '2'\n\n  const signature = (await wallet.signTypedData({\n    account,\n    domain: {\n      name: tokenName,\n      version: tokenVersion,\n      chainId: chainIdForNetwork(requirement.network),\n      verifyingContract: requirement.asset,\n    },\n    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    },\n    primaryType: 'TransferWithAuthorization',\n    message: {\n      from: account.address as Address,\n      to: requirement.payTo,\n      value: BigInt(requirement.maxAmountRequired),\n      validAfter,\n      validBefore,\n      nonce,\n    },\n  })) as Hex\n\n  return {\n    x402Version: 1,\n    scheme: 'exact',\n    network: requirement.network,\n    payload: {\n      signature,\n      authorization: {\n        from: account.address as Address,\n        to: requirement.payTo,\n        value: requirement.maxAmountRequired,\n        validAfter: validAfter.toString(),\n        validBefore: validBefore.toString(),\n        nonce,\n      },\n    },\n  }\n}\n\nfunction chainIdForNetwork(network: X402Network): number {\n  switch (network) {\n    case 'base':\n      return 8453\n    case 'base-sepolia':\n      return 84532\n    case 'ethereum':\n      return 1\n    case 'optimism':\n      return 10\n    case 'arbitrum':\n      return 42161\n    case 'polygon':\n      return 137\n  }\n}\n","/**\n * yeetful/agent — the \"agent expense account.\"\n *\n * Wrap your agent's HTTP calls in a single grant-aware `pay()`. Before any x402\n * payment is signed it enforces a spend grant — an allowlist of hosts plus\n * per-call / per-day / lifetime USD caps and an expiry — then pays via the\n * standard x402 client and emits a receipt for every call.\n *\n * One grant authorizes MANY endpoints (the allowlist). It's a guardrail for\n * your own agents (runaway loops, bugs, prompt-injected tool calls) and the\n * receipt feed behind budgets + audit. Enforcement here is local + instant;\n * for hard, adversarial guarantees back the grant with an on-chain Spend\n * Permission (the wallet contract caps spend regardless of this SDK).\n *\n * @example\n * ```ts\n * import { yeetful } from 'yeetful/agent'\n *\n * const pay = yeetful({\n *   wallet,                                   // viem WalletClient\n *   grant: {\n *     allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],\n *     perCallUsd: 0.05,\n *     perDayUsd: 2,\n *     expiresAt: '2026-12-31',\n *   },\n *   onReceipt: (r) => console.log(r.host, r.amountUsd, r.txHash),\n * })\n *\n * const res = await pay('https://tripadvisor.x402.paysponge.com/api/v1/location/search?searchQuery=tokyo')\n * // throws GrantError on NOT_ALLOWED / OVER_PER_CALL / BUDGET_EXCEEDED / EXPIRED\n * ```\n */\n\nimport type { WalletClient } from 'viem'\nimport { createPaymentClient, PaymentError } from './client.js'\nimport { decodePayment } from './utils.js'\nimport type { PaymentRequirement, SettleResult, X402Network } from './types.js'\n\nexport type GrantViolation =\n  | 'EXPIRED'\n  | 'REVOKED'\n  | 'NOT_ALLOWED'\n  | 'OVER_PER_CALL'\n  | 'BUDGET_EXCEEDED'\n\nexport class GrantError extends Error {\n  constructor(\n    public code: GrantViolation,\n    message: string,\n  ) {\n    super(message)\n    this.name = 'GrantError'\n  }\n}\n\n/** A scoped spend authorization (mirrors the hosted SpendGrant). */\nexport interface GrantPolicy {\n  /** Optional id of the hosted grant this mirrors. */\n  id?: string\n  /** Exact hostnames this grant may pay (e.g. \"tripadvisor.x402.paysponge.com\"). */\n  allow: string[]\n  perCallUsd: number\n  perDayUsd: number\n  /** Optional lifetime cap across the life of this client instance. */\n  totalUsd?: number | null\n  /** Unix ms, ISO string, or Date. Omit for no expiry. */\n  expiresAt?: number | string | Date\n  /** 'active' | 'revoked'. Defaults to active. */\n  status?: string\n}\n\n/** A single authorization decision — the audit trail + x402 receipt. */\nexport interface Receipt {\n  host: string\n  amountUsd: number\n  ok: boolean\n  txHash?: string\n  /** \"settled\" on success, or the GrantViolation code on a denial. */\n  note: string\n  ts: number\n}\n\nexport interface AgentOptions {\n  /** viem WalletClient that signs the EIP-3009 payment. */\n  wallet: WalletClient\n  /** The spend grant to enforce. */\n  grant: GrantPolicy\n  /** Underlying fetch (defaults to global fetch). */\n  fetch?: typeof fetch\n  /** Restrict payments to specific networks (defaults to all). */\n  allowedNetworks?: X402Network[]\n  /** Called after every decision — wire this to your ledger / dashboard. */\n  onReceipt?: (receipt: Receipt) => void | Promise<void>\n  /** Human-readable progress logging. */\n  onEvent?: (message: string) => void\n}\n\nexport interface PayFn {\n  (input: string | URL | Request, init?: RequestInit): Promise<Response>\n  /** USD spent under this grant since UTC midnight (this client instance). */\n  spentTodayUsd(): number\n  /** USD remaining in today's budget. */\n  remainingTodayUsd(): number\n  /** USD spent over the life of this client instance. */\n  spentTotalUsd(): number\n}\n\nfunction expiryMs(expiresAt: GrantPolicy['expiresAt']): number {\n  if (expiresAt == null) return Infinity\n  if (expiresAt instanceof Date) return expiresAt.getTime()\n  if (typeof expiresAt === 'number') return expiresAt\n  const t = new Date(expiresAt).getTime()\n  return Number.isNaN(t) ? Infinity : t\n}\n\nfunction utcDayIndex(ms: number): number {\n  return Math.floor(ms / 86_400_000)\n}\n\nfunction hostOf(input: string | URL | Request): string {\n  const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url\n  try {\n    return new URL(url).host.toLowerCase()\n  } catch {\n    return ''\n  }\n}\n\n/** Pull the settlement tx hash from the X-PAYMENT-RESPONSE header, if present. */\nfunction txHashOf(res: Response): string | undefined {\n  const header = res.headers.get('x-payment-response')\n  if (!header) return undefined\n  try {\n    return decodePayment<SettleResult>(header).transaction\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Create a grant-aware paid `fetch`. Enforces the grant locally before signing\n * any x402 payment, pays with the wallet, and emits a receipt per call.\n */\nexport function yeetful(options: AgentOptions): PayFn {\n  const { wallet, grant, onReceipt, onEvent } = options\n  const log = onEvent ?? (() => {})\n\n  let spentToday = 0\n  let spentTotal = 0\n  let dayIndex = utcDayIndex(Date.now())\n\n  const emit = (r: Receipt) => {\n    void Promise.resolve(onReceipt?.(r)).catch(() => {})\n  }\n  const deny = (host: string, code: GrantViolation, msg: string): never => {\n    emit({ host, amountUsd: 0, ok: false, note: code, ts: Date.now() })\n    log(`✗ ${host} — ${code}: ${msg}`)\n    throw new GrantError(code, msg)\n  }\n\n  const pay = async function pay(\n    input: string | URL | Request,\n    init: RequestInit = {},\n  ): Promise<Response> {\n    // Roll the daily budget at UTC midnight.\n    const today = utcDayIndex(Date.now())\n    if (today !== dayIndex) {\n      dayIndex = today\n      spentToday = 0\n    }\n\n    const host = hostOf(input)\n\n    // ── Pre-flight policy (no network): status → expiry → allowlist ─────────\n    if ((grant.status ?? 'active') === 'revoked') deny(host, 'REVOKED', 'grant is revoked')\n    if (Date.now() > expiryMs(grant.expiresAt)) deny(host, 'EXPIRED', 'grant has expired')\n    if (!grant.allow.map((h) => h.toLowerCase()).includes(host)) {\n      deny(host, 'NOT_ALLOWED', `${host} is not in this grant's allowlist`)\n    }\n\n    // Price is only known from the 402 challenge — check caps in the hook,\n    // which runs after the challenge is parsed and before the payment is signed.\n    let pricedUsd = 0\n    const client = createPaymentClient({\n      wallet,\n      fetch: options.fetch,\n      allowedNetworks: options.allowedNetworks,\n      // Per-call enforcement lives in the hook (not maxAmountAtomic) so an\n      // over-cap call surfaces a clean GrantError instead of a filtered no-match.\n      onPaymentRequired: (req: PaymentRequirement) => {\n        const price = Number(req.maxAmountRequired) / 1e6\n        if (price > grant.perCallUsd) {\n          deny(host, 'OVER_PER_CALL', `$${price.toFixed(4)} exceeds per-call cap $${grant.perCallUsd}`)\n        }\n        if (spentToday + price > grant.perDayUsd) {\n          deny(host, 'BUDGET_EXCEEDED', `$${(spentToday + price).toFixed(2)} exceeds today's cap $${grant.perDayUsd}`)\n        }\n        if (grant.totalUsd != null && spentTotal + price > grant.totalUsd) {\n          deny(host, 'BUDGET_EXCEEDED', `$${(spentTotal + price).toFixed(2)} exceeds lifetime cap $${grant.totalUsd}`)\n        }\n        pricedUsd = price\n        return true\n      },\n    })\n\n    let res: Response\n    try {\n      res = await client(input, init)\n    } catch (err) {\n      if (err instanceof GrantError) throw err // already denied + receipted\n      // A rejection from the underlying client (e.g. no acceptable requirement).\n      const note = err instanceof PaymentError ? 'payment-failed' : 'error'\n      emit({ host, amountUsd: 0, ok: false, note, ts: Date.now() })\n      throw err\n    }\n\n    // Settled (or a free, non-402 call where pricedUsd stayed 0).\n    if (pricedUsd > 0) {\n      spentToday += pricedUsd\n      spentTotal += pricedUsd\n    }\n    const txHash = txHashOf(res)\n    emit({ host, amountUsd: pricedUsd, ok: true, txHash, note: 'settled', ts: Date.now() })\n    log(`✓ ${host} — $${pricedUsd.toFixed(4)} · today $${spentToday.toFixed(2)}/$${grant.perDayUsd}`)\n    return res\n  } as PayFn\n\n  pay.spentTodayUsd = () => spentToday\n  pay.remainingTodayUsd = () => Math.max(0, grant.perDayUsd - spentToday)\n  pay.spentTotalUsd = () => spentTotal\n  return pay\n}\n"]}

package/dist/agent.d.cts

@@ -0,0 +1,97 @@
+import { WalletClient } from 'viem';
+import { X as X402Network } from './types-DzGpKiV3.cjs';
+
+/**
+ * yeetful/agent — the "agent expense account."
+ *
+ * Wrap your agent's HTTP calls in a single grant-aware `pay()`. Before any x402
+ * payment is signed it enforces a spend grant — an allowlist of hosts plus
+ * per-call / per-day / lifetime USD caps and an expiry — then pays via the
+ * standard x402 client and emits a receipt for every call.
+ *
+ * One grant authorizes MANY endpoints (the allowlist). It's a guardrail for
+ * your own agents (runaway loops, bugs, prompt-injected tool calls) and the
+ * receipt feed behind budgets + audit. Enforcement here is local + instant;
+ * for hard, adversarial guarantees back the grant with an on-chain Spend
+ * Permission (the wallet contract caps spend regardless of this SDK).
+ *
+ * @example
+ * ```ts
+ * import { yeetful } from 'yeetful/agent'
+ *
+ * const pay = yeetful({
+ *   wallet,                                   // viem WalletClient
+ *   grant: {
+ *     allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
+ *     perCallUsd: 0.05,
+ *     perDayUsd: 2,
+ *     expiresAt: '2026-12-31',
+ *   },
+ *   onReceipt: (r) => console.log(r.host, r.amountUsd, r.txHash),
+ * })
+ *
+ * const res = await pay('https://tripadvisor.x402.paysponge.com/api/v1/location/search?searchQuery=tokyo')
+ * // throws GrantError on NOT_ALLOWED / OVER_PER_CALL / BUDGET_EXCEEDED / EXPIRED
+ * ```
+ */
+
+type GrantViolation = 'EXPIRED' | 'REVOKED' | 'NOT_ALLOWED' | 'OVER_PER_CALL' | 'BUDGET_EXCEEDED';
+declare class GrantError extends Error {
+    code: GrantViolation;
+    constructor(code: GrantViolation, message: string);
+}
+/** A scoped spend authorization (mirrors the hosted SpendGrant). */
+interface GrantPolicy {
+    /** Optional id of the hosted grant this mirrors. */
+    id?: string;
+    /** Exact hostnames this grant may pay (e.g. "tripadvisor.x402.paysponge.com"). */
+    allow: string[];
+    perCallUsd: number;
+    perDayUsd: number;
+    /** Optional lifetime cap across the life of this client instance. */
+    totalUsd?: number | null;
+    /** Unix ms, ISO string, or Date. Omit for no expiry. */
+    expiresAt?: number | string | Date;
+    /** 'active' | 'revoked'. Defaults to active. */
+    status?: string;
+}
+/** A single authorization decision — the audit trail + x402 receipt. */
+interface Receipt {
+    host: string;
+    amountUsd: number;
+    ok: boolean;
+    txHash?: string;
+    /** "settled" on success, or the GrantViolation code on a denial. */
+    note: string;
+    ts: number;
+}
+interface AgentOptions {
+    /** viem WalletClient that signs the EIP-3009 payment. */
+    wallet: WalletClient;
+    /** The spend grant to enforce. */
+    grant: GrantPolicy;
+    /** Underlying fetch (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /** Restrict payments to specific networks (defaults to all). */
+    allowedNetworks?: X402Network[];
+    /** Called after every decision — wire this to your ledger / dashboard. */
+    onReceipt?: (receipt: Receipt) => void | Promise<void>;
+    /** Human-readable progress logging. */
+    onEvent?: (message: string) => void;
+}
+interface PayFn {
+    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    /** USD spent under this grant since UTC midnight (this client instance). */
+    spentTodayUsd(): number;
+    /** USD remaining in today's budget. */
+    remainingTodayUsd(): number;
+    /** USD spent over the life of this client instance. */
+    spentTotalUsd(): number;
+}
+/**
+ * Create a grant-aware paid `fetch`. Enforces the grant locally before signing
+ * any x402 payment, pays with the wallet, and emits a receipt per call.
+ */
+declare function yeetful(options: AgentOptions): PayFn;
+
+export { type AgentOptions, GrantError, type GrantPolicy, type GrantViolation, type PayFn, type Receipt, yeetful };

package/dist/agent.d.ts

@@ -0,0 +1,97 @@
+import { WalletClient } from 'viem';
+import { X as X402Network } from './types-DzGpKiV3.js';
+
+/**
+ * yeetful/agent — the "agent expense account."
+ *
+ * Wrap your agent's HTTP calls in a single grant-aware `pay()`. Before any x402
+ * payment is signed it enforces a spend grant — an allowlist of hosts plus
+ * per-call / per-day / lifetime USD caps and an expiry — then pays via the
+ * standard x402 client and emits a receipt for every call.
+ *
+ * One grant authorizes MANY endpoints (the allowlist). It's a guardrail for
+ * your own agents (runaway loops, bugs, prompt-injected tool calls) and the
+ * receipt feed behind budgets + audit. Enforcement here is local + instant;
+ * for hard, adversarial guarantees back the grant with an on-chain Spend
+ * Permission (the wallet contract caps spend regardless of this SDK).
+ *
+ * @example
+ * ```ts
+ * import { yeetful } from 'yeetful/agent'
+ *
+ * const pay = yeetful({
+ *   wallet,                                   // viem WalletClient
+ *   grant: {
+ *     allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
+ *     perCallUsd: 0.05,
+ *     perDayUsd: 2,
+ *     expiresAt: '2026-12-31',
+ *   },
+ *   onReceipt: (r) => console.log(r.host, r.amountUsd, r.txHash),
+ * })
+ *
+ * const res = await pay('https://tripadvisor.x402.paysponge.com/api/v1/location/search?searchQuery=tokyo')
+ * // throws GrantError on NOT_ALLOWED / OVER_PER_CALL / BUDGET_EXCEEDED / EXPIRED
+ * ```
+ */
+
+type GrantViolation = 'EXPIRED' | 'REVOKED' | 'NOT_ALLOWED' | 'OVER_PER_CALL' | 'BUDGET_EXCEEDED';
+declare class GrantError extends Error {
+    code: GrantViolation;
+    constructor(code: GrantViolation, message: string);
+}
+/** A scoped spend authorization (mirrors the hosted SpendGrant). */
+interface GrantPolicy {
+    /** Optional id of the hosted grant this mirrors. */
+    id?: string;
+    /** Exact hostnames this grant may pay (e.g. "tripadvisor.x402.paysponge.com"). */
+    allow: string[];
+    perCallUsd: number;
+    perDayUsd: number;
+    /** Optional lifetime cap across the life of this client instance. */
+    totalUsd?: number | null;
+    /** Unix ms, ISO string, or Date. Omit for no expiry. */
+    expiresAt?: number | string | Date;
+    /** 'active' | 'revoked'. Defaults to active. */
+    status?: string;
+}
+/** A single authorization decision — the audit trail + x402 receipt. */
+interface Receipt {
+    host: string;
+    amountUsd: number;
+    ok: boolean;
+    txHash?: string;
+    /** "settled" on success, or the GrantViolation code on a denial. */
+    note: string;
+    ts: number;
+}
+interface AgentOptions {
+    /** viem WalletClient that signs the EIP-3009 payment. */
+    wallet: WalletClient;
+    /** The spend grant to enforce. */
+    grant: GrantPolicy;
+    /** Underlying fetch (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /** Restrict payments to specific networks (defaults to all). */
+    allowedNetworks?: X402Network[];
+    /** Called after every decision — wire this to your ledger / dashboard. */
+    onReceipt?: (receipt: Receipt) => void | Promise<void>;
+    /** Human-readable progress logging. */
+    onEvent?: (message: string) => void;
+}
+interface PayFn {
+    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
+    /** USD spent under this grant since UTC midnight (this client instance). */
+    spentTodayUsd(): number;
+    /** USD remaining in today's budget. */
+    remainingTodayUsd(): number;
+    /** USD spent over the life of this client instance. */
+    spentTotalUsd(): number;
+}
+/**
+ * Create a grant-aware paid `fetch`. Enforces the grant locally before signing
+ * any x402 payment, pays with the wallet, and emits a receipt per call.
+ */
+declare function yeetful(options: AgentOptions): PayFn;
+
+export { type AgentOptions, GrantError, type GrantPolicy, type GrantViolation, type PayFn, type Receipt, yeetful };