@ch4p/plugin-x402 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -72,6 +72,26 @@ interface X402PaymentPayload {
         authorization: X402PaymentAuthorization;
     };
 }
+/**
+ * Per-route payment override for a specific path pattern.
+ * When a request matches this pattern (using the same rules as `protectedPaths`),
+ * the route's `amount` and optional `description` take precedence over the
+ * global `X402ServerConfig` values.
+ */
+interface X402RouteConfig {
+    /**
+     * URL path pattern to match. Supports the same syntax as `protectedPaths`:
+     * exact match ("/sessions"), wildcard prefix ("/webhooks/*"), or catch-all ("/*").
+     */
+    path: string;
+    /**
+     * Amount in the asset's smallest unit for requests matching this route.
+     * Overrides the global `amount` for this path.
+     */
+    amount: string;
+    /** Human-readable description override for this route's 402 response. */
+    description?: string;
+}
 /**
  * Server-side x402 protection configuration.
  */
@@ -79,8 +99,9 @@ interface X402ServerConfig {
     /** Wallet address that receives payments. */
     payTo: string;
     /**
-     * Payment amount in the asset's smallest unit.
+     * Global payment amount in the asset's smallest unit.
      * Example: "1000000" = 1 USDC (6 decimals).
+     * Individual routes can override this via `routes`.
      */
     amount: string;
     /**
@@ -103,6 +124,15 @@ interface X402ServerConfig {
     protectedPaths?: string[];
     /** Seconds before a payment authorization expires. Default: 300. */
     maxTimeoutSeconds?: number;
+    /**
+     * Per-route pricing overrides.
+     * Each entry matches a path pattern and supplies an `amount` (and optional
+     * `description`) that replaces the global values for requests on that path.
+     * Routes are checked in order; the first match wins.
+     * Paths still need to appear in `protectedPaths` (or the default "/*") to
+     * be gated at all — `routes` only changes the *price*, not the *gating*.
+     */
+    routes?: X402RouteConfig[];
     /**
      * Optional payment verifier. Called with the decoded payment and the
      * active requirements after the X-PAYMENT header passes structural

package/dist/index.js

@@ -69,12 +69,15 @@ function createX402Middleware(config) {
     if (PUBLIC_PATHS.has(urlPath)) return false;
     const isProtected = protectedPaths.some((p) => pathMatches(urlPath, p));
     if (!isProtected) return false;
+    const matchedRoute = serverCfg.routes?.find((r) => pathMatches(urlPath, r.path));
+    const effectiveAmount = matchedRoute?.amount ?? serverCfg.amount;
+    const effectiveDescription = matchedRoute?.description ?? description;
     const requirements = {
       scheme: "exact",
       network,
-      maxAmountRequired: serverCfg.amount,
+      maxAmountRequired: effectiveAmount,
       resource: urlPath,
-      description,
+      description: effectiveDescription,
       mimeType: "application/json",
       payTo: serverCfg.payTo,
       maxTimeoutSeconds,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ch4p/plugin-x402",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "x402 HTTP micropayment plugin for ch4p — server middleware and agent payment tool",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "ethers": "^6.14.0",
-    "@ch4p/core": "0.1.5"
+    "@ch4p/core": "0.2.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",

package/src/middleware.test.ts

@@ -295,6 +295,114 @@ describe('createX402Middleware — valid payment', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// createX402Middleware — per-route pricing
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — per-route pricing', () => {
+  const ROUTE_CONFIG: X402Config = {
+    enabled: true,
+    server: {
+      payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+      amount: '1000000',   // global: 1 USDC
+      description: 'Global description',
+      protectedPaths: ['/sessions', '/sessions/*', '/webhooks/*'],
+      routes: [
+        { path: '/sessions',    amount: '500000',  description: 'Session route' },
+        { path: '/sessions/*',  amount: '250000' },
+        { path: '/webhooks/*',  amount: '2000000', description: 'Webhook route' },
+      ],
+    },
+  };
+
+  it('route-specific amount overrides global amount', async () => {
+    const handler = createX402Middleware(ROUTE_CONFIG)!;
+    const res = makeRes();
+    await handler(makeReq('/sessions'), res as unknown as ServerResponse);
+    expect(res.statusCode).toBe(402);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].maxAmountRequired).toBe('500000');
+  });
+
+  it('route-specific description overrides global description', async () => {
+    const handler = createX402Middleware(ROUTE_CONFIG)!;
+    const res = makeRes();
+    await handler(makeReq('/sessions'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].description).toBe('Session route');
+  });
+
+  it('wildcard route matches sub-path with its amount', async () => {
+    const handler = createX402Middleware(ROUTE_CONFIG)!;
+    const res = makeRes();
+    await handler(makeReq('/sessions/abc'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].maxAmountRequired).toBe('250000');
+  });
+
+  it('falls back to global description when route has none', async () => {
+    const handler = createX402Middleware(ROUTE_CONFIG)!;
+    const res = makeRes();
+    await handler(makeReq('/sessions/abc'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].description).toBe('Global description');
+  });
+
+  it('path not in routes falls back to global amount', async () => {
+    const cfg: X402Config = {
+      enabled: true,
+      server: {
+        payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        amount: '1000000',
+        protectedPaths: ['/other'],
+        routes: [{ path: '/sessions', amount: '500000' }],
+      },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    await handler(makeReq('/other'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].maxAmountRequired).toBe('1000000');
+  });
+
+  it('routes: [] (empty) falls back to global amount', async () => {
+    const cfg: X402Config = {
+      enabled: true,
+      server: {
+        payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        amount: '1000000',
+        protectedPaths: ['/sessions'],
+        routes: [],
+      },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    await handler(makeReq('/sessions'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].maxAmountRequired).toBe('1000000');
+  });
+
+  it('first matching route wins when multiple routes could match', async () => {
+    const cfg: X402Config = {
+      enabled: true,
+      server: {
+        payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        amount: '1000000',
+        protectedPaths: ['/api/*'],
+        routes: [
+          { path: '/api/*',     amount: '100000' },
+          { path: '/api/data',  amount: '999999' }, // should never be reached for /api/data
+        ],
+      },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    await handler(makeReq('/api/data'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].maxAmountRequired).toBe('100000');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // createX402Middleware — defaults
 // ---------------------------------------------------------------------------

package/src/middleware.ts

@@ -141,12 +141,18 @@ export function createX402Middleware(config: X402Config): X402PreHandler | null
     const isProtected = protectedPaths.some((p) => pathMatches(urlPath, p));
     if (!isProtected) return false;
 
+    // Per-route pricing: find the first route whose path pattern matches.
+    const matchedRoute = serverCfg.routes?.find((r) => pathMatches(urlPath, r.path));
+    const effectiveAmount = matchedRoute?.amount ?? serverCfg.amount;
+    const effectiveDescription =
+      matchedRoute?.description ?? description;
+
     const requirements: X402PaymentRequirements = {
       scheme: 'exact',
       network,
-      maxAmountRequired: serverCfg.amount,
+      maxAmountRequired: effectiveAmount,
       resource: urlPath,
-      description,
+      description: effectiveDescription,
       mimeType: 'application/json',
       payTo: serverCfg.payTo,
       maxTimeoutSeconds,

package/src/types.ts

@@ -74,6 +74,27 @@ export interface X402PaymentPayload {
   };
 }
 
+/**
+ * Per-route payment override for a specific path pattern.
+ * When a request matches this pattern (using the same rules as `protectedPaths`),
+ * the route's `amount` and optional `description` take precedence over the
+ * global `X402ServerConfig` values.
+ */
+export interface X402RouteConfig {
+  /**
+   * URL path pattern to match. Supports the same syntax as `protectedPaths`:
+   * exact match ("/sessions"), wildcard prefix ("/webhooks/*"), or catch-all ("/*").
+   */
+  path: string;
+  /**
+   * Amount in the asset's smallest unit for requests matching this route.
+   * Overrides the global `amount` for this path.
+   */
+  amount: string;
+  /** Human-readable description override for this route's 402 response. */
+  description?: string;
+}
+
 /**
  * Server-side x402 protection configuration.
  */
@@ -81,8 +102,9 @@ export interface X402ServerConfig {
   /** Wallet address that receives payments. */
   payTo: string;
   /**
-   * Payment amount in the asset's smallest unit.
+   * Global payment amount in the asset's smallest unit.
    * Example: "1000000" = 1 USDC (6 decimals).
+   * Individual routes can override this via `routes`.
    */
   amount: string;
   /**
@@ -105,6 +127,15 @@ export interface X402ServerConfig {
   protectedPaths?: string[];
   /** Seconds before a payment authorization expires. Default: 300. */
   maxTimeoutSeconds?: number;
+  /**
+   * Per-route pricing overrides.
+   * Each entry matches a path pattern and supplies an `amount` (and optional
+   * `description`) that replaces the global values for requests on that path.
+   * Routes are checked in order; the first match wins.
+   * Paths still need to appear in `protectedPaths` (or the default "/*") to
+   * be gated at all — `routes` only changes the *price*, not the *gating*.
+   */
+  routes?: X402RouteConfig[];
   /**
    * Optional payment verifier. Called with the decoded payment and the
    * active requirements after the X-PAYMENT header passes structural