yeetful 0.1.0

package/dist/server.js

@@ -0,0 +1,172 @@
+// src/facilitator.ts
+var Facilitator = class {
+  url;
+  authHeader;
+  fetcher;
+  constructor(config) {
+    this.url = config.url.replace(/\/$/, "");
+    this.authHeader = config.authHeader;
+    this.fetcher = config.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  async verify(payment, requirement) {
+    return this.post("/verify", { paymentPayload: payment, paymentRequirements: requirement });
+  }
+  async settle(payment, requirement) {
+    return this.post("/settle", { paymentPayload: payment, paymentRequirements: requirement });
+  }
+  async post(path, body) {
+    const res = await this.fetcher(this.url + path, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...this.authHeader ? { authorization: this.authHeader } : {}
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Facilitator ${path} failed: ${res.status} ${text}`);
+    }
+    return await res.json();
+  }
+};
+var DEFAULT_FACILITATOR_URL = "https://facilitator.yeetful.com";
+
+// src/utils.ts
+var USDC_BY_NETWORK = {
+  base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  optimism: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+  arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  polygon: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
+};
+var USDC_DECIMALS = 6;
+function usdcAddress(network) {
+  return USDC_BY_NETWORK[network];
+}
+function usdToAtomic(amount, decimals = USDC_DECIMALS) {
+  const str = typeof amount === "number" ? amount.toString() : amount;
+  if (!/^\d+(\.\d+)?$/.test(str)) {
+    throw new Error(`Invalid amount: ${str}`);
+  }
+  const [whole, frac = ""] = str.split(".");
+  const padded = frac.slice(0, decimals).padEnd(decimals, "0");
+  return (BigInt(whole ?? "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+}
+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));
+}
+
+// src/server.ts
+async function gate(request, opts) {
+  const requirements = buildRequirements(request, opts);
+  const header = request.headers.get("x-payment") ?? request.headers.get("X-PAYMENT");
+  if (!header) {
+    return { type: "paymentRequired", response: paymentRequiredResponse(requirements) };
+  }
+  let payment;
+  try {
+    payment = decodePayment(header);
+  } catch {
+    return {
+      type: "paymentRequired",
+      response: paymentRequiredResponse(requirements, "Invalid X-PAYMENT header")
+    };
+  }
+  const matched = requirements.find(
+    (r) => r.network === payment.network && r.scheme === payment.scheme
+  );
+  if (!matched) {
+    return {
+      type: "paymentRequired",
+      response: paymentRequiredResponse(requirements, "Payment does not match any accepted requirement")
+    };
+  }
+  if (opts.facilitator === false) {
+    const payer2 = payment.payload.authorization.from;
+    return {
+      type: "ok",
+      payer: payer2,
+      settle: async () => ({
+        header: encodePayment({ success: true, network: matched.network }),
+        result: { success: true }
+      })
+    };
+  }
+  const facilitator = new Facilitator(opts.facilitator ?? { url: DEFAULT_FACILITATOR_URL });
+  const verified = await facilitator.verify(payment, matched);
+  if (!verified.isValid) {
+    return {
+      type: "paymentRequired",
+      response: paymentRequiredResponse(
+        requirements,
+        verified.invalidReason ?? "Payment verification failed"
+      )
+    };
+  }
+  const payer = verified.payer ?? payment.payload.authorization.from;
+  return {
+    type: "ok",
+    payer,
+    settle: async () => {
+      const result = await facilitator.settle(payment, matched);
+      return {
+        header: encodePayment({
+          success: result.success,
+          transaction: result.transaction,
+          network: result.network ?? matched.network,
+          errorReason: result.errorReason,
+          payer
+        }),
+        result
+      };
+    }
+  };
+}
+function buildRequirements(request, opts) {
+  const networks = Array.isArray(opts.network) ? opts.network : [opts.network ?? "base"];
+  const atomic = usdToAtomic(opts.price);
+  const resource = opts.resource ?? request.url;
+  return networks.map((network) => ({
+    scheme: "exact",
+    network,
+    asset: opts.asset ?? usdcAddress(network),
+    maxAmountRequired: atomic,
+    payTo: opts.recipient,
+    description: opts.description,
+    resource,
+    maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 600,
+    extra: { name: "USD Coin", version: "2" }
+  }));
+}
+function paymentRequiredResponse(accepts, error) {
+  const body = { x402Version: 1, accepts, ...error ? { error } : {} };
+  return new Response(JSON.stringify(body), {
+    status: 402,
+    headers: { "content-type": "application/json" }
+  });
+}
+
+export { DEFAULT_FACILITATOR_URL, Facilitator, gate };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/facilitator.ts","../src/utils.ts","../src/server.ts"],"names":["payer"],"mappings":"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","file":"server.js","sourcesContent":["import type {\n  FacilitatorConfig,\n  PaymentPayload,\n  PaymentRequirement,\n  SettleResult,\n  VerifyResult,\n} from './types.js'\n\n/**\n * Thin wrapper around an x402 facilitator HTTP service.\n * The facilitator verifies signed payment authorizations and settles them on-chain.\n */\nexport class Facilitator {\n  private readonly url: string\n  private readonly authHeader?: string\n  private readonly fetcher: typeof fetch\n\n  constructor(config: FacilitatorConfig) {\n    this.url = config.url.replace(/\\/$/, '')\n    this.authHeader = config.authHeader\n    this.fetcher = config.fetch ?? globalThis.fetch.bind(globalThis)\n  }\n\n  async verify(\n    payment: PaymentPayload,\n    requirement: PaymentRequirement,\n  ): Promise<VerifyResult> {\n    return this.post<VerifyResult>('/verify', { paymentPayload: payment, paymentRequirements: requirement })\n  }\n\n  async settle(\n    payment: PaymentPayload,\n    requirement: PaymentRequirement,\n  ): Promise<SettleResult> {\n    return this.post<SettleResult>('/settle', { paymentPayload: payment, paymentRequirements: requirement })\n  }\n\n  private async post<T>(path: string, body: unknown): Promise<T> {\n    const res = await this.fetcher(this.url + path, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        ...(this.authHeader ? { authorization: this.authHeader } : {}),\n      },\n      body: JSON.stringify(body),\n    })\n    if (!res.ok) {\n      const text = await res.text().catch(() => '')\n      throw new Error(`Facilitator ${path} failed: ${res.status} ${text}`)\n    }\n    return (await res.json()) as T\n  }\n}\n\n/** Default hosted facilitator. Override for self-hosted deployments. */\nexport const DEFAULT_FACILITATOR_URL = 'https://facilitator.yeetful.com'\n","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 } from 'viem'\nimport { Facilitator, DEFAULT_FACILITATOR_URL } from './facilitator.js'\nimport type {\n  FacilitatorConfig,\n  PaymentPayload,\n  PaymentRequirement,\n  PaymentRequiredResponse,\n  SettleResult,\n  X402Network,\n} from './types.js'\nimport { decodePayment, encodePayment, usdcAddress, usdToAtomic } from './utils.js'\n\nexport interface RouteGateOptions {\n  /** Price in USD, e.g. \"0.01\". Converted to USDC atomic units. */\n  price: string | number\n  /** Recipient address that receives the funds. */\n  recipient: Address\n  /** Network(s) to accept. Defaults to `['base']`. Pass an array for multi-chain. */\n  network?: X402Network | X402Network[]\n  /** Override the payment asset (defaults to USDC for the given network). */\n  asset?: Address\n  /** Human-readable description of the resource. */\n  description?: string\n  /** Seconds the signed authorization is valid. Default: 600. */\n  maxTimeoutSeconds?: number\n  /** Facilitator config, or `false` to skip verification/settlement (trust-mode). */\n  facilitator?: FacilitatorConfig | false\n  /**\n   * Optional resource identifier (defaults to the request URL). Useful for\n   * logging / receipts.\n   */\n  resource?: string\n}\n\n/**\n * Runtime-agnostic gate: given a Fetch-API `Request`, either returns a 402\n * `Response` or a `{ settle }` handle. After your handler runs, call `settle()`\n * to finalize the payment and get a `X-PAYMENT-RESPONSE` header to attach.\n *\n * This is the building block used by the framework adapters (`./next`, `./express`).\n */\nexport async function gate(\n  request: Request,\n  opts: RouteGateOptions,\n): Promise<\n  | { type: 'paymentRequired'; response: Response }\n  | { type: 'ok'; payer: Address; settle: () => Promise<{ header: string; result: SettleResult }> }\n> {\n  const requirements = buildRequirements(request, opts)\n\n  const header = request.headers.get('x-payment') ?? request.headers.get('X-PAYMENT')\n  if (!header) {\n    return { type: 'paymentRequired', response: paymentRequiredResponse(requirements) }\n  }\n\n  let payment: PaymentPayload\n  try {\n    payment = decodePayment<PaymentPayload>(header)\n  } catch {\n    return {\n      type: 'paymentRequired',\n      response: paymentRequiredResponse(requirements, 'Invalid X-PAYMENT header'),\n    }\n  }\n\n  const matched = requirements.find(\n    (r) => r.network === payment.network && r.scheme === payment.scheme,\n  )\n  if (!matched) {\n    return {\n      type: 'paymentRequired',\n      response: paymentRequiredResponse(requirements, 'Payment does not match any accepted requirement'),\n    }\n  }\n\n  if (opts.facilitator === false) {\n    const payer = payment.payload.authorization.from as Address\n    return {\n      type: 'ok',\n      payer,\n      settle: async () => ({\n        header: encodePayment({ success: true, network: matched.network }),\n        result: { success: true },\n      }),\n    }\n  }\n\n  const facilitator = new Facilitator(opts.facilitator ?? { url: DEFAULT_FACILITATOR_URL })\n  const verified = await facilitator.verify(payment, matched)\n  if (!verified.isValid) {\n    return {\n      type: 'paymentRequired',\n      response: paymentRequiredResponse(\n        requirements,\n        verified.invalidReason ?? 'Payment verification failed',\n      ),\n    }\n  }\n\n  const payer = (verified.payer ?? payment.payload.authorization.from) as Address\n\n  return {\n    type: 'ok',\n    payer,\n    settle: async () => {\n      const result = await facilitator.settle(payment, matched)\n      return {\n        header: encodePayment({\n          success: result.success,\n          transaction: result.transaction,\n          network: result.network ?? matched.network,\n          errorReason: result.errorReason,\n          payer,\n        }),\n        result,\n      }\n    },\n  }\n}\n\nfunction buildRequirements(request: Request, opts: RouteGateOptions): PaymentRequirement[] {\n  const networks = Array.isArray(opts.network) ? opts.network : [opts.network ?? 'base']\n  const atomic = usdToAtomic(opts.price)\n  const resource = opts.resource ?? request.url\n\n  return networks.map((network) => ({\n    scheme: 'exact',\n    network,\n    asset: opts.asset ?? usdcAddress(network),\n    maxAmountRequired: atomic,\n    payTo: opts.recipient,\n    description: opts.description,\n    resource,\n    maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 600,\n    extra: { name: 'USD Coin', version: '2' },\n  }))\n}\n\nfunction paymentRequiredResponse(\n  accepts: PaymentRequirement[],\n  error?: string,\n): Response {\n  const body: PaymentRequiredResponse = { x402Version: 1, accepts, ...(error ? { error } : {}) }\n  return new Response(JSON.stringify(body), {\n    status: 402,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\nexport { Facilitator, DEFAULT_FACILITATOR_URL } from './facilitator.js'\n"]}

package/dist/types-DzGpKiV3.d.cts

@@ -0,0 +1,83 @@
+import { Address, Hex } from 'viem';
+
+type X402Network = 'base' | 'base-sepolia' | 'ethereum' | 'optimism' | 'arbitrum' | 'polygon';
+type X402Scheme = 'exact';
+/**
+ * A single acceptable way to satisfy a payment requirement.
+ * Servers may advertise multiple (e.g. USDC on Base and USDC on Optimism).
+ */
+interface PaymentRequirement {
+    scheme: X402Scheme;
+    network: X402Network;
+    /** Smart contract address of the payment asset (e.g. USDC). */
+    asset: Address;
+    /** Atomic units owed (e.g. 10000 = 0.01 USDC at 6 decimals). */
+    maxAmountRequired: string;
+    /** Recipient address that receives the payment. */
+    payTo: Address;
+    /** Human-readable description of what the buyer is paying for. */
+    description?: string;
+    /** Resource URL being paid for. */
+    resource?: string;
+    /** Seconds the signed authorization remains valid. */
+    maxTimeoutSeconds?: number;
+    /** Optional scheme-specific extra data. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The JSON body returned with an HTTP 402 response.
+ * Matches the x402 spec's discovery document.
+ */
+interface PaymentRequiredResponse {
+    x402Version: 1;
+    accepts: PaymentRequirement[];
+    error?: string;
+}
+/**
+ * A signed payment payload the client sends back in the `X-PAYMENT` header.
+ * The body is a base64-encoded JSON of this shape.
+ */
+interface PaymentPayload {
+    x402Version: 1;
+    scheme: X402Scheme;
+    network: X402Network;
+    payload: ExactEvmPayload;
+}
+/**
+ * EIP-3009 transferWithAuthorization payload for the `exact` scheme.
+ */
+interface ExactEvmPayload {
+    signature: Hex;
+    authorization: {
+        from: Address;
+        to: Address;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: Hex;
+    };
+}
+/** Result of a facilitator verify call. */
+interface VerifyResult {
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: Address;
+}
+/** Result of a facilitator settle call. */
+interface SettleResult {
+    success: boolean;
+    transaction?: Hex;
+    network?: X402Network;
+    errorReason?: string;
+    payer?: Address;
+}
+/** Config for talking to an x402 facilitator service. */
+interface FacilitatorConfig {
+    url: string;
+    /** Optional auth header value, e.g. `Bearer <token>`. */
+    authHeader?: string;
+    /** Pluggable fetcher (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+
+export type { ExactEvmPayload as E, FacilitatorConfig as F, PaymentPayload as P, SettleResult as S, VerifyResult as V, X402Network as X, PaymentRequiredResponse as a, PaymentRequirement as b, X402Scheme as c };

package/dist/types-DzGpKiV3.d.ts

@@ -0,0 +1,83 @@
+import { Address, Hex } from 'viem';
+
+type X402Network = 'base' | 'base-sepolia' | 'ethereum' | 'optimism' | 'arbitrum' | 'polygon';
+type X402Scheme = 'exact';
+/**
+ * A single acceptable way to satisfy a payment requirement.
+ * Servers may advertise multiple (e.g. USDC on Base and USDC on Optimism).
+ */
+interface PaymentRequirement {
+    scheme: X402Scheme;
+    network: X402Network;
+    /** Smart contract address of the payment asset (e.g. USDC). */
+    asset: Address;
+    /** Atomic units owed (e.g. 10000 = 0.01 USDC at 6 decimals). */
+    maxAmountRequired: string;
+    /** Recipient address that receives the payment. */
+    payTo: Address;
+    /** Human-readable description of what the buyer is paying for. */
+    description?: string;
+    /** Resource URL being paid for. */
+    resource?: string;
+    /** Seconds the signed authorization remains valid. */
+    maxTimeoutSeconds?: number;
+    /** Optional scheme-specific extra data. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * The JSON body returned with an HTTP 402 response.
+ * Matches the x402 spec's discovery document.
+ */
+interface PaymentRequiredResponse {
+    x402Version: 1;
+    accepts: PaymentRequirement[];
+    error?: string;
+}
+/**
+ * A signed payment payload the client sends back in the `X-PAYMENT` header.
+ * The body is a base64-encoded JSON of this shape.
+ */
+interface PaymentPayload {
+    x402Version: 1;
+    scheme: X402Scheme;
+    network: X402Network;
+    payload: ExactEvmPayload;
+}
+/**
+ * EIP-3009 transferWithAuthorization payload for the `exact` scheme.
+ */
+interface ExactEvmPayload {
+    signature: Hex;
+    authorization: {
+        from: Address;
+        to: Address;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: Hex;
+    };
+}
+/** Result of a facilitator verify call. */
+interface VerifyResult {
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: Address;
+}
+/** Result of a facilitator settle call. */
+interface SettleResult {
+    success: boolean;
+    transaction?: Hex;
+    network?: X402Network;
+    errorReason?: string;
+    payer?: Address;
+}
+/** Config for talking to an x402 facilitator service. */
+interface FacilitatorConfig {
+    url: string;
+    /** Optional auth header value, e.g. `Bearer <token>`. */
+    authHeader?: string;
+    /** Pluggable fetcher (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+
+export type { ExactEvmPayload as E, FacilitatorConfig as F, PaymentPayload as P, SettleResult as S, VerifyResult as V, X402Network as X, PaymentRequiredResponse as a, PaymentRequirement as b, X402Scheme as c };

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "yeetful",
+  "version": "0.1.0",
+  "description": "Drop-in x402 payments for APIs and clients. Gate routes behind stablecoin micropayments in a few lines.",
+  "keywords": [
+    "x402",
+    "payments",
+    "stablecoin",
+    "usdc",
+    "micropayments",
+    "http-402",
+    "next",
+    "express",
+    "viem",
+    "yeetful"
+  ],
+  "homepage": "https://yeetful.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yeetful/yeetful.git",
+    "directory": "sdk"
+  },
+  "license": "MIT",
+  "author": "Yeetful",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "require": "./dist/next.cjs"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js",
+      "require": "./dist/express.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "viem": "^2.21.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "express": "^4.19.2",
+    "next": "^15.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "viem": "^2.21.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}