@relai-fi/x402 0.5.31 → 0.5.32

package/README.md

@@ -340,6 +340,9 @@ import {
   fromAtomicUnits,
 } from '@relai-fi/x402/utils';
 
+// Plugins — extend protect() with free tier, custom logic
+import { freeTier } from '@relai-fi/x402/plugins';
+
 // Management API — create/manage APIs, pricing, analytics, agent bootstrap
 import {
   createManagementClient,
@@ -508,6 +511,105 @@ app.get('/api/solana-data', relai.protect({
 
 ---
 
+## Plugins
+
+Extend `Relai.protect()` with plugins that run before payment checks. Plugins can skip payment (e.g. free tier), add headers, or attach metadata to requests.
+
+### Free Tier Plugin
+
+Allow buyers to make free API calls before requiring x402 payment. Usage is tracked per buyer (by JWT `sub`, wallet address, or IP) with optional global caps and periodic resets.
+
+```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,        // 10 free calls per buyer
+      resetPeriod: 'daily',     // reset daily (or 'monthly', 'never')
+      globalCap: 1000,          // optional: max 1000 free calls total
+      paths: ['*'],             // optional: apply to all endpoints (default)
+    }),
+  ],
+});
+
+app.get('/api/data', relai.protect({
+  payTo: '0xYourWallet',
+  price: 0.01,
+}), (req, res) => {
+  if (req.x402Free) {
+    // Free tier call — no payment was made
+    console.log('Free call from:', req.x402Plugin);
+  }
+  res.json({ data: 'content' });
+});
+```
+
+**How it works:**
+1. On server start, the plugin syncs its config to the RelAI backend via your service key.
+2. On each request, `beforePaymentCheck` asks the RelAI API if the buyer has free calls remaining.
+3. If free → `next()` is called without payment, `req.x402Free = true`, and usage is recorded.
+4. If exhausted → normal x402 payment flow continues.
+
+**Free Tier config:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceKey` | `string` | **required** | Your RelAI service key (`sk_live_...`) |
+| `perBuyerLimit` | `number` | **required** | Free calls each buyer gets per period |
+| `resetPeriod` | `'never' \| 'daily' \| 'monthly'` | `'never'` | When counters reset |
+| `globalCap` | `number` | — | Max total free calls across all buyers |
+| `paths` | `string[]` | `['*']` | Which endpoints the free tier applies to |
+| `baseUrl` | `string` | `https://api.relai.fi` | RelAI API URL (override for testing) |
+
+**Request properties set on free-tier bypass:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `req.x402Free` | `boolean` | `true` when request was served for free |
+| `req.x402Paid` | `boolean` | `false` on free tier, `true` on paid |
+| `req.x402Plugin` | `string` | Plugin name that granted the bypass (`'freeTier'`) |
+| `req.pluginMeta` | `object` | `{ freeTier: true, remaining: number }` |
+
+**Dashboard:** Manage plugin config and view usage in the RelAI dashboard under **SDK Plugins**.
+
+### Custom Plugins
+
+```typescript
+import type { RelaiPlugin } from '@relai-fi/x402';
+
+const myPlugin: RelaiPlugin = {
+  name: 'myPlugin',
+  beforePaymentCheck: async (ctx) => {
+    if (ctx.req.headers['x-vip'] === 'true') {
+      return { skip: true, reason: 'VIP bypass' };
+    }
+    return {};
+  },
+};
+
+const relai = new Relai({
+  network: 'base',
+  plugins: [myPlugin],
+});
+```
+
+**Plugin interface:**
+
+```typescript
+interface RelaiPlugin {
+  name: string;
+  beforePaymentCheck?: (ctx: PluginContext) => Promise<PluginResult>;
+  afterSettled?: (ctx: PluginContext) => Promise<void>;
+  onInit?: (config: RelaiServerConfig) => Promise<void>;
+}
+```
+
+---
+
 ## Management API
 
 Programmatically create and manage monetised APIs, update pricing, and read analytics. Designed for agents and CI/CD — no browser needed.

package/dist/index.cjs

@@ -508,11 +508,30 @@ async function createStripeDepositAddress(secretKey, amountUsdCents, network = "
   return address;
 }
 var Relai = class {
-  // Cache feePayer per network
   constructor(config) {
     this.feePayerCache = /* @__PURE__ */ new Map();
+    this.pluginsInitialized = false;
     this.network = config.network;
     this.facilitatorUrl = config.facilitatorUrl || RELAI_FACILITATOR_URL;
+    this.plugins = config.plugins ?? [];
+    if (this.plugins.length > 0) {
+      this.initPlugins().catch((err) => {
+        console.warn("[Relai] Plugin initialization error (non-blocking):", err);
+      });
+    }
+  }
+  async initPlugins() {
+    if (this.pluginsInitialized) return;
+    for (const plugin of this.plugins) {
+      if (plugin.onInit) {
+        try {
+          await plugin.onInit();
+        } catch (err) {
+          console.warn(`[Relai] Plugin '${plugin.name}' init failed:`, err);
+        }
+      }
+    }
+    this.pluginsInitialized = true;
   }
   /**
    * Get feePayer address for a network (cached)
@@ -603,6 +622,34 @@ var Relai = class {
         const integritasFlow = headerIntegritasFlow || configuredIntegritas.flow;
         const integritasMode = integritasFlow === "single" ? "single_signature_fee_included" : integritasFlow === "dual" ? "dual_signature_split" : void 0;
         const paymentHeader = req.headers["x-payment"] || req.headers["payment-signature"] || req.headers["x-payment-signature"];
+        if (!paymentHeader && self.plugins.length > 0) {
+          const pluginCtx = {
+            network,
+            price: resolvedPrice,
+            path: req.path || req.originalUrl || "/",
+            method: (req.method || "GET").toUpperCase()
+          };
+          for (const plugin of self.plugins) {
+            if (!plugin.beforePaymentCheck) continue;
+            try {
+              const pluginResult = await plugin.beforePaymentCheck(req, pluginCtx);
+              if (pluginResult?.skip) {
+                if (pluginResult.headers) {
+                  for (const [k, v] of Object.entries(pluginResult.headers)) {
+                    res.setHeader(k, v);
+                  }
+                }
+                req.pluginMeta = { ...req.pluginMeta || {}, ...pluginResult.meta || {} };
+                req.x402Paid = false;
+                req.x402Free = true;
+                req.x402Plugin = plugin.name;
+                return next();
+              }
+            } catch (pluginErr) {
+              console.warn(`[Relai] Plugin '${plugin.name}' beforePaymentCheck error (non-blocking):`, pluginErr);
+            }
+          }
+        }
         if (!paymentHeader) {
           options.onPaymentRequired?.(req, { price: resolvedPrice, network });
           let resolvedPayTo;
@@ -741,6 +788,22 @@ var Relai = class {
           Buffer.from(JSON.stringify(paymentResponse)).toString("base64")
         );
         options.onPaymentSettled?.(req, result);
+        if (self.plugins.length > 0) {
+          const settleCtx = {
+            network,
+            price: resolvedPrice,
+            path: req.path || req.originalUrl || "/",
+            method: (req.method || "GET").toUpperCase()
+          };
+          for (const plugin of self.plugins) {
+            if (!plugin.afterSettled) continue;
+            try {
+              await plugin.afterSettled(req, result, settleCtx);
+            } catch (pluginErr) {
+              console.warn(`[Relai] Plugin '${plugin.name}' afterSettled error (non-blocking):`, pluginErr);
+            }
+          }
+        }
         if (options.customRules) {
           const valid = await options.customRules(req);
           if (!valid) {