@agentcash/router 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,273 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ZodType } from 'zod';
+
+interface NonceStore {
+    check(nonce: string): Promise<boolean>;
+}
+declare class MemoryNonceStore implements NonceStore {
+    private seen;
+    check(nonce: string): Promise<boolean>;
+    private evict;
+}
+
+interface RequestMeta {
+    requestId: string;
+    method: string;
+    route: string;
+    origin: string;
+    referer: string | null;
+    walletAddress: string | null;
+    clientId: string | null;
+    sessionId: string | null;
+    contentType: string | null;
+    headers: Record<string, string>;
+    startTime: number;
+}
+interface PluginContext {
+    readonly requestId: string;
+    readonly route: string;
+    readonly walletAddress: string | null;
+    readonly clientId: string | null;
+    readonly sessionId: string | null;
+    verifiedWallet: string | null;
+    setVerifiedWallet(address: string): void;
+}
+interface PaymentEvent {
+    protocol: 'x402' | 'mpp';
+    payer: string;
+    amount: string;
+    network: string;
+}
+interface SettlementEvent {
+    protocol: 'x402' | 'mpp';
+    payer: string;
+    transaction: string;
+    network: string;
+}
+interface ResponseMeta {
+    statusCode: number;
+    statusText: string;
+    duration: number;
+    contentType: string | null;
+    headers: Record<string, string>;
+}
+interface ErrorEvent {
+    status: number;
+    message: string;
+    settled: boolean;
+}
+interface RouterPlugin {
+    init?(config: {
+        origin?: string;
+    }): void | Promise<void>;
+    onRequest?(meta: RequestMeta): PluginContext;
+    onPaymentVerified?(ctx: PluginContext, payment: PaymentEvent): void;
+    onPaymentSettled?(ctx: PluginContext, settlement: SettlementEvent): void;
+    onResponse?(ctx: PluginContext, response: ResponseMeta): void;
+    onError?(ctx: PluginContext, error: ErrorEvent): void;
+    onAlert?(ctx: PluginContext, alert: AlertEvent): void;
+    onProviderQuota?(ctx: PluginContext, event: ProviderQuotaEvent): void;
+}
+declare function consolePlugin(): RouterPlugin;
+
+declare class HttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+type AlertLevel = 'info' | 'warn' | 'error' | 'critical';
+interface AlertEvent {
+    level: AlertLevel;
+    message: string;
+    route: string;
+    meta?: Record<string, unknown>;
+}
+type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+type ProtocolType = 'x402' | 'mpp';
+type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface TierConfig {
+    price: string;
+    label?: string;
+}
+type PricingConfig<TBody = unknown> = string | ((body: TBody) => string | Promise<string>) | {
+    field: string;
+    tiers: Record<string, TierConfig>;
+    default?: string;
+};
+interface PaidOptions {
+    protocols?: ProtocolType[];
+    maxPrice?: string;
+}
+interface HandlerContext<TBody = undefined, TQuery = undefined> {
+    body: TBody;
+    query: TQuery;
+    request: NextRequest;
+    requestId: string;
+    route: string;
+    wallet: string | null;
+    account: unknown;
+    alert: AlertFn;
+    setVerifiedWallet: (addr: string) => void;
+}
+type OveragePolicy = 'same-rate' | 'increased-rate' | 'hard-stop';
+type QuotaLevel = 'healthy' | 'warn' | 'critical';
+interface QuotaInfo {
+    remaining: number | null;
+    limit: number | null;
+    spend?: number;
+}
+interface ProviderConfig {
+    extractQuota?: (result: unknown, headers: Headers) => QuotaInfo | null;
+    monitor?: () => Promise<QuotaInfo | null>;
+    overage?: OveragePolicy;
+    warn?: number;
+    critical?: number;
+}
+interface ProviderQuotaEvent {
+    provider: string;
+    route: string;
+    remaining: number | null;
+    limit: number | null;
+    spend?: number;
+    level: QuotaLevel;
+    overage: OveragePolicy;
+    message: string;
+}
+interface RouteEntry {
+    key: string;
+    authMode: AuthMode;
+    pricing?: PricingConfig;
+    protocols: ProtocolType[];
+    bodySchema?: ZodType;
+    querySchema?: ZodType;
+    outputSchema?: ZodType;
+    description?: string;
+    path?: string;
+    method: 'GET' | 'POST';
+    maxPrice?: string;
+    apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
+    providerName?: string;
+    providerConfig?: ProviderConfig;
+}
+interface RouterConfig {
+    payeeAddress: string;
+    network?: string;
+    facilitatorUrl?: string;
+    plugin?: RouterPlugin;
+    siwx?: {
+        nonceStore?: NonceStore;
+    };
+    prices?: Record<string, string>;
+    mpp?: {
+        secretKey: string;
+        currency: string;
+        recipient?: string;
+    };
+}
+
+declare class RouteRegistry {
+    private routes;
+    register(entry: RouteEntry): void;
+    get(key: string): RouteEntry | undefined;
+    entries(): IterableIterator<[string, RouteEntry]>;
+    has(key: string): boolean;
+    get size(): number;
+    validate(expectedKeys?: string[]): void;
+}
+
+interface WellKnownOptions {
+    instructions?: string | (() => string | Promise<string>);
+    ownershipProofs?: string[];
+}
+
+interface OpenAPIOptions {
+    title: string;
+    version: string;
+    description?: string;
+    baseUrl?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+}
+
+interface OrchestrateDeps {
+    x402Server: Record<string, Function> | null;
+    initPromise: Promise<void>;
+    x402InitError?: string;
+    plugin?: RouterPlugin;
+    nonceStore: NonceStore;
+    payeeAddress: string;
+    network: string;
+    mppConfig?: {
+        secretKey: string;
+        currency: string;
+        recipient?: string;
+    };
+}
+
+type True = true;
+type False = false;
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false> {
+    /** @internal */ readonly _key: string;
+    /** @internal */ readonly _registry: RouteRegistry;
+    /** @internal */ readonly _deps: OrchestrateDeps;
+    /** @internal */ _authMode: AuthMode | null;
+    /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _protocols: ProtocolType[];
+    /** @internal */ _maxPrice: string | undefined;
+    /** @internal */ _bodySchema: ZodType | undefined;
+    /** @internal */ _querySchema: ZodType | undefined;
+    /** @internal */ _outputSchema: ZodType | undefined;
+    /** @internal */ _description: string | undefined;
+    /** @internal */ _path: string | undefined;
+    /** @internal */ _method: 'GET' | 'POST';
+    /** @internal */ _apiKeyResolver: ((key: string) => unknown | Promise<unknown>) | undefined;
+    /** @internal */ _providerName: string | undefined;
+    /** @internal */ _providerConfig: ProviderConfig | undefined;
+    constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
+    private fork;
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
+        maxPrice: string;
+    }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    paid(pricing: {
+        field: string;
+        tiers: Record<string, {
+            price: string;
+            label?: string;
+        }>;
+        default?: string;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    siwx(): HasAuth extends true ? never : 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;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, HasAuth, NeedsBody, True>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, HasAuth, NeedsBody, HasBody>;
+    output(schema: ZodType): this;
+    description(text: string): this;
+    path(p: string): this;
+    handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
+    handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
+    handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+    handler(this: RouteBuilder<TBody, TQuery, True, True, True>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+}
+
+interface MonitorEntry {
+    provider: string;
+    route: string;
+    monitor: () => Promise<QuotaInfo | null>;
+    overage: OveragePolicy;
+    warn?: number;
+    critical?: number;
+}
+interface ServiceRouter {
+    route(key: string): RouteBuilder;
+    wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
+    openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
+    monitors(): MonitorEntry[];
+    registry: RouteRegistry;
+}
+declare function createRouter(config: RouterConfig): ServiceRouter;
+
+export { type AlertEvent, type AlertFn, type AlertLevel, 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 RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, type ServiceRouter, type SettlementEvent, type TierConfig, consolePlugin, createRouter };

package/dist/index.d.ts

@@ -0,0 +1,273 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ZodType } from 'zod';
+
+interface NonceStore {
+    check(nonce: string): Promise<boolean>;
+}
+declare class MemoryNonceStore implements NonceStore {
+    private seen;
+    check(nonce: string): Promise<boolean>;
+    private evict;
+}
+
+interface RequestMeta {
+    requestId: string;
+    method: string;
+    route: string;
+    origin: string;
+    referer: string | null;
+    walletAddress: string | null;
+    clientId: string | null;
+    sessionId: string | null;
+    contentType: string | null;
+    headers: Record<string, string>;
+    startTime: number;
+}
+interface PluginContext {
+    readonly requestId: string;
+    readonly route: string;
+    readonly walletAddress: string | null;
+    readonly clientId: string | null;
+    readonly sessionId: string | null;
+    verifiedWallet: string | null;
+    setVerifiedWallet(address: string): void;
+}
+interface PaymentEvent {
+    protocol: 'x402' | 'mpp';
+    payer: string;
+    amount: string;
+    network: string;
+}
+interface SettlementEvent {
+    protocol: 'x402' | 'mpp';
+    payer: string;
+    transaction: string;
+    network: string;
+}
+interface ResponseMeta {
+    statusCode: number;
+    statusText: string;
+    duration: number;
+    contentType: string | null;
+    headers: Record<string, string>;
+}
+interface ErrorEvent {
+    status: number;
+    message: string;
+    settled: boolean;
+}
+interface RouterPlugin {
+    init?(config: {
+        origin?: string;
+    }): void | Promise<void>;
+    onRequest?(meta: RequestMeta): PluginContext;
+    onPaymentVerified?(ctx: PluginContext, payment: PaymentEvent): void;
+    onPaymentSettled?(ctx: PluginContext, settlement: SettlementEvent): void;
+    onResponse?(ctx: PluginContext, response: ResponseMeta): void;
+    onError?(ctx: PluginContext, error: ErrorEvent): void;
+    onAlert?(ctx: PluginContext, alert: AlertEvent): void;
+    onProviderQuota?(ctx: PluginContext, event: ProviderQuotaEvent): void;
+}
+declare function consolePlugin(): RouterPlugin;
+
+declare class HttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+type AlertLevel = 'info' | 'warn' | 'error' | 'critical';
+interface AlertEvent {
+    level: AlertLevel;
+    message: string;
+    route: string;
+    meta?: Record<string, unknown>;
+}
+type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+type ProtocolType = 'x402' | 'mpp';
+type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+interface TierConfig {
+    price: string;
+    label?: string;
+}
+type PricingConfig<TBody = unknown> = string | ((body: TBody) => string | Promise<string>) | {
+    field: string;
+    tiers: Record<string, TierConfig>;
+    default?: string;
+};
+interface PaidOptions {
+    protocols?: ProtocolType[];
+    maxPrice?: string;
+}
+interface HandlerContext<TBody = undefined, TQuery = undefined> {
+    body: TBody;
+    query: TQuery;
+    request: NextRequest;
+    requestId: string;
+    route: string;
+    wallet: string | null;
+    account: unknown;
+    alert: AlertFn;
+    setVerifiedWallet: (addr: string) => void;
+}
+type OveragePolicy = 'same-rate' | 'increased-rate' | 'hard-stop';
+type QuotaLevel = 'healthy' | 'warn' | 'critical';
+interface QuotaInfo {
+    remaining: number | null;
+    limit: number | null;
+    spend?: number;
+}
+interface ProviderConfig {
+    extractQuota?: (result: unknown, headers: Headers) => QuotaInfo | null;
+    monitor?: () => Promise<QuotaInfo | null>;
+    overage?: OveragePolicy;
+    warn?: number;
+    critical?: number;
+}
+interface ProviderQuotaEvent {
+    provider: string;
+    route: string;
+    remaining: number | null;
+    limit: number | null;
+    spend?: number;
+    level: QuotaLevel;
+    overage: OveragePolicy;
+    message: string;
+}
+interface RouteEntry {
+    key: string;
+    authMode: AuthMode;
+    pricing?: PricingConfig;
+    protocols: ProtocolType[];
+    bodySchema?: ZodType;
+    querySchema?: ZodType;
+    outputSchema?: ZodType;
+    description?: string;
+    path?: string;
+    method: 'GET' | 'POST';
+    maxPrice?: string;
+    apiKeyResolver?: (key: string) => unknown | Promise<unknown>;
+    providerName?: string;
+    providerConfig?: ProviderConfig;
+}
+interface RouterConfig {
+    payeeAddress: string;
+    network?: string;
+    facilitatorUrl?: string;
+    plugin?: RouterPlugin;
+    siwx?: {
+        nonceStore?: NonceStore;
+    };
+    prices?: Record<string, string>;
+    mpp?: {
+        secretKey: string;
+        currency: string;
+        recipient?: string;
+    };
+}
+
+declare class RouteRegistry {
+    private routes;
+    register(entry: RouteEntry): void;
+    get(key: string): RouteEntry | undefined;
+    entries(): IterableIterator<[string, RouteEntry]>;
+    has(key: string): boolean;
+    get size(): number;
+    validate(expectedKeys?: string[]): void;
+}
+
+interface WellKnownOptions {
+    instructions?: string | (() => string | Promise<string>);
+    ownershipProofs?: string[];
+}
+
+interface OpenAPIOptions {
+    title: string;
+    version: string;
+    description?: string;
+    baseUrl?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+}
+
+interface OrchestrateDeps {
+    x402Server: Record<string, Function> | null;
+    initPromise: Promise<void>;
+    x402InitError?: string;
+    plugin?: RouterPlugin;
+    nonceStore: NonceStore;
+    payeeAddress: string;
+    network: string;
+    mppConfig?: {
+        secretKey: string;
+        currency: string;
+        recipient?: string;
+    };
+}
+
+type True = true;
+type False = false;
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false> {
+    /** @internal */ readonly _key: string;
+    /** @internal */ readonly _registry: RouteRegistry;
+    /** @internal */ readonly _deps: OrchestrateDeps;
+    /** @internal */ _authMode: AuthMode | null;
+    /** @internal */ _pricing: PricingConfig | undefined;
+    /** @internal */ _protocols: ProtocolType[];
+    /** @internal */ _maxPrice: string | undefined;
+    /** @internal */ _bodySchema: ZodType | undefined;
+    /** @internal */ _querySchema: ZodType | undefined;
+    /** @internal */ _outputSchema: ZodType | undefined;
+    /** @internal */ _description: string | undefined;
+    /** @internal */ _path: string | undefined;
+    /** @internal */ _method: 'GET' | 'POST';
+    /** @internal */ _apiKeyResolver: ((key: string) => unknown | Promise<unknown>) | undefined;
+    /** @internal */ _providerName: string | undefined;
+    /** @internal */ _providerConfig: ProviderConfig | undefined;
+    constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
+    private fork;
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
+    paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
+        maxPrice: string;
+    }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    paid(pricing: {
+        field: string;
+        tiers: Record<string, {
+            price: string;
+            label?: string;
+        }>;
+        default?: string;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, True, HasBody>;
+    siwx(): HasAuth extends true ? never : 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;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, HasAuth, NeedsBody, True>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, HasAuth, NeedsBody, HasBody>;
+    output(schema: ZodType): this;
+    description(text: string): this;
+    path(p: string): this;
+    handler(this: RouteBuilder<TBody, TQuery, True, true, false>, fn: never): never;
+    handler(this: RouteBuilder<TBody, TQuery, false, boolean, boolean>, fn: never): never;
+    handler(this: RouteBuilder<TBody, TQuery, True, False, HasBody>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+    handler(this: RouteBuilder<TBody, TQuery, True, True, True>, fn: (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>): (request: NextRequest) => Promise<Response>;
+}
+
+interface MonitorEntry {
+    provider: string;
+    route: string;
+    monitor: () => Promise<QuotaInfo | null>;
+    overage: OveragePolicy;
+    warn?: number;
+    critical?: number;
+}
+interface ServiceRouter {
+    route(key: string): RouteBuilder;
+    wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
+    openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
+    monitors(): MonitorEntry[];
+    registry: RouteRegistry;
+}
+declare function createRouter(config: RouterConfig): ServiceRouter;
+
+export { type AlertEvent, type AlertFn, type AlertLevel, 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 RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, type ServiceRouter, type SettlementEvent, type TierConfig, consolePlugin, createRouter };