@agentcash/router 1.10.4 → 1.10.5

package/dist/index.cjs

@@ -2106,6 +2106,7 @@ function invalidPaymentVerification(failure) {
 }
 
 // src/protocols/x402/strategy.ts
+var SETTLE_RETRY_DELAYS_MS = [500, 1e3];
 function formatVerifyFailureMessage(failure) {
   if (failure.reason === "permit2_allowance_required") {
     const wallet = failure.payer ?? "<the payer wallet>";
@@ -2196,7 +2197,17 @@ async function settleX402(args) {
   const { payload, requirements } = token;
   const override = routeEntry.billing === "exact" ? void 0 : { amount: billedAmount };
   try {
-    const settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    let settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    for (let attempt = 0; !settle.result?.success && attempt < SETTLE_RETRY_DELAYS_MS.length; attempt++) {
+      report("warn", "Retrying x402 settlement", {
+        attempt: attempt + 1,
+        errorReason: settle.result?.errorReason
+      });
+      await new Promise((resolve) => {
+        setTimeout(resolve, SETTLE_RETRY_DELAYS_MS[attempt]);
+      });
+      settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    }
     if (!settle.result?.success) {
       throw Object.assign(
         new Error(settle.result?.errorReason ?? "x402 settlement returned success=false"),
@@ -3590,7 +3601,8 @@ var RouteBuilder = class _RouteBuilder {
       providerConfig: void 0,
       validateFn: void 0,
       settlement: void 0,
-      mppInfo: void 0
+      mppInfo: void 0,
+      hasCheckout: false
     };
   }
   fork() {
@@ -3681,6 +3693,7 @@ var RouteBuilder = class _RouteBuilder {
     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.checkout) next.#s.hasCheckout = true;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4114,6 +4127,7 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: this.#s.validateFn,
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
+      hasCheckout: this.#s.hasCheckout ? true : void 0,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4320,6 +4334,7 @@ function buildOperation(routeKey, entry, tag) {
   const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
   const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
   const pricingInfo = buildPricingInfo(entry);
+  const hasCheckout = entry.hasCheckout === true;
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -4345,10 +4360,11 @@ function buildOperation(routeKey, entry, tag) {
       }
     }
   };
-  if (paymentRequired && (pricingInfo || protocols)) {
+  if (paymentRequired && (pricingInfo || protocols || hasCheckout)) {
     operation["x-payment-info"] = {
       ...pricingInfo ?? {},
-      ...protocols && { protocols }
+      ...protocols && { protocols },
+      ...hasCheckout && { has_checkout: true }
     };
   }
   if (requiresSiwxScheme) {

package/dist/index.d.cts

@@ -227,6 +227,8 @@ interface PaidOptions {
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
+    /** Signal in discovery that clients should use an explicit checkout flow before payment. */
+    checkout?: boolean;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -371,6 +373,7 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
+    hasCheckout?: boolean;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -554,7 +557,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`) live
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
      * alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *

package/dist/index.d.ts

@@ -227,6 +227,8 @@ interface PaidOptions {
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
+    /** Signal in discovery that clients should use an explicit checkout flow before payment. */
+    checkout?: boolean;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -371,6 +373,7 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
+    hasCheckout?: boolean;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -554,7 +557,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`) live
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
      * alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *

package/dist/index.js

@@ -2064,6 +2064,7 @@ function invalidPaymentVerification(failure) {
 }
 
 // src/protocols/x402/strategy.ts
+var SETTLE_RETRY_DELAYS_MS = [500, 1e3];
 function formatVerifyFailureMessage(failure) {
   if (failure.reason === "permit2_allowance_required") {
     const wallet = failure.payer ?? "<the payer wallet>";
@@ -2154,7 +2155,17 @@ async function settleX402(args) {
   const { payload, requirements } = token;
   const override = routeEntry.billing === "exact" ? void 0 : { amount: billedAmount };
   try {
-    const settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    let settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    for (let attempt = 0; !settle.result?.success && attempt < SETTLE_RETRY_DELAYS_MS.length; attempt++) {
+      report("warn", "Retrying x402 settlement", {
+        attempt: attempt + 1,
+        errorReason: settle.result?.errorReason
+      });
+      await new Promise((resolve) => {
+        setTimeout(resolve, SETTLE_RETRY_DELAYS_MS[attempt]);
+      });
+      settle = await settleX402Payment(deps.x402Server, payload, requirements, override);
+    }
     if (!settle.result?.success) {
       throw Object.assign(
         new Error(settle.result?.errorReason ?? "x402 settlement returned success=false"),
@@ -3548,7 +3559,8 @@ var RouteBuilder = class _RouteBuilder {
       providerConfig: void 0,
       validateFn: void 0,
       settlement: void 0,
-      mppInfo: void 0
+      mppInfo: void 0,
+      hasCheckout: false
     };
   }
   fork() {
@@ -3639,6 +3651,7 @@ var RouteBuilder = class _RouteBuilder {
     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.checkout) next.#s.hasCheckout = true;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4072,6 +4085,7 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: this.#s.validateFn,
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
+      hasCheckout: this.#s.hasCheckout ? true : void 0,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4278,6 +4292,7 @@ function buildOperation(routeKey, entry, tag) {
   const requiresSiwxScheme = entry.authMode === "siwx" || Boolean(entry.siwxEnabled);
   const requiresApiKeyScheme = Boolean(entry.apiKeyResolver) && entry.authMode !== "siwx";
   const pricingInfo = buildPricingInfo(entry);
+  const hasCheckout = entry.hasCheckout === true;
   const operation = {
     operationId: routeKey.replace(/\//g, "_"),
     summary: entry.description ?? routeKey,
@@ -4303,10 +4318,11 @@ function buildOperation(routeKey, entry, tag) {
       }
     }
   };
-  if (paymentRequired && (pricingInfo || protocols)) {
+  if (paymentRequired && (pricingInfo || protocols || hasCheckout)) {
     operation["x-payment-info"] = {
       ...pricingInfo ?? {},
-      ...protocols && { protocols }
+      ...protocols && { protocols },
+      ...hasCheckout && { has_checkout: true }
     };
   }
   if (requiresSiwxScheme) {

package/package.json

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