@agentcash/router 0.7.0 → 0.7.1

package/README.md

@@ -58,6 +58,8 @@ import { createRouter } from '@agentcash/router';
 
 export const router = createRouter({
   payeeAddress: process.env.X402_PAYEE_ADDRESS!,
+  baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
+  strictRoutes: true, // recommended
 });
 ```
 
@@ -70,7 +72,7 @@ export const router = createRouter({
 import { router } from '@/lib/routes';
 import { searchSchema, searchResponseSchema } from '@/lib/schemas';
 
-export const POST = router.route('search')
+export const POST = router.route({ path: 'search' })
   .paid('0.01')
   .body(searchSchema)
   .output(searchResponseSchema)
@@ -81,7 +83,7 @@ export const POST = router.route('search')
 **SIWX-authenticated route**
 
 ```typescript
-export const GET = router.route('inbox/status')
+export const GET = router.route({ path: 'inbox/status' })
   .siwx()
   .query(statusQuerySchema)
   .handler(async ({ query, wallet }) => getStatus(query, wallet));
@@ -90,7 +92,7 @@ export const GET = router.route('inbox/status')
 **Unprotected route**
 
 ```typescript
-export const GET = router.route('health')
+export const GET = router.route({ path: 'health' })
   .unprotected()
   .handler(async () => ({ status: 'ok' }));
 ```
@@ -101,7 +103,7 @@ export const GET = router.route('health')
 // app/.well-known/x402/route.ts
 import { router } from '@/lib/routes';
 import '@/lib/routes/barrel'; // ensures all routes are imported
-export const GET = router.wellKnown();
+export const GET = router.wellKnown({ methodHints: 'non-default' });
 
 // app/openapi.json/route.ts
 import { router } from '@/lib/routes';
@@ -129,11 +131,29 @@ Creates a `ServiceRouter` instance.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `payeeAddress` | `string` | **required** | Wallet address to receive payments |
+| `baseUrl` | `string` | **required** | Service origin used for discovery/OpenAPI/realm |
 | `network` | `string` | `'eip155:8453'` | Blockchain network |
 | `plugin` | `RouterPlugin` | `undefined` | Observability plugin |
 | `prices` | `Record<string, string>` | `undefined` | Central pricing map (auto-applied) |
 | `siwx.nonceStore` | `NonceStore` | `MemoryNonceStore` | Custom nonce store |
 | `mpp` | `{ secretKey, currency, recipient? }` | `undefined` | MPP config |
+| `strictRoutes` | `boolean` | `false` | Enforce `route({ path })` and prevent key/path divergence |
+
+### Path-First Routing
+
+Use path-first route definitions to keep runtime, OpenAPI, and discovery aligned:
+
+```typescript
+router.route({ path: 'flightaware/airports/id/flights/arrivals', method: 'GET' })
+```
+
+If you need a custom internal key (legacy pricing map), you can pass:
+
+```typescript
+router.route({ path: 'public/path', key: 'legacy/key' })
+```
+
+In `strictRoutes` mode, custom keys are rejected to prevent discovery drift.
 
 ### Route Builder
 

package/dist/index.cjs

@@ -1466,10 +1466,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
+    const methodHints = options.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
-      if (entry.authMode !== "unprotected") x402Set.add(url);
-      if (entry.protocols.includes("mpp")) mppSet.add(url);
+      const resource = toDiscoveryResource(entry.method, url, methodHints);
+      if (entry.authMode !== "unprotected") x402Set.add(resource);
+      if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
     let instructions;
     if (typeof options.instructions === "function") {
@@ -1503,6 +1505,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     });
   };
 }
+function toDiscoveryResource(method, url, mode) {
+  if (mode === "off") return url;
+  if (mode === "always") return `${method} ${url}`;
+  const isDefaultProbeMethod = method === "GET" || method === "POST";
+  return isDefaultProbeMethod ? url : `${method} ${url}`;
+}
 
 // src/discovery/openapi.ts
 var import_server4 = require("next/server");
@@ -1783,8 +1791,26 @@ function createRouter(config) {
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;
   return {
-    route(key) {
-      const builder = new RouteBuilder(key, registry, deps);
+    route(keyOrDefinition) {
+      const isDefinition = typeof keyOrDefinition !== "string";
+      if (config.strictRoutes && !isDefinition) {
+        throw new Error(
+          "[router] strictRoutes=true requires route({ path }) form. Replace route('my/key') with route({ path: 'my/key' })."
+        );
+      }
+      const definition = isDefinition ? keyOrDefinition : { path: keyOrDefinition, key: keyOrDefinition };
+      const normalizedPath = normalizePath(definition.path);
+      const key = definition.key ?? normalizedPath;
+      if (config.strictRoutes && definition.key && definition.key !== definition.path) {
+        throw new Error(
+          `[router] strictRoutes=true forbids key/path divergence for route '${definition.path}'. Remove custom \`key\` or make it equal to \`path\`.`
+        );
+      }
+      let builder = new RouteBuilder(key, registry, deps);
+      builder = builder.path(normalizedPath);
+      if (definition.method) {
+        builder = builder.method(definition.method);
+      }
       if (config.prices && key in config.prices) {
         const options = config.protocols ? { protocols: config.protocols } : void 0;
         return builder.paid(config.prices[key], options);
@@ -1816,6 +1842,12 @@ function createRouter(config) {
     registry
   };
 }
+function normalizePath(path) {
+  let normalized = path.trim();
+  normalized = normalized.replace(/^\/+/, "");
+  normalized = normalized.replace(/^api\/+/, "");
+  return normalized.replace(/\/+$/, "");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HttpError,

package/dist/index.d.cts

@@ -185,6 +185,26 @@ interface X402Server {
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+interface RouteDefinition<K extends string = string> {
+    /**
+     * Public API path segment (without `/api/` prefix).
+     * Example: `flightaware/airports/id/flights/arrivals`
+     */
+    path: K;
+    /**
+     * Internal route ID for pricing maps / analytics. Defaults to `path`.
+     *
+     * In `strictRoutes` mode, custom keys are disallowed to prevent discovery
+     * drift between internal IDs and advertised paths.
+     */
+    key?: string;
+    /**
+     * Optional explicit method. If omitted, defaults to builder behavior
+     * (`POST`, or `GET` when `.query()` is used).
+     */
+    method?: RouteMethod;
+}
 interface TierConfig {
     price: string;
     label?: string;
@@ -251,7 +271,7 @@ interface RouteEntry {
     outputSchema?: ZodType;
     description?: string;
     path?: string;
-    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    method: RouteMethod;
     maxPrice?: string;
     minPrice?: string;
     payTo?: string | ((request: Request) => string | Promise<string>);
@@ -299,6 +319,16 @@ interface RouterConfig {
      * })
      */
     protocols?: ProtocolType[];
+    /**
+     * Enforce explicit, path-first route definitions.
+     *
+     * When enabled:
+     * - `.route('key')` is rejected; use `.route({ path })`.
+     * - custom `key` differing from `path` is rejected.
+     *
+     * This prevents discovery/openapi drift caused by shorthand internal keys.
+     */
+    strictRoutes?: boolean;
 }
 
 declare class RouteRegistry {
@@ -315,6 +345,15 @@ interface WellKnownOptions {
     description?: string;
     instructions?: string | (() => string | Promise<string>);
     ownershipProofs?: string[];
+    /**
+     * Whether to include explicit HTTP method prefixes in `resources`.
+     * - `off`: always emit plain URLs.
+     * - `non-default`: emit `METHOD url` for PUT/PATCH/DELETE routes.
+     * - `always`: emit `METHOD url` for all routes.
+     *
+     * @default 'non-default'
+     */
+    methodHints?: 'off' | 'non-default' | 'always';
 }
 
 interface OpenAPIOptions {
@@ -437,7 +476,7 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
     wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
     openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];

package/dist/index.d.ts

@@ -185,6 +185,26 @@ interface X402Server {
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+interface RouteDefinition<K extends string = string> {
+    /**
+     * Public API path segment (without `/api/` prefix).
+     * Example: `flightaware/airports/id/flights/arrivals`
+     */
+    path: K;
+    /**
+     * Internal route ID for pricing maps / analytics. Defaults to `path`.
+     *
+     * In `strictRoutes` mode, custom keys are disallowed to prevent discovery
+     * drift between internal IDs and advertised paths.
+     */
+    key?: string;
+    /**
+     * Optional explicit method. If omitted, defaults to builder behavior
+     * (`POST`, or `GET` when `.query()` is used).
+     */
+    method?: RouteMethod;
+}
 interface TierConfig {
     price: string;
     label?: string;
@@ -251,7 +271,7 @@ interface RouteEntry {
     outputSchema?: ZodType;
     description?: string;
     path?: string;
-    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    method: RouteMethod;
     maxPrice?: string;
     minPrice?: string;
     payTo?: string | ((request: Request) => string | Promise<string>);
@@ -299,6 +319,16 @@ interface RouterConfig {
      * })
      */
     protocols?: ProtocolType[];
+    /**
+     * Enforce explicit, path-first route definitions.
+     *
+     * When enabled:
+     * - `.route('key')` is rejected; use `.route({ path })`.
+     * - custom `key` differing from `path` is rejected.
+     *
+     * This prevents discovery/openapi drift caused by shorthand internal keys.
+     */
+    strictRoutes?: boolean;
 }
 
 declare class RouteRegistry {
@@ -315,6 +345,15 @@ interface WellKnownOptions {
     description?: string;
     instructions?: string | (() => string | Promise<string>);
     ownershipProofs?: string[];
+    /**
+     * Whether to include explicit HTTP method prefixes in `resources`.
+     * - `off`: always emit plain URLs.
+     * - `non-default`: emit `METHOD url` for PUT/PATCH/DELETE routes.
+     * - `always`: emit `METHOD url` for all routes.
+     *
+     * @default 'non-default'
+     */
+    methodHints?: 'off' | 'non-default' | 'always';
 }
 
 interface OpenAPIOptions {
@@ -437,7 +476,7 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
     wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
     openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];

package/dist/index.js

@@ -1427,10 +1427,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
+    const methodHints = options.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
-      if (entry.authMode !== "unprotected") x402Set.add(url);
-      if (entry.protocols.includes("mpp")) mppSet.add(url);
+      const resource = toDiscoveryResource(entry.method, url, methodHints);
+      if (entry.authMode !== "unprotected") x402Set.add(resource);
+      if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
     let instructions;
     if (typeof options.instructions === "function") {
@@ -1464,6 +1466,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     });
   };
 }
+function toDiscoveryResource(method, url, mode) {
+  if (mode === "off") return url;
+  if (mode === "always") return `${method} ${url}`;
+  const isDefaultProbeMethod = method === "GET" || method === "POST";
+  return isDefaultProbeMethod ? url : `${method} ${url}`;
+}
 
 // src/discovery/openapi.ts
 import { NextResponse as NextResponse4 } from "next/server";
@@ -1744,8 +1752,26 @@ function createRouter(config) {
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;
   return {
-    route(key) {
-      const builder = new RouteBuilder(key, registry, deps);
+    route(keyOrDefinition) {
+      const isDefinition = typeof keyOrDefinition !== "string";
+      if (config.strictRoutes && !isDefinition) {
+        throw new Error(
+          "[router] strictRoutes=true requires route({ path }) form. Replace route('my/key') with route({ path: 'my/key' })."
+        );
+      }
+      const definition = isDefinition ? keyOrDefinition : { path: keyOrDefinition, key: keyOrDefinition };
+      const normalizedPath = normalizePath(definition.path);
+      const key = definition.key ?? normalizedPath;
+      if (config.strictRoutes && definition.key && definition.key !== definition.path) {
+        throw new Error(
+          `[router] strictRoutes=true forbids key/path divergence for route '${definition.path}'. Remove custom \`key\` or make it equal to \`path\`.`
+        );
+      }
+      let builder = new RouteBuilder(key, registry, deps);
+      builder = builder.path(normalizedPath);
+      if (definition.method) {
+        builder = builder.method(definition.method);
+      }
       if (config.prices && key in config.prices) {
         const options = config.protocols ? { protocols: config.protocols } : void 0;
         return builder.paid(config.prices[key], options);
@@ -1777,6 +1803,12 @@ function createRouter(config) {
     registry
   };
 }
+function normalizePath(path) {
+  let normalized = path.trim();
+  normalized = normalized.replace(/^\/+/, "");
+  normalized = normalized.replace(/^api\/+/, "");
+  return normalized.replace(/\/+$/, "");
+}
 export {
   HttpError,
   MemoryEntitlementStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -48,7 +48,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.3.9",
+    "mppx": "^0.3.13",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",