@agentcash/router 1.5.0 → 1.5.2

package/dist/index.d.cts

@@ -4,7 +4,6 @@ import { ZodType } from 'zod';
 import { Store } from 'mppx';
 import { PaymentRequirements, PaymentRequired, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
-export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.cjs';
 
 interface EntitlementStore {
     has(route: string, wallet: string): Promise<boolean>;
@@ -128,7 +127,7 @@ interface ErrorEvent {
 interface AuthEvent {
     /** Authentication mode that was verified */
     authMode: 'siwx' | 'apiKey';
-    /** Verified wallet address (lowercase) */
+    /** Verified canonical wallet address (EVM lowercase, non-EVM preserved) */
     wallet: string | null;
     /** Route key */
     route: string;
@@ -271,6 +270,49 @@ interface HandlerPaymentContext {
     transaction?: string;
     receipt?: string;
 }
+interface SettlementLifecycleContext<TBody = unknown> {
+    route: string;
+    request: NextRequest;
+    body: TBody;
+    wallet: string;
+    account: unknown;
+    payment: HandlerPaymentContext;
+    response: NextResponse;
+    result: unknown;
+}
+interface SettlementSettledContext<TBody = unknown> extends Omit<SettlementLifecycleContext<TBody>, 'payment'> {
+    payment: HandlerPaymentContext & {
+        status: 'settled';
+    };
+}
+interface SettlementErrorContext<TBody = unknown> extends SettlementLifecycleContext<TBody> {
+    error: unknown;
+    phase: 'settle' | 'afterSettle';
+}
+interface SettledHandlerErrorContext<TBody = unknown> extends SettlementSettledContext<TBody> {
+    error: unknown;
+}
+interface SettlementLifecycle<TBody = unknown> {
+    /**
+     * Runs after the handler returns a successful response, before router-controlled
+     * settlement/broadcast. Throw with `.status` to return a specific error and
+     * skip settlement when the protocol flow has not already settled.
+     */
+    beforeSettle?: (ctx: SettlementLifecycleContext<TBody>) => void | Promise<void>;
+    /**
+     * Runs after successful settlement. Use for durable ledgers and audit rows.
+     * Errors are alerted and do not change the already-settled response.
+     */
+    afterSettle?: (ctx: SettlementSettledContext<TBody>) => void | Promise<void>;
+    /**
+     * Runs when the router has already observed a settled payment, then the
+     * handler returns an error response. Use for app-owned refund or
+     * compensation queues.
+     */
+    onSettledHandlerError?: (ctx: SettledHandlerErrorContext<TBody>) => void | Promise<void>;
+    /** Runs when router-controlled settlement fails after the handler succeeded. */
+    onSettlementError?: (ctx: SettlementErrorContext<TBody>) => void | Promise<void>;
+}
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
     query: TQuery;
@@ -321,22 +363,22 @@ interface RouteEntry {
     querySchema?: ZodType;
     outputSchema?: ZodType;
     /**
-     * Conforming example for the request input (body for body routes, query params for query routes).
-     * Required whenever `bodySchema` or `querySchema` is set. Must satisfy the corresponding schema —
-     * validated at route-registration time via the Zod schema.
+     * Optional conforming example for the request input (body for body routes, query params for query routes).
+     * When present, it must satisfy the corresponding schema and is validated at route registration.
      *
      * Emitted in the bazaar discovery extension so indexers can advertise a working sample call.
      */
     inputExample?: JsonObject;
     /**
-     * Conforming example for the response output. Required whenever `outputSchema` is set.
-     * Must satisfy `outputSchema` — validated at route-registration time via the Zod schema.
+     * Optional conforming example for the response output. When present, it must
+     * satisfy `outputSchema` and is validated at route registration.
      *
      * Accepts any JSON value (object, array, or primitive) to support top-level array or
      * primitive response schemas.
      *
-     * Emitted in the bazaar discovery extension. Without it the `output` block is dropped from
-     * the declaration entirely (the output schema alone cannot be exposed in bazaar without an example).
+     * Emitted in the bazaar discovery extension. Without it the `output` block is
+     * dropped from the declaration entirely (the output schema alone cannot be
+     * exposed in bazaar without an example).
      */
     outputExample?: JsonValue;
     description?: string;
@@ -349,6 +391,7 @@ interface RouteEntry {
     providerName?: string;
     providerConfig?: ProviderConfig;
     validateFn?: (body: unknown) => void | Promise<void>;
+    settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
 }
 interface DiscoveryConfig {
@@ -423,7 +466,7 @@ interface RouterConfig {
          * createRouter({
          *   mpp: {
          *     secretKey: process.env.MPP_SECRET_KEY!,
-         *     currency: USDC,
+         *     currency: TEMPO_USDC_CURRENCY,
          *     useDefaultStore: true,
          *   }
          * })
@@ -431,7 +474,7 @@ interface RouterConfig {
         useDefaultStore?: boolean;
     };
     /**
-     * Payment protocols to accept on auto-priced routes (those using the `prices` config).
+     * Payment protocols to accept on paid routes unless a route overrides them.
      *
      * @default ['x402']
      *
@@ -439,7 +482,7 @@ interface RouterConfig {
      * // Accept both x402 and MPP payments
      * createRouter({
      *   protocols: ['x402', 'mpp'],
-     *   mpp: { secretKey, currency, recipient },
+     *   mpp: { secretKey, currency: TEMPO_USDC_CURRENCY, recipient },
      *   prices: { 'exa/search': '0.01' }
      * })
      */
@@ -476,7 +519,7 @@ interface ResolvedX402Facilitator {
     config: X402RouterFacilitatorConfig;
 }
 
-interface OrchestrateDeps {
+interface RouterDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
     x402InitError?: string;
@@ -485,6 +528,7 @@ interface OrchestrateDeps {
     nonceStore: NonceStore;
     entitlementStore: EntitlementStore;
     payeeAddress: string;
+    mppRecipient?: string;
     network: string;
     x402FacilitatorsByNetwork?: Record<string, ResolvedX402Facilitator>;
     x402Accepts: X402AcceptConfig[];
@@ -502,6 +546,9 @@ interface OrchestrateDeps {
     tempoClient?: viem.Client | null;
 }
 
+/** @deprecated alias kept for downstream consumers; use `RouterDeps`. */
+type OrchestrateDeps = RouterDeps;
+
 type True = true;
 type False = false;
 /**
@@ -521,16 +568,12 @@ type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extend
  * because TypeScript doesn't reliably gate overload selection on `this` for
  * generic classes (structurally identical instance types collapse).
  */
-type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, NeedsInputExample extends boolean, NeedsOutputExample extends boolean> = HasAuth extends true ? [NeedsBody, HasBody] extends [true, false] ? {
+type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean> = HasAuth extends true ? [NeedsBody, HasBody] extends [true, false] ? {
     __missing: 'Call .body(schema) — dynamic/tiered pricing requires a body schema to resolve the price against';
-} : NeedsInputExample extends true ? {
-    __missing: 'Call .inputExample(sample) — .body()/.query() routes must advertise a conforming request example for bazaar discovery';
-} : NeedsOutputExample extends true ? {
-    __missing: 'Call .outputExample(sample) — .output() routes must advertise a conforming response example for bazaar discovery';
 } : (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown> : {
     __missing: 'Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()';
 };
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, NeedsInputExample extends boolean = false, NeedsOutputExample extends boolean = false> {
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = 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;
@@ -540,7 +583,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     /** @internal */ _protocols: ProtocolType[];
     /** @internal */ _maxPrice: string | undefined;
     /** @internal */ _minPrice: string | undefined;
-    /** @internal */ _payTo: string | ((request: Request) => string | Promise<string>) | undefined;
+    /** @internal */ _payTo: PayToConfig | undefined;
     /** @internal */ _bodySchema: ZodType | undefined;
     /** @internal */ _querySchema: ZodType | undefined;
     /** @internal */ _outputSchema: ZodType | undefined;
@@ -555,13 +598,14 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
     /** @internal */ _providerName: string | undefined;
     /** @internal */ _providerConfig: ProviderConfig | undefined;
     /** @internal */ _validateFn: ((body: TBody) => void | Promise<void>) | undefined;
+    /** @internal */ _settlement: SettlementLifecycle<TBody> | undefined;
     /** @internal */ _mppInfo: MppProtocolInfo | undefined;
     constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
     private fork;
-    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
+    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
         maxPrice?: string;
-    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
+    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody>;
     paid(pricing: {
         field: string;
         tiers: Record<string, {
@@ -569,21 +613,26 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
             label?: string;
         }>;
         default?: string;
-    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, NeedsInputExample, NeedsOutputExample>;
-    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
-    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
-    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, NeedsInputExample, NeedsOutputExample>;
+    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody>;
+    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
+    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody>;
+    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody>;
     provider(name: string, config?: ProviderConfig): this;
-    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True, True, NeedsOutputExample>;
-    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody, True, NeedsOutputExample>;
-    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, NeedsInputExample, True>;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True>;
+    body<T>(schema: ZodType<T>, example: T & JsonObject): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody>;
+    query<T>(schema: ZodType<T>, example: T & JsonObject): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody>;
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody>;
+    output<T>(schema: ZodType<T>, example: T & JsonValue): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody>;
     /**
      * Provide a conforming example of the request input (body or query params).
      *
-     * **Required** whenever `.body()` or `.query()` is set — enforced at compile time via
-     * `.handler()` overloads, and at route-registration time via Zod validation of the
-     * example against the schema. The example is embedded in the bazaar discovery extension
-     * so indexers can advertise a working sample call.
+     * Optional. When provided, the example is validated against the request schema
+     * at route registration and embedded in the bazaar discovery extension so
+     * indexers can advertise a working sample call.
+     *
+     * For the common case, pass the example directly to `.body(schema, example)` or
+     * `.query(schema, example)` instead.
      *
      * @example
      * ```ts
@@ -594,14 +643,15 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body }) => { ... });
      * ```
      */
-    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, False, NeedsOutputExample>;
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
     /**
      * Provide a conforming example of the response output.
      *
-     * **Required** whenever `.output()` is set — enforced at compile time via `.handler()`
-     * overloads, and at route-registration time via Zod validation of the example against
-     * the schema. The example is embedded in the bazaar discovery extension so indexers
-     * can advertise the response shape.
+     * Optional. When provided, the example is validated against the output schema
+     * at route registration and embedded in the bazaar discovery extension so
+     * indexers can advertise the response shape.
+     *
+     * For the common case, pass the example directly to `.output(schema, example)` instead.
      *
      * Accepts any JSON value (objects, arrays, or primitives) — top-level array
      * or primitive responses (e.g. `z.array(...)`) are supported alongside the
@@ -623,7 +673,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async () => { ... });
      * ```
      */
-    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, False>;
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
     description(text: string): this;
     path(p: string): this;
     method(m: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH'): this;
@@ -648,8 +698,17 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body }) => { ... });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>;
-    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, NeedsInputExample, NeedsOutputExample>): (request: NextRequest) => Promise<Response>;
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
+    /**
+     * Add route-specific settlement hooks.
+     *
+     * `beforeSettle` runs after a successful handler response but before
+     * router-controlled settlement/broadcast, so it can still prevent the charge
+     * for x402 and MPP transaction-payload flows. `afterSettle` runs after
+     * settlement and is intended for durable ledgers or app-owned refund queues.
+     */
+    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody>;
+    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody>): (request: NextRequest) => Promise<Response>;
 }
 
 declare const BASE_NETWORK = "eip155:8453";
@@ -658,7 +717,7 @@ declare const TEMPO_USDC_CURRENCY = "0x20c000000000000000000000b9537d11c60e8b50"
 declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
 
 type RouterEnv = Record<string, string | undefined>;
-type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'missing_mpp_recipient' | 'missing_mpp_rpc_url' | 'missing_mpp_default_store_env';
+type RouterConfigIssueCode = 'missing_base_url' | 'empty_protocols' | 'missing_x402_accepts' | 'missing_x402_network' | 'unsupported_x402_network' | 'missing_x402_asset' | 'invalid_x402_decimals' | 'missing_x402_payee' | 'missing_cdp_keys' | 'placeholder_payee' | 'missing_mpp_config' | 'missing_mpp_secret_key' | 'missing_mpp_currency' | 'invalid_mpp_currency' | 'missing_mpp_recipient' | 'invalid_mpp_recipient' | 'missing_mpp_rpc_url' | 'invalid_mpp_fee_payer_key' | 'missing_mpp_default_store_env';
 interface RouterConfigIssue {
     code: RouterConfigIssueCode;
     message: string;
@@ -690,6 +749,14 @@ declare function x402AcceptsFromEnv(env: RouterEnv, options?: {
 }): X402AcceptConfig[];
 declare function paidOptionsForProtocols(protocols: readonly ProtocolType[]): PaidOptions;
 
+/**
+ * SIWX verification error codes.
+ * Enables clients to auto-retry transient failures (e.g., expired challenge).
+ */
+type SiwxErrorCode = 'siwx_missing_header' | 'siwx_malformed' | 'siwx_expired' | 'siwx_nonce_used' | 'siwx_invalid_signature';
+/** Human-readable error messages for each SIWX error code. */
+declare const SIWX_ERROR_MESSAGES: Record<SiwxErrorCode, string>;
+
 interface MonitorEntry {
     provider: string;
     route: string;
@@ -699,7 +766,7 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, true, false, false, false, false> : RouteBuilder<undefined, undefined, undefined, false, false, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, undefined, false, false, false>;
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
@@ -710,4 +777,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, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, 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, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementEvent, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, x402AcceptsFromEnv };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, BASE_NETWORK, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, type HandlerPaymentContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type MppProtocolInfo, type NonceStore, type OveragePolicy, type PaidOptions, type PayToConfig, type PaymentEvent, type PaymentStatus, 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, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigValidationOptions, type RouterEnv, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, SIWX_ERROR_MESSAGES, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettledHandlerErrorContext, type SettlementErrorContext, type SettlementEvent, type SettlementLifecycle, type SettlementLifecycleContext, type SettlementSettledContext, type SiwxErrorCode, TEMPO_USDC_CURRENCY, type TierConfig, type X402AcceptConfig, type X402FacilitatorTarget, type X402FacilitatorsConfig, type X402ResolvedAccept, type X402RouterFacilitatorConfig, type X402Server, ZERO_EVM_ADDRESS, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter, formatRouterConfigIssues, getRouterConfigIssues, mppFromEnv, paidOptionsForProtocols, validateRouterConfig, x402AcceptsFromEnv };