@agentcash/router 1.10.7 → 1.12.0

package/AGENTS.md

@@ -39,6 +39,8 @@ src/
 
 `auth check -> body parse -> validate -> 402 challenge -> payment verify -> handler -> settle -> finalize`
 
+Paid `.paid()` routes may set `mpp: { settleBeforeHandler: true }` (or chain `.mpp({ settleBeforeHandler: true })` on auto-priced routes) to broadcast MPP transaction (pull) credentials at verify instead of after the handler. x402 on the same route is unaffected. MPP hash (push) credentials already settle at verify. Use `.settlement({ onSettledHandlerError })` when eager MPP settle can charge before an upstream failure.
+
 ## Naming
 
 Constructor-style functions use `build<Noun>` — one verb, one domain noun. Name them after the domain concept, never after an HTTP status code or transport detail (the function that builds a payment challenge is `buildChallengeResponse`, not `build402`). The challenge family shares the `Challenge` backbone: `buildChallengeResponse`, `buildChallengeExtensions`, `buildSiwxChallenge`, `buildSessionChallenge`, `buildX402Challenge`.

package/dist/index.cjs

@@ -1784,7 +1784,8 @@ var mppStrategy = {
       return verifySessionMode(args, info);
     }
     if (info.sessionAction) return { ok: false, kind: "invalid" };
-    if (info.payloadType === "transaction" && args.deps.tempoClient) {
+    const deferTransactionSettlement = info.payloadType === "transaction" && args.deps.tempoClient && !args.routeEntry.mppInfo?.settleBeforeHandler;
+    if (deferTransactionSettlement) {
       return verifyTxMode(args, info);
     }
     return verifyHashMode(args, info);
@@ -3856,7 +3857,9 @@ var RouteBuilder = class _RouteBuilder {
     if (maxPrice) next.#s.maxPrice = maxPrice;
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
-    if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.mpp) {
+      next.#s.mppInfo = { ...next.#s.mppInfo, ...resolvedOptions.mpp };
+    }
     if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
     if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
@@ -4151,6 +4154,24 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.validateFn = fn;
     return next;
   }
+  /**
+   * Override MPP protocol metadata and per-route MPP settlement options.
+   * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+   * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+   *
+   * @example
+   * ```ts
+   * router.route('exa/answer')
+   *   .mpp({ settleBeforeHandler: true })
+   *   .body(schema)
+   *   .handler(handler);
+   * ```
+   */
+  mpp(info) {
+    const next = this.fork();
+    next.#s.mppInfo = { ...this.#s.mppInfo, ...info };
+    return next;
+  }
   /**
    * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
    * succeeds but before on-chain settlement and can cancel the charge;
@@ -4166,7 +4187,7 @@ var RouteBuilder = class _RouteBuilder {
    */
   settlement(lifecycle) {
     const next = this.fork();
-    next.#s.settlement = lifecycle;
+    next.#s.settlement = { ...this.#s.settlement, ...lifecycle };
     return next;
   }
   /**
@@ -4222,6 +4243,21 @@ var RouteBuilder = class _RouteBuilder {
     if (this.#s.settlement && !this.#s.pricing) {
       throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
     }
+    if (this.#s.mppInfo?.settleBeforeHandler) {
+      if (!this.#s.pricing) {
+        throw new Error(`route '${this.#s.key}': mpp.settleBeforeHandler requires a paid route`);
+      }
+      if (this.#s.billing !== "exact") {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is only supported on .paid() routes`
+        );
+      }
+      if (this.#s.settlement?.beforeSettle) {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
+        );
+      }
+    }
     if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {

package/dist/index.d.cts

@@ -221,6 +221,7 @@ interface MppProtocolInfo {
     method?: string;
     intent?: string;
     currency?: string;
+    settleBeforeHandler?: boolean;
 }
 type CheckoutSessionResponse = Record<string, unknown>;
 interface CheckoutSessionContext<TBody = unknown> {
@@ -409,6 +410,7 @@ interface DiscoveryConfig {
     contact?: {
         name?: string;
         url?: string;
+        email?: string;
     };
     ownershipProofs?: string[];
     methodHints?: 'off' | 'non-default' | 'always';
@@ -582,8 +584,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
      * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
-     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
-     * for per-tick billing use `.metered()`.
+     * `checkoutSession`) live alongside the pricing shape. Set `mpp.settleBeforeHandler`
+     * on slow upstream routes so MPP transaction (pull) credentials broadcast at verify.
+     * For auto-priced routes from `RouterConfig.prices`, chain `.mpp({ settleBeforeHandler: true })`.
      *
      * @example
      * ```ts
@@ -779,6 +782,20 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * ```
      */
     validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    /**
+     * Override MPP protocol metadata and per-route MPP settlement options.
+     * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+     * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+     *
+     * @example
+     * ```ts
+     * router.route('exa/answer')
+     *   .mpp({ settleBeforeHandler: true })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
+    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -953,4 +970,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type MppProtocolInfo, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.d.ts

@@ -221,6 +221,7 @@ interface MppProtocolInfo {
     method?: string;
     intent?: string;
     currency?: string;
+    settleBeforeHandler?: boolean;
 }
 type CheckoutSessionResponse = Record<string, unknown>;
 interface CheckoutSessionContext<TBody = unknown> {
@@ -409,6 +410,7 @@ interface DiscoveryConfig {
     contact?: {
         name?: string;
         url?: string;
+        email?: string;
     };
     ownershipProofs?: string[];
     methodHints?: 'off' | 'non-default' | 'always';
@@ -582,8 +584,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
      * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
-     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
-     * for per-tick billing use `.metered()`.
+     * `checkoutSession`) live alongside the pricing shape. Set `mpp.settleBeforeHandler`
+     * on slow upstream routes so MPP transaction (pull) credentials broadcast at verify.
+     * For auto-priced routes from `RouterConfig.prices`, chain `.mpp({ settleBeforeHandler: true })`.
      *
      * @example
      * ```ts
@@ -779,6 +782,20 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * ```
      */
     validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    /**
+     * Override MPP protocol metadata and per-route MPP settlement options.
+     * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+     * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+     *
+     * @example
+     * ```ts
+     * router.route('exa/answer')
+     *   .mpp({ settleBeforeHandler: true })
+     *   .body(schema)
+     *   .handler(handler);
+     * ```
+     */
+    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -953,4 +970,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type MppProtocolInfo, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.js

@@ -1746,7 +1746,8 @@ var mppStrategy = {
       return verifySessionMode(args, info);
     }
     if (info.sessionAction) return { ok: false, kind: "invalid" };
-    if (info.payloadType === "transaction" && args.deps.tempoClient) {
+    const deferTransactionSettlement = info.payloadType === "transaction" && args.deps.tempoClient && !args.routeEntry.mppInfo?.settleBeforeHandler;
+    if (deferTransactionSettlement) {
       return verifyTxMode(args, info);
     }
     return verifyHashMode(args, info);
@@ -3818,7 +3819,9 @@ var RouteBuilder = class _RouteBuilder {
     if (maxPrice) next.#s.maxPrice = maxPrice;
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
-    if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
+    if (resolvedOptions.mpp) {
+      next.#s.mppInfo = { ...next.#s.mppInfo, ...resolvedOptions.mpp };
+    }
     if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
     if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
@@ -4113,6 +4116,24 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.validateFn = fn;
     return next;
   }
+  /**
+   * Override MPP protocol metadata and per-route MPP settlement options.
+   * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
+   * (from `RouterConfig.prices`) when you cannot call `.paid()` again.
+   *
+   * @example
+   * ```ts
+   * router.route('exa/answer')
+   *   .mpp({ settleBeforeHandler: true })
+   *   .body(schema)
+   *   .handler(handler);
+   * ```
+   */
+  mpp(info) {
+    const next = this.fork();
+    next.#s.mppInfo = { ...this.#s.mppInfo, ...info };
+    return next;
+  }
   /**
    * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
    * succeeds but before on-chain settlement and can cancel the charge;
@@ -4128,7 +4149,7 @@ var RouteBuilder = class _RouteBuilder {
    */
   settlement(lifecycle) {
     const next = this.fork();
-    next.#s.settlement = lifecycle;
+    next.#s.settlement = { ...this.#s.settlement, ...lifecycle };
     return next;
   }
   /**
@@ -4184,6 +4205,21 @@ var RouteBuilder = class _RouteBuilder {
     if (this.#s.settlement && !this.#s.pricing) {
       throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
     }
+    if (this.#s.mppInfo?.settleBeforeHandler) {
+      if (!this.#s.pricing) {
+        throw new Error(`route '${this.#s.key}': mpp.settleBeforeHandler requires a paid route`);
+      }
+      if (this.#s.billing !== "exact") {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is only supported on .paid() routes`
+        );
+      }
+      if (this.#s.settlement?.beforeSettle) {
+        throw new Error(
+          `route '${this.#s.key}': mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
+        );
+      }
+    }
     if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {

package/package.json

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