@armory-sh/base 0.2.19 → 0.2.21

package/dist/index.d.ts

@@ -14,7 +14,10 @@ export { ERC20_ABI } from "./abi/erc20";
 export type { TypedDataDomain, EIP712Domain, TransferWithAuthorization, TypedDataField, EIP712Types, } from "./eip712";
 export { EIP712_TYPES, USDC_DOMAIN, createEIP712Domain, createTransferWithAuthorization, validateTransferWithAuthorization, } from "./eip712";
 export { resolveNetwork, resolveToken, resolveFacilitator, checkFacilitatorSupport, validatePaymentConfig, validateAcceptConfig, getAvailableNetworks, getAvailableTokens, isValidationError, isResolvedNetwork, isResolvedToken, createError, normalizeNetworkName, } from "./validation";
+export type { RoutePattern, RouteMatcher, RouteConfig, ParsedPattern, RouteInputConfig, RouteValidationError, } from "./utils/routes";
+export { parseRoutePattern, matchRoute, findMatchingRoute, validateRouteConfig, } from "./utils/routes";
 export { encodePaymentV2, decodePaymentV2, encodeSettlementV2, decodeSettlementV2, isPaymentV2, isSettlementV2, } from "./encoding";
 export type { NetworkId, TokenId, FacilitatorConfig, FacilitatorVerifyResult, FacilitatorSettleResult, SettlementMode, PayToAddress, AcceptPaymentOptions, PricingConfig, PaymentResult, PaymentError, PaymentErrorCode, ArmoryPaymentResult, ResolvedNetwork, ResolvedToken, ResolvedFacilitator, ResolvedPaymentConfig, ValidationError, } from "./types/api";
+export type { PaymentRequiredContext, PaymentPayloadContext, HookResult, OnPaymentRequiredHook, BeforePaymentHook, ExtensionHook, HookConfig, HookRegistry, } from "./types/hooks";
 export { createX402V2Payload, createLegacyV2Payload, INVALID_PAYLOADS, TEST_PAYER_ADDRESS, TEST_PAY_TO_ADDRESS, TEST_CONTRACT_ADDRESS, TEST_PRIVATE_KEY, } from "./fixtures/payloads";
 export { DEFAULT_PAYMENT_CONFIG, type TestPaymentConfig } from "./fixtures/config";

package/dist/index.js

@@ -1109,6 +1109,168 @@ var isResolvedToken = (value) => {
   return typeof value === "object" && value !== null && "config" in value && "caipAsset" in value;
 };
 
+// src/utils/routes.ts
+var PRIORITY_EXACT = 3;
+var PRIORITY_PARAMETRIZED = 2;
+var PRIORITY_WILDCARD = 1;
+function parseRoutePattern(pattern) {
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+  const segments = normalizedPattern.split("/").filter(Boolean);
+  let isWildcard = false;
+  let isParametrized = false;
+  const paramNames = [];
+  const seenParamNames = /* @__PURE__ */ new Set();
+  const recordParamName = (name) => {
+    if (!name) {
+      return;
+    }
+    if (seenParamNames.has(name)) {
+      return;
+    }
+    seenParamNames.add(name);
+    paramNames.push(name);
+  };
+  for (const segment of segments) {
+    if (segment === "*") {
+      isWildcard = true;
+      continue;
+    }
+    const hasWildcardToken = segment.includes("*");
+    if (segment.startsWith(":")) {
+      isParametrized = true;
+      const paramName = segment.replace(/\*+$/, "").slice(1);
+      recordParamName(paramName);
+      if (hasWildcardToken) {
+        isWildcard = true;
+      }
+      continue;
+    }
+    if (hasWildcardToken) {
+      const parts = segment.split("*");
+      for (const part of parts) {
+        if (part.startsWith(":")) {
+          isParametrized = true;
+          recordParamName(part.slice(1));
+        }
+      }
+      isWildcard = true;
+    }
+  }
+  let priority = PRIORITY_WILDCARD;
+  if (!isWildcard && !isParametrized) {
+    priority = PRIORITY_EXACT;
+  } else if (isParametrized && !isWildcard) {
+    priority = PRIORITY_PARAMETRIZED;
+  } else if (isParametrized && isWildcard) {
+    priority = PRIORITY_PARAMETRIZED;
+  }
+  return { segments, isWildcard, isParametrized, paramNames, priority };
+}
+function matchSegment(patternSegment, pathSegment) {
+  if (patternSegment === "*") {
+    return true;
+  }
+  if (patternSegment.startsWith(":")) {
+    return true;
+  }
+  if (patternSegment.includes("*")) {
+    const regex = new RegExp(
+      "^" + patternSegment.replace(/\*/g, ".*").replace(/:/g, "") + "$"
+    );
+    return regex.test(pathSegment);
+  }
+  return patternSegment === pathSegment;
+}
+function matchWildcardPattern(patternSegments, pathSegments) {
+  const requiredSegments = patternSegments.filter((s) => s !== "*");
+  if (requiredSegments.length > pathSegments.length) {
+    return false;
+  }
+  for (let i = 0; i < requiredSegments.length; i++) {
+    const patternIndex = patternSegments.indexOf(requiredSegments[i]);
+    if (pathSegments[patternIndex] !== requiredSegments[i].replace(/^\:/, "")) {
+      if (!requiredSegments[i].startsWith(":") && requiredSegments[i] !== "*") {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function matchRoute(pattern, path) {
+  const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  if (normalizedPattern === normalizedPath) {
+    return true;
+  }
+  const parsed = parseRoutePattern(normalizedPattern);
+  const patternSegments = parsed.segments;
+  const pathSegments = normalizedPath.split("/").filter(Boolean);
+  if (!parsed.isWildcard && patternSegments.length !== pathSegments.length) {
+    return false;
+  }
+  if (parsed.isWildcard && patternSegments.length > pathSegments.length + 1) {
+    return false;
+  }
+  if (parsed.isWildcard) {
+    return matchWildcardPattern(patternSegments, pathSegments);
+  }
+  for (let i = 0; i < patternSegments.length; i++) {
+    if (!matchSegment(patternSegments[i], pathSegments[i])) {
+      return false;
+    }
+  }
+  return true;
+}
+function findMatchingRoute(routes, path) {
+  const matchingRoutes = [];
+  for (const route of routes) {
+    if (matchRoute(route.pattern, path)) {
+      const parsed = parseRoutePattern(route.pattern);
+      matchingRoutes.push({ route, parsed });
+    }
+  }
+  if (matchingRoutes.length === 0) {
+    return null;
+  }
+  matchingRoutes.sort((a, b) => {
+    if (b.parsed.priority !== a.parsed.priority) {
+      return b.parsed.priority - a.parsed.priority;
+    }
+    if (b.parsed.segments.length !== a.parsed.segments.length) {
+      return b.parsed.segments.length - a.parsed.segments.length;
+    }
+    return b.route.pattern.length - a.route.pattern.length;
+  });
+  return matchingRoutes[0].route;
+}
+function containsWildcard(pattern) {
+  return pattern.includes("*");
+}
+function validateRouteConfig(config) {
+  const { route, routes } = config;
+  if (!route && !routes) {
+    return null;
+  }
+  if (route && routes) {
+    return {
+      code: "INVALID_ROUTE_CONFIG",
+      message: "Cannot specify both 'route' and 'routes'. Use 'route' for a single exact path or 'routes' for multiple paths.",
+      path: "route",
+      value: { route, routes }
+    };
+  }
+  if (route && containsWildcard(route)) {
+    return {
+      code: "INVALID_ROUTE_PATTERN",
+      message: `Wildcard routes must use the routes array, not 'route'. Use 'routes: ["/api/*"]' instead of 'route: "/api/*"'.`,
+      path: "route",
+      value: route,
+      validOptions: ['routes: ["/api/*"]', 'routes: ["/api/users", "/api/posts"]']
+    };
+  }
+  return null;
+}
+
 // src/encoding.ts
 function safeBase64Decode2(str) {
   const padding = 4 - str.length % 4;
@@ -1275,6 +1437,7 @@ export {
   encodeSettlementV2,
   encodeX402Response,
   extractPaymentFromHeaders,
+  findMatchingRoute,
   fromAtomicUnits,
   getAllCustomTokens,
   getAllTokens,
@@ -1318,9 +1481,11 @@ export {
   isX402V2Requirements,
   isX402V2Settlement,
   legacyToPaymentPayload,
+  matchRoute,
   networkToCaip2,
   normalizeAddress,
   normalizeNetworkName,
+  parseRoutePattern,
   parseSignature as parseSignatureV2,
   registerToken,
   resolveFacilitator,
@@ -1332,5 +1497,6 @@ export {
   unregisterToken,
   validateAcceptConfig,
   validatePaymentConfig,
+  validateRouteConfig,
   validateTransferWithAuthorization
 };

package/dist/types/api.d.ts

@@ -194,3 +194,59 @@ export interface ValidationError {
     /** Valid options */
     validOptions?: string[];
 }
+/**
+ * Route pattern type for matching paths
+ */
+export type RoutePattern = string;
+/**
+ * Route matcher function type
+ */
+export type RouteMatcher = (path: string) => boolean;
+/**
+ * Route configuration with associated config data
+ */
+export interface RouteConfig<T = unknown> {
+    /** Route pattern (e.g., "/api/users", "/api/*", "/api/users/:id") */
+    pattern: RoutePattern;
+    /** Configuration associated with this route */
+    config: T;
+}
+/**
+ * Parsed route pattern information
+ */
+export interface ParsedPattern {
+    /** Route segments split by "/" */
+    segments: string[];
+    /** Whether this pattern contains a wildcard */
+    isWildcard: boolean;
+    /** Whether this pattern contains parameters (e.g., :id) */
+    isParametrized: boolean;
+    /** Parameter names extracted from the pattern */
+    paramNames: string[];
+    /** Match priority (higher = more specific) */
+    priority: number;
+}
+/**
+ * Route input configuration for middleware
+ */
+export interface RouteInputConfig {
+    /** Single exact route (no wildcards allowed) */
+    route?: string;
+    /** Multiple routes (allows wildcards) */
+    routes?: string[];
+}
+/**
+ * Route-specific validation error details
+ */
+export interface RouteValidationError {
+    /** Error code (custom string, not PaymentErrorCode) */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Path to the invalid value */
+    path?: string;
+    /** Invalid value */
+    value?: unknown;
+    /** Valid options */
+    validOptions?: string[];
+}

package/dist/types/hooks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Extension Hook System Types
+ *
+ * Provides a generic hook system for x402 clients to register
+ * extension handlers that can modify payment payloads or respond
+ * to payment requirements.
+ *
+ * Hooks allow extensibility without custom code in each client package.
+ */
+import type { PaymentPayloadV2, PaymentRequirementsV2, Extensions, Address } from "./v2";
+export interface PaymentRequiredContext {
+    url: RequestInfo | URL;
+    requestInit: RequestInit | undefined;
+    requirements: PaymentRequirementsV2;
+    serverExtensions: Extensions | undefined;
+    fromAddress: Address;
+    nonce: `0x${string}`;
+    validBefore: number;
+}
+export interface PaymentPayloadContext<TWallet = unknown> {
+    payload: PaymentPayloadV2;
+    requirements: PaymentRequirementsV2;
+    wallet: TWallet;
+    paymentContext: PaymentRequiredContext;
+}
+export type HookResult = void | Promise<void>;
+export type OnPaymentRequiredHook<TWallet = unknown> = (context: PaymentRequiredContext) => HookResult;
+export type BeforePaymentHook<TWallet = unknown> = (context: PaymentPayloadContext<TWallet>) => HookResult;
+export type ExtensionHook<TWallet = unknown> = OnPaymentRequiredHook<TWallet> | BeforePaymentHook<TWallet>;
+export interface HookConfig<TWallet = unknown> {
+    hook: ExtensionHook<TWallet>;
+    priority?: number;
+    name?: string;
+}
+export type HookRegistry<TWallet = unknown> = Record<string, HookConfig<TWallet>>;

package/dist/utils/routes.d.ts

@@ -0,0 +1,28 @@
+export type RoutePattern = string;
+export type RouteMatcher = (path: string) => boolean;
+export interface RouteConfig<T = unknown> {
+    pattern: RoutePattern;
+    config: T;
+}
+export interface ParsedPattern {
+    segments: string[];
+    isWildcard: boolean;
+    isParametrized: boolean;
+    paramNames: string[];
+    priority: number;
+}
+export declare function parseRoutePattern(pattern: string): ParsedPattern;
+export declare function matchRoute(pattern: string, path: string): boolean;
+export declare function findMatchingRoute<T>(routes: RouteConfig<T>[], path: string): RouteConfig<T> | null;
+export interface RouteInputConfig {
+    route?: string;
+    routes?: string[];
+}
+export interface RouteValidationError {
+    code: string;
+    message: string;
+    path?: string;
+    value?: unknown;
+    validOptions?: string[];
+}
+export declare function validateRouteConfig(config: RouteInputConfig): RouteValidationError | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/base",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "type": "module",