@agentcash/router 0.7.1 → 1.0.0

package/dist/index.cjs

@@ -1456,7 +1456,15 @@ function createRedisEntitlementStore(client, options) {
 
 // src/discovery/well-known.ts
 var import_server3 = require("next/server");
-function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
+
+// src/discovery/utils/guidance.ts
+async function resolveGuidance(discovery) {
+  if (typeof discovery.guidance === "function") return discovery.guidance();
+  return discovery.guidance;
+}
+
+// src/discovery/well-known.ts
+function createWellKnownHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let validated = false;
   return async (_request) => {
@@ -1466,19 +1474,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
-    const methodHints = options.methodHints ?? "non-default";
+    const methodHints = discovery.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
       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") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
-    }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1487,11 +1490,11 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (mppResources.length > 0) {
       body.mppResources = mppResources;
     }
-    if (options.description) {
-      body.description = options.description;
+    if (discovery.description) {
+      body.description = discovery.description;
     }
-    if (options.ownershipProofs) {
-      body.ownershipProofs = options.ownershipProofs;
+    if (discovery.ownershipProofs) {
+      body.ownershipProofs = discovery.ownershipProofs;
     }
     if (instructions) {
       body.instructions = instructions;
@@ -1514,7 +1517,7 @@ function toDiscoveryResource(method, url, mode) {
 
 // src/discovery/openapi.ts
 var import_server4 = require("next/server");
-function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
+function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
   let validated = false;
@@ -1555,21 +1558,20 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       };
     }
     const discoveryMetadata = {};
-    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
-      discoveryMetadata.ownershipProofs = options.ownershipProofs;
-    }
-    if (options.llmsTxtUrl) {
-      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    if (discovery.ownershipProofs && discovery.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = discovery.ownershipProofs;
     }
+    const guidance = await resolveGuidance(discovery);
     const openApiDocument = {
       openapi: "3.1.0",
       info: {
-        title: options.title,
-        description: options.description,
-        version: options.version,
-        ...options.contact && { contact: options.contact }
+        title: discovery.title,
+        description: discovery.description,
+        version: discovery.version,
+        guidance,
+        ...discovery.contact && { contact: discovery.contact }
       },
-      servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
+      servers: [{ url: (discovery.serverUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       ...Object.keys(securitySchemes).length > 0 ? {
         components: {
@@ -1689,6 +1691,20 @@ function buildPricingInfo(entry) {
   return void 0;
 }
 
+// src/discovery/llms-txt.ts
+var import_server5 = require("next/server");
+function createLlmsTxtHandler(discovery) {
+  return async (_request) => {
+    const guidance = await resolveGuidance(discovery) ?? "";
+    return new import_server5.NextResponse(guidance, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Access-Control-Allow-Origin": "*"
+      }
+    });
+  };
+}
+
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
@@ -1817,11 +1833,14 @@ function createRouter(config) {
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];

package/dist/index.d.cts

@@ -280,6 +280,21 @@ interface RouteEntry {
     providerConfig?: ProviderConfig;
     validateFn?: (body: unknown) => void | Promise<void>;
 }
+interface DiscoveryConfig {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+    ownershipProofs?: string[];
+    methodHints?: 'off' | 'non-default' | 'always';
+    /** Natural language guidance for agents. Served as wellknown `instructions` and `/llms.txt`. */
+    guidance?: string | (() => string | Promise<string>);
+    /** Override the OpenAPI `servers` URL. Defaults to `RouterConfig.baseUrl`. Use when the public API hostname differs from the payment realm URL. */
+    serverUrl?: string;
+}
 interface RouterConfig {
     payeeAddress: string;
     /**
@@ -329,6 +344,7 @@ interface RouterConfig {
      * This prevents discovery/openapi drift caused by shorthand internal keys.
      */
     strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
@@ -341,34 +357,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-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 {
-    title: string;
-    version: string;
-    description?: string;
-    baseUrl?: string;
-    contact?: {
-        name?: string;
-        url?: string;
-    };
-    llmsTxtUrl?: string;
-    ownershipProofs?: string[];
-}
-
 interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -477,8 +465,9 @@ interface MonitorEntry {
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
     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>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -486,4 +475,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.d.ts

@@ -280,6 +280,21 @@ interface RouteEntry {
     providerConfig?: ProviderConfig;
     validateFn?: (body: unknown) => void | Promise<void>;
 }
+interface DiscoveryConfig {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+    ownershipProofs?: string[];
+    methodHints?: 'off' | 'non-default' | 'always';
+    /** Natural language guidance for agents. Served as wellknown `instructions` and `/llms.txt`. */
+    guidance?: string | (() => string | Promise<string>);
+    /** Override the OpenAPI `servers` URL. Defaults to `RouterConfig.baseUrl`. Use when the public API hostname differs from the payment realm URL. */
+    serverUrl?: string;
+}
 interface RouterConfig {
     payeeAddress: string;
     /**
@@ -329,6 +344,7 @@ interface RouterConfig {
      * This prevents discovery/openapi drift caused by shorthand internal keys.
      */
     strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
@@ -341,34 +357,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-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 {
-    title: string;
-    version: string;
-    description?: string;
-    baseUrl?: string;
-    contact?: {
-        name?: string;
-        url?: string;
-    };
-    llmsTxtUrl?: string;
-    ownershipProofs?: string[];
-}
-
 interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -477,8 +465,9 @@ interface MonitorEntry {
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
     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>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -486,4 +475,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.js

@@ -1417,7 +1417,15 @@ function createRedisEntitlementStore(client, options) {
 
 // src/discovery/well-known.ts
 import { NextResponse as NextResponse3 } from "next/server";
-function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
+
+// src/discovery/utils/guidance.ts
+async function resolveGuidance(discovery) {
+  if (typeof discovery.guidance === "function") return discovery.guidance();
+  return discovery.guidance;
+}
+
+// src/discovery/well-known.ts
+function createWellKnownHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let validated = false;
   return async (_request) => {
@@ -1427,19 +1435,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
-    const methodHints = options.methodHints ?? "non-default";
+    const methodHints = discovery.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
       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") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
-    }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1448,11 +1451,11 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (mppResources.length > 0) {
       body.mppResources = mppResources;
     }
-    if (options.description) {
-      body.description = options.description;
+    if (discovery.description) {
+      body.description = discovery.description;
     }
-    if (options.ownershipProofs) {
-      body.ownershipProofs = options.ownershipProofs;
+    if (discovery.ownershipProofs) {
+      body.ownershipProofs = discovery.ownershipProofs;
     }
     if (instructions) {
       body.instructions = instructions;
@@ -1475,7 +1478,7 @@ function toDiscoveryResource(method, url, mode) {
 
 // src/discovery/openapi.ts
 import { NextResponse as NextResponse4 } from "next/server";
-function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
+function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
   let validated = false;
@@ -1516,21 +1519,20 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       };
     }
     const discoveryMetadata = {};
-    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
-      discoveryMetadata.ownershipProofs = options.ownershipProofs;
-    }
-    if (options.llmsTxtUrl) {
-      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    if (discovery.ownershipProofs && discovery.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = discovery.ownershipProofs;
     }
+    const guidance = await resolveGuidance(discovery);
     const openApiDocument = {
       openapi: "3.1.0",
       info: {
-        title: options.title,
-        description: options.description,
-        version: options.version,
-        ...options.contact && { contact: options.contact }
+        title: discovery.title,
+        description: discovery.description,
+        version: discovery.version,
+        guidance,
+        ...discovery.contact && { contact: discovery.contact }
       },
-      servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
+      servers: [{ url: (discovery.serverUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       ...Object.keys(securitySchemes).length > 0 ? {
         components: {
@@ -1650,6 +1652,20 @@ function buildPricingInfo(entry) {
   return void 0;
 }
 
+// src/discovery/llms-txt.ts
+import { NextResponse as NextResponse5 } from "next/server";
+function createLlmsTxtHandler(discovery) {
+  return async (_request) => {
+    const guidance = await resolveGuidance(discovery) ?? "";
+    return new NextResponse5(guidance, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Access-Control-Allow-Origin": "*"
+      }
+    });
+  };
+}
+
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
@@ -1778,11 +1794,14 @@ function createRouter(config) {
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];

package/package.json

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