@relai-fi/x402 0.5.31 → 0.5.33

package/dist/plugins.cjs

@@ -0,0 +1,150 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugins.ts
+var plugins_exports = {};
+__export(plugins_exports, {
+  freeTier: () => freeTier
+});
+module.exports = __toCommonJS(plugins_exports);
+var RELAI_API_BASE = "https://api.relai.fi";
+function freeTier(config) {
+  const base = (config.baseUrl ?? RELAI_API_BASE).replace(/\/$/, "");
+  const cacheTtl = config.cacheTtlMs ?? 5e3;
+  const cache = /* @__PURE__ */ new Map();
+  function resolveHeaders() {
+    return {
+      "X-Service-Key": config.serviceKey,
+      "Content-Type": "application/json"
+    };
+  }
+  function resolveBuyerId(req) {
+    try {
+      const auth = req.headers?.authorization || "";
+      if (auth.startsWith("Bearer ")) {
+        const token = auth.slice(7).trim();
+        const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64").toString());
+        if (payload?.sub) return `user:${payload.sub}`;
+      }
+    } catch {
+    }
+    const wallet = req.headers?.["x-wallet-address"] || req.headers?.["x-buyer-address"];
+    if (wallet) return `wallet:${wallet}`;
+    const ip = (req.headers?.["x-forwarded-for"] || "").split(",")[0].trim() || req.socket?.remoteAddress || req.ip || "unknown";
+    return `ip:${ip}`;
+  }
+  function cacheKey(path, buyerId) {
+    return `${config.serviceKey}:${path}:${buyerId}`;
+  }
+  async function checkFreeTier(path, buyerId) {
+    const key = cacheKey(path, buyerId);
+    const now = Date.now();
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return cached.result;
+    }
+    try {
+      const res = await fetch(`${base}/v1/plugins/free-tier/check`, {
+        method: "POST",
+        headers: resolveHeaders(),
+        body: JSON.stringify({ path, buyerId })
+      });
+      if (!res.ok) {
+        return { free: false, reason: `api_error_${res.status}` };
+      }
+      const result = await res.json();
+      cache.set(key, { result, expiresAt: now + cacheTtl });
+      return result;
+    } catch (err) {
+      return { free: false, reason: "network_error" };
+    }
+  }
+  async function recordCall(path, buyerId) {
+    try {
+      await fetch(`${base}/v1/plugins/free-tier/record`, {
+        method: "POST",
+        headers: resolveHeaders(),
+        body: JSON.stringify({ path, buyerId })
+      });
+      cache.delete(cacheKey(path, buyerId));
+    } catch {
+    }
+  }
+  async function syncConfig() {
+    try {
+      const paths = config.paths ?? ["*"];
+      await fetch(`${base}/v1/plugins/free-tier/config`, {
+        method: "PUT",
+        headers: resolveHeaders(),
+        body: JSON.stringify({
+          perBuyerLimit: config.perBuyerLimit,
+          resetPeriod: config.resetPeriod ?? "never",
+          globalCap: config.globalCap ?? null,
+          paths
+        })
+      });
+    } catch (err) {
+      console.warn(`[relai:freeTier] Failed to sync config to RelAI: ${err}`);
+    }
+  }
+  return {
+    name: "free-tier",
+    async onInit() {
+      await syncConfig();
+    },
+    async beforePaymentCheck(req, ctx) {
+      const requestPath = ctx.path || "/";
+      const paths = config.paths ?? ["*"];
+      const pathMatches = paths.includes("*") || paths.some((p) => {
+        const normalized = p.toLowerCase().replace(/\/+$/, "") || "/";
+        const reqNormalized = requestPath.toLowerCase().replace(/\/+$/, "") || "/";
+        return normalized === reqNormalized || normalized === "*";
+      });
+      if (!pathMatches) {
+        return {};
+      }
+      const buyerId = resolveBuyerId(req);
+      const result = await checkFreeTier(requestPath, buyerId);
+      if (result.free) {
+        recordCall(requestPath, buyerId).catch(() => {
+        });
+        return {
+          skip: true,
+          headers: {
+            "X-Free-Calls-Remaining": String(result.remaining ?? 0),
+            "X-Free-Calls-Total": String(result.total ?? config.perBuyerLimit),
+            ...result.globalRemaining != null ? { "X-Free-Calls-Global-Remaining": String(result.globalRemaining) } : {}
+          },
+          meta: {
+            freeTier: true,
+            buyerId,
+            remaining: result.remaining,
+            total: result.total ?? config.perBuyerLimit
+          }
+        };
+      }
+      return {};
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  freeTier
+});
+//# sourceMappingURL=plugins.cjs.map

package/dist/plugins.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugins.ts"],"sourcesContent":["// src/plugins.ts\n// RelAI Plugin System - extensible middleware hooks for Relai.protect()\n\nimport type { RelaiNetwork } from './types';\nimport type { SettleResult } from './server';\n\nconst RELAI_API_BASE = 'https://api.relai.fi';\n\n// ============================================================================\n// Plugin Interface\n// ============================================================================\n\nexport interface PluginContext {\n  /** Network for this endpoint */\n  network: RelaiNetwork;\n  /** Price in USD */\n  price: number;\n  /** Request path */\n  path: string;\n  /** HTTP method */\n  method: string;\n}\n\nexport interface PluginResult {\n  /** If true, skip payment and serve content for free */\n  skip?: boolean;\n  /** Extra response headers to set */\n  headers?: Record<string, string>;\n  /** Metadata attached to req.pluginMeta */\n  meta?: Record<string, unknown>;\n}\n\nexport interface RelaiPlugin {\n  /** Unique plugin name */\n  name: string;\n\n  /**\n   * Called before the 402 payment check.\n   * Return { skip: true } to bypass payment entirely.\n   */\n  beforePaymentCheck?(req: any, ctx: PluginContext): Promise<PluginResult>;\n\n  /**\n   * Called after a successful payment settlement.\n   * Use for analytics, logging, webhooks, etc.\n   */\n  afterSettled?(req: any, result: SettleResult, ctx: PluginContext): Promise<void>;\n\n  /**\n   * Called once when the Relai instance initializes (server start).\n   * Use to sync config to RelAI backend or validate credentials.\n   */\n  onInit?(): Promise<void>;\n}\n\n// ============================================================================\n// Free Tier Plugin\n// ============================================================================\n\nexport interface FreeTierPluginConfig {\n  /** Service key (sk_live_...) for authenticating with RelAI API */\n  serviceKey: string;\n  /** Max free calls per buyer per period */\n  perBuyerLimit: number;\n  /** Reset period for per-buyer counters */\n  resetPeriod?: 'never' | 'daily' | 'monthly';\n  /** Optional global cap across all buyers */\n  globalCap?: number;\n  /** Specific paths to apply free tier to (default: '*' = all) */\n  paths?: string[];\n  /** Override RelAI API base URL (default: https://api.relai.fi) */\n  baseUrl?: string;\n  /** Cache TTL in ms for check results (default: 5000) */\n  cacheTtlMs?: number;\n}\n\ninterface FreeTierCheckResponse {\n  free: boolean;\n  remaining?: number;\n  total?: number;\n  reason?: string;\n  globalRemaining?: number;\n}\n\n/**\n * Free Tier plugin - gives buyers a number of free API calls\n * before requiring payment.\n *\n * State is stored in the RelAI backend, keyed by your service key.\n * Config can be set here (SDK-side) or overridden in the relai.fi dashboard.\n *\n * @example\n * ```typescript\n * import Relai from '@relai-fi/x402/server';\n * import { freeTier } from '@relai-fi/x402/plugins';\n *\n * const relai = new Relai({\n *   network: 'base',\n *   plugins: [\n *     freeTier({\n *       serviceKey: process.env.RELAI_SERVICE_KEY!,\n *       perBuyerLimit: 10,\n *       resetPeriod: 'daily',\n *     }),\n *   ],\n * });\n *\n * app.get('/api/data', relai.protect({\n *   payTo: '0xYourWallet',\n *   price: 0.01,\n * }), (req, res) => {\n *   res.json({ data: 'paid content' });\n * });\n * ```\n */\nexport function freeTier(config: FreeTierPluginConfig): RelaiPlugin {\n  const base = (config.baseUrl ?? RELAI_API_BASE).replace(/\\/$/, '');\n  const cacheTtl = config.cacheTtlMs ?? 5000;\n\n  // Simple in-memory cache: \"serviceKey:path:buyerId\" -> { result, expiresAt }\n  const cache = new Map<string, { result: FreeTierCheckResponse; expiresAt: number }>();\n\n  function resolveHeaders(): Record<string, string> {\n    return {\n      'X-Service-Key': config.serviceKey,\n      'Content-Type': 'application/json',\n    };\n  }\n\n  /**\n   * Resolve buyer identity from the request.\n   * Priority: JWT sub > x-wallet-address > IP fallback\n   */\n  function resolveBuyerId(req: any): string {\n    // 1. JWT Bearer token\n    try {\n      const auth = req.headers?.authorization || '';\n      if (auth.startsWith('Bearer ')) {\n        const token = auth.slice(7).trim();\n        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());\n        if (payload?.sub) return `user:${payload.sub}`;\n      }\n    } catch { /* ignore */ }\n\n    // 2. Explicit wallet header\n    const wallet = req.headers?.['x-wallet-address'] || req.headers?.['x-buyer-address'];\n    if (wallet) return `wallet:${wallet}`;\n\n    // 3. IP fallback\n    const ip =\n      (req.headers?.['x-forwarded-for'] || '').split(',')[0].trim() ||\n      req.socket?.remoteAddress ||\n      req.ip ||\n      'unknown';\n    return `ip:${ip}`;\n  }\n\n  function cacheKey(path: string, buyerId: string): string {\n    return `${config.serviceKey}:${path}:${buyerId}`;\n  }\n\n  async function checkFreeTier(path: string, buyerId: string): Promise<FreeTierCheckResponse> {\n    const key = cacheKey(path, buyerId);\n    const now = Date.now();\n    const cached = cache.get(key);\n    if (cached && cached.expiresAt > now) {\n      return cached.result;\n    }\n\n    try {\n      const res = await fetch(`${base}/v1/plugins/free-tier/check`, {\n        method: 'POST',\n        headers: resolveHeaders(),\n        body: JSON.stringify({ path, buyerId }),\n      });\n\n      if (!res.ok) {\n        // Non-blocking: if API unreachable, default to not-free\n        return { free: false, reason: `api_error_${res.status}` };\n      }\n\n      const result = await res.json() as FreeTierCheckResponse;\n      cache.set(key, { result, expiresAt: now + cacheTtl });\n      return result;\n    } catch (err) {\n      // Network error - non-blocking, default to paid\n      return { free: false, reason: 'network_error' };\n    }\n  }\n\n  async function recordCall(path: string, buyerId: string): Promise<void> {\n    try {\n      await fetch(`${base}/v1/plugins/free-tier/record`, {\n        method: 'POST',\n        headers: resolveHeaders(),\n        body: JSON.stringify({ path, buyerId }),\n      });\n      // Invalidate cache for this buyer+path after recording\n      cache.delete(cacheKey(path, buyerId));\n    } catch {\n      // Fire-and-forget\n    }\n  }\n\n  async function syncConfig(): Promise<void> {\n    try {\n      const paths = config.paths ?? ['*'];\n      await fetch(`${base}/v1/plugins/free-tier/config`, {\n        method: 'PUT',\n        headers: resolveHeaders(),\n        body: JSON.stringify({\n          perBuyerLimit: config.perBuyerLimit,\n          resetPeriod: config.resetPeriod ?? 'never',\n          globalCap: config.globalCap ?? null,\n          paths,\n        }),\n      });\n    } catch (err) {\n      console.warn(`[relai:freeTier] Failed to sync config to RelAI: ${err}`);\n    }\n  }\n\n  return {\n    name: 'free-tier',\n\n    async onInit() {\n      await syncConfig();\n    },\n\n    async beforePaymentCheck(req, ctx) {\n      const requestPath = ctx.path || '/';\n\n      // Check if this path is covered by the plugin\n      const paths = config.paths ?? ['*'];\n      const pathMatches = paths.includes('*') || paths.some((p) => {\n        const normalized = p.toLowerCase().replace(/\\/+$/, '') || '/';\n        const reqNormalized = requestPath.toLowerCase().replace(/\\/+$/, '') || '/';\n        return normalized === reqNormalized || normalized === '*';\n      });\n\n      if (!pathMatches) {\n        return {};\n      }\n\n      const buyerId = resolveBuyerId(req);\n      const result = await checkFreeTier(requestPath, buyerId);\n\n      if (result.free) {\n        // Record the call (fire-and-forget)\n        recordCall(requestPath, buyerId).catch(() => {});\n\n        return {\n          skip: true,\n          headers: {\n            'X-Free-Calls-Remaining': String(result.remaining ?? 0),\n            'X-Free-Calls-Total': String(result.total ?? config.perBuyerLimit),\n            ...(result.globalRemaining != null\n              ? { 'X-Free-Calls-Global-Remaining': String(result.globalRemaining) }\n              : {}),\n          },\n          meta: {\n            freeTier: true,\n            buyerId,\n            remaining: result.remaining,\n            total: result.total ?? config.perBuyerLimit,\n          },\n        };\n      }\n\n      return {};\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/plugins.d.cts

@@ -0,0 +1,2 @@
+import './types-Y9ni5XwY.cjs';
+export { F as FreeTierPluginConfig, g as PluginContext, h as PluginResult, f as RelaiPlugin, i as freeTier } from './server-BAPqyEka.cjs';

package/dist/plugins.d.ts

@@ -0,0 +1,2 @@
+import './types-Y9ni5XwY.js';
+export { F as FreeTierPluginConfig, g as PluginContext, h as PluginResult, f as RelaiPlugin, i as freeTier } from './server-BRSLRU_Y.js';

package/dist/plugins.js

@@ -0,0 +1,125 @@
+// src/plugins.ts
+var RELAI_API_BASE = "https://api.relai.fi";
+function freeTier(config) {
+  const base = (config.baseUrl ?? RELAI_API_BASE).replace(/\/$/, "");
+  const cacheTtl = config.cacheTtlMs ?? 5e3;
+  const cache = /* @__PURE__ */ new Map();
+  function resolveHeaders() {
+    return {
+      "X-Service-Key": config.serviceKey,
+      "Content-Type": "application/json"
+    };
+  }
+  function resolveBuyerId(req) {
+    try {
+      const auth = req.headers?.authorization || "";
+      if (auth.startsWith("Bearer ")) {
+        const token = auth.slice(7).trim();
+        const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64").toString());
+        if (payload?.sub) return `user:${payload.sub}`;
+      }
+    } catch {
+    }
+    const wallet = req.headers?.["x-wallet-address"] || req.headers?.["x-buyer-address"];
+    if (wallet) return `wallet:${wallet}`;
+    const ip = (req.headers?.["x-forwarded-for"] || "").split(",")[0].trim() || req.socket?.remoteAddress || req.ip || "unknown";
+    return `ip:${ip}`;
+  }
+  function cacheKey(path, buyerId) {
+    return `${config.serviceKey}:${path}:${buyerId}`;
+  }
+  async function checkFreeTier(path, buyerId) {
+    const key = cacheKey(path, buyerId);
+    const now = Date.now();
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return cached.result;
+    }
+    try {
+      const res = await fetch(`${base}/v1/plugins/free-tier/check`, {
+        method: "POST",
+        headers: resolveHeaders(),
+        body: JSON.stringify({ path, buyerId })
+      });
+      if (!res.ok) {
+        return { free: false, reason: `api_error_${res.status}` };
+      }
+      const result = await res.json();
+      cache.set(key, { result, expiresAt: now + cacheTtl });
+      return result;
+    } catch (err) {
+      return { free: false, reason: "network_error" };
+    }
+  }
+  async function recordCall(path, buyerId) {
+    try {
+      await fetch(`${base}/v1/plugins/free-tier/record`, {
+        method: "POST",
+        headers: resolveHeaders(),
+        body: JSON.stringify({ path, buyerId })
+      });
+      cache.delete(cacheKey(path, buyerId));
+    } catch {
+    }
+  }
+  async function syncConfig() {
+    try {
+      const paths = config.paths ?? ["*"];
+      await fetch(`${base}/v1/plugins/free-tier/config`, {
+        method: "PUT",
+        headers: resolveHeaders(),
+        body: JSON.stringify({
+          perBuyerLimit: config.perBuyerLimit,
+          resetPeriod: config.resetPeriod ?? "never",
+          globalCap: config.globalCap ?? null,
+          paths
+        })
+      });
+    } catch (err) {
+      console.warn(`[relai:freeTier] Failed to sync config to RelAI: ${err}`);
+    }
+  }
+  return {
+    name: "free-tier",
+    async onInit() {
+      await syncConfig();
+    },
+    async beforePaymentCheck(req, ctx) {
+      const requestPath = ctx.path || "/";
+      const paths = config.paths ?? ["*"];
+      const pathMatches = paths.includes("*") || paths.some((p) => {
+        const normalized = p.toLowerCase().replace(/\/+$/, "") || "/";
+        const reqNormalized = requestPath.toLowerCase().replace(/\/+$/, "") || "/";
+        return normalized === reqNormalized || normalized === "*";
+      });
+      if (!pathMatches) {
+        return {};
+      }
+      const buyerId = resolveBuyerId(req);
+      const result = await checkFreeTier(requestPath, buyerId);
+      if (result.free) {
+        recordCall(requestPath, buyerId).catch(() => {
+        });
+        return {
+          skip: true,
+          headers: {
+            "X-Free-Calls-Remaining": String(result.remaining ?? 0),
+            "X-Free-Calls-Total": String(result.total ?? config.perBuyerLimit),
+            ...result.globalRemaining != null ? { "X-Free-Calls-Global-Remaining": String(result.globalRemaining) } : {}
+          },
+          meta: {
+            freeTier: true,
+            buyerId,
+            remaining: result.remaining,
+            total: result.total ?? config.perBuyerLimit
+          }
+        };
+      }
+      return {};
+    }
+  };
+}
+export {
+  freeTier
+};
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugins.ts"],"sourcesContent":["// src/plugins.ts\n// RelAI Plugin System - extensible middleware hooks for Relai.protect()\n\nimport type { RelaiNetwork } from './types';\nimport type { SettleResult } from './server';\n\nconst RELAI_API_BASE = 'https://api.relai.fi';\n\n// ============================================================================\n// Plugin Interface\n// ============================================================================\n\nexport interface PluginContext {\n  /** Network for this endpoint */\n  network: RelaiNetwork;\n  /** Price in USD */\n  price: number;\n  /** Request path */\n  path: string;\n  /** HTTP method */\n  method: string;\n}\n\nexport interface PluginResult {\n  /** If true, skip payment and serve content for free */\n  skip?: boolean;\n  /** Extra response headers to set */\n  headers?: Record<string, string>;\n  /** Metadata attached to req.pluginMeta */\n  meta?: Record<string, unknown>;\n}\n\nexport interface RelaiPlugin {\n  /** Unique plugin name */\n  name: string;\n\n  /**\n   * Called before the 402 payment check.\n   * Return { skip: true } to bypass payment entirely.\n   */\n  beforePaymentCheck?(req: any, ctx: PluginContext): Promise<PluginResult>;\n\n  /**\n   * Called after a successful payment settlement.\n   * Use for analytics, logging, webhooks, etc.\n   */\n  afterSettled?(req: any, result: SettleResult, ctx: PluginContext): Promise<void>;\n\n  /**\n   * Called once when the Relai instance initializes (server start).\n   * Use to sync config to RelAI backend or validate credentials.\n   */\n  onInit?(): Promise<void>;\n}\n\n// ============================================================================\n// Free Tier Plugin\n// ============================================================================\n\nexport interface FreeTierPluginConfig {\n  /** Service key (sk_live_...) for authenticating with RelAI API */\n  serviceKey: string;\n  /** Max free calls per buyer per period */\n  perBuyerLimit: number;\n  /** Reset period for per-buyer counters */\n  resetPeriod?: 'never' | 'daily' | 'monthly';\n  /** Optional global cap across all buyers */\n  globalCap?: number;\n  /** Specific paths to apply free tier to (default: '*' = all) */\n  paths?: string[];\n  /** Override RelAI API base URL (default: https://api.relai.fi) */\n  baseUrl?: string;\n  /** Cache TTL in ms for check results (default: 5000) */\n  cacheTtlMs?: number;\n}\n\ninterface FreeTierCheckResponse {\n  free: boolean;\n  remaining?: number;\n  total?: number;\n  reason?: string;\n  globalRemaining?: number;\n}\n\n/**\n * Free Tier plugin - gives buyers a number of free API calls\n * before requiring payment.\n *\n * State is stored in the RelAI backend, keyed by your service key.\n * Config can be set here (SDK-side) or overridden in the relai.fi dashboard.\n *\n * @example\n * ```typescript\n * import Relai from '@relai-fi/x402/server';\n * import { freeTier } from '@relai-fi/x402/plugins';\n *\n * const relai = new Relai({\n *   network: 'base',\n *   plugins: [\n *     freeTier({\n *       serviceKey: process.env.RELAI_SERVICE_KEY!,\n *       perBuyerLimit: 10,\n *       resetPeriod: 'daily',\n *     }),\n *   ],\n * });\n *\n * app.get('/api/data', relai.protect({\n *   payTo: '0xYourWallet',\n *   price: 0.01,\n * }), (req, res) => {\n *   res.json({ data: 'paid content' });\n * });\n * ```\n */\nexport function freeTier(config: FreeTierPluginConfig): RelaiPlugin {\n  const base = (config.baseUrl ?? RELAI_API_BASE).replace(/\\/$/, '');\n  const cacheTtl = config.cacheTtlMs ?? 5000;\n\n  // Simple in-memory cache: \"serviceKey:path:buyerId\" -> { result, expiresAt }\n  const cache = new Map<string, { result: FreeTierCheckResponse; expiresAt: number }>();\n\n  function resolveHeaders(): Record<string, string> {\n    return {\n      'X-Service-Key': config.serviceKey,\n      'Content-Type': 'application/json',\n    };\n  }\n\n  /**\n   * Resolve buyer identity from the request.\n   * Priority: JWT sub > x-wallet-address > IP fallback\n   */\n  function resolveBuyerId(req: any): string {\n    // 1. JWT Bearer token\n    try {\n      const auth = req.headers?.authorization || '';\n      if (auth.startsWith('Bearer ')) {\n        const token = auth.slice(7).trim();\n        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());\n        if (payload?.sub) return `user:${payload.sub}`;\n      }\n    } catch { /* ignore */ }\n\n    // 2. Explicit wallet header\n    const wallet = req.headers?.['x-wallet-address'] || req.headers?.['x-buyer-address'];\n    if (wallet) return `wallet:${wallet}`;\n\n    // 3. IP fallback\n    const ip =\n      (req.headers?.['x-forwarded-for'] || '').split(',')[0].trim() ||\n      req.socket?.remoteAddress ||\n      req.ip ||\n      'unknown';\n    return `ip:${ip}`;\n  }\n\n  function cacheKey(path: string, buyerId: string): string {\n    return `${config.serviceKey}:${path}:${buyerId}`;\n  }\n\n  async function checkFreeTier(path: string, buyerId: string): Promise<FreeTierCheckResponse> {\n    const key = cacheKey(path, buyerId);\n    const now = Date.now();\n    const cached = cache.get(key);\n    if (cached && cached.expiresAt > now) {\n      return cached.result;\n    }\n\n    try {\n      const res = await fetch(`${base}/v1/plugins/free-tier/check`, {\n        method: 'POST',\n        headers: resolveHeaders(),\n        body: JSON.stringify({ path, buyerId }),\n      });\n\n      if (!res.ok) {\n        // Non-blocking: if API unreachable, default to not-free\n        return { free: false, reason: `api_error_${res.status}` };\n      }\n\n      const result = await res.json() as FreeTierCheckResponse;\n      cache.set(key, { result, expiresAt: now + cacheTtl });\n      return result;\n    } catch (err) {\n      // Network error - non-blocking, default to paid\n      return { free: false, reason: 'network_error' };\n    }\n  }\n\n  async function recordCall(path: string, buyerId: string): Promise<void> {\n    try {\n      await fetch(`${base}/v1/plugins/free-tier/record`, {\n        method: 'POST',\n        headers: resolveHeaders(),\n        body: JSON.stringify({ path, buyerId }),\n      });\n      // Invalidate cache for this buyer+path after recording\n      cache.delete(cacheKey(path, buyerId));\n    } catch {\n      // Fire-and-forget\n    }\n  }\n\n  async function syncConfig(): Promise<void> {\n    try {\n      const paths = config.paths ?? ['*'];\n      await fetch(`${base}/v1/plugins/free-tier/config`, {\n        method: 'PUT',\n        headers: resolveHeaders(),\n        body: JSON.stringify({\n          perBuyerLimit: config.perBuyerLimit,\n          resetPeriod: config.resetPeriod ?? 'never',\n          globalCap: config.globalCap ?? null,\n          paths,\n        }),\n      });\n    } catch (err) {\n      console.warn(`[relai:freeTier] Failed to sync config to RelAI: ${err}`);\n    }\n  }\n\n  return {\n    name: 'free-tier',\n\n    async onInit() {\n      await syncConfig();\n    },\n\n    async beforePaymentCheck(req, ctx) {\n      const requestPath = ctx.path || '/';\n\n      // Check if this path is covered by the plugin\n      const paths = config.paths ?? ['*'];\n      const pathMatches = paths.includes('*') || paths.some((p) => {\n        const normalized = p.toLowerCase().replace(/\\/+$/, '') || '/';\n        const reqNormalized = requestPath.toLowerCase().replace(/\\/+$/, '') || '/';\n        return normalized === reqNormalized || normalized === '*';\n      });\n\n      if (!pathMatches) {\n        return {};\n      }\n\n      const buyerId = resolveBuyerId(req);\n      const result = await checkFreeTier(requestPath, buyerId);\n\n      if (result.free) {\n        // Record the call (fire-and-forget)\n        recordCall(requestPath, buyerId).catch(() => {});\n\n        return {\n          skip: true,\n          headers: {\n            'X-Free-Calls-Remaining': String(result.remaining ?? 0),\n            'X-Free-Calls-Total': String(result.total ?? config.perBuyerLimit),\n            ...(result.globalRemaining != null\n              ? { 'X-Free-Calls-Global-Remaining': String(result.globalRemaining) }\n              : {}),\n          },\n          meta: {\n            freeTier: true,\n            buyerId,\n            remaining: result.remaining,\n            total: result.total ?? config.perBuyerLimit,\n          },\n        };\n      }\n\n      return {};\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/server-BAPqyEka.d.cts

@@ -0,0 +1,229 @@
+import { a as RelaiNetwork } from './types-Y9ni5XwY.cjs';
+
+interface PluginContext {
+    /** Network for this endpoint */
+    network: RelaiNetwork;
+    /** Price in USD */
+    price: number;
+    /** Request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+}
+interface PluginResult {
+    /** If true, skip payment and serve content for free */
+    skip?: boolean;
+    /** Extra response headers to set */
+    headers?: Record<string, string>;
+    /** Metadata attached to req.pluginMeta */
+    meta?: Record<string, unknown>;
+}
+interface RelaiPlugin {
+    /** Unique plugin name */
+    name: string;
+    /**
+     * Called before the 402 payment check.
+     * Return { skip: true } to bypass payment entirely.
+     */
+    beforePaymentCheck?(req: any, ctx: PluginContext): Promise<PluginResult>;
+    /**
+     * Called after a successful payment settlement.
+     * Use for analytics, logging, webhooks, etc.
+     */
+    afterSettled?(req: any, result: SettleResult, ctx: PluginContext): Promise<void>;
+    /**
+     * Called once when the Relai instance initializes (server start).
+     * Use to sync config to RelAI backend or validate credentials.
+     */
+    onInit?(): Promise<void>;
+}
+interface FreeTierPluginConfig {
+    /** Service key (sk_live_...) for authenticating with RelAI API */
+    serviceKey: string;
+    /** Max free calls per buyer per period */
+    perBuyerLimit: number;
+    /** Reset period for per-buyer counters */
+    resetPeriod?: 'never' | 'daily' | 'monthly';
+    /** Optional global cap across all buyers */
+    globalCap?: number;
+    /** Specific paths to apply free tier to (default: '*' = all) */
+    paths?: string[];
+    /** Override RelAI API base URL (default: https://api.relai.fi) */
+    baseUrl?: string;
+    /** Cache TTL in ms for check results (default: 5000) */
+    cacheTtlMs?: number;
+}
+/**
+ * Free Tier plugin - gives buyers a number of free API calls
+ * before requiring payment.
+ *
+ * State is stored in the RelAI backend, keyed by your service key.
+ * Config can be set here (SDK-side) or overridden in the relai.fi dashboard.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ * import { freeTier } from '@relai-fi/x402/plugins';
+ *
+ * const relai = new Relai({
+ *   network: 'base',
+ *   plugins: [
+ *     freeTier({
+ *       serviceKey: process.env.RELAI_SERVICE_KEY!,
+ *       perBuyerLimit: 10,
+ *       resetPeriod: 'daily',
+ *     }),
+ *   ],
+ * });
+ *
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,
+ * }), (req, res) => {
+ *   res.json({ data: 'paid content' });
+ * });
+ * ```
+ */
+declare function freeTier(config: FreeTierPluginConfig): RelaiPlugin;
+
+interface RelaiServerConfig {
+    /** Network to accept payments on */
+    network: RelaiNetwork;
+    /** RelAI facilitator URL (default: https://facilitator.x402.fi) */
+    facilitatorUrl?: string;
+    /** Plugins to extend protect() behavior (e.g. freeTier, rateLimit) */
+    plugins?: RelaiPlugin[];
+}
+type DynamicPrice = number | ((req: any) => number | Promise<number>);
+type RelaiIntegritasFlow = 'single' | 'dual';
+interface RelaiIntegritasOptions {
+    /** Enable Integritas by default for this endpoint */
+    enabled?: boolean;
+    /** Default flow when Integritas is enabled */
+    flow?: RelaiIntegritasFlow;
+}
+interface ProtectOptions {
+    /** Price in USD (e.g., 0.01 for 1 cent) */
+    price: DynamicPrice;
+    /** Optional token asset address for networks supporting multiple tokens */
+    asset?: string;
+    /** Wallet address to receive payments, or stripePayTo() for Stripe settlement */
+    payTo: string | StripePayTo;
+    /** Description shown to payer */
+    description?: string;
+    /** MIME type of the response (default: application/json) */
+    mimeType?: string;
+    /** Maximum timeout in seconds (default: 60) */
+    maxTimeoutSeconds?: number;
+    /** Integritas options (or simple boolean enable flag) */
+    integritas?: boolean | RelaiIntegritasOptions;
+    /** Override network for this endpoint */
+    network?: RelaiNetwork;
+    /** Override feePayer address (Solana only) — bypasses facilitator /supported fetch */
+    feePayer?: string;
+    /** Custom validation after payment is settled */
+    customRules?: (req: any) => boolean | Promise<boolean>;
+    /** Callback when 402 is returned (no payment provided) */
+    onPaymentRequired?: (req: any, info: {
+        price: number;
+        network: RelaiNetwork;
+    }) => void;
+    /** Callback when payment is settled successfully */
+    onPaymentSettled?: (req: any, result: SettleResult) => void;
+    /** Callback on error */
+    onError?: (req: any, error: unknown) => void;
+}
+interface SettleResult {
+    success: boolean;
+    transaction?: string;
+    payer?: string;
+    network?: string;
+    splitTransfers?: Record<string, unknown>;
+    integritasFeePaid?: boolean;
+    provenance?: Record<string, unknown>;
+    integritas?: Record<string, unknown>;
+    error?: string;
+    errorReason?: string;
+}
+interface PaymentInfo {
+    verified: boolean;
+    transactionId?: string;
+    payer?: string;
+    network: RelaiNetwork;
+    amount: number;
+}
+/** Config returned by stripePayTo() - used by protect() to create Stripe deposit addresses */
+interface StripePayTo {
+    readonly __brand: 'stripePayTo';
+    readonly secretKey: string;
+    /** Stripe crypto deposits network (default: 'base') */
+    readonly stripeNetwork: string;
+}
+/**
+ * Create a Stripe pay-to configuration for x402 payments.
+ * Payments settle as USD in your Stripe Dashboard - no crypto knowledge required.
+ *
+ * Stripe creates a fresh PaymentIntent + deposit address per request.
+ * Network is auto-set to Base (Stripe settles USDC on Base).
+ *
+ * @example
+ * ```typescript
+ * import Relai, { stripePayTo } from '@relai-fi/x402/server';
+ *
+ * const relai = new Relai({ network: 'base' });
+ *
+ * app.get('/api/data', relai.protect({
+ *   price: 0.01,
+ *   payTo: stripePayTo(process.env.STRIPE_SECRET_KEY!),
+ * }), (req, res) => {
+ *   res.json({ data: 'paid content' });
+ * });
+ * ```
+ */
+declare function stripePayTo(stripeSecretKey: string, options?: {
+    network?: string;
+}): StripePayTo;
+/**
+ * Server-side SDK for protecting Express endpoints with x402 micropayments.
+ * Settles payments through the RelAI facilitator (zero gas fees for users).
+ *
+ * Supports: Solana, Base, Avalanche, SKALE Base, SKALE Base Sepolia, SKALE BITE, Polygon, and Ethereum.
+ *
+ * @example
+ * ```typescript
+ * import Relai from '@relai-fi/x402/server';
+ *
+ * const relai = new Relai({ network: 'base' });
+ *
+ * app.get('/api/data', relai.protect({
+ *   payTo: '0xYourWallet',
+ *   price: 0.01,  // $0.01 USDC
+ * }), (req, res) => {
+ *   res.json({ data: 'Protected content', payment: req.payment });
+ * });
+ * ```
+ */
+declare class Relai {
+    private network;
+    private facilitatorUrl;
+    private feePayerCache;
+    private plugins;
+    private pluginInitPromise;
+    constructor(config: RelaiServerConfig);
+    private runPluginInit;
+    /**
+     * Get feePayer address for a network (cached)
+     */
+    private getFeePayer;
+    /**
+     * Express middleware to protect an endpoint with x402 micropayments.
+     *
+     * Flow:
+     * 1. No payment header → returns 402 with payment requirements
+     * 2. Payment header present → calls RelAI facilitator `/settle`
+     * 3. Settlement success → sets `PAYMENT-RESPONSE` header, attaches `req.payment`, calls `next()`
+     */
+    protect(options: ProtectOptions): (req: any, res: any, next: any) => Promise<any>;
+}
+
+export { type DynamicPrice as D, type FreeTierPluginConfig as F, type ProtectOptions as P, Relai as R, type SettleResult as S, type RelaiServerConfig as a, type PaymentInfo as b, type StripePayTo as c, type RelaiIntegritasFlow as d, type RelaiIntegritasOptions as e, type RelaiPlugin as f, type PluginContext as g, type PluginResult as h, freeTier as i, stripePayTo as s };