@armory-sh/base 0.2.27-alpha.23.76 → 0.2.27-alpha.23.78

package/src/types/api.ts

@@ -0,0 +1,304 @@
+/**
+ * Simple, developer-friendly API types for Armory
+ * Focuses on DX/UX - "everything just magically works"
+ */
+
+import type { CustomToken, NetworkConfig } from "./networks";
+import type { Address, CAIPAssetId } from "./v2";
+
+// ═══════════════════════════════════════════════════════════════
+// Simple API Types
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Network identifier - flexible input that resolves to a chain
+ * - Network name: "base", "ethereum", "skale-base"
+ * - CAIP-2: "eip155:8453"
+ * - Chain ID: 8453
+ */
+export type NetworkId = string | number;
+
+/**
+ * Token identifier - flexible input that resolves to a token
+ * - Symbol: "usdc", "eurc", "usdt" (case-insensitive)
+ * - CAIP Asset ID: "eip155:8453/erc20:0x..."
+ * - Full token config object
+ */
+export type TokenId = string | CustomToken;
+
+/**
+ * Facilitator configuration
+ */
+export interface FacilitatorConfig {
+  /** Facilitator URL for verification/settlement */
+  url: string;
+  /** Optional authentication headers */
+  headers?: () => Record<string, string>;
+  /** Networks this facilitator supports (auto-detected if not provided) */
+  networks?: NetworkId[];
+  /** Tokens this facilitator supports (optional) */
+  tokens?: TokenId[];
+}
+
+/**
+ * Result from facilitator verification
+ */
+export interface FacilitatorVerifyResult {
+  success: boolean;
+  payerAddress?: string;
+  balance?: string;
+  requiredAmount?: string;
+  error?: string;
+}
+
+/**
+ * Result from facilitator settlement
+ */
+export interface FacilitatorSettleResult {
+  success: boolean;
+  txHash?: string;
+  error?: string;
+}
+
+/**
+ * Settlement mode - verify only, settle only, or both
+ */
+export type SettlementMode = "verify" | "settle" | "async";
+
+/**
+ * CAIP-2 chain ID type (e.g., eip155:8453)
+ */
+export type CAIP2ChainId = `eip155:${string}`;
+
+/**
+ * CAIP-2 asset ID type (e.g., eip155:8453/erc20:0xa0b8691...)
+ */
+export type CAIP2AssetId = `eip155:${string}/erc20:${string}`;
+
+/**
+ * Payment destination - address, CAIP-2 chain ID, or CAIP asset ID
+ */
+export type PayToAddress = `0x${string}` | CAIP2ChainId | CAIP2AssetId;
+
+/**
+ * Pricing configuration for a specific network/token/facilitator combination
+ */
+export interface PricingConfig {
+  /** Network for this pricing */
+  network?: NetworkId;
+  /** Token for this pricing */
+  token?: TokenId;
+  /** Facilitator URL for this pricing (optional - applies to all facilitators if not specified) */
+  facilitator?: string;
+  /** Amount to charge */
+  amount: string;
+}
+
+/**
+ * Payment accept options for merchants (v2 multi-support)
+ */
+export interface AcceptPaymentOptions {
+  /** Networks to accept payments on */
+  networks?: NetworkId[];
+  /** Tokens to accept (defaults to ["usdc"]) */
+  tokens?: TokenId[];
+  /** Facilitator(s) for payment verification/settlement */
+  facilitators?: FacilitatorConfig | FacilitatorConfig[];
+  /** Protocol version (V2 only) */
+  version?: 2;
+  /** Pricing configurations - if not provided, uses amount from top-level config */
+  pricing?: PricingConfig[];
+}
+
+/**
+ * Result of a payment attempt
+ */
+export interface PaymentResult<T = unknown> {
+  /** Payment successful */
+  success: true;
+  /** Response data */
+  data: T;
+  /** Transaction hash (if settled) */
+  txHash?: string;
+}
+
+/**
+ * Payment error result
+ */
+export interface PaymentError {
+  /** Payment failed */
+  success: false;
+  /** Error code */
+  code: PaymentErrorCode;
+  /** Human-readable error message */
+  message: string;
+  /** Underlying error details */
+  details?: unknown;
+}
+
+/**
+ * Payment error codes
+ */
+export type PaymentErrorCode =
+  | "UNKNOWN_NETWORK"
+  | "UNKNOWN_TOKEN"
+  | "TOKEN_NOT_ON_NETWORK"
+  | "FACILITATOR_UNSUPPORTED"
+  | "FACILITATOR_NO_NETWORK_SUPPORT"
+  | "FACILITATOR_NO_TOKEN_SUPPORT"
+  | "INVALID_CAIP_FORMAT"
+  | "CHAIN_MISMATCH"
+  | "PAYMENT_REQUIRED"
+  | "PAYMENT_DECLINED"
+  | "SIGNING_FAILED"
+  | "NETWORK_ERROR"
+  | "VALIDATION_FAILED";
+
+/**
+ * Combined payment result type
+ */
+export type ArmoryPaymentResult<T = unknown> = PaymentResult<T> | PaymentError;
+
+// ═══════════════════════════════════════════════════════════════
+// Resolved Configuration (internal use)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Fully resolved network configuration
+ */
+export interface ResolvedNetwork {
+  /** Original input */
+  input: NetworkId;
+  /** Network config */
+  config: NetworkConfig;
+  /** CAIP-2 ID */
+  caip2: `eip155:${string}`;
+}
+
+/**
+ * Fully resolved token configuration
+ */
+export interface ResolvedToken {
+  /** Original input */
+  input: TokenId;
+  /** Token config */
+  config: CustomToken;
+  /** CAIP Asset ID */
+  caipAsset: CAIPAssetId;
+  /** Network this token is on */
+  network: ResolvedNetwork;
+}
+
+/**
+ * Fully resolved facilitator configuration
+ */
+export interface ResolvedFacilitator {
+  /** Original input */
+  input: FacilitatorConfig;
+  /** URL */
+  url: string;
+  /** Supported networks (resolved) */
+  networks: ResolvedNetwork[];
+  /** Supported tokens (resolved) */
+  tokens: ResolvedToken[];
+}
+
+/**
+ * Fully resolved payment configuration
+ */
+export interface ResolvedPaymentConfig {
+  /** Network to use */
+  network: ResolvedNetwork;
+  /** Token to use */
+  token: ResolvedToken;
+  /** Facilitator(s) to use */
+  facilitators: ResolvedFacilitator[];
+  /** Protocol version (V2 only) */
+  version: 2;
+  /** Recipient address */
+  payTo: Address;
+  /** Amount to charge */
+  amount: string;
+}
+
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+  /** Error code */
+  code: PaymentErrorCode;
+  /** Error message */
+  message: string;
+  /** Path to the invalid value */
+  path?: string;
+  /** Invalid value */
+  value?: unknown;
+  /** Valid options */
+  validOptions?: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Route Configuration Types
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 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/src/types/hooks.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 {
+  Address,
+  Extensions,
+  PaymentPayloadV2,
+  PaymentRequirementsV2,
+} from "./v2";
+
+export interface PaymentRequiredContext {
+  url: RequestInfo | URL;
+  requestInit: RequestInit | undefined;
+  accepts: PaymentRequirementsV2[];
+  requirements: PaymentRequirementsV2;
+  selectedRequirement?: 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>
+>;
+
+export interface ClientHookErrorContext {
+  error: unknown;
+  phase:
+    | "onPaymentRequired"
+    | "selectRequirement"
+    | "beforeSignPayment"
+    | "afterPaymentResponse";
+}
+
+export interface ClientHook<TWallet = unknown> {
+  name?: string;
+  onPaymentRequired?: (context: PaymentRequiredContext) => HookResult;
+  selectRequirement?: (
+    context: PaymentRequiredContext,
+  ) =>
+    | PaymentRequirementsV2
+    | undefined
+    | Promise<PaymentRequirementsV2 | undefined>;
+  beforeSignPayment?: (context: PaymentPayloadContext<TWallet>) => HookResult;
+  afterPaymentResponse?: (
+    context: PaymentPayloadContext<TWallet> & { response: Response },
+  ) => HookResult;
+  onError?: (context: ClientHookErrorContext) => HookResult;
+}

package/src/types/networks.ts

@@ -0,0 +1,175 @@
+const isEvmAddress = (value: string): boolean =>
+  /^0x[a-fA-F0-9]{40}$/.test(value);
+
+export interface NetworkConfig {
+  name: string;
+  chainId: number;
+  usdcAddress: `0x${string}`;
+  rpcUrl: string;
+  caip2Id: string;
+  caipAssetId: string;
+}
+
+export interface CustomToken {
+  symbol: string;
+  name: string;
+  version: string;
+  contractAddress: `0x${string}`;
+  chainId: number;
+  decimals?: number;
+}
+
+const tokenRegistry = new Map<string, CustomToken>();
+const tokenKey = (chainId: number, contractAddress: string): string =>
+  `${chainId}:${contractAddress.toLowerCase()}`;
+
+export const NETWORKS: Record<string, NetworkConfig> = {
+  ethereum: {
+    name: "Ethereum Mainnet",
+    chainId: 1,
+    usdcAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" as const,
+    rpcUrl: "https://eth.llamarpc.com",
+    caip2Id: "eip155:1",
+    caipAssetId: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  },
+  base: {
+    name: "Base Mainnet",
+    chainId: 8453,
+    usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const,
+    rpcUrl: "https://mainnet.base.org",
+    caip2Id: "eip155:8453",
+    caipAssetId: "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+  "base-sepolia": {
+    name: "Base Sepolia",
+    chainId: 84532,
+    usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as const,
+    rpcUrl: "https://sepolia.base.org",
+    caip2Id: "eip155:84532",
+    caipAssetId:
+      "eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+  },
+  "skale-base": {
+    name: "SKALE Base",
+    chainId: 1187947933,
+    usdcAddress: "0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20" as const,
+    rpcUrl: "https://skale-base.skalenodes.com/v1/base",
+    caip2Id: "eip155:1187947933",
+    caipAssetId:
+      "eip155:1187947933/erc20:0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20",
+  },
+  "skale-base-sepolia": {
+    name: "SKALE Base Sepolia",
+    chainId: 324705682,
+    usdcAddress: "0x2e08028E3C4c2356572E096d8EF835cD5C6030bD" as const,
+    rpcUrl:
+      "https://base-sepolia-testnet.skalenodes.com/v1/jubilant-horrible-ancha",
+    caip2Id: "eip155:324705682",
+    caipAssetId:
+      "eip155:324705682/erc20:0x2e08028E3C4c2356572E096d8EF835cD5C6030bD",
+  },
+  "ethereum-sepolia": {
+    name: "Ethereum Sepolia",
+    chainId: 11155111,
+    usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238" as const,
+    rpcUrl: "https://rpc.sepolia.org",
+    caip2Id: "eip155:11155111",
+    caipAssetId:
+      "eip155:11155111/erc20:0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+  },
+};
+
+export const getNetworkConfig = (name: string): NetworkConfig | undefined =>
+  NETWORKS[name];
+export const getNetworkByChainId = (
+  chainId: number,
+): NetworkConfig | undefined =>
+  Object.values(NETWORKS).find((c) => c.chainId === chainId);
+export const getMainnets = (): NetworkConfig[] =>
+  Object.values(NETWORKS).filter(
+    (c) => !c.name.toLowerCase().includes("sepolia"),
+  );
+export const getTestnets = (): NetworkConfig[] =>
+  Object.values(NETWORKS).filter((c) =>
+    c.name.toLowerCase().includes("sepolia"),
+  );
+
+export const registerToken = (token: unknown): CustomToken => {
+  if (typeof token !== "object" || token === null) {
+    throw new Error("Invalid token: must be an object");
+  }
+
+  const t = token as Record<string, unknown>;
+
+  if (typeof t.symbol !== "string") {
+    throw new Error("Invalid token: symbol must be a string");
+  }
+
+  if (typeof t.name !== "string") {
+    throw new Error("Invalid token: name must be a string");
+  }
+
+  if (typeof t.version !== "string") {
+    throw new Error("Invalid token: version must be a string");
+  }
+
+  if (
+    typeof t.contractAddress !== "string" ||
+    !isEvmAddress(t.contractAddress)
+  ) {
+    throw new Error(
+      "Invalid token: contractAddress must be a valid EVM address",
+    );
+  }
+
+  if (
+    typeof t.chainId !== "number" ||
+    !Number.isInteger(t.chainId) ||
+    t.chainId <= 0
+  ) {
+    throw new Error("Invalid token: chainId must be a positive integer");
+  }
+
+  if (
+    t.decimals !== undefined &&
+    (typeof t.decimals !== "number" ||
+      !Number.isInteger(t.decimals) ||
+      t.decimals < 0)
+  ) {
+    throw new Error("Invalid token: decimals must be a non-negative integer");
+  }
+
+  const validated: CustomToken = {
+    symbol: t.symbol,
+    name: t.name,
+    version: t.version,
+    contractAddress: t.contractAddress as `0x${string}`,
+    chainId: t.chainId,
+    decimals: t.decimals,
+  };
+
+  tokenRegistry.set(
+    tokenKey(validated.chainId, validated.contractAddress),
+    validated,
+  );
+  return validated;
+};
+
+export const getCustomToken = (
+  chainId: number,
+  contractAddress: string,
+): CustomToken | undefined =>
+  tokenRegistry.get(tokenKey(chainId, contractAddress));
+
+export const getAllCustomTokens = (): CustomToken[] =>
+  Array.from(tokenRegistry.values());
+
+export const unregisterToken = (
+  chainId: number,
+  contractAddress: string,
+): boolean => tokenRegistry.delete(tokenKey(chainId, contractAddress));
+
+export const isCustomToken = (
+  chainId: number,
+  contractAddress: string,
+): boolean => tokenRegistry.has(tokenKey(chainId, contractAddress));