yeetful 0.1.0 → 0.3.0

package/dist/agent.d.ts

@@ -0,0 +1,115 @@
+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: {
+ *     id: 'cmbq…',                            // hosted grant id (yeetful.com)
+ *     allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],
+ *     perCallUsd: 0.05,
+ *     perDayUsd: 2,
+ *     expiresAt: '2026-12-31',
+ *   },
+ *   apiKey: process.env.YEETFUL_API_KEY,      // yf_… → receipts sync to your dashboard
+ *   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;
+    /**
+     * Yeetful API key (`yf_…`, minted at yeetful.com while signed in). Together
+     * with `grant.id` it turns on hosted-ledger sync: every receipt is POSTed to
+     * `{ledgerUrl}/api/grants/{grant.id}/ledger` with Bearer auth, so the
+     * dashboard's budgets/audit trail include this agent's calls. Sync is
+     * best-effort and never blocks or fails a payment.
+     */
+    apiKey?: string;
+    /** Base URL of the hosted ledger. Defaults to https://yeetful.com. */
+    ledgerUrl?: string;
+}
+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;
+    /**
+     * Resolves once every hosted-ledger sync issued so far has settled (no-op
+     * without `apiKey`). Await this before a short-lived script exits so the
+     * last receipts aren't dropped with the process.
+     */
+    flushLedger(): Promise<void>;
+}
+/**
+ * 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.js

@@ -0,0 +1,285 @@
+// 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 ledgerEndpoint = options.apiKey && grant.id ? `${(options.ledgerUrl ?? "https://yeetful.com").replace(/\/+$/, "")}/api/grants/${grant.id}/ledger` : null;
+  if (options.apiKey && !grant.id) {
+    log("hosted-ledger sync disabled: grant.id is not set (use the id of your yeetful.com grant)");
+  }
+  let ledgerChain = Promise.resolve();
+  const ledgerFetch = options.fetch ?? globalThis.fetch;
+  const sync = (r) => {
+    if (!ledgerEndpoint) return;
+    ledgerChain = ledgerChain.then(async () => {
+      const res = await ledgerFetch(ledgerEndpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.apiKey}`
+        },
+        body: JSON.stringify({
+          host: r.host,
+          amountUsd: r.amountUsd,
+          ok: r.ok,
+          txHash: r.txHash,
+          note: r.note
+        })
+      });
+      if (!res.ok) log(`ledger sync \u2192 ${res.status} for ${r.host}`);
+    }).catch((err) => {
+      log(`ledger sync failed for ${r.host}: ${err instanceof Error ? err.message : err}`);
+    });
+  };
+  const emit = (r) => {
+    sync(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;
+  pay.flushLedger = () => ledgerChain;
+  return pay;
+}
+
+export { GrantError, yeetful };
+//# sourceMappingURL=agent.js.map
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/client.ts","../src/agent.ts"],"names":["pay"],"mappings":";AAgCA,IAAM,WAAA,GAAc,IAAI,WAAA,EAAY;AACpC,IAAM,WAAA,GAAc,IAAI,WAAA,EAAY;AAG7B,SAAS,cAAc,KAAA,EAAwB;AACpD,EAAA,MAAM,QAAQ,WAAA,CAAY,MAAA,CAAO,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAA;AACtD,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACjC,IAAA,OAAO,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,CAAE,SAAS,QAAQ,CAAA;AAAA,EAC7C;AACA,EAAA,IAAI,MAAA,GAAS,EAAA;AACb,EAAA,KAAA,MAAW,IAAA,IAAQ,KAAA,EAAO,MAAA,IAAU,MAAA,CAAO,aAAa,IAAI,CAAA;AAC5D,EAAA,OAAO,KAAK,MAAM,CAAA;AACpB;AAGO,SAAS,cAA2B,GAAA,EAAgB;AACzD,EAAA,IAAI,KAAA;AACJ,EAAA,IAAI,OAAO,WAAW,WAAA,EAAa;AACjC,IAAA,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,CAAO,IAAA,CAAK,GAAA,EAAK,QAAQ,CAAC,CAAA;AAAA,EACnD,CAAA,MAAO;AACL,IAAA,MAAM,MAAA,GAAS,KAAK,GAAG,CAAA;AACvB,IAAA,KAAA,GAAQ,IAAI,UAAA,CAAW,MAAA,CAAO,MAAM,CAAA;AACpC,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,MAAA,CAAO,MAAA,EAAQ,CAAA,EAAA,EAAK,KAAA,CAAM,CAAC,CAAA,GAAI,MAAA,CAAO,UAAA,CAAW,CAAC,CAAA;AAAA,EACxE;AACA,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,WAAA,CAAY,MAAA,CAAO,KAAK,CAAC,CAAA;AAC7C;AAGO,SAAS,WAAA,GAA6B;AAC3C,EAAA,MAAM,KAAA,GAAQ,IAAI,UAAA,CAAW,EAAE,CAAA;AAC/B,EAAA,UAAA,CAAW,MAAA,CAAO,gBAAgB,KAAK,CAAA;AACvC,EAAA,OAAQ,OAAO,KAAA,CAAM,IAAA,CAAK,KAAA,EAAO,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAClF;;;AC1BO,SAAS,oBAAoB,OAAA,EAAwB;AAC1D,EAAA,MAAM,YAAY,OAAA,CAAQ,KAAA,IAAS,UAAA,CAAW,KAAA,CAAM,KAAK,UAAU,CAAA;AAEnE,EAAA,OAAO,eAAe,QAAA,CACpB,KAAA,EACA,IAAA,GAAoB,EAAC,EACF;AACnB,IAAA,MAAM,KAAA,GAAQ,MAAM,SAAA,CAAU,KAAA,EAAO,IAAI,CAAA;AACzC,IAAA,IAAI,KAAA,CAAM,MAAA,KAAW,GAAA,EAAK,OAAO,KAAA;AAEjC,IAAA,MAAM,YAAA,GAAe,MAAM,oBAAA,CAAqB,KAAK,CAAA;AACrD,IAAA,MAAM,WAAA,GAAc,iBAAA,CAAkB,YAAA,CAAa,OAAA,EAAS,OAAO,CAAA;AACnE,IAAA,IAAI,CAAC,WAAA,EAAa;AAChB,MAAA,MAAM,IAAI,YAAA,CAAa,8DAAA,EAAgE,YAAY,CAAA;AAAA,IACrG;AAEA,IAAA,IAAI,QAAQ,iBAAA,EAAmB;AAC7B,MAAA,MAAM,QAAA,GAAW,MAAM,OAAA,CAAQ,iBAAA,CAAkB,WAAW,CAAA;AAC5D,MAAA,IAAI,CAAC,QAAA,EAAU,MAAM,IAAI,YAAA,CAAa,4BAA4B,YAAY,CAAA;AAAA,IAChF;AAEA,IAAA,MAAM,OAAA,GAAU,MAAM,WAAA,CAAY,OAAA,CAAQ,QAAQ,WAAW,CAAA;AAC7D,IAAA,MAAM,OAAA,GAAU,IAAI,OAAA,CAAQ,IAAA,CAAK,OAAO,CAAA;AACxC,IAAA,OAAA,CAAQ,GAAA,CAAI,WAAA,EAAa,aAAA,CAAc,OAAO,CAAC,CAAA;AAE/C,IAAA,OAAO,UAAU,KAAA,EAAO,EAAE,GAAG,IAAA,EAAM,SAAS,CAAA;AAAA,EAC9C,CAAA;AACF;AAEO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAC7B,YAAA;AAAA,EACT,WAAA,CAAY,SAAiB,YAAA,EAAwC;AACnE,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,YAAA,GAAe,YAAA;AAAA,EACtB;AACF,CAAA;AAEA,eAAe,qBAAqB,GAAA,EAAiD;AACnF,EAAA,IAAI;AACF,IAAA,OAAQ,MAAM,GAAA,CAAI,KAAA,EAAM,CAAE,IAAA,EAAK;AAAA,EACjC,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,aAAa,0DAA0D,CAAA;AAAA,EACnF;AACF;AAEA,SAAS,iBAAA,CACP,SACA,IAAA,EACgC;AAChC,EAAA,MAAM,QAAA,GAAW,OAAA,CACd,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,MAAA,KAAW,OAAO,CAAA,CAClC,MAAA,CAAO,CAAC,CAAA,KAAM,CAAC,KAAK,eAAA,IAAmB,IAAA,CAAK,eAAA,CAAgB,QAAA,CAAS,CAAA,CAAE,OAAO,CAAC,CAAA,CAC/E,OAAO,CAAC,CAAA,KAAM,CAAC,IAAA,CAAK,mBAAmB,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,IAAK,KAAK,eAAe,CAAA;AAE7F,EAAA,OAAO,QAAA,CAAS,IAAA;AAAA,IAAK,CAAC,CAAA,EAAG,CAAA,KACvB,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,GAAI,MAAA,CAAO,CAAA,CAAE,iBAAiB,CAAA,GAAI,EAAA,GAAK;AAAA,IACjE,CAAC,CAAA;AACL;AAGA,eAAsB,WAAA,CACpB,QACA,WAAA,EACyB;AACzB,EAAA,MAAM,UAAU,MAAA,CAAO,OAAA;AACvB,EAAA,IAAI,CAAC,OAAA,EAAS,MAAM,IAAI,aAAa,gCAAgC,CAAA;AAErE,EAAA,MAAM,MAAM,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AACxC,EAAA,MAAM,UAAA,GAAa,MAAA,CAAO,GAAA,GAAM,EAAE,CAAA;AAClC,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,GAAA,IAAO,WAAA,CAAY,qBAAqB,GAAA,CAAI,CAAA;AACvE,EAAA,MAAM,QAAQ,WAAA,EAAY;AAE1B,EAAA,MAAM,SAAA,GACH,WAAA,CAAY,KAAA,EAAO,IAAA,IAA+B,UAAA;AACrD,EAAA,MAAM,YAAA,GACH,WAAA,CAAY,KAAA,EAAO,OAAA,IAAkC,GAAA;AAExD,EAAA,MAAM,SAAA,GAAa,MAAM,MAAA,CAAO,aAAA,CAAc;AAAA,IAC5C,OAAA;AAAA,IACA,MAAA,EAAQ;AAAA,MACN,IAAA,EAAM,SAAA;AAAA,MACN,OAAA,EAAS,YAAA;AAAA,MACT,OAAA,EAAS,iBAAA,CAAkB,WAAA,CAAY,OAAO,CAAA;AAAA,MAC9C,mBAAmB,WAAA,CAAY;AAAA,KACjC;AAAA,IACA,KAAA,EAAO;AAAA,MACL,yBAAA,EAA2B;AAAA,QACzB,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,SAAA,EAAU;AAAA,QAChC,EAAE,IAAA,EAAM,IAAA,EAAM,IAAA,EAAM,SAAA,EAAU;AAAA,QAC9B,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,SAAA,EAAU;AAAA,QACjC,EAAE,IAAA,EAAM,YAAA,EAAc,IAAA,EAAM,SAAA,EAAU;AAAA,QACtC,EAAE,IAAA,EAAM,aAAA,EAAe,IAAA,EAAM,SAAA,EAAU;AAAA,QACvC,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,SAAA;AAAU;AACnC,KACF;AAAA,IACA,WAAA,EAAa,2BAAA;AAAA,IACb,OAAA,EAAS;AAAA,MACP,MAAM,OAAA,CAAQ,OAAA;AAAA,MACd,IAAI,WAAA,CAAY,KAAA;AAAA,MAChB,KAAA,EAAO,MAAA,CAAO,WAAA,CAAY,iBAAiB,CAAA;AAAA,MAC3C,UAAA;AAAA,MACA,WAAA;AAAA,MACA;AAAA;AACF,GACD,CAAA;AAED,EAAA,OAAO;AAAA,IACL,WAAA,EAAa,CAAA;AAAA,IACb,MAAA,EAAQ,OAAA;AAAA,IACR,SAAS,WAAA,CAAY,OAAA;AAAA,IACrB,OAAA,EAAS;AAAA,MACP,SAAA;AAAA,MACA,aAAA,EAAe;AAAA,QACb,MAAM,OAAA,CAAQ,OAAA;AAAA,QACd,IAAI,WAAA,CAAY,KAAA;AAAA,QAChB,OAAO,WAAA,CAAY,iBAAA;AAAA,QACnB,UAAA,EAAY,WAAW,QAAA,EAAS;AAAA,QAChC,WAAA,EAAa,YAAY,QAAA,EAAS;AAAA,QAClC;AAAA;AACF;AACF,GACF;AACF;AAEA,SAAS,kBAAkB,OAAA,EAA8B;AACvD,EAAA,QAAQ,OAAA;AAAS,IACf,KAAK,MAAA;AACH,MAAA,OAAO,IAAA;AAAA,IACT,KAAK,cAAA;AACH,MAAA,OAAO,KAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,CAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,EAAA;AAAA,IACT,KAAK,UAAA;AACH,MAAA,OAAO,KAAA;AAAA,IACT,KAAK,SAAA;AACH,MAAA,OAAO,GAAA;AAAA;AAEb;;;AClIO,IAAM,UAAA,GAAN,cAAyB,KAAA,CAAM;AAAA,EACpC,WAAA,CACS,MACP,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAO,CAAA;AAHN,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAIP,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AAAA,EACd;AAAA,EALS,IAAA;AAMX;AAsEA,SAAS,SAAS,SAAA,EAA6C;AAC7D,EAAA,IAAI,SAAA,IAAa,MAAM,OAAO,QAAA;AAC9B,EAAA,IAAI,SAAA,YAAqB,IAAA,EAAM,OAAO,SAAA,CAAU,OAAA,EAAQ;AACxD,EAAA,IAAI,OAAO,SAAA,KAAc,QAAA,EAAU,OAAO,SAAA;AAC1C,EAAA,MAAM,CAAA,GAAI,IAAI,IAAA,CAAK,SAAS,EAAE,OAAA,EAAQ;AACtC,EAAA,OAAO,MAAA,CAAO,KAAA,CAAM,CAAC,CAAA,GAAI,QAAA,GAAW,CAAA;AACtC;AAEA,SAAS,YAAY,EAAA,EAAoB;AACvC,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,EAAA,GAAK,KAAU,CAAA;AACnC;AAEA,SAAS,OAAO,KAAA,EAAuC;AACrD,EAAA,MAAM,GAAA,GAAM,OAAO,KAAA,KAAU,QAAA,GAAW,QAAQ,KAAA,YAAiB,GAAA,GAAM,KAAA,CAAM,IAAA,GAAO,KAAA,CAAM,GAAA;AAC1F,EAAA,IAAI;AACF,IAAA,OAAO,IAAI,GAAA,CAAI,GAAG,CAAA,CAAE,KAAK,WAAA,EAAY;AAAA,EACvC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAA;AAAA,EACT;AACF;AAGA,SAAS,SAAS,GAAA,EAAmC;AACnD,EAAA,MAAM,MAAA,GAAS,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,oBAAoB,CAAA;AACnD,EAAA,IAAI,CAAC,QAAQ,OAAO,MAAA;AACpB,EAAA,IAAI;AACF,IAAA,OAAO,aAAA,CAA4B,MAAM,CAAA,CAAE,WAAA;AAAA,EAC7C,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;AAMO,SAAS,QAAQ,OAAA,EAA8B;AACpD,EAAA,MAAM,EAAE,MAAA,EAAQ,KAAA,EAAO,SAAA,EAAW,SAAQ,GAAI,OAAA;AAC9C,EAAA,MAAM,GAAA,GAAM,YAAY,MAAM;AAAA,EAAC,CAAA,CAAA;AAE/B,EAAA,IAAI,UAAA,GAAa,CAAA;AACjB,EAAA,IAAI,UAAA,GAAa,CAAA;AACjB,EAAA,IAAI,QAAA,GAAW,WAAA,CAAY,IAAA,CAAK,GAAA,EAAK,CAAA;AAGrC,EAAA,MAAM,iBACJ,OAAA,CAAQ,MAAA,IAAU,KAAA,CAAM,EAAA,GACpB,IAAI,OAAA,CAAQ,SAAA,IAAa,qBAAA,EAAuB,OAAA,CAAQ,QAAQ,EAAE,CAAC,CAAA,YAAA,EAAe,KAAA,CAAM,EAAE,CAAA,OAAA,CAAA,GAC1F,IAAA;AACN,EAAA,IAAI,OAAA,CAAQ,MAAA,IAAU,CAAC,KAAA,CAAM,EAAA,EAAI;AAC/B,IAAA,GAAA,CAAI,yFAAyF,CAAA;AAAA,EAC/F;AAGA,EAAA,IAAI,WAAA,GAA6B,QAAQ,OAAA,EAAQ;AACjD,EAAA,MAAM,WAAA,GAAc,OAAA,CAAQ,KAAA,IAAS,UAAA,CAAW,KAAA;AAChD,EAAA,MAAM,IAAA,GAAO,CAAC,CAAA,KAAe;AAC3B,IAAA,IAAI,CAAC,cAAA,EAAgB;AACrB,IAAA,WAAA,GAAc,WAAA,CACX,KAAK,YAAY;AAChB,MAAA,MAAM,GAAA,GAAM,MAAM,WAAA,CAAY,cAAA,EAAgB;AAAA,QAC5C,MAAA,EAAQ,MAAA;AAAA,QACR,OAAA,EAAS;AAAA,UACP,cAAA,EAAgB,kBAAA;AAAA,UAChB,aAAA,EAAe,CAAA,OAAA,EAAU,OAAA,CAAQ,MAAM,CAAA;AAAA,SACzC;AAAA,QACA,IAAA,EAAM,KAAK,SAAA,CAAU;AAAA,UACnB,MAAM,CAAA,CAAE,IAAA;AAAA,UACR,WAAW,CAAA,CAAE,SAAA;AAAA,UACb,IAAI,CAAA,CAAE,EAAA;AAAA,UACN,QAAQ,CAAA,CAAE,MAAA;AAAA,UACV,MAAM,CAAA,CAAE;AAAA,SACT;AAAA,OACF,CAAA;AACD,MAAA,IAAI,CAAC,GAAA,CAAI,EAAA,EAAI,GAAA,CAAI,CAAA,mBAAA,EAAiB,IAAI,MAAM,CAAA,KAAA,EAAQ,CAAA,CAAE,IAAI,CAAA,CAAE,CAAA;AAAA,IAC9D,CAAC,CAAA,CACA,KAAA,CAAM,CAAC,GAAA,KAAQ;AACd,MAAA,GAAA,CAAI,CAAA,uBAAA,EAA0B,EAAE,IAAI,CAAA,EAAA,EAAK,eAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,GAAG,CAAA,CAAE,CAAA;AAAA,IACrF,CAAC,CAAA;AAAA,EACL,CAAA;AAEA,EAAA,MAAM,IAAA,GAAO,CAAC,CAAA,KAAe;AAC3B,IAAA,IAAA,CAAK,CAAC,CAAA;AACN,IAAA,KAAK,QAAQ,OAAA,CAAQ,SAAA,GAAY,CAAC,CAAC,CAAA,CAAE,MAAM,MAAM;AAAA,IAAC,CAAC,CAAA;AAAA,EACrD,CAAA;AACA,EAAA,MAAM,IAAA,GAAO,CAAC,IAAA,EAAc,IAAA,EAAsB,GAAA,KAAuB;AACvE,IAAA,IAAA,CAAK,EAAE,IAAA,EAAM,SAAA,EAAW,CAAA,EAAG,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,IAAA,EAAM,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,EAAG,CAAA;AAClE,IAAA,GAAA,CAAI,UAAK,IAAI,CAAA,QAAA,EAAM,IAAI,CAAA,EAAA,EAAK,GAAG,CAAA,CAAE,CAAA;AACjC,IAAA,MAAM,IAAI,UAAA,CAAW,IAAA,EAAM,GAAG,CAAA;AAAA,EAChC,CAAA;AAEA,EAAA,MAAM,MAAM,eAAeA,IAAAA,CACzB,KAAA,EACA,IAAA,GAAoB,EAAC,EACF;AAEnB,IAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,GAAA,EAAK,CAAA;AACpC,IAAA,IAAI,UAAU,QAAA,EAAU;AACtB,MAAA,QAAA,GAAW,KAAA;AACX,MAAA,UAAA,GAAa,CAAA;AAAA,IACf;AAEA,IAAA,MAAM,IAAA,GAAO,OAAO,KAAK,CAAA;AAGzB,IAAA,IAAA,CAAK,MAAM,MAAA,IAAU,QAAA,MAAc,WAAW,IAAA,CAAK,IAAA,EAAM,WAAW,kBAAkB,CAAA;AACtF,IAAA,IAAI,IAAA,CAAK,GAAA,EAAI,GAAI,QAAA,CAAS,KAAA,CAAM,SAAS,CAAA,EAAG,IAAA,CAAK,IAAA,EAAM,SAAA,EAAW,mBAAmB,CAAA;AACrF,IAAA,IAAI,CAAC,KAAA,CAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,WAAA,EAAa,CAAA,CAAE,QAAA,CAAS,IAAI,CAAA,EAAG;AAC3D,MAAA,IAAA,CAAK,IAAA,EAAM,aAAA,EAAe,CAAA,EAAG,IAAI,CAAA,iCAAA,CAAmC,CAAA;AAAA,IACtE;AAIA,IAAA,IAAI,SAAA,GAAY,CAAA;AAChB,IAAA,MAAM,SAAS,mBAAA,CAAoB;AAAA,MACjC,MAAA;AAAA,MACA,OAAO,OAAA,CAAQ,KAAA;AAAA,MACf,iBAAiB,OAAA,CAAQ,eAAA;AAAA;AAAA;AAAA,MAGzB,iBAAA,EAAmB,CAAC,GAAA,KAA4B;AAC9C,QAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,GAAA,CAAI,iBAAiB,CAAA,GAAI,GAAA;AAC9C,QAAA,IAAI,KAAA,GAAQ,MAAM,UAAA,EAAY;AAC5B,UAAA,IAAA,CAAK,IAAA,EAAM,eAAA,EAAiB,CAAA,CAAA,EAAI,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAC,CAAA,uBAAA,EAA0B,KAAA,CAAM,UAAU,CAAA,CAAE,CAAA;AAAA,QAC9F;AACA,QAAA,IAAI,UAAA,GAAa,KAAA,GAAQ,KAAA,CAAM,SAAA,EAAW;AACxC,UAAA,IAAA,CAAK,IAAA,EAAM,iBAAA,EAAmB,CAAA,CAAA,EAAA,CAAK,UAAA,GAAa,KAAA,EAAO,OAAA,CAAQ,CAAC,CAAC,CAAA,sBAAA,EAAyB,KAAA,CAAM,SAAS,CAAA,CAAE,CAAA;AAAA,QAC7G;AACA,QAAA,IAAI,MAAM,QAAA,IAAY,IAAA,IAAQ,UAAA,GAAa,KAAA,GAAQ,MAAM,QAAA,EAAU;AACjE,UAAA,IAAA,CAAK,IAAA,EAAM,iBAAA,EAAmB,CAAA,CAAA,EAAA,CAAK,UAAA,GAAa,KAAA,EAAO,OAAA,CAAQ,CAAC,CAAC,CAAA,uBAAA,EAA0B,KAAA,CAAM,QAAQ,CAAA,CAAE,CAAA;AAAA,QAC7G;AACA,QAAA,SAAA,GAAY,KAAA;AACZ,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,KACD,CAAA;AAED,IAAA,IAAI,GAAA;AACJ,IAAA,IAAI;AACF,MAAA,GAAA,GAAM,MAAM,MAAA,CAAO,KAAA,EAAO,IAAI,CAAA;AAAA,IAChC,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,GAAA,YAAe,YAAY,MAAM,GAAA;AAErC,MAAA,MAAM,IAAA,GAAO,GAAA,YAAe,YAAA,GAAe,gBAAA,GAAmB,OAAA;AAC9D,MAAA,IAAA,CAAK,EAAE,IAAA,EAAM,SAAA,EAAW,CAAA,EAAG,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,EAAG,CAAA;AAC5D,MAAA,MAAM,GAAA;AAAA,IACR;AAGA,IAAA,IAAI,YAAY,CAAA,EAAG;AACjB,MAAA,UAAA,IAAc,SAAA;AACd,MAAA,UAAA,IAAc,SAAA;AAAA,IAChB;AACA,IAAA,MAAM,MAAA,GAAS,SAAS,GAAG,CAAA;AAC3B,IAAA,IAAA,CAAK,EAAE,IAAA,EAAM,SAAA,EAAW,SAAA,EAAW,EAAA,EAAI,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,SAAA,EAAW,EAAA,EAAI,IAAA,CAAK,GAAA,IAAO,CAAA;AACtF,IAAA,GAAA,CAAI,CAAA,OAAA,EAAK,IAAI,CAAA,SAAA,EAAO,SAAA,CAAU,QAAQ,CAAC,CAAC,CAAA,aAAA,EAAa,UAAA,CAAW,QAAQ,CAAC,CAAC,CAAA,EAAA,EAAK,KAAA,CAAM,SAAS,CAAA,CAAE,CAAA;AAChG,IAAA,OAAO,GAAA;AAAA,EACT,CAAA;AAEA,EAAA,GAAA,CAAI,gBAAgB,MAAM,UAAA;AAC1B,EAAA,GAAA,CAAI,oBAAoB,MAAM,IAAA,CAAK,IAAI,CAAA,EAAG,KAAA,CAAM,YAAY,UAAU,CAAA;AACtE,EAAA,GAAA,CAAI,gBAAgB,MAAM,UAAA;AAC1B,EAAA,GAAA,CAAI,cAAc,MAAM,WAAA;AACxB,EAAA,OAAO,GAAA;AACT","file":"agent.js","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 *     id: 'cmbq…',                            // hosted grant id (yeetful.com)\n *     allow: ['tripadvisor.x402.paysponge.com', 'anthropic.yeetful.com'],\n *     perCallUsd: 0.05,\n *     perDayUsd: 2,\n *     expiresAt: '2026-12-31',\n *   },\n *   apiKey: process.env.YEETFUL_API_KEY,      // yf_… → receipts sync to your dashboard\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   * Yeetful API key (`yf_…`, minted at yeetful.com while signed in). Together\n   * with `grant.id` it turns on hosted-ledger sync: every receipt is POSTed to\n   * `{ledgerUrl}/api/grants/{grant.id}/ledger` with Bearer auth, so the\n   * dashboard's budgets/audit trail include this agent's calls. Sync is\n   * best-effort and never blocks or fails a payment.\n   */\n  apiKey?: string\n  /** Base URL of the hosted ledger. Defaults to https://yeetful.com. */\n  ledgerUrl?: string\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   * Resolves once every hosted-ledger sync issued so far has settled (no-op\n   * without `apiKey`). Await this before a short-lived script exits so the\n   * last receipts aren't dropped with the process.\n   */\n  flushLedger(): Promise<void>\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  // ── Hosted-ledger sync (optional): receipts → POST /api/grants/:id/ledger ──\n  const ledgerEndpoint =\n    options.apiKey && grant.id\n      ? `${(options.ledgerUrl ?? 'https://yeetful.com').replace(/\\/+$/, '')}/api/grants/${grant.id}/ledger`\n      : null\n  if (options.apiKey && !grant.id) {\n    log('hosted-ledger sync disabled: grant.id is not set (use the id of your yeetful.com grant)')\n  }\n  // A chain (not fire-and-forget) so receipts land in order and flushLedger()\n  // can await them; one failed POST is logged and never poisons the chain.\n  let ledgerChain: Promise<void> = Promise.resolve()\n  const ledgerFetch = options.fetch ?? globalThis.fetch\n  const sync = (r: Receipt) => {\n    if (!ledgerEndpoint) return\n    ledgerChain = ledgerChain\n      .then(async () => {\n        const res = await ledgerFetch(ledgerEndpoint, {\n          method: 'POST',\n          headers: {\n            'content-type': 'application/json',\n            authorization: `Bearer ${options.apiKey}`,\n          },\n          body: JSON.stringify({\n            host: r.host,\n            amountUsd: r.amountUsd,\n            ok: r.ok,\n            txHash: r.txHash,\n            note: r.note,\n          }),\n        })\n        if (!res.ok) log(`ledger sync → ${res.status} for ${r.host}`)\n      })\n      .catch((err) => {\n        log(`ledger sync failed for ${r.host}: ${err instanceof Error ? err.message : err}`)\n      })\n  }\n\n  const emit = (r: Receipt) => {\n    sync(r)\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  pay.flushLedger = () => ledgerChain\n  return pay\n}\n"]}

package/dist/index.cjs

@@ -163,6 +163,146 @@ function chainIdForNetwork(network) {
   }
 }
 
+// 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 ledgerEndpoint = options.apiKey && grant.id ? `${(options.ledgerUrl ?? "https://yeetful.com").replace(/\/+$/, "")}/api/grants/${grant.id}/ledger` : null;
+  if (options.apiKey && !grant.id) {
+    log("hosted-ledger sync disabled: grant.id is not set (use the id of your yeetful.com grant)");
+  }
+  let ledgerChain = Promise.resolve();
+  const ledgerFetch = options.fetch ?? globalThis.fetch;
+  const sync = (r) => {
+    if (!ledgerEndpoint) return;
+    ledgerChain = ledgerChain.then(async () => {
+      const res = await ledgerFetch(ledgerEndpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${options.apiKey}`
+        },
+        body: JSON.stringify({
+          host: r.host,
+          amountUsd: r.amountUsd,
+          ok: r.ok,
+          txHash: r.txHash,
+          note: r.note
+        })
+      });
+      if (!res.ok) log(`ledger sync \u2192 ${res.status} for ${r.host}`);
+    }).catch((err) => {
+      log(`ledger sync failed for ${r.host}: ${err instanceof Error ? err.message : err}`);
+    });
+  };
+  const emit = (r) => {
+    sync(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;
+  pay.flushLedger = () => ledgerChain;
+  return pay;
+}
+
 // src/facilitator.ts
 var Facilitator = class {
   url;
@@ -289,6 +429,7 @@ function paymentRequiredResponse(accepts, error) {
 
 exports.DEFAULT_FACILITATOR_URL = DEFAULT_FACILITATOR_URL;
 exports.Facilitator = Facilitator;
+exports.GrantError = GrantError;
 exports.PaymentError = PaymentError;
 exports.createPaymentClient = createPaymentClient;
 exports.decodePayment = decodePayment;
@@ -297,5 +438,6 @@ exports.gate = gate;
 exports.signPayment = signPayment;
 exports.usdToAtomic = usdToAtomic;
 exports.usdcAddress = usdcAddress;
+exports.yeetful = yeetful;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map