@agentcash/router 1.10.0 → 1.10.1

package/README.md

@@ -18,6 +18,12 @@
   <a href="#install"><img alt="next.js" src="https://img.shields.io/badge/Next.js-App%20Router-111"></a>
 </p>
 
+<p align="center">
+  <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FMerit-Systems%2Fagentcash-router%2Ftree%2Fmain%2Fexamples%2Fvercel-deploy&project-name=agentcash-fortune-demo&repository-name=agentcash-fortune-demo&demo-title=AgentCash%20Router%20Fortune%20Demo&demo-description=Pay-per-call%20fortune%20API%20on%20x402%20and%20MPP&demo-url=https%3A%2F%2Fagentcash.dev&env=EVM_PAYEE_ADDRESS%2CCDP_API_KEY_ID%2CCDP_API_KEY_SECRET&envDescription=Wallet%20that%20receives%20payments%20%2B%20Coinbase%20Developer%20Platform%20API%20keys%20for%20the%20default%20x402%20facilitator.%20Create%20keys%20in%20the%20generous%20CDP%20free%20tier%3A%20https%3A%2F%2Fportal.cdp.coinbase.com%2Fprojects%2Fapi-keys&envLink=https%3A%2F%2Fgithub.com%2FMerit-Systems%2Fagentcash-router%2Fblob%2Fmain%2Fexamples%2Fvercel-deploy%2FREADME.md%23environment-variables">
+    <img alt="Deploy with Vercel" src="https://vercel.com/button">
+  </a>
+</p>
+
 ---
 
 ## Install
@@ -36,7 +42,7 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 | Var | Required | Purpose |
 |-----|----------|---------|
 | `EVM_PAYEE_ADDRESS` | yes | EVM address that receives x402 and MPP payments (`0x…`, 20 bytes). Canonicalized to lowercase. The zero address is rejected. |
-| `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET` | yes (EVM) | Coinbase Developer Platform credentials for the default EVM facilitator. Create an API key at https://portal.cdp.coinbase.com. T3 / `@t3-oss/env-nextjs` users must declare these in their env schema. |
+| `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET` | yes (EVM) | Coinbase Developer Platform credentials for the default EVM facilitator. Create API keys in the generous CDP free tier at https://portal.cdp.coinbase.com/projects/api-keys. T3 / `@t3-oss/env-nextjs` users must declare these in their env schema. |
 
 ### Solana
 
@@ -59,7 +65,8 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 
 | Var | Required | Purpose |
 |-----|----------|---------|
-| `BASE_URL` | yes | Origin URL (`https://api.example.com`). Load-bearing: used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain. |
+| `BASE_URL` | yes outside Vercel | Origin URL (`https://api.example.com`). Load-bearing: used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain. On Vercel, `createRouterFromEnv` auto-derives this from `VERCEL_PROJECT_PRODUCTION_URL`, then `VERCEL_URL`. |
+| `VERCEL_PROJECT_PRODUCTION_URL`, `VERCEL_URL` | no | Vercel system env vars used as fallbacks when `BASE_URL` is unset. Do not set these manually; Vercel provides them during builds and runtime. |
 | `KV_REST_API_URL`, `KV_REST_API_TOKEN` | no | Upstash / Vercel KV. Backs SIWX nonce, SIWX entitlement, and MPP replay. In-memory fallback is unsafe in serverless production. Providing a Kv Store is highly recommended. |
 
 ## Quick start
@@ -306,4 +313,3 @@ const loggingPlugin: RouterPlugin = {
   },
 };
 ```
-

package/dist/index.cjs

@@ -1938,8 +1938,15 @@ function tagBareDecimalAsDollars(amount) {
 var import_types2 = require("@x402/core/types");
 async function verifyX402Payment(opts) {
   const { server, request, price, accepts, report } = opts;
-  const payload = await readPaymentPayload(request);
-  if (!payload) return null;
+  const payment = await readPaymentPayload(request);
+  if (payment.kind === "none") return null;
+  if (payment.kind === "malformed") {
+    return invalidPaymentVerification({
+      reason: "malformed_payment_header",
+      message: `X-PAYMENT header could not be decoded: ${payment.message}`
+    });
+  }
+  const payload = payment.payload;
   const requirements = await buildExpectedRequirements(server, request, price, accepts, report);
   const matching = findVerifiableRequirements(server, requirements, payload);
   const accepted = payload.x402Version === 2 ? payload.accepted : void 0;
@@ -2000,9 +2007,16 @@ function matchesStableFields(requirement, accepted) {
 }
 async function readPaymentPayload(request) {
   const paymentHeader = request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY);
-  if (!paymentHeader) return null;
+  if (!paymentHeader) return { kind: "none" };
   const { decodePaymentSignatureHeader } = await import("@x402/core/http");
-  return decodePaymentSignatureHeader(paymentHeader);
+  try {
+    return { kind: "ok", payload: decodePaymentSignatureHeader(paymentHeader) };
+  } catch (err) {
+    return {
+      kind: "malformed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
 }
 function invalidPaymentVerification(failure) {
   return {
@@ -3445,6 +3459,7 @@ ${issues}`
 }
 
 // src/builder.ts
+var MAX_X402_DESCRIPTION_LENGTH = 400;
 var RouteBuilder = class _RouteBuilder {
   #s;
   constructor(key, registry, deps, defaults) {
@@ -3961,6 +3976,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': .stream() requires .metered() \u2014 static/free/upto routes can't meter per-chunk billing.`
       );
     }
+    if (this.#s.description !== void 0 && this.#s.description.length > MAX_X402_DESCRIPTION_LENGTH && this.#s.pricing !== void 0 && this.#s.protocols.includes("x402")) {
+      throw new Error(
+        `route '${this.#s.key}': .description() is ${this.#s.description.length} chars; must be \u2264 ${MAX_X402_DESCRIPTION_LENGTH} chars \u2014 the CDP x402 facilitator rejects payments whose 402 challenge resource.description exceeds ~500 chars.`
+      );
+    }
     validateExamples(
       this.#s.key,
       this.#s.bodySchema,
@@ -4416,6 +4436,8 @@ var envShape = {
     params: { code: "invalid_base_url" },
     message: "BASE_URL must be a valid URL \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain."
   }).optional(),
+  VERCEL_PROJECT_PRODUCTION_URL: import_zod.z.string().optional(),
+  VERCEL_URL: import_zod.z.string().optional(),
   EVM_PAYEE_ADDRESS: import_zod.z.string().refine(isEvmAddress, {
     params: { code: "invalid_x402_payee", ...x402 },
     message: "EVM_PAYEE_ADDRESS must be a 0x-prefixed 20-byte EVM address \u2014 the wallet that receives x402 and MPP payments."
@@ -4460,7 +4482,7 @@ var EnvInputSchema = import_zod.z.object(envShape).passthrough().superRefine((en
     addIssue(
       ctx,
       { code: "missing_base_url" },
-      "BASE_URL is required \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Set it to your production domain.",
+      "BASE_URL is required \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Set it to your production domain. On Vercel, the router auto-derives it from VERCEL_PROJECT_PRODUCTION_URL or VERCEL_URL.",
       ["BASE_URL"]
     );
   }
@@ -4541,6 +4563,19 @@ function collectKvWarnings(env, kvStoreOptionProvided) {
   }
   return [];
 }
+function withHttps(host) {
+  if (!host) return void 0;
+  return host.startsWith("http://") || host.startsWith("https://") ? host : `https://${host}`;
+}
+function deriveBaseUrlEnv(env) {
+  if (env.BASE_URL) return env;
+  const vercelBaseUrl = withHttps(env.VERCEL_PROJECT_PRODUCTION_URL) ?? withHttps(env.VERCEL_URL);
+  if (!vercelBaseUrl) return env;
+  return {
+    ...env,
+    BASE_URL: vercelBaseUrl
+  };
+}
 function getConfiguredX402Accepts2(config) {
   if (config.x402?.accepts?.length) return [...config.x402.accepts];
   return [
@@ -4709,7 +4744,7 @@ function translateZodIssues(error) {
 }
 function routerConfigFromEnv(options) {
   const rawEnv = options.env ?? process.env;
-  const env = trimAll(rawEnv);
+  const env = deriveBaseUrlEnv(trimAll(rawEnv));
   const optionIssues = [];
   if (!options.title?.trim()) {
     optionIssues.push({

package/dist/index.js

@@ -1897,8 +1897,15 @@ function tagBareDecimalAsDollars(amount) {
 import { VerifyError } from "@x402/core/types";
 async function verifyX402Payment(opts) {
   const { server, request, price, accepts, report } = opts;
-  const payload = await readPaymentPayload(request);
-  if (!payload) return null;
+  const payment = await readPaymentPayload(request);
+  if (payment.kind === "none") return null;
+  if (payment.kind === "malformed") {
+    return invalidPaymentVerification({
+      reason: "malformed_payment_header",
+      message: `X-PAYMENT header could not be decoded: ${payment.message}`
+    });
+  }
+  const payload = payment.payload;
   const requirements = await buildExpectedRequirements(server, request, price, accepts, report);
   const matching = findVerifiableRequirements(server, requirements, payload);
   const accepted = payload.x402Version === 2 ? payload.accepted : void 0;
@@ -1959,9 +1966,16 @@ function matchesStableFields(requirement, accepted) {
 }
 async function readPaymentPayload(request) {
   const paymentHeader = request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY);
-  if (!paymentHeader) return null;
+  if (!paymentHeader) return { kind: "none" };
   const { decodePaymentSignatureHeader } = await import("@x402/core/http");
-  return decodePaymentSignatureHeader(paymentHeader);
+  try {
+    return { kind: "ok", payload: decodePaymentSignatureHeader(paymentHeader) };
+  } catch (err) {
+    return {
+      kind: "malformed",
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
 }
 function invalidPaymentVerification(failure) {
   return {
@@ -3404,6 +3418,7 @@ ${issues}`
 }
 
 // src/builder.ts
+var MAX_X402_DESCRIPTION_LENGTH = 400;
 var RouteBuilder = class _RouteBuilder {
   #s;
   constructor(key, registry, deps, defaults) {
@@ -3920,6 +3935,11 @@ var RouteBuilder = class _RouteBuilder {
         `route '${this.#s.key}': .stream() requires .metered() \u2014 static/free/upto routes can't meter per-chunk billing.`
       );
     }
+    if (this.#s.description !== void 0 && this.#s.description.length > MAX_X402_DESCRIPTION_LENGTH && this.#s.pricing !== void 0 && this.#s.protocols.includes("x402")) {
+      throw new Error(
+        `route '${this.#s.key}': .description() is ${this.#s.description.length} chars; must be \u2264 ${MAX_X402_DESCRIPTION_LENGTH} chars \u2014 the CDP x402 facilitator rejects payments whose 402 challenge resource.description exceeds ~500 chars.`
+      );
+    }
     validateExamples(
       this.#s.key,
       this.#s.bodySchema,
@@ -4375,6 +4395,8 @@ var envShape = {
     params: { code: "invalid_base_url" },
     message: "BASE_URL must be a valid URL \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain."
   }).optional(),
+  VERCEL_PROJECT_PRODUCTION_URL: z.string().optional(),
+  VERCEL_URL: z.string().optional(),
   EVM_PAYEE_ADDRESS: z.string().refine(isEvmAddress, {
     params: { code: "invalid_x402_payee", ...x402 },
     message: "EVM_PAYEE_ADDRESS must be a 0x-prefixed 20-byte EVM address \u2014 the wallet that receives x402 and MPP payments."
@@ -4419,7 +4441,7 @@ var EnvInputSchema = z.object(envShape).passthrough().superRefine((env, ctx) =>
     addIssue(
       ctx,
       { code: "missing_base_url" },
-      "BASE_URL is required \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Set it to your production domain.",
+      "BASE_URL is required \u2014 the public origin used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Set it to your production domain. On Vercel, the router auto-derives it from VERCEL_PROJECT_PRODUCTION_URL or VERCEL_URL.",
       ["BASE_URL"]
     );
   }
@@ -4500,6 +4522,19 @@ function collectKvWarnings(env, kvStoreOptionProvided) {
   }
   return [];
 }
+function withHttps(host) {
+  if (!host) return void 0;
+  return host.startsWith("http://") || host.startsWith("https://") ? host : `https://${host}`;
+}
+function deriveBaseUrlEnv(env) {
+  if (env.BASE_URL) return env;
+  const vercelBaseUrl = withHttps(env.VERCEL_PROJECT_PRODUCTION_URL) ?? withHttps(env.VERCEL_URL);
+  if (!vercelBaseUrl) return env;
+  return {
+    ...env,
+    BASE_URL: vercelBaseUrl
+  };
+}
 function getConfiguredX402Accepts2(config) {
   if (config.x402?.accepts?.length) return [...config.x402.accepts];
   return [
@@ -4668,7 +4703,7 @@ function translateZodIssues(error) {
 }
 function routerConfigFromEnv(options) {
   const rawEnv = options.env ?? process.env;
-  const env = trimAll(rawEnv);
+  const env = deriveBaseUrlEnv(trimAll(rawEnv));
   const optionIssues = [];
   if (!options.title?.trim()) {
     optionIssues.push({

package/package.json

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