@armory-sh/base 0.2.28 → 0.2.30

package/README.md

@@ -14,56 +14,343 @@ bun add @armory-sh/base
 
 Armory enables HTTP API payments via EIP-3009 `transferWithAuthorization`. Let your users pay with USDC directly from their wallet—no credit cards, no middlemen, no gas for payers.
 
-## Key Exports
+## API Reference
+
+### Protocol Types
 
 ```typescript
-import {
-  // Types
-  type PaymentPayload,
-  type PaymentPayloadV2,
-  type PaymentRequirementsV2,
-  type SettlementResponseV2,
-  type CustomToken,
-  type NetworkConfig,
+import type {
+  // V2 Protocol (x402 v2 / CAIP)
+  PaymentPayloadV2,
+  PaymentRequirementsV2,
+  PaymentRequiredV2,
+  SettlementResponseV2,
+  PayToV2,
+  EIP3009Authorization,
+  Extensions,
+  ResourceInfo,
+  Signature,
+  Address,
+  CAIPAssetId,
+
+  // Unified Types
+  PaymentPayload,
+  PaymentRequirements,
+  SettlementResponse,
+} from '@armory-sh/base';
+```
 
-  // Encoding/Decoding
+### Encoding / Decoding
+
+```typescript
+import {
+  // V2 Encoding
   encodePaymentV2,
   decodePaymentV2,
   encodeSettlementV2,
   decodeSettlementV2,
+
+  // x402 Cross-Version Encoding
+  encodePayment,
+  decodePayment,
+  encodeSettlementResponse,
+  decodeSettlementResponse,
+  encodeX402Response,
+  decodeX402Response,
+
+  // Base64 Utilities
   safeBase64Encode,
   safeBase64Decode,
+  toBase64Url,
+  normalizeBase64Url,
+  encodeUtf8ToBase64,
+  decodeBase64ToUtf8,
+
+  // Header Creation
+  createPaymentRequiredHeaders,
+  createSettlementHeaders,
+  extractPaymentFromHeaders,
+
+  // Type Guards
+  isPaymentV2,
+  isSettlementV2,
+  isX402V2Payload,
+  isX402V2PaymentRequired,
+  isX402V2Settlement,
+  isPaymentPayload,
+  detectPaymentVersion,
+} from '@armory-sh/base';
+```
+
+### EIP-712 (EIP-3009 Signing)
 
-  // EIP-712
+```typescript
+import {
+  // Domain & Typed Data
   createEIP712Domain,
+  EIP712_TYPES,
+  USDC_DOMAIN,
+
+  // Transfer With Authorization
   createTransferWithAuthorization,
   validateTransferWithAuthorization,
-  EIP712_TYPES,
 
-  // Networks
+  // Types
+  type EIP712Domain,
+  type TransferWithAuthorization,
+  type TypedDataDomain,
+} from '@armory-sh/base';
+```
+
+### Networks
+
+```typescript
+import {
+  // Network Registry
   NETWORKS,
   getNetworkConfig,
   getNetworkByChainId,
   getMainnets,
   getTestnets,
 
-  // Token Registry
+  // Network Resolution
+  resolveNetwork,
+  normalizeNetworkName,
+  getAvailableNetworks,
+
+  // CAIP-2 Conversion
+  networkToCaip2,
+  caip2ToNetwork,
+
+  // Types
+  type NetworkConfig,
+  type ResolvedNetwork,
+} from '@armory-sh/base';
+```
+
+**Supported Networks**
+
+| Key | Chain ID | Name |
+|-----|----------|------|
+| `ethereum` | 1 | Ethereum Mainnet |
+| `base` | 8453 | Base Mainnet |
+| `base-sepolia` | 84532 | Base Sepolia |
+| `skale-base` | 1187947933 | SKALE Base |
+| `skale-base-sepolia` | 324705682 | SKALE Base Sepolia |
+| `ethereum-sepolia` | 11155111 | Ethereum Sepolia |
+
+### Tokens
+
+```typescript
+import {
+  // Pre-configured Tokens
   TOKENS,
+  USDC_BASE,
+  USDC_BASE_SEPOLIA,
+  EURC_BASE,
+  getUSDCTokens,
+  getEURCTokens,
+  getAllTokens,
+  getTokensByChain,
+  getTokensBySymbol,
+
+  // Custom Token Registry
   registerToken,
   getCustomToken,
   getAllCustomTokens,
   unregisterToken,
   isCustomToken,
 
-  // Utilities
+  // Token Resolution
+  resolveToken,
+  getAvailableTokens,
+  addressToAssetId,
+  assetIdToAddress,
+
+  // Types
+  type CustomToken,
+  type ResolvedToken,
+} from '@armory-sh/base';
+```
+
+**Supported Tokens**
+
+USDC, EURC, USDT, WBTC, WETH, SKL across supported networks.
+
+### Protocol Utilities
+
+```typescript
+import {
+  // Nonce & Time
+  generateNonce,
   createNonce,
-  toAtomicUnits,
-  fromAtomicUnits,
+  getCurrentTimestamp,
+  calculateValidBefore,
+
+  // Parsing
+  parseJsonOrBase64,
+
+  // Headers
+  getPaymentHeaderName,
+  PAYMENT_REQUIRED_HEADER,
+  PAYMENT_SIGNATURE_HEADER,
+  PAYMENT_RESPONSE_HEADER,
+
+  // Version Detection
+  detectX402Version,
+  X402_VERSION,
+} from '@armory-sh/base';
+```
+
+### Payment Requirements (Middleware)
+
+```typescript
+import {
+  // Requirement Creation
+  createPaymentRequirements,
+
+  // Requirement Lookup
+  findRequirementByNetwork,
+  findRequirementByAccepted,
+
+  // Types
+  type PaymentConfig,
+  type ResolvedRequirementsConfig,
+} from '@armory-sh/base';
+```
+
+### Validation
+
+```typescript
+import {
+  // Network & Token Validation
   resolveNetwork,
   resolveToken,
+  validatePaymentConfig,
+  validateAcceptConfig,
+
+  // Facilitator Validation
+  resolveFacilitator,
+  checkFacilitatorSupport,
+
+  // Error Creation
+  createError,
+
+  // Type Guards
+  isValidationError,
+  isResolvedNetwork,
+  isResolvedToken,
+
+  // Available Options
+  getAvailableNetworks,
+  getAvailableTokens,
 } from '@armory-sh/base';
 ```
 
+### Utilities
+
+```typescript
+import {
+  // Unit Conversion
+  toAtomicUnits,
+  fromAtomicUnits,
+
+  // Address Utilities
+  normalizeAddress,
+  isValidAddress,
+  isAddress,
+
+  // Route Matching
+  matchRoute,
+  parseRoutePattern,
+  findMatchingRoute,
+  validateRouteConfig,
+
+  // Types
+  type RouteMatcher,
+  type RoutePattern,
+} from '@armory-sh/base';
+```
+
+### Client Hooks Runtime
+
+```typescript
+import {
+  // Hook Execution
+  runOnPaymentRequiredHooks,
+  runBeforeSignPaymentHooks,
+  runAfterPaymentResponseHooks,
+  selectRequirementWithHooks,
+
+  // Types
+  type ClientHook,
+  type OnPaymentRequiredHook,
+  type BeforePaymentHook,
+  type PaymentRequiredContext,
+  type PaymentPayloadContext,
+  type ClientHookErrorContext,
+} from '@armory-sh/base';
+```
+
+### ERC20 ABI
+
+```typescript
+import {
+  ERC20_ABI,
+
+  // Types
+  type ERC20Abi,
+  type TransferWithAuthorizationParams,
+  type BalanceOfParams,
+} from '@armory-sh/base';
+```
+
+### Payment Client (Facilitator)
+
+```typescript
+import {
+  // Payment Operations
+  verifyPayment,
+  settlePayment,
+
+  // Payload Extraction
+  decodePayloadHeader,
+  extractPayerAddress,
+
+  // Facilitator Discovery
+  getSupported,
+
+  // Types
+  type FacilitatorClientConfig,
+  type SupportedResponse,
+} from '@armory-sh/base';
+```
+
+### Error Classes
+
+```typescript
+import {
+  X402ClientError,
+  SigningError,
+  PaymentException,
+} from '@armory-sh/base';
+```
+
+### Headers Constants
+
+```typescript
+import {
+  PAYMENT_REQUIRED_HEADER,
+  PAYMENT_SIGNATURE_HEADER,
+  PAYMENT_RESPONSE_HEADER,
+  V2_HEADERS,
+} from '@armory-sh/base';
+```
+
+---
+
+## Quick Start
+
 ## Quick Start
 
 ### Pre-configured Tokens
@@ -155,17 +442,6 @@ const decoded = decodePaymentV2(encoded)
 - **Custom Tokens**: Register your own tokens
 - **Encoding**: Base64URL encoding for HTTP headers
 
-## Supported Networks
-
-| Network | Chain ID |
-|---------|----------|
-| Ethereum | 1 |
-| Base | 8453 |
-| Base Sepolia | 84532 |
-| SKALE Base | 1187947933 |
-| SKALE Base Sepolia | 324705682 |
-| Ethereum Sepolia | 11155111 |
-
 ## License
 
 MIT © [Sawyer Cutler](https://github.com/TheGreatAxios/armory)

package/dist/client-hooks-runtime.d.ts

@@ -0,0 +1,9 @@
+import type { ClientHook, PaymentPayloadContext, PaymentRequiredContext } from "./types/hooks";
+import type { PaymentRequirementsV2 } from "./types/v2";
+export declare const runOnPaymentRequiredHooks: <TWallet>(hooks: ClientHook<TWallet>[] | undefined, context: PaymentRequiredContext) => Promise<void>;
+export declare const selectRequirementWithHooks: <TWallet>(hooks: ClientHook<TWallet>[] | undefined, context: PaymentRequiredContext) => Promise<PaymentRequirementsV2>;
+export declare const getRequirementAttemptOrderWithHooks: <TWallet>(hooks: ClientHook<TWallet>[] | undefined, context: PaymentRequiredContext) => Promise<PaymentRequirementsV2[]>;
+export declare const runBeforeSignPaymentHooks: <TWallet>(hooks: ClientHook<TWallet>[] | undefined, context: PaymentPayloadContext<TWallet>) => Promise<void>;
+export declare const runAfterPaymentResponseHooks: <TWallet>(hooks: ClientHook<TWallet>[] | undefined, context: PaymentPayloadContext<TWallet> & {
+    response: Response;
+}) => Promise<void>;

package/dist/encoding/x402.d.ts

@@ -4,7 +4,7 @@
  * Payment payloads are JSON-encoded for transport in HTTP headers.
  * Matches the Coinbase x402 v2 SDK format.
  */
-import type { PaymentPayload, X402Response, PaymentRequirements, SettlementResponse } from "../types/x402";
+import type { PaymentPayload, PaymentRequirements, SettlementResponse, X402Response } from "../types/x402";
 /**
  * Safe Base64 encode (URL-safe, no padding)
  */

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class X402ClientError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class SigningError extends X402ClientError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class PaymentException extends X402ClientError {
+    constructor(message: string, cause?: unknown);
+}

package/dist/facilitator-capabilities.d.ts

@@ -0,0 +1,9 @@
+import type { PaymentRequirementsV2 } from "./types/v2";
+import type { FacilitatorRoutingConfig } from "./payment-requirements";
+export declare function filterExtensionsForFacilitator(extensions: Record<string, unknown> | undefined, facilitatorUrl: string | undefined, network: string, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function filterExtensionsForFacilitators(extensions: Record<string, unknown> | undefined, facilitators: Array<{
+    url?: string;
+    network: string;
+}>, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function filterExtensionsForRequirements(extensions: Record<string, unknown> | undefined, requirements: PaymentRequirementsV2[], config: FacilitatorRoutingConfig, ttlMs?: number): Promise<Record<string, unknown>>;
+export declare function clearFacilitatorCapabilityCache(): void;

package/dist/index.d.ts

@@ -1,24 +1,32 @@
-export type { Address as X402Address, Hex, X402Version, Scheme, Network as X402Network, ExactEvmAuthorization, ExactEvmPayload, PaymentPayload as X402PaymentPayload, UnsignedPaymentPayload as X402UnsignedPaymentPayload, PaymentRequirements as X402PaymentRequirements, SettlementResponse as X402SettlementResponse, VerifyResponse, X402Response, } from "./types/x402";
-export { X402_VERSION, SCHEMES, isPaymentPayload, isExactEvmPayload, } from "./types/x402";
-export { safeBase64Encode, safeBase64Decode, encodePayment, decodePayment, encodeSettlementResponse, decodeSettlementResponse, encodeX402Response, decodeX402Response, detectPaymentVersion, extractPaymentFromHeaders, createPaymentRequiredHeaders, createSettlementHeaders, } from "./encoding/x402";
-export type { PaymentRequiredOptions } from "./encoding/x402";
-export { createNonce, toAtomicUnits, fromAtomicUnits, caip2ToNetwork, networkToCaip2, getCurrentTimestamp, isValidAddress, normalizeAddress, } from "./utils/x402";
-export type { CAIP2Network as CAIP2ChainId, CAIPAssetId, Address, Signature, PayToV2, Extensions, PaymentPayloadV2, PaymentRequirementsV2, SettlementResponseV2, PaymentRequiredV2, ResourceInfo, EIP3009Authorization, SchemePayloadV2, } from "./types/v2";
-export { V2_HEADERS, isCAIP2ChainId, isCAIPAssetId, isAddress, isPaymentRequiredV2, isPaymentPayloadV2, assetIdToAddress, addressToAssetId, parseSignature as parseSignatureV2, combineSignature as combineSignatureV2, } from "./types/v2";
-export type { PaymentPayload, PaymentRequirements, SettlementResponse, PaymentRequired, } from "./types/protocol";
-export { isX402V2Payload, isX402V2Requirements, isX402V2Settlement, isX402V2PaymentRequired, isSettlementSuccessful, getTxHash, PAYMENT_SIGNATURE_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_REQUIRED_HEADER, } from "./types/protocol";
-export type { NetworkConfig, CustomToken } from "./types/networks";
-export { NETWORKS, getNetworkConfig, getNetworkByChainId, getMainnets, getTestnets, registerToken, getCustomToken, getAllCustomTokens, unregisterToken, isCustomToken, } from "./types/networks";
-export { TOKENS, USDC_BASE, EURC_BASE, USDC_BASE_SEPOLIA, USDC_SKALE_BASE, SKL_SKALE_BASE, USDT_SKALE_BASE, WBTC_SKALE_BASE, WETH_SKALE_BASE, SKL_SKALE_BASE_SEPOLIA, USDC_SKALE_BASE_SEPOLIA, USDT_SKALE_BASE_SEPOLIA, WBTC_SKALE_BASE_SEPOLIA, WETH_SKALE_BASE_SEPOLIA, getToken, getAllTokens, getTokensBySymbol, getTokensByChain, getUSDCTokens, getEURCTokens, getSKLTokens, getUSDTTokens, getWBTCTokens, getWETHTokens, } from "./data/tokens";
-export type { TransferWithAuthorizationParams, ReceiveWithAuthorizationParams, BalanceOfParams, BalanceOfReturnType, NameReturnType, SymbolReturnType, ERC20Abi, } from "./abi/erc20";
+export type { BalanceOfParams, BalanceOfReturnType, ERC20Abi, NameReturnType, ReceiveWithAuthorizationParams, SymbolReturnType, TransferWithAuthorizationParams, } from "./abi/erc20";
 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 { runAfterPaymentResponseHooks, runBeforeSignPaymentHooks, runOnPaymentRequiredHooks, selectRequirementWithHooks, } from "./client-hooks-runtime";
+export { EURC_BASE, getAllTokens, getEURCTokens, getSKLTokens, getToken, getTokensByChain, getTokensBySymbol, getUSDCTokens, getUSDTTokens, getWBTCTokens, getWETHTokens, SKL_SKALE_BASE, SKL_SKALE_BASE_SEPOLIA, TOKENS, USDC_BASE, USDC_BASE_SEPOLIA, USDC_SKALE_BASE, USDC_SKALE_BASE_SEPOLIA, USDT_SKALE_BASE, USDT_SKALE_BASE_SEPOLIA, WBTC_SKALE_BASE, WBTC_SKALE_BASE_SEPOLIA, WETH_SKALE_BASE, WETH_SKALE_BASE_SEPOLIA, } from "./data/tokens";
+export type { EIP712Domain, EIP712Types, TransferWithAuthorization, TypedDataDomain, TypedDataField, } from "./eip712";
+export { createEIP712Domain, createTransferWithAuthorization, EIP712_TYPES, USDC_DOMAIN, validateTransferWithAuthorization, } from "./eip712";
+export { decodePaymentV2, decodeSettlementV2, encodePaymentV2, encodeSettlementV2, isPaymentV2, isSettlementV2, } from "./encoding";
+export type { PaymentRequiredOptions } from "./encoding/x402";
+export { createPaymentRequiredHeaders, createSettlementHeaders, decodePayment, decodeSettlementResponse, decodeX402Response, detectPaymentVersion, encodePayment, encodeSettlementResponse, encodeX402Response, extractPaymentFromHeaders, safeBase64Decode, safeBase64Encode, } from "./encoding/x402";
+export { PaymentException, SigningError, X402ClientError, } from "./errors";
 export type { FacilitatorClientConfig, SupportedKind, SupportedResponse, } from "./payment-client";
-export { verifyPayment, settlePayment, getSupported, decodePayloadHeader, extractPayerAddress, } from "./payment-client";
+export { decodePayloadHeader, extractPayerAddress, getSupported, settlePayment, verifyPayment, } from "./payment-client";
+export { clearFacilitatorCapabilityCache, filterExtensionsForFacilitator, filterExtensionsForFacilitators, filterExtensionsForRequirements, } from "./facilitator-capabilities";
+export type { PaymentConfig, ResolvedRequirementsConfig, } from "./payment-requirements";
+export { createPaymentRequirements, findRequirementByAccepted, findRequirementByNetwork, resolveFacilitatorUrlFromRequirement, } from "./payment-requirements";
+export { calculateValidBefore, detectX402Version, generateNonce, getPaymentHeaderName, parseJsonOrBase64, } from "./protocol";
+export type { AcceptPaymentOptions, ArmoryPaymentResult, FacilitatorConfig, FacilitatorSettleResult, FacilitatorVerifyResult, NetworkId, PaymentError, PaymentErrorCode, PaymentResult, PayToAddress, PricingConfig, ResolvedFacilitator, ResolvedNetwork, ResolvedPaymentConfig, ResolvedToken, SettlementMode, TokenId, ValidationError, } from "./types/api";
+export type { BeforePaymentHook, ClientHook, ClientHookErrorContext, ExtensionHook, HookConfig, HookRegistry, HookResult, OnPaymentRequiredHook, PaymentPayloadContext, PaymentRequiredContext, } from "./types/hooks";
+export type { CustomToken, NetworkConfig } from "./types/networks";
+export { getAllCustomTokens, getCustomToken, getMainnets, getNetworkByChainId, getNetworkConfig, getTestnets, isCustomToken, NETWORKS, registerToken, unregisterToken, } from "./types/networks";
+export type { PaymentPayload, PaymentRequired, PaymentRequirements, SettlementResponse, } from "./types/protocol";
+export { getTxHash, isSettlementSuccessful, isX402V2Payload, isX402V2PaymentRequired, isX402V2Requirements, isX402V2Settlement, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, } from "./types/protocol";
+export type { Address, CAIP2Network as CAIP2ChainId, CAIPAssetId, EIP3009Authorization, Extensions, PaymentPayloadV2, PaymentRequiredV2, PaymentRequirementsV2, PayToV2, ResourceInfo, SchemePayloadV2, SettlementResponseV2, Signature, } from "./types/v2";
+export { addressToAssetId, assetIdToAddress, combineSignature as combineSignatureV2, isAddress, isCAIP2ChainId, isCAIPAssetId, isPaymentPayloadV2, isPaymentRequiredV2, parseSignature as parseSignatureV2, V2_HEADERS, } from "./types/v2";
+export type { PaymentWallet } from "./types/wallet";
+export type { Address as X402Address, ExactEvmAuthorization, ExactEvmPayload, Hex, Network as X402Network, PaymentPayload as X402PaymentPayload, PaymentRequirements as X402PaymentRequirements, Scheme, SettlementResponse as X402SettlementResponse, UnsignedPaymentPayload as X402UnsignedPaymentPayload, VerifyResponse, X402Response, X402Version, } from "./types/x402";
+export { isExactEvmPayload, isPaymentPayload, SCHEMES, X402_VERSION, } from "./types/x402";
+export { decodeBase64ToUtf8, encodeUtf8ToBase64, normalizeBase64Url, toBase64Url, } from "./utils/base64";
+export type { ParsedPattern, RouteConfig, RouteInputConfig, RouteMatcher, RoutePattern, RouteValidationError, } from "./utils/routes";
+export { findMatchingRoute, matchRoute, parseRoutePattern, validateRouteConfig, } from "./utils/routes";
+export { caip2ToNetwork, createNonce, fromAtomicUnits, getCurrentTimestamp, isValidAddress, networkToCaip2, normalizeAddress, toAtomicUnits, } from "./utils/x402";
+export { checkFacilitatorSupport, createError, getAvailableNetworks, getAvailableTokens, isResolvedNetwork, isResolvedToken, isValidationError, normalizeNetworkName, resolveFacilitator, resolveNetwork, resolveToken, validateAcceptConfig, validatePaymentConfig, } from "./validation";