@agentcash/router 0.2.1 → 0.3.0

package/README.md

@@ -18,6 +18,36 @@ pnpm add next zod @x402/core @x402/evm @x402/extensions @coinbase/x402 zod-opena
 pnpm add mpay
 ```
 
+## Environment Setup
+
+The router uses the default facilitator from `@coinbase/x402` for x402 payments, which requires CDP API keys:
+
+```bash
+CDP_API_KEY_ID=your-key-id
+CDP_API_KEY_SECRET=your-key-secret
+```
+
+**For Next.js apps with env validation** (T3 stack, `@t3-oss/env-nextjs`): Add these to your env schema — Next.js doesn't expose undeclared env vars to `process.env`.
+
+```typescript
+// src/env.js
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    CDP_API_KEY_ID: z.string(),
+    CDP_API_KEY_SECRET: z.string(),
+  },
+  runtimeEnv: {
+    CDP_API_KEY_ID: process.env.CDP_API_KEY_ID,
+    CDP_API_KEY_SECRET: process.env.CDP_API_KEY_SECRET,
+  },
+});
+```
+
+Without these keys, x402 routes will fail to initialize (empty 402 responses, no payment header).
+
 ## Quick Start
 
 ### 1. Create the router (once per service)

package/dist/index.cjs

@@ -84,9 +84,15 @@ module.exports = __toCommonJS(index_exports);
 // src/registry.ts
 var RouteRegistry = class {
   routes = /* @__PURE__ */ new Map();
+  // Silently overwrites on duplicate key. Next.js module loading order is
+  // non-deterministic during build — discovery stubs and real handlers may
+  // register the same route key in either order. Last writer wins.
+  // Prior art: ElysiaJS uses the same pattern (silent overwrite in router.history).
   register(entry) {
-    if (this.routes.has(entry.key)) {
-      throw new Error(`route '${entry.key}': already registered (duplicate route key)`);
+    if (this.routes.has(entry.key) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(
+        `[agentcash/router] route '${entry.key}' registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
+      );
     }
     this.routes.set(entry.key, entry);
   }
@@ -1172,6 +1178,23 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
+  if (config.protocols) {
+    if (config.protocols.length === 0) {
+      throw new Error(
+        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+      );
+    }
+    if (config.protocols.includes("mpp") && !config.mpp) {
+      throw new Error(
+        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
+      );
+    }
+    if (config.protocols.includes("x402") && !config.payeeAddress) {
+      throw new Error(
+        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
+      );
+    }
+  }
   if (config.plugin?.init) {
     try {
       const result = config.plugin.init({ origin: baseUrl });
@@ -1207,7 +1230,8 @@ function createRouter(config) {
     route(key) {
       const builder = new RouteBuilder(key, registry, deps);
       if (config.prices && key in config.prices) {
-        return builder.paid(config.prices[key]);
+        const options = config.protocols ? { protocols: config.protocols } : void 0;
+        return builder.paid(config.prices[key], options);
       }
       return builder;
     },

package/dist/index.d.cts

@@ -184,6 +184,20 @@ interface RouterConfig {
         currency: string;
         recipient?: string;
     };
+    /**
+     * Payment protocols to accept on auto-priced routes (those using the `prices` config).
+     *
+     * @default ['x402']
+     *
+     * @example
+     * // Accept both x402 and MPP payments
+     * createRouter({
+     *   protocols: ['x402', 'mpp'],
+     *   mpp: { secretKey, currency, recipient },
+     *   prices: { 'exa/search': '0.01' }
+     * })
+     */
+    protocols?: ProtocolType[];
 }
 
 declare class RouteRegistry {

package/dist/index.d.ts

@@ -184,6 +184,20 @@ interface RouterConfig {
         currency: string;
         recipient?: string;
     };
+    /**
+     * Payment protocols to accept on auto-priced routes (those using the `prices` config).
+     *
+     * @default ['x402']
+     *
+     * @example
+     * // Accept both x402 and MPP payments
+     * createRouter({
+     *   protocols: ['x402', 'mpp'],
+     *   mpp: { secretKey, currency, recipient },
+     *   prices: { 'exa/search': '0.01' }
+     * })
+     */
+    protocols?: ProtocolType[];
 }
 
 declare class RouteRegistry {

package/dist/index.js

@@ -50,9 +50,15 @@ var init_server = __esm({
 // src/registry.ts
 var RouteRegistry = class {
   routes = /* @__PURE__ */ new Map();
+  // Silently overwrites on duplicate key. Next.js module loading order is
+  // non-deterministic during build — discovery stubs and real handlers may
+  // register the same route key in either order. Last writer wins.
+  // Prior art: ElysiaJS uses the same pattern (silent overwrite in router.history).
   register(entry) {
-    if (this.routes.has(entry.key)) {
-      throw new Error(`route '${entry.key}': already registered (duplicate route key)`);
+    if (this.routes.has(entry.key) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+      console.warn(
+        `[agentcash/router] route '${entry.key}' registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
+      );
     }
     this.routes.set(entry.key, entry);
   }
@@ -1138,6 +1144,23 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
+  if (config.protocols) {
+    if (config.protocols.length === 0) {
+      throw new Error(
+        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+      );
+    }
+    if (config.protocols.includes("mpp") && !config.mpp) {
+      throw new Error(
+        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
+      );
+    }
+    if (config.protocols.includes("x402") && !config.payeeAddress) {
+      throw new Error(
+        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
+      );
+    }
+  }
   if (config.plugin?.init) {
     try {
       const result = config.plugin.init({ origin: baseUrl });
@@ -1173,7 +1196,8 @@ function createRouter(config) {
     route(key) {
       const builder = new RouteBuilder(key, registry, deps);
       if (config.prices && key in config.prices) {
-        return builder.paid(config.prices[key]);
+        const options = config.protocols ? { protocols: config.protocols } : void 0;
+        return builder.paid(config.prices[key], options);
       }
       return builder;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {