@agentcash/router 0.6.8 → 0.7.1

package/dist/index.d.cts

@@ -3,6 +3,29 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.cjs';
 
+interface EntitlementStore {
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+/**
+ * In-memory SIWX entitlement store.
+ *
+ * Suitable for development and tests. Not durable across server restarts.
+ */
+declare class MemoryEntitlementStore implements EntitlementStore {
+    private readonly routeToWallets;
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+interface RedisEntitlementStoreOptions {
+    /** Key prefix. Default: 'siwx:entitlement:' */
+    prefix?: string;
+}
+/**
+ * Redis-backed entitlement store for paid+SIWX acceleration.
+ */
+declare function createRedisEntitlementStore(client: unknown, options?: RedisEntitlementStoreOptions): EntitlementStore;
+
 /**
  * SIWX challenge expiry in milliseconds.
  * Currently not configurable per-route — this is a known limitation.
@@ -162,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;
@@ -216,6 +259,11 @@ interface ProviderQuotaEvent {
 interface RouteEntry {
     key: string;
     authMode: AuthMode;
+    /**
+     * Enables SIWX acceleration on paid routes.
+     * When true, valid SIWX proofs can bypass repeat payment if entitlement exists.
+     */
+    siwxEnabled?: boolean;
     pricing?: PricingConfig;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
@@ -223,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>);
@@ -247,6 +295,7 @@ interface RouterConfig {
     plugin?: RouterPlugin;
     siwx?: {
         nonceStore?: NonceStore;
+        entitlementStore?: EntitlementStore;
     };
     prices?: Record<string, string>;
     mpp?: {
@@ -270,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 {
@@ -286,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 {
@@ -297,6 +365,8 @@ interface OpenAPIOptions {
         name?: string;
         url?: string;
     };
+    llmsTxtUrl?: string;
+    ownershipProofs?: string[];
 }
 
 interface OrchestrateDeps {
@@ -306,6 +376,7 @@ interface OrchestrateDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    entitlementStore: EntitlementStore;
     payeeAddress: string;
     network: string;
     mppx?: {
@@ -329,6 +400,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ readonly _deps: OrchestrateDeps;
     /** @internal */ _authMode: AuthMode | null;
     /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _siwxEnabled: boolean;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
@@ -357,7 +429,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
         }>;
         default?: string;
     }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): HasAuth extends true ? never : RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
     unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     provider(name: string, config?: ProviderConfig): this;
@@ -404,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[];
@@ -414,4 +486,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 ErrorEvent, type HandlerContext, HttpError, 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 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, createRedisNonceStore, createRouter };
+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 };

package/dist/index.d.ts

@@ -3,6 +3,29 @@ import { ZodType } from 'zod';
 import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.js';
 
+interface EntitlementStore {
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+/**
+ * In-memory SIWX entitlement store.
+ *
+ * Suitable for development and tests. Not durable across server restarts.
+ */
+declare class MemoryEntitlementStore implements EntitlementStore {
+    private readonly routeToWallets;
+    has(route: string, wallet: string): Promise<boolean>;
+    grant(route: string, wallet: string): Promise<void>;
+}
+interface RedisEntitlementStoreOptions {
+    /** Key prefix. Default: 'siwx:entitlement:' */
+    prefix?: string;
+}
+/**
+ * Redis-backed entitlement store for paid+SIWX acceleration.
+ */
+declare function createRedisEntitlementStore(client: unknown, options?: RedisEntitlementStoreOptions): EntitlementStore;
+
 /**
  * SIWX challenge expiry in milliseconds.
  * Currently not configurable per-route — this is a known limitation.
@@ -162,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;
@@ -216,6 +259,11 @@ interface ProviderQuotaEvent {
 interface RouteEntry {
     key: string;
     authMode: AuthMode;
+    /**
+     * Enables SIWX acceleration on paid routes.
+     * When true, valid SIWX proofs can bypass repeat payment if entitlement exists.
+     */
+    siwxEnabled?: boolean;
     pricing?: PricingConfig;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
@@ -223,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>);
@@ -247,6 +295,7 @@ interface RouterConfig {
     plugin?: RouterPlugin;
     siwx?: {
         nonceStore?: NonceStore;
+        entitlementStore?: EntitlementStore;
     };
     prices?: Record<string, string>;
     mpp?: {
@@ -270,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 {
@@ -286,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 {
@@ -297,6 +365,8 @@ interface OpenAPIOptions {
         name?: string;
         url?: string;
     };
+    llmsTxtUrl?: string;
+    ownershipProofs?: string[];
 }
 
 interface OrchestrateDeps {
@@ -306,6 +376,7 @@ interface OrchestrateDeps {
     mppInitError?: string;
     plugin?: RouterPlugin;
     nonceStore: NonceStore;
+    entitlementStore: EntitlementStore;
     payeeAddress: string;
     network: string;
     mppx?: {
@@ -329,6 +400,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     /** @internal */ readonly _deps: OrchestrateDeps;
     /** @internal */ _authMode: AuthMode | null;
     /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _siwxEnabled: boolean;
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
@@ -357,7 +429,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
         }>;
         default?: string;
     }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
-    siwx(): HasAuth extends true ? never : RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    siwx(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, True, NeedsBody, HasBody>;
     unprotected(): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     provider(name: string, config?: ProviderConfig): this;
@@ -404,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[];
@@ -414,4 +486,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 ErrorEvent, type HandlerContext, HttpError, 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 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, createRedisNonceStore, createRouter };
+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 };