@parallel-protocol/x402 0.6.0 → 0.7.0

package/dist/{chunk-TLCEPWQI.js → chunk-AENXD4OC.js}

@@ -1,27 +1,51 @@
-import { z } from 'zod';
+import { X402_ERROR_CODES, X402RuntimeError, X402ConfigError, isPriceRejection } from './chunk-AFRDHGDT.js';
 import { getTokenDecimals as getTokenDecimals$1 } from '@parallel-protocol/chains';
+import { z } from 'zod';
 
-// src/errors.ts
-var X402_ERROR_CODES = {
-  FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
-  FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
-  INVALID_PAYMENT: "INVALID_PAYMENT"
-};
-var X402ConfigError = class extends Error {
-  constructor(message, cause) {
-    super(message);
-    this.name = "X402ConfigError";
-    this.cause = cause;
-  }
-};
-var X402RuntimeError = class extends Error {
-  constructor(code) {
-    super(code);
-    this.code = code;
-    this.name = "X402RuntimeError";
+var PARALLEL_TOKENS = {
+  ethereum: {
+    usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
+    susdp: "0xd3a452B305C8285c0Dd7b8537665c734d3D279eF",
+    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    frxUSD: "0xCAcd6fd266aF91b8AeD52aCCc382b4e165586E29",
+    sfrxUSD: "0xcf62F905562626CfcDD2261162a51fd02Fc9c5b6",
+    USDe: "0x4c9EDD5852cd905f086C759E8383e09bff1E68B3",
+    sUSDe: "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497"
+  },
+  base: {
+    usdp: "0x76A9A0062ec6712b99B4f63bD2b4270185759dd5",
+    susdp: "0x472eD57b376fE400259FB28e5C46eB53f0E3e7E7",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    USDS: "0x820C137fa70C8691f0e44Dc420a5e53c168921Dc",
+    sUSDS: "0x5875eEE11Cf8398102FdAd704C9E96607675467a"
+  },
+  avalanche: {
+    usdp: "0x9eE1963f05553eF838604Dd39403be21ceF26AA4",
+    susdp: "0x9d92c21205383651610f90722131655a5b8ed3e0",
+    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
+    ygamiUSDC: "0x9fD32FD5e32C6B95483d36C5E724C5C5250Ce010"
+  },
+  hyperevm: {
+    usdp: "0xBE65F0F410A72BeC163dC65d46c83699e957D588",
+    susdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
+    usdc: "0xb88339cb7199b77e23db6e890353e22632ba630f",
+    USDe: "0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34",
+    sUSDe: "0x211Cc4DD073734dA055fbF44a2b4667d5E5fE5d2"
   }
-  code;
 };
+function getDefaultAcceptedTokens(network) {
+  const entry = PARALLEL_TOKENS[network];
+  if (!entry) return void 0;
+  return [entry.usdp, entry.usdc, entry.susdp];
+}
+function getMeteredAcceptedTokens(network) {
+  const entry = PARALLEL_TOKENS[network];
+  if (!entry) return void 0;
+  return [entry.usdp];
+}
+function getTokenDecimals(network, address) {
+  return getTokenDecimals$1(network, address);
+}
 
 // src/utils.ts
 var EIP155_NETWORKS = {
@@ -45,6 +69,28 @@ function parsePrice(price, decimals = 18) {
     `Invalid price format: "${price}". Expected "0.01" or a bigint.`
   );
 }
+function isJsonContentType(contentType) {
+  return /^application\/(?:[\w.-]+\+)?json(?:\s*;.*)?$/i.test(
+    contentType?.trim() ?? ""
+  );
+}
+function parseJsonBody(contentType, text) {
+  if (text === void 0 || !isJsonContentType(contentType)) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+async function jsonFromResponse(res) {
+  const contentType = res.headers.get("content-type") ?? void 0;
+  if (!isJsonContentType(contentType)) return void 0;
+  try {
+    return parseJsonBody(contentType, await res.clone().text());
+  } catch {
+    return void 0;
+  }
+}
 function validateAddress(address) {
   return /^0x[0-9a-fA-F]{40}$/.test(address);
 }
@@ -74,7 +120,12 @@ var ethereumAddressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/, "Invalid Eth
 var txHashSchema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
 var priceSchema = z.union([
   z.bigint().positive("Price must be greater than 0"),
-  z.string().regex(/^\d+(?:\.\d+)?$/, 'Price must be in format "0.01"').refine((price) => Number(price) > 0, "Price must be greater than 0")
+  z.string().regex(/^\d+(?:\.\d+)?$/, 'Price must be in format "0.01"').refine((price) => Number(price) > 0, "Price must be greater than 0"),
+  // A per-request price function; its return value is checked per request.
+  z.custom(
+    (value) => typeof value === "function",
+    "Price must be a string, a bigint or a function of the request"
+  )
 ]);
 var facilitatorConfigSchema = z.object({
   url: z.string().refine((v) => URL.canParse(v), "Invalid facilitator URL"),
@@ -88,11 +139,25 @@ var routeConfigSchema = z.object({
   acceptedTokens: z.array(ethereumAddressSchema).optional(),
   description: z.string().optional(),
   scheme: z.enum(["exact", "upto"]).optional(),
-  maxTimeoutSeconds: z.number().int().positive().optional()
+  maxTimeoutSeconds: z.number().int().positive().optional(),
+  meter: z.custom(
+    (value) => typeof value === "function",
+    "meter must be a function of the response"
+  ).optional()
 }).refine(
+  (route) => route.meter === void 0 || route.scheme === "upto",
+  "meter only applies to upto routes"
+).refine(
   (route) => route.scheme !== "upto" || (route.maxTimeoutSeconds ?? 300) <= UPTO_MAX_TIMEOUT_SECONDS,
   `maxTimeoutSeconds must be at most ${UPTO_MAX_TIMEOUT_SECONDS} on an upto route`
-);
+).refine((route) => {
+  if (route.scheme !== "upto" || !route.acceptedTokens?.length) return true;
+  const usdp = PARALLEL_TOKENS[route.network]?.usdp;
+  if (!usdp) return true;
+  return route.acceptedTokens.every(
+    (token) => token.toLowerCase() === usdp.toLowerCase()
+  );
+}, "acceptedTokens on an upto route may only list the network's USDp");
 var paymentMiddlewareConfigSchema = z.object({
   facilitator: facilitatorConfigSchema,
   routes: z.record(z.string(), routeConfigSchema).refine((r) => Object.keys(r).length > 0, "At least one route is required")
@@ -277,47 +342,41 @@ async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
     clearTimeout(timer);
   }
 }
-var PARALLEL_TOKENS = {
-  ethereum: {
-    usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
-    susdp: "0xd3a452B305C8285c0Dd7b8537665c734d3D279eF",
-    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
-    frxUSD: "0xCAcd6fd266aF91b8AeD52aCCc382b4e165586E29",
-    sfrxUSD: "0xcf62F905562626CfcDD2261162a51fd02Fc9c5b6",
-    USDe: "0x4c9EDD5852cd905f086C759E8383e09bff1E68B3",
-    sUSDe: "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497"
-  },
-  base: {
-    usdp: "0x76A9A0062ec6712b99B4f63bD2b4270185759dd5",
-    susdp: "0x472eD57b376fE400259FB28e5C46eB53f0E3e7E7",
-    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    USDS: "0x820C137fa70C8691f0e44Dc420a5e53c168921Dc",
-    sUSDS: "0x5875eEE11Cf8398102FdAd704C9E96607675467a"
-  },
-  avalanche: {
-    usdp: "0x9eE1963f05553eF838604Dd39403be21ceF26AA4",
-    susdp: "0x9d92c21205383651610f90722131655a5b8ed3e0",
-    usdc: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
-    ygamiUSDC: "0x9fD32FD5e32C6B95483d36C5E724C5C5250Ce010"
-  },
-  hyperevm: {
-    usdp: "0xBE65F0F410A72BeC163dC65d46c83699e957D588",
-    susdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
-    usdc: "0xb88339cb7199b77e23db6e890353e22632ba630f",
-    USDe: "0x5d3a1Ff2b6BAb83b63cd9AD0787074081a52ef34",
-    sUSDe: "0x211Cc4DD073734dA055fbF44a2b4667d5E5fE5d2"
-  }
-};
-function getDefaultAcceptedTokens(network) {
-  const entry = PARALLEL_TOKENS[network];
-  if (!entry) return void 0;
-  return [entry.usdp, entry.usdc, entry.susdp];
-}
-function getTokenDecimals(network, address) {
-  return getTokenDecimals$1(network, address);
-}
 
 // src/middleware.ts
+var PRICE_FORMAT = /^\d+(?:\.\d+)?$/;
+async function requestContext(adapter) {
+  return {
+    method: adapter.getMethod(),
+    path: adapter.getPath(),
+    url: adapter.getUrl(),
+    header: (name) => adapter.getHeader(name),
+    body: adapter.getBody ? await adapter.getBody() : void 0
+  };
+}
+async function resolvePrice(config, ctx) {
+  if (typeof config.price !== "function") return config.price;
+  if (!ctx) throw new X402ConfigError("A price function needs the request");
+  let price;
+  try {
+    price = await config.price(ctx);
+  } catch (cause) {
+    if (isPriceRejection(cause)) throw cause;
+    throw new X402ConfigError(
+      `The price function of route "${config.network}${ctx.path}" threw`,
+      cause
+    );
+  }
+  const valid = typeof price === "bigint" ? price > 0n : typeof price === "string" && PRICE_FORMAT.test(price) && Number(price) > 0;
+  if (!valid) {
+    throw new X402ConfigError(
+      `The price function of route "${config.network}${ctx.path}" returned ${JSON.stringify(
+        typeof price === "bigint" ? price.toString() : price
+      )} \u2014 expected a positive amount like "0.01" or a bigint`
+    );
+  }
+  return price;
+}
 var SETTLE_AMOUNT_HEADER = "payment-settle-amount";
 var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
 function handlerTimeoutFor(config) {
@@ -346,11 +405,67 @@ var INVALID_SETTLE_AMOUNT_RESPONSE = {
   error: "INVALID_SETTLE_AMOUNT",
   message: `The handler set an invalid ${SETTLE_AMOUNT_HEADER} header \u2014 expected a decimal amount in token units, formatted like the route price and within the token's precision, at most the route price.`
 };
+var INVALID_METER_RESPONSE = {
+  error: "INVALID_SETTLE_AMOUNT",
+  message: "The route's meter function failed or returned something that is not an amount; the response was discarded and nothing was charged."
+};
+function invalidSettleAmountResponse(reason) {
+  return reason === "meter" ? INVALID_METER_RESPONSE : INVALID_SETTLE_AMOUNT_RESPONSE;
+}
+var AMOUNT_FORMAT = /^\d+(?:\.\d+)?$/;
+async function resolveCharge(verified, settleHeader, response) {
+  if (verified.meter) {
+    if (!verified.request) {
+      throw new X402ConfigError(
+        "A metered payment carries a meter but no request context"
+      );
+    }
+    let result;
+    try {
+      const body = await raceTimeout(
+        response.body(),
+        verified.handlerTimeoutMs
+      );
+      if (body === HANDLER_TIMEOUT) return { kind: "invalid", reason: "meter" };
+      result = await verified.meter({
+        status: response.status,
+        header: response.header,
+        body,
+        request: verified.request
+      });
+    } catch {
+      return { kind: "invalid", reason: "meter" };
+    }
+    if (result != null) {
+      let amount;
+      if (typeof result === "bigint") {
+        if (result < 0n) return { kind: "invalid", reason: "meter" };
+        amount = result;
+      } else if (typeof result === "string" && AMOUNT_FORMAT.test(result)) {
+        const fraction = result.split(".")[1] ?? "";
+        if (fraction.length > verified.decimals) {
+          return { kind: "invalid", reason: "meter" };
+        }
+        amount = parsePrice(result, verified.decimals);
+      } else {
+        return { kind: "invalid", reason: "meter" };
+      }
+      if (amount === 0n) return { kind: "skip" };
+      if (amount > verified.maxAmount) amount = verified.maxAmount;
+      return { kind: "settle", amount: amount.toString() };
+    }
+  }
+  return resolveSettleAmount(
+    settleHeader,
+    verified.maxAmount,
+    verified.decimals
+  );
+}
 function resolveAcceptedTokens(config) {
   if (config.acceptedTokens?.length) {
     return config.acceptedTokens;
   }
-  const defaults = getDefaultAcceptedTokens(config.network);
+  const defaults = config.scheme === "upto" ? getMeteredAcceptedTokens(config.network) : getDefaultAcceptedTokens(config.network);
   if (defaults) return defaults;
   throw new X402ConfigError(
     `acceptedTokens is required for network "${config.network}" \u2014 no defaults available for this chain`
@@ -365,7 +480,16 @@ function resolveDecimals(config, asset) {
   }
   return decimals;
 }
-function buildPaymentRequired(url, config, resolvedTokens) {
+function priceInUnits(price, decimals, asset) {
+  const units = parsePrice(price, decimals);
+  if (units === 0n) {
+    throw new X402ConfigError(
+      `Price ${typeof price === "bigint" ? price.toString() : `"${price}"`} is below the precision of token ${asset} (${decimals} decimals)`
+    );
+  }
+  return units.toString();
+}
+function buildPaymentRequired(url, config, resolvedTokens, price) {
   const network = toEip155Network(config.network);
   const accepts = resolvedTokens.map((asset) => {
     const decimals = resolveDecimals(config, asset);
@@ -373,7 +497,7 @@ function buildPaymentRequired(url, config, resolvedTokens) {
       scheme: config.scheme ?? "exact",
       network,
       asset,
-      amount: parsePrice(config.price, decimals).toString(),
+      amount: priceInUnits(price, decimals, asset),
       payTo: config.payTo,
       maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS,
       extra: { decimals }
@@ -419,11 +543,11 @@ function resolveDeliveredAsset(header, config, resolvedTokens) {
   const lower = target?.toLowerCase();
   return resolvedTokens.find((token) => token.toLowerCase() === lower) ?? resolvedTokens[0];
 }
-function buildFacilitatorRequirements(config, asset) {
+function buildFacilitatorRequirements(config, asset, price) {
   const decimals = resolveDecimals(config, asset);
   const scheme = config.scheme ?? "exact";
   return {
-    maxAmountRequired: parsePrice(config.price, decimals).toString(),
+    maxAmountRequired: priceInUnits(price, decimals, asset),
     asset,
     payTo: config.payTo,
     network: config.network,
@@ -434,8 +558,13 @@ function buildFacilitatorRequirements(config, asset) {
     }
   };
 }
-function paymentRequiredResponse(url, config, resolvedTokens, error) {
-  const paymentRequired = buildPaymentRequired(url, config, resolvedTokens);
+function paymentRequiredResponse(url, config, resolvedTokens, price, error) {
+  const paymentRequired = buildPaymentRequired(
+    url,
+    config,
+    resolvedTokens,
+    price
+  );
   if (error) paymentRequired.error = error;
   return {
     status: 402,
@@ -463,6 +592,22 @@ function createPaymentGate(config) {
     const routeConfig = matchRoute(adapter.getPath(), config.routes);
     if (!routeConfig) return { type: "pass" };
     const resolvedTokens = resolveAcceptedTokens(routeConfig);
+    let request = typeof routeConfig.price === "function" ? await requestContext(adapter) : void 0;
+    let price;
+    try {
+      price = await resolvePrice(routeConfig, request);
+    } catch (err) {
+      if (!isPriceRejection(err)) throw err;
+      const status = Number.isInteger(err.status) && err.status >= 400 && err.status <= 599 ? err.status : 400;
+      return {
+        type: "error",
+        result: {
+          status,
+          headers: { "Content-Type": "application/json" },
+          body: { error: err.code, message: err.message }
+        }
+      };
+    }
     const paymentHeader = adapter.getHeader("payment-signature") ?? adapter.getHeader("x-payment");
     if (!paymentHeader) {
       return {
@@ -470,7 +615,8 @@ function createPaymentGate(config) {
         result: paymentRequiredResponse(
           adapter.getUrl(),
           routeConfig,
-          resolvedTokens
+          resolvedTokens,
+          price
         )
       };
     }
@@ -479,7 +625,11 @@ function createPaymentGate(config) {
       routeConfig,
       resolvedTokens
     );
-    const requirements = buildFacilitatorRequirements(routeConfig, asset);
+    const requirements = buildFacilitatorRequirements(
+      routeConfig,
+      asset,
+      price
+    );
     try {
       await client.verify(paymentHeader, requirements);
     } catch (e) {
@@ -490,10 +640,12 @@ function createPaymentGate(config) {
           adapter.getUrl(),
           routeConfig,
           resolvedTokens,
+          price,
           code
         )
       };
     }
+    if (routeConfig.meter && !request) request = await requestContext(adapter);
     return {
       type: "verified",
       scheme: routeConfig.scheme ?? "exact",
@@ -501,7 +653,8 @@ function createPaymentGate(config) {
       decimals: resolveDecimals(routeConfig, asset),
       handlerTimeoutMs: handlerTimeoutFor(routeConfig),
       // Exact routes keep the historical two-argument client call.
-      settle: (options) => options ? client.settle(paymentHeader, requirements, options) : client.settle(paymentHeader, requirements)
+      settle: (options) => options ? client.settle(paymentHeader, requirements, options) : client.settle(paymentHeader, requirements),
+      ...routeConfig.meter && { meter: routeConfig.meter, request }
     };
   };
 }
@@ -527,17 +680,17 @@ function createPaymentMiddleware(config) {
     if (handlerResult.status >= 200 && handlerResult.status < 300) {
       let settleOptions;
       if (gateResult.scheme === "upto") {
-        const resolved = resolveSettleAmount(
-          raw,
-          gateResult.maxAmount,
-          gateResult.decimals
-        );
+        const resolved = await resolveCharge(gateResult, raw, {
+          status: handlerResult.status,
+          header: (name) => handlerResult.getResponseHeader?.(name),
+          body: async () => handlerResult.getResponseBody?.()
+        });
         if (resolved.kind === "invalid") {
           handlerResult.discardResponse();
           return {
             status: 402,
             headers: { "Content-Type": "application/json" },
-            body: INVALID_SETTLE_AMOUNT_RESPONSE
+            body: invalidSettleAmountResponse(resolved.reason)
           };
         }
         if (resolved.kind === "skip") {
@@ -579,4 +732,4 @@ function createPaymentMiddleware(config) {
   };
 }
 
-export { FacilitatorClient, HANDLER_TIMEOUT, INVALID_SETTLE_AMOUNT_RESPONSE, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, raceTimeout, resolveSettleAmount, toEip155Network, validateAddress };
+export { FacilitatorClient, HANDLER_TIMEOUT, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, invalidSettleAmountResponse, isJsonContentType, jsonFromResponse, matchRoute, parseJsonBody, parsePrice, raceTimeout, resolveCharge, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/chunk-AFRDHGDT.js

@@ -0,0 +1,36 @@
+// src/errors.ts
+var X402_ERROR_CODES = {
+  FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
+  FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
+  INVALID_PAYMENT: "INVALID_PAYMENT"
+};
+var X402ConfigError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "X402ConfigError";
+    this.cause = cause;
+  }
+};
+var X402RuntimeError = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "X402RuntimeError";
+  }
+  code;
+};
+var X402PriceRejectedError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "X402PriceRejectedError";
+  }
+  code;
+  status;
+};
+function isPriceRejection(error) {
+  return error instanceof Error && error.name === "X402PriceRejectedError" && typeof error.code === "string";
+}
+
+export { X402ConfigError, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, isPriceRejection };

package/dist/chunk-JPMK5YBU.cjs

@@ -0,0 +1,42 @@
+'use strict';
+
+// src/errors.ts
+var X402_ERROR_CODES = {
+  FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
+  FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
+  INVALID_PAYMENT: "INVALID_PAYMENT"
+};
+var X402ConfigError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "X402ConfigError";
+    this.cause = cause;
+  }
+};
+var X402RuntimeError = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "X402RuntimeError";
+  }
+  code;
+};
+var X402PriceRejectedError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "X402PriceRejectedError";
+  }
+  code;
+  status;
+};
+function isPriceRejection(error) {
+  return error instanceof Error && error.name === "X402PriceRejectedError" && typeof error.code === "string";
+}
+
+exports.X402ConfigError = X402ConfigError;
+exports.X402PriceRejectedError = X402PriceRejectedError;
+exports.X402RuntimeError = X402RuntimeError;
+exports.X402_ERROR_CODES = X402_ERROR_CODES;
+exports.isPriceRejection = isPriceRejection;