@agent-score/commerce 2.0.2 → 2.1.1

package/dist/middleware/web.js

@@ -0,0 +1,128 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/middleware/web.ts
+var web_exports = {};
+__export(web_exports, {
+  createRateLimit: () => createRateLimit
+});
+module.exports = __toCommonJS(web_exports);
+
+// src/_redis.ts
+async function tryCreateRedis(opts) {
+  const url = opts.url ?? process.env.REDIS_URL;
+  if (!url) return null;
+  try {
+    const mod = await import("ioredis");
+    const client = new mod.default(url, {
+      connectTimeout: opts.connectTimeout ?? 3e3,
+      maxRetriesPerRequest: opts.maxRetriesPerRequest ?? 1,
+      tls: url.startsWith("rediss://") ? {} : void 0
+    });
+    client.on("error", (err) => console.error(`[${opts.label}] Redis error:`, err.message));
+    return client;
+  } catch {
+    return null;
+  }
+}
+function memoizedRedis(opts) {
+  let promise = null;
+  return () => {
+    if (!promise) promise = tryCreateRedis(opts);
+    return promise;
+  };
+}
+
+// src/middleware/_core.ts
+function createRateLimiter(opts = {}) {
+  const windowSeconds = opts.windowSeconds ?? 60;
+  const maxRequests = opts.maxRequests ?? 60;
+  const keyPrefix = opts.keyPrefix ?? "rl:";
+  const memMap = /* @__PURE__ */ new Map();
+  const getRedis = memoizedRedis({ url: opts.redisUrl, label: "rate-limit" });
+  const checkMem = (key) => {
+    const now = Date.now();
+    const entry = memMap.get(key);
+    if (!entry || entry.resetAt < now) {
+      memMap.set(key, { count: 1, resetAt: now + windowSeconds * 1e3 });
+      return { allowed: true, remaining: maxRequests - 1, limit: maxRequests };
+    }
+    entry.count++;
+    const remaining = Math.max(0, maxRequests - entry.count);
+    return { allowed: entry.count <= maxRequests, remaining, limit: maxRequests };
+  };
+  return {
+    async check(key) {
+      const r = await getRedis();
+      if (!r) return checkMem(key);
+      try {
+        const fullKey = `${keyPrefix}${key}`;
+        const count = await r.incr(fullKey);
+        if (count === 1) await r.expire(fullKey, windowSeconds);
+        const remaining = Math.max(0, maxRequests - count);
+        return { allowed: count <= maxRequests, remaining, limit: maxRequests };
+      } catch {
+        return checkMem(key);
+      }
+    }
+  };
+}
+var RATE_LIMIT_JSON_BODY = {
+  error: { code: "rate_limited", message: "Too many requests" }
+};
+function defaultKeyFromForwardedFor(forwardedFor) {
+  if (!forwardedFor) return "unknown";
+  return forwardedFor.split(",")[0]?.trim() || "unknown";
+}
+
+// src/middleware/web.ts
+function createRateLimit(opts = {}) {
+  const limiter = createRateLimiter(opts);
+  const keyResolver = opts.keyResolver ?? ((req) => defaultKeyFromForwardedFor(req.headers.get("x-forwarded-for")));
+  return async (req) => {
+    const { allowed, remaining, limit } = await limiter.check(keyResolver(req));
+    const baseHeaders = {
+      "X-RateLimit-Limit": String(limit),
+      "X-RateLimit-Remaining": String(remaining)
+    };
+    if (!allowed) {
+      const response = new Response(JSON.stringify(RATE_LIMIT_JSON_BODY), {
+        status: 429,
+        headers: { ...baseHeaders, "Content-Type": "application/json", "Cache-Control": "no-store" }
+      });
+      return { allowed: false, remaining, limit, response };
+    }
+    return { allowed: true, remaining, limit };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRateLimit
+});
+//# sourceMappingURL=web.js.map

package/dist/middleware/web.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/middleware/web.ts","../../src/_redis.ts","../../src/middleware/_core.ts"],"sourcesContent":["import {\n  RATE_LIMIT_JSON_BODY,\n  createRateLimiter,\n  defaultKeyFromForwardedFor,\n  type RateLimitCoreOptions,\n} from './_core';\n\nexport interface RateLimitWebOptions extends RateLimitCoreOptions {\n  /** Bucket key resolver. Default: first hop of `x-forwarded-for`, else `'unknown'`. */\n  keyResolver?: (req: Request) => string;\n}\n\nexport type RateLimitGuardResult =\n  | { allowed: true; remaining: number; limit: number; response?: undefined }\n  | { allowed: false; remaining: number; limit: number; response: Response };\n\nexport type RateLimitGuard = (req: Request) => Promise<RateLimitGuardResult>;\n\n/**\n * Build a rate-limit guard for Web Fetch–style handlers. Call `guard(req)` at the top\n * of your route. When `allowed === false`, return `result.response` directly.\n */\nexport function createRateLimit(opts: RateLimitWebOptions = {}): RateLimitGuard {\n  const limiter = createRateLimiter(opts);\n  const keyResolver =\n    opts.keyResolver ?? ((req: Request) => defaultKeyFromForwardedFor(req.headers.get('x-forwarded-for')));\n\n  return async (req: Request) => {\n    const { allowed, remaining, limit } = await limiter.check(keyResolver(req));\n    const baseHeaders = {\n      'X-RateLimit-Limit': String(limit),\n      'X-RateLimit-Remaining': String(remaining),\n    };\n    if (!allowed) {\n      const response = new Response(JSON.stringify(RATE_LIMIT_JSON_BODY), {\n        status: 429,\n        headers: { ...baseHeaders, 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },\n      });\n      return { allowed: false, remaining, limit, response };\n    }\n    return { allowed: true, remaining, limit };\n  };\n}\n","/** Shared lazy `ioredis` factory. Used by `quote_cache`, `middleware/_core`,\n *  and `stripe-multichain/pi-cache` so they don't drift on connect-timeout,\n *  TLS handling, or error-logging posture.\n *\n *  `ioredis` is an optional peer dep — callers pass `redisUrl` (or rely on\n *  `process.env.REDIS_URL`); when unset or the lazy import fails, this returns\n *  null and the caller falls back to its in-process `Map`.\n *\n *  Not part of the public API.\n */\n\n/** Minimal Redis surface — each caller intersects with its own usage\n *  (incr/expire for rate-limit, get/set/del for caches). Returning `unknown`\n *  on commands keeps the shape narrow; cast at the call site. */\nexport interface MinimalRedis {\n  on(event: 'error', handler: (err: Error) => void): unknown;\n}\n\nexport interface CreateRedisOptions {\n  /** Override `process.env.REDIS_URL` for tests. */\n  url?: string;\n  /** Logging label, e.g. `'quote-cache'` / `'rate-limit'` / `'pi-cache'`. */\n  label: string;\n  /** Connect timeout in ms. Default `3000`. */\n  connectTimeout?: number;\n  /** Per-request retry cap. Default `1`. */\n  maxRetriesPerRequest?: number;\n}\n\n/** Lazy-import ioredis and construct a client. Returns null when:\n *   - no URL is configured (caller falls back to in-memory)\n *   - `ioredis` isn't installed (optional peer; caller falls back to in-memory)\n *   - the import throws for any other reason\n *\n *  `rediss://` URLs auto-enable TLS. The error handler logs with the caller's\n *  label so multi-cache deployments can tell which subsystem complained. */\nasync function tryCreateRedis<T extends MinimalRedis>(opts: CreateRedisOptions): Promise<T | null> {\n  const url = opts.url ?? process.env.REDIS_URL;\n  if (!url) return null;\n  try {\n    const mod = (await import('ioredis')) as unknown as { default: new (url: string, opts?: unknown) => T };\n    const client = new mod.default(url, {\n      connectTimeout: opts.connectTimeout ?? 3000,\n      maxRetriesPerRequest: opts.maxRetriesPerRequest ?? 1,\n      tls: url.startsWith('rediss://') ? {} : undefined,\n    });\n    client.on('error', (err) => console.error(`[${opts.label}] Redis error:`, err.message));\n    return client;\n  } catch {\n    return null;\n  }\n}\n\n/** Memoized-promise variant: call once per caller; subsequent calls return the\n *  same promise. Pairs with the pattern `let p: Promise<T|null> | null = null;\n *  const getRedis = () => (p ??= tryCreateRedis(...))` in callers that want\n *  per-call promise caching without managing the closure themselves. */\nexport function memoizedRedis<T extends MinimalRedis>(opts: CreateRedisOptions): () => Promise<T | null> {\n  let promise: Promise<T | null> | null = null;\n  return () => {\n    if (!promise) promise = tryCreateRedis<T>(opts);\n    return promise;\n  };\n}\n","import { memoizedRedis, type MinimalRedis } from '../_redis';\n\nexport interface RateLimitCoreOptions {\n  windowSeconds?: number;\n  maxRequests?: number;\n  /** Redis connection URL. Default: `process.env.REDIS_URL`. Falls back to in-memory when unset or the lazy `ioredis` import fails. */\n  redisUrl?: string;\n  /** Per-instance key prefix so multiple limiters sharing a Redis don't collide. */\n  keyPrefix?: string;\n}\n\ninterface RateLimitDecision {\n  allowed: boolean;\n  remaining: number;\n  limit: number;\n}\n\nexport interface RateLimiter {\n  check(key: string): Promise<RateLimitDecision>;\n}\n\ninterface RedisLike extends MinimalRedis {\n  incr(key: string): Promise<number>;\n  expire(key: string, seconds: number): Promise<unknown>;\n}\n\n/** Framework-agnostic rate limiter. Hono / Express / Fastify / Next.js / Web adapters\n *  share one core. Each `createRateLimiter` call owns its own memory map + redis\n *  connection, so multiple instances in the same process don't share state unless\n *  they share a Redis with the same `keyPrefix`. */\nexport function createRateLimiter(opts: RateLimitCoreOptions = {}): RateLimiter {\n  const windowSeconds = opts.windowSeconds ?? 60;\n  const maxRequests = opts.maxRequests ?? 60;\n  const keyPrefix = opts.keyPrefix ?? 'rl:';\n\n  const memMap = new Map<string, { count: number; resetAt: number }>();\n  const getRedis = memoizedRedis<RedisLike>({ url: opts.redisUrl, label: 'rate-limit' });\n\n  const checkMem = (key: string): RateLimitDecision => {\n    const now = Date.now();\n    const entry = memMap.get(key);\n    if (!entry || entry.resetAt < now) {\n      memMap.set(key, { count: 1, resetAt: now + windowSeconds * 1000 });\n      return { allowed: true, remaining: maxRequests - 1, limit: maxRequests };\n    }\n    entry.count++;\n    const remaining = Math.max(0, maxRequests - entry.count);\n    return { allowed: entry.count <= maxRequests, remaining, limit: maxRequests };\n  };\n\n  return {\n    async check(key: string): Promise<RateLimitDecision> {\n      const r = await getRedis();\n      if (!r) return checkMem(key);\n      try {\n        const fullKey = `${keyPrefix}${key}`;\n        const count = await r.incr(fullKey);\n        if (count === 1) await r.expire(fullKey, windowSeconds);\n        const remaining = Math.max(0, maxRequests - count);\n        return { allowed: count <= maxRequests, remaining, limit: maxRequests };\n      } catch {\n        return checkMem(key);\n      }\n    },\n  };\n}\n\nexport const RATE_LIMIT_JSON_BODY = {\n  error: { code: 'rate_limited', message: 'Too many requests' },\n} as const;\n\n/** Default key resolver: first hop of `x-forwarded-for`, else `'unknown'`. Works on any\n *  framework's request once you adapt the header read. */\nexport function defaultKeyFromForwardedFor(forwardedFor: string | null | undefined): string {\n  if (!forwardedFor) return 'unknown';\n  return forwardedFor.split(',')[0]?.trim() || 'unknown';\n}\n"],"mappings":"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","names":[]}

package/dist/middleware/web.mjs

@@ -0,0 +1,91 @@
+// src/_redis.ts
+async function tryCreateRedis(opts) {
+  const url = opts.url ?? process.env.REDIS_URL;
+  if (!url) return null;
+  try {
+    const mod = await import("ioredis");
+    const client = new mod.default(url, {
+      connectTimeout: opts.connectTimeout ?? 3e3,
+      maxRetriesPerRequest: opts.maxRetriesPerRequest ?? 1,
+      tls: url.startsWith("rediss://") ? {} : void 0
+    });
+    client.on("error", (err) => console.error(`[${opts.label}] Redis error:`, err.message));
+    return client;
+  } catch {
+    return null;
+  }
+}
+function memoizedRedis(opts) {
+  let promise = null;
+  return () => {
+    if (!promise) promise = tryCreateRedis(opts);
+    return promise;
+  };
+}
+
+// src/middleware/_core.ts
+function createRateLimiter(opts = {}) {
+  const windowSeconds = opts.windowSeconds ?? 60;
+  const maxRequests = opts.maxRequests ?? 60;
+  const keyPrefix = opts.keyPrefix ?? "rl:";
+  const memMap = /* @__PURE__ */ new Map();
+  const getRedis = memoizedRedis({ url: opts.redisUrl, label: "rate-limit" });
+  const checkMem = (key) => {
+    const now = Date.now();
+    const entry = memMap.get(key);
+    if (!entry || entry.resetAt < now) {
+      memMap.set(key, { count: 1, resetAt: now + windowSeconds * 1e3 });
+      return { allowed: true, remaining: maxRequests - 1, limit: maxRequests };
+    }
+    entry.count++;
+    const remaining = Math.max(0, maxRequests - entry.count);
+    return { allowed: entry.count <= maxRequests, remaining, limit: maxRequests };
+  };
+  return {
+    async check(key) {
+      const r = await getRedis();
+      if (!r) return checkMem(key);
+      try {
+        const fullKey = `${keyPrefix}${key}`;
+        const count = await r.incr(fullKey);
+        if (count === 1) await r.expire(fullKey, windowSeconds);
+        const remaining = Math.max(0, maxRequests - count);
+        return { allowed: count <= maxRequests, remaining, limit: maxRequests };
+      } catch {
+        return checkMem(key);
+      }
+    }
+  };
+}
+var RATE_LIMIT_JSON_BODY = {
+  error: { code: "rate_limited", message: "Too many requests" }
+};
+function defaultKeyFromForwardedFor(forwardedFor) {
+  if (!forwardedFor) return "unknown";
+  return forwardedFor.split(",")[0]?.trim() || "unknown";
+}
+
+// src/middleware/web.ts
+function createRateLimit(opts = {}) {
+  const limiter = createRateLimiter(opts);
+  const keyResolver = opts.keyResolver ?? ((req) => defaultKeyFromForwardedFor(req.headers.get("x-forwarded-for")));
+  return async (req) => {
+    const { allowed, remaining, limit } = await limiter.check(keyResolver(req));
+    const baseHeaders = {
+      "X-RateLimit-Limit": String(limit),
+      "X-RateLimit-Remaining": String(remaining)
+    };
+    if (!allowed) {
+      const response = new Response(JSON.stringify(RATE_LIMIT_JSON_BODY), {
+        status: 429,
+        headers: { ...baseHeaders, "Content-Type": "application/json", "Cache-Control": "no-store" }
+      });
+      return { allowed: false, remaining, limit, response };
+    }
+    return { allowed: true, remaining, limit };
+  };
+}
+export {
+  createRateLimit
+};
+//# sourceMappingURL=web.mjs.map

package/dist/middleware/web.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/_redis.ts","../../src/middleware/_core.ts","../../src/middleware/web.ts"],"sourcesContent":["/** Shared lazy `ioredis` factory. Used by `quote_cache`, `middleware/_core`,\n *  and `stripe-multichain/pi-cache` so they don't drift on connect-timeout,\n *  TLS handling, or error-logging posture.\n *\n *  `ioredis` is an optional peer dep — callers pass `redisUrl` (or rely on\n *  `process.env.REDIS_URL`); when unset or the lazy import fails, this returns\n *  null and the caller falls back to its in-process `Map`.\n *\n *  Not part of the public API.\n */\n\n/** Minimal Redis surface — each caller intersects with its own usage\n *  (incr/expire for rate-limit, get/set/del for caches). Returning `unknown`\n *  on commands keeps the shape narrow; cast at the call site. */\nexport interface MinimalRedis {\n  on(event: 'error', handler: (err: Error) => void): unknown;\n}\n\nexport interface CreateRedisOptions {\n  /** Override `process.env.REDIS_URL` for tests. */\n  url?: string;\n  /** Logging label, e.g. `'quote-cache'` / `'rate-limit'` / `'pi-cache'`. */\n  label: string;\n  /** Connect timeout in ms. Default `3000`. */\n  connectTimeout?: number;\n  /** Per-request retry cap. Default `1`. */\n  maxRetriesPerRequest?: number;\n}\n\n/** Lazy-import ioredis and construct a client. Returns null when:\n *   - no URL is configured (caller falls back to in-memory)\n *   - `ioredis` isn't installed (optional peer; caller falls back to in-memory)\n *   - the import throws for any other reason\n *\n *  `rediss://` URLs auto-enable TLS. The error handler logs with the caller's\n *  label so multi-cache deployments can tell which subsystem complained. */\nasync function tryCreateRedis<T extends MinimalRedis>(opts: CreateRedisOptions): Promise<T | null> {\n  const url = opts.url ?? process.env.REDIS_URL;\n  if (!url) return null;\n  try {\n    const mod = (await import('ioredis')) as unknown as { default: new (url: string, opts?: unknown) => T };\n    const client = new mod.default(url, {\n      connectTimeout: opts.connectTimeout ?? 3000,\n      maxRetriesPerRequest: opts.maxRetriesPerRequest ?? 1,\n      tls: url.startsWith('rediss://') ? {} : undefined,\n    });\n    client.on('error', (err) => console.error(`[${opts.label}] Redis error:`, err.message));\n    return client;\n  } catch {\n    return null;\n  }\n}\n\n/** Memoized-promise variant: call once per caller; subsequent calls return the\n *  same promise. Pairs with the pattern `let p: Promise<T|null> | null = null;\n *  const getRedis = () => (p ??= tryCreateRedis(...))` in callers that want\n *  per-call promise caching without managing the closure themselves. */\nexport function memoizedRedis<T extends MinimalRedis>(opts: CreateRedisOptions): () => Promise<T | null> {\n  let promise: Promise<T | null> | null = null;\n  return () => {\n    if (!promise) promise = tryCreateRedis<T>(opts);\n    return promise;\n  };\n}\n","import { memoizedRedis, type MinimalRedis } from '../_redis';\n\nexport interface RateLimitCoreOptions {\n  windowSeconds?: number;\n  maxRequests?: number;\n  /** Redis connection URL. Default: `process.env.REDIS_URL`. Falls back to in-memory when unset or the lazy `ioredis` import fails. */\n  redisUrl?: string;\n  /** Per-instance key prefix so multiple limiters sharing a Redis don't collide. */\n  keyPrefix?: string;\n}\n\ninterface RateLimitDecision {\n  allowed: boolean;\n  remaining: number;\n  limit: number;\n}\n\nexport interface RateLimiter {\n  check(key: string): Promise<RateLimitDecision>;\n}\n\ninterface RedisLike extends MinimalRedis {\n  incr(key: string): Promise<number>;\n  expire(key: string, seconds: number): Promise<unknown>;\n}\n\n/** Framework-agnostic rate limiter. Hono / Express / Fastify / Next.js / Web adapters\n *  share one core. Each `createRateLimiter` call owns its own memory map + redis\n *  connection, so multiple instances in the same process don't share state unless\n *  they share a Redis with the same `keyPrefix`. */\nexport function createRateLimiter(opts: RateLimitCoreOptions = {}): RateLimiter {\n  const windowSeconds = opts.windowSeconds ?? 60;\n  const maxRequests = opts.maxRequests ?? 60;\n  const keyPrefix = opts.keyPrefix ?? 'rl:';\n\n  const memMap = new Map<string, { count: number; resetAt: number }>();\n  const getRedis = memoizedRedis<RedisLike>({ url: opts.redisUrl, label: 'rate-limit' });\n\n  const checkMem = (key: string): RateLimitDecision => {\n    const now = Date.now();\n    const entry = memMap.get(key);\n    if (!entry || entry.resetAt < now) {\n      memMap.set(key, { count: 1, resetAt: now + windowSeconds * 1000 });\n      return { allowed: true, remaining: maxRequests - 1, limit: maxRequests };\n    }\n    entry.count++;\n    const remaining = Math.max(0, maxRequests - entry.count);\n    return { allowed: entry.count <= maxRequests, remaining, limit: maxRequests };\n  };\n\n  return {\n    async check(key: string): Promise<RateLimitDecision> {\n      const r = await getRedis();\n      if (!r) return checkMem(key);\n      try {\n        const fullKey = `${keyPrefix}${key}`;\n        const count = await r.incr(fullKey);\n        if (count === 1) await r.expire(fullKey, windowSeconds);\n        const remaining = Math.max(0, maxRequests - count);\n        return { allowed: count <= maxRequests, remaining, limit: maxRequests };\n      } catch {\n        return checkMem(key);\n      }\n    },\n  };\n}\n\nexport const RATE_LIMIT_JSON_BODY = {\n  error: { code: 'rate_limited', message: 'Too many requests' },\n} as const;\n\n/** Default key resolver: first hop of `x-forwarded-for`, else `'unknown'`. Works on any\n *  framework's request once you adapt the header read. */\nexport function defaultKeyFromForwardedFor(forwardedFor: string | null | undefined): string {\n  if (!forwardedFor) return 'unknown';\n  return forwardedFor.split(',')[0]?.trim() || 'unknown';\n}\n","import {\n  RATE_LIMIT_JSON_BODY,\n  createRateLimiter,\n  defaultKeyFromForwardedFor,\n  type RateLimitCoreOptions,\n} from './_core';\n\nexport interface RateLimitWebOptions extends RateLimitCoreOptions {\n  /** Bucket key resolver. Default: first hop of `x-forwarded-for`, else `'unknown'`. */\n  keyResolver?: (req: Request) => string;\n}\n\nexport type RateLimitGuardResult =\n  | { allowed: true; remaining: number; limit: number; response?: undefined }\n  | { allowed: false; remaining: number; limit: number; response: Response };\n\nexport type RateLimitGuard = (req: Request) => Promise<RateLimitGuardResult>;\n\n/**\n * Build a rate-limit guard for Web Fetch–style handlers. Call `guard(req)` at the top\n * of your route. When `allowed === false`, return `result.response` directly.\n */\nexport function createRateLimit(opts: RateLimitWebOptions = {}): RateLimitGuard {\n  const limiter = createRateLimiter(opts);\n  const keyResolver =\n    opts.keyResolver ?? ((req: Request) => defaultKeyFromForwardedFor(req.headers.get('x-forwarded-for')));\n\n  return async (req: Request) => {\n    const { allowed, remaining, limit } = await limiter.check(keyResolver(req));\n    const baseHeaders = {\n      'X-RateLimit-Limit': String(limit),\n      'X-RateLimit-Remaining': String(remaining),\n    };\n    if (!allowed) {\n      const response = new Response(JSON.stringify(RATE_LIMIT_JSON_BODY), {\n        status: 429,\n        headers: { ...baseHeaders, 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },\n      });\n      return { allowed: false, remaining, limit, response };\n    }\n    return { allowed: true, remaining, limit };\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/payment/index.d.mts

@@ -1,11 +1,11 @@
-import { T as TempoRailSpec, S as SolanaMppRailSpec, a as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from '../rail_spec-XP0wKgJV.mjs';
-export { R as RAIL_SPEC_DEFAULTS, c as RecipientLike, r as resolveRecipient } from '../rail_spec-XP0wKgJV.mjs';
-import { X as X402Server } from '../x402_server-hgQzWQwB.mjs';
-export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, a as X402FacilitatorChoice, b as X402SymbolicRail, c as buildX402AcceptsFor402, d as createX402Server } from '../x402_server-hgQzWQwB.mjs';
+import { T as TempoRailSpec, S as SolanaMppRailSpec, c as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from '../rail_spec-D6qzh3J0.mjs';
+export { R as RAIL_SPEC_DEFAULTS, a as RecipientLike, r as resolveRecipient } from '../rail_spec-D6qzh3J0.mjs';
+import { a as X402Server } from '../x402_server-Ciz2mls2.mjs';
+export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, X as X402FacilitatorChoice, b as X402SymbolicRail, c as buildX402AcceptsFor402, d as createX402Server } from '../x402_server-Ciz2mls2.mjs';
 export { a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-D_FMnPgU.mjs';
 import { S as SignerNetwork } from '../signer-3FAit11j.mjs';
 export { P as PaymentSigner, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from '../signer-3FAit11j.mjs';
-export { f as formatUsdCents, l as loadSolanaFeePayer, u as usdToAtomic } from '../solana-Cds87OTu.mjs';
+export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer, r as readHeader, u as usdToAtomic } from '../default_rails-XFCuRddA.mjs';
 
 /**
  * Build the base64-encoded `request` blob for an MPP Payment directive (per the
@@ -569,21 +569,17 @@ type MppxComposeResult = {
     challenge: Response;
     [k: string]: unknown;
 };
-/**
- * Run `mppx.compose(...intents)(request)` with a typed return. Replaces the
- * `(mppx as any).compose(...intents)(request)` cast every hand-rolled
- * `composeMppx` hook ends up writing.
- *
- * @example
- * ```ts
- * const result = await composeMppxRequest(mppx, [
- *   ['tempo/charge', { amount, currency, decimals, recipient }],
- *   ['stripe/charge', { amount, currency: 'usd', decimals: 2 }],
- * ], ctx.request.raw);
- * if (result.status === 402) return { status: 402, headers: mppxChallengeHeaders(result) };
- * return { status: 200, raw: result };
- * ```
- */
+/** Run `fn` inside an async context that captures the inner mppx
+ *  verification error (when one fires). Returns the function's result
+ *  plus the captured `failureReason` string (null if no error fired or
+ *  no console.error hit during this scope). Used by `Checkout.handleMppx`
+ *  to surface typed error codes (`tempo_key_not_registered`, etc.) on
+ *  the 402 path without changing the per-merchant `composeMppx` API.
+ */
+declare function runWithMppxFailureCapture<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    failureReason: string | null;
+}>;
 declare function composeMppxRequest(mppx: unknown, intents: readonly unknown[], request: Request): Promise<MppxComposeResult>;
 /**
  * Extract the 402 challenge response's headers as a plain `Record<string, string>`,
@@ -879,4 +875,19 @@ declare function lazyMppxServer(opts: {
     secretKey: string;
 }): () => Promise<unknown>;
 
-export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };
+/** CAIP-2 prefix discriminators. Replaces the ad-hoc `startsWith('eip155:')` /
+ *  `startsWith('solana:')` calls scattered across `checkout`, `checkout_compute_first`,
+ *  `payment/lazy`, and `identity/ucp` so the prefix strings live in one place.
+ *
+ *  Accepts the bare network spec `'eip155:8453'` or a rail-spec object with a
+ *  `network` field. Pure functions; no peer-dep imports.
+ */
+type NetworkLike = string | object | null | undefined;
+/** True when the network is a CAIP-2 EVM chain (`eip155:<chainId>`). */
+declare function isEvmNetwork(input: NetworkLike): boolean;
+/** True when the network is a CAIP-2 Solana chain (`solana:<genesis-hash>`).
+ *  Note: `'solana'` bare (no `:`) is the mppx-internal label, NOT a CAIP-2
+ *  network spec — this helper treats it as false. */
+declare function isSolanaNetwork(input: NetworkLike): boolean;
+
+export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, isEvmNetwork, isSolanaNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, runWithMppxFailureCapture, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };

package/dist/payment/index.d.ts

@@ -1,11 +1,11 @@
-import { T as TempoRailSpec, S as SolanaMppRailSpec, a as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from '../rail_spec-XP0wKgJV.js';
-export { R as RAIL_SPEC_DEFAULTS, c as RecipientLike, r as resolveRecipient } from '../rail_spec-XP0wKgJV.js';
-import { X as X402Server } from '../x402_server-hgQzWQwB.js';
-export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, a as X402FacilitatorChoice, b as X402SymbolicRail, c as buildX402AcceptsFor402, d as createX402Server } from '../x402_server-hgQzWQwB.js';
+import { T as TempoRailSpec, S as SolanaMppRailSpec, c as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from '../rail_spec-D6qzh3J0.js';
+export { R as RAIL_SPEC_DEFAULTS, a as RecipientLike, r as resolveRecipient } from '../rail_spec-D6qzh3J0.js';
+import { a as X402Server } from '../x402_server-Ciz2mls2.js';
+export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, X as X402FacilitatorChoice, b as X402SymbolicRail, c as buildX402AcceptsFor402, d as createX402Server } from '../x402_server-Ciz2mls2.js';
 export { a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-D_FMnPgU.js';
 import { S as SignerNetwork } from '../signer-3FAit11j.js';
 export { P as PaymentSigner, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from '../signer-3FAit11j.js';
-export { f as formatUsdCents, l as loadSolanaFeePayer, u as usdToAtomic } from '../solana-Cds87OTu.js';
+export { B as BuildDefaultCheckoutRailsOptions, a as BuildMppxComposeRailsOptions, H as HeadersLike, b as asHeaders, c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer, r as readHeader, u as usdToAtomic } from '../default_rails-C5gKZJMI.js';
 
 /**
  * Build the base64-encoded `request` blob for an MPP Payment directive (per the
@@ -569,21 +569,17 @@ type MppxComposeResult = {
     challenge: Response;
     [k: string]: unknown;
 };
-/**
- * Run `mppx.compose(...intents)(request)` with a typed return. Replaces the
- * `(mppx as any).compose(...intents)(request)` cast every hand-rolled
- * `composeMppx` hook ends up writing.
- *
- * @example
- * ```ts
- * const result = await composeMppxRequest(mppx, [
- *   ['tempo/charge', { amount, currency, decimals, recipient }],
- *   ['stripe/charge', { amount, currency: 'usd', decimals: 2 }],
- * ], ctx.request.raw);
- * if (result.status === 402) return { status: 402, headers: mppxChallengeHeaders(result) };
- * return { status: 200, raw: result };
- * ```
- */
+/** Run `fn` inside an async context that captures the inner mppx
+ *  verification error (when one fires). Returns the function's result
+ *  plus the captured `failureReason` string (null if no error fired or
+ *  no console.error hit during this scope). Used by `Checkout.handleMppx`
+ *  to surface typed error codes (`tempo_key_not_registered`, etc.) on
+ *  the 402 path without changing the per-merchant `composeMppx` API.
+ */
+declare function runWithMppxFailureCapture<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    failureReason: string | null;
+}>;
 declare function composeMppxRequest(mppx: unknown, intents: readonly unknown[], request: Request): Promise<MppxComposeResult>;
 /**
  * Extract the 402 challenge response's headers as a plain `Record<string, string>`,
@@ -879,4 +875,19 @@ declare function lazyMppxServer(opts: {
     secretKey: string;
 }): () => Promise<unknown>;
 
-export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };
+/** CAIP-2 prefix discriminators. Replaces the ad-hoc `startsWith('eip155:')` /
+ *  `startsWith('solana:')` calls scattered across `checkout`, `checkout_compute_first`,
+ *  `payment/lazy`, and `identity/ucp` so the prefix strings live in one place.
+ *
+ *  Accepts the bare network spec `'eip155:8453'` or a rail-spec object with a
+ *  `network` field. Pure functions; no peer-dep imports.
+ */
+type NetworkLike = string | object | null | undefined;
+/** True when the network is a CAIP-2 EVM chain (`eip155:<chainId>`). */
+declare function isEvmNetwork(input: NetworkLike): boolean;
+/** True when the network is a CAIP-2 Solana chain (`solana:<genesis-hash>`).
+ *  Note: `'solana'` bare (no `:`) is the mppx-internal label, NOT a CAIP-2
+ *  network spec — this helper treats it as false. */
+declare function isSolanaNetwork(input: NetworkLike): boolean;
+
+export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, isEvmNetwork, isSolanaNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, runWithMppxFailureCapture, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };