@armory-sh/client-ethers 0.2.27 → 0.2.28

package/README.md

@@ -8,6 +8,7 @@ Armory x402 SDK — Payment client for ethers.js v6. Make payments from any ethe
 
 ```bash
 bun add @armory-sh/client-ethers
+bun add @armory-sh/client-hooks # optional preference/logger hooks
 ```
 
 ## Why Armory?
@@ -60,9 +61,30 @@ const response = await client.fetch('https://api.example.com/protected')
 const data = await response.json()
 ```
 
+## Hook Pipeline
+
+```typescript
+import { createX402Client } from '@armory-sh/client-ethers'
+import { PaymentPreference, Logger } from '@armory-sh/client-hooks'
+
+const client = createX402Client({
+  signer,
+  hooks: [
+    PaymentPreference.chain(['base', 'polygon', 'skale']),
+    PaymentPreference.token(['USDT', 'USDC', 'WBTC']),
+    PaymentPreference.cheapest(),
+    Logger.console(),
+  ],
+})
+```
+
+`parsePaymentRequired` returns `accepts[]` (x402 v2 challenge options). Clients select from this list.
+`hooks` are lifecycle callbacks. `extensions` are protocol payload fields. Hooks can drive selection and payload behavior, but they are not extensions.
+
 ## Features
 
 - **Auto 402 Handling**: Automatically intercepts and pays for 402 responses
+- **Detailed Verification Errors**: 402 retry failures include server details (for example `insufficient_funds`)
 - **EIP-3009 Signing**: Full support for EIP-3009 TransferWithAuthorization
 - **Multi-Network**: Ethereum, Base, SKALE support
 - **Multi-Token**: USDC, EURC, USDT, WBTC, WETH, SKL

package/dist/index.d.ts

@@ -1,52 +1,121 @@
-import { PaymentRequirementsV2, Address, PaymentPayloadV2, CustomToken, NetworkId, TokenId, ArmoryPaymentResult, ValidationError } from '@armory-sh/base';
-export { Address, BalanceOfParams, CAIP2ChainId, CAIPAssetId, EIP712_TYPES, ERC20_ABI, Extensions, NETWORKS, NetworkConfig, PayToV2, PaymentPayload, PaymentPayloadV2, PaymentRequirements, PaymentRequirementsV2, SettlementResponse, SettlementResponseV2, Signature, TransferWithAuthorizationParams, V2_HEADERS, createEIP712Domain, createTransferWithAuthorization, decodePayment, decodePaymentV2, decodeSettlementV2, detectPaymentVersion, encodePaymentV2, encodeSettlementV2, getMainnets, getNetworkByChainId, getNetworkConfig, getTestnets, getTxHash, isCAIP2ChainId, isCAIPAssetId, isPaymentV2, isSettlementSuccessful, isSettlementV2, isX402V2PaymentRequired, safeBase64Decode, validateTransferWithAuthorization } from '@armory-sh/base';
+import { NetworkId, TokenId, ArmoryPaymentResult, ValidationError, X402ClientError, CustomToken, PaymentRequirementsV2, Address, PaymentPayloadV2 } from '@armory-sh/base';
+export { PaymentException as PaymentError, SigningError, X402ClientError } from '@armory-sh/base';
 import { Signer, Provider } from 'ethers';
 export { Provider, Signer } from 'ethers';
+import { ClientHook } from '@armory-sh/base/types/hooks';
 
 /**
- * X402 Protocol Implementation for Ethers Client (V2 Only)
- *
- * Handles parsing x402 V2 PAYMENT-REQUIRED headers
- * and generating x402 V2 PAYMENT-SIGNATURE payloads
+ * Simple one-line payment API for Armory (Ethers)
+ * Focus on DX/UX - "everything just magically works"
  */
 
 /**
- * Detect x402 protocol version from response headers
- * V2-only: Always returns 2
+ * Simple wallet input - accepts wallet directly or wrapped for backward compatibility
  */
-declare function detectX402Version(_response: Response): 2;
+type SimpleWalletInput = Signer | {
+    signer: Signer;
+};
 /**
- * Get payment header name for protocol version
+ * Normalized wallet (internal use)
  */
-declare function getPaymentHeaderName(_version: 2): string;
-interface ParsedPaymentRequirements {
-    version: 2;
-    requirements: PaymentRequirementsV2;
-}
+type NormalizedWallet = Signer;
 /**
- * Parse x402 PAYMENT-REQUIRED header from response
- * V2 only
+ * Normalize wallet input to internal format
  */
-declare function parsePaymentRequired(response: Response): ParsedPaymentRequirements;
+declare const normalizeWallet: (wallet: SimpleWalletInput) => NormalizedWallet;
 /**
- * Create x402 payment payload (V2-only wrapper)
+ * Make a payment-protected API request with one line of code
+ */
+declare const armoryPay: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: {
+    /** Request method (default: GET) */
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    /** Request body (for POST/PUT/PATCH) */
+    body?: unknown;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Protocol version (V2 only) */
+    version?: 2;
+    /** Payment amount in token units (default: from 402 header) */
+    amount?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a GET request with payment
  */
-declare function createX402Payment(signer: Signer, parsed: ParsedPaymentRequirements, fromAddress: Address, nonce?: `0x${string}`, validBefore?: number, domainName?: string, domainVersion?: string): Promise<PaymentPayloadV2>;
+declare const armoryGet: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: Omit<Parameters<typeof armoryPay>[4], "method">) => Promise<ArmoryPaymentResult<T>>;
 /**
- * Encode x402 payment payload to Base64 for transport
+ * Make a POST request with payment
  */
-declare function encodeX402Payment(payload: PaymentPayloadV2): string;
+declare const armoryPost: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a PUT request with payment
+ */
+declare const armoryPut: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a DELETE request with payment
+ */
+declare const armoryDelete: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: Omit<Parameters<typeof armoryPay>[4], "method">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Make a PATCH request with payment
+ */
+declare const armoryPatch: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
+/**
+ * Get the wallet address from a SimpleWalletInput
+ */
+declare const getWalletAddress: (wallet: SimpleWalletInput) => Promise<string>;
+/**
+ * Validate a network identifier without making a request
+ */
+declare const validateNetwork: (network: NetworkId) => ValidationError | {
+    success: true;
+    network: string;
+};
+/**
+ * Validate a token identifier without making a request
+ */
+declare const validateToken: (token: TokenId, network?: NetworkId) => ValidationError | {
+    success: true;
+    token: string;
+    network: string;
+};
+/**
+ * Get list of available networks
+ */
+declare const getNetworks: () => string[];
+/**
+ * Get list of available tokens
+ */
+declare const getTokens: () => string[];
 
-declare class X402ClientError extends Error {
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
+/**
+ * Armory API - Simplified payment interface (Ethers)
+ * Provides a configurable object with method-based payment functions
+ */
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+interface ArmoryConfig {
+    wallet: SimpleWalletInput;
+    methods?: HttpMethod[] | HttpMethod;
+    tokens?: TokenId[] | TokenId;
+    chains?: NetworkId[] | NetworkId;
+    debug?: boolean;
 }
-declare class SigningError extends X402ClientError {
-    constructor(message: string, cause?: unknown);
+interface PaymentOptions {
+    method?: HttpMethod;
+    body?: unknown;
 }
-declare class PaymentError extends X402ClientError {
-    constructor(message: string, cause?: unknown);
+interface ArmoryInstance {
+    get<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
+    post<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
+    put<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
+    delete<T>(url: string): Promise<ArmoryPaymentResult<T>>;
+    patch<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
+    pay<T>(url: string, options?: PaymentOptions): Promise<ArmoryPaymentResult<T>>;
+    call<T>(url: string): Promise<ArmoryPaymentResult<T>>;
 }
+declare const createArmory: (config: ArmoryConfig) => ArmoryInstance;
+
 declare class SignerRequiredError extends X402ClientError {
     constructor(message?: string);
 }
@@ -72,6 +141,7 @@ interface X402ClientConfig {
     domainName?: string;
     /** Override EIP-712 domain version for custom tokens */
     domainVersion?: string;
+    hooks?: ClientHook<Signer>[];
 }
 interface SignerClientConfig extends X402ClientConfig {
     signer: Signer;
@@ -91,6 +161,7 @@ interface X402TransportConfig {
     onPaymentRequired?: (requirements: unknown) => boolean | Promise<boolean>;
     onPaymentSuccess?: (settlement: unknown) => void;
     onPaymentError?: (error: Error) => void;
+    hooks?: ClientHook<Signer>[];
 }
 interface X402RequestInit extends Omit<RequestInit, "headers"> {
     headers?: Record<string, string> | Headers;
@@ -112,40 +183,6 @@ interface EIP712Domain {
     verifyingContract: `0x${string}`;
 }
 
-interface X402Transport {
-    fetch(url: string, init?: X402RequestInit): Promise<Response>;
-    get(url: string, init?: X402RequestInit): Promise<Response>;
-    post(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
-    put(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
-    del(url: string, init?: X402RequestInit): Promise<Response>;
-    patch(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
-    setSigner(signer: Signer): void;
-    getSigner(): Signer | undefined;
-}
-declare const createX402Transport: (config?: X402TransportConfig) => X402Transport;
-
-declare function signEIP3009(signer: Signer, params: TransferWithAuthorizationParams, domain: EIP712Domain): Promise<{
-    v: number;
-    r: string;
-    s: string;
-}>;
-declare function signEIP3009WithDomain(signer: Signer, params: TransferWithAuthorizationParams, chainId: number, verifyingContract: `0x${string}`, domainName?: string, domainVersion?: string): Promise<{
-    v: number;
-    r: string;
-    s: string;
-}>;
-declare function signPayment(signer: Signer, from: `0x${string}`, to: `0x${string}`, value: bigint, chainId: number, verifyingContract: `0x${string}`, expirySeconds?: number, domainName?: string, domainVersion?: string): Promise<{
-    v: number;
-    r: string;
-    s: string;
-    nonce: `0x${string}`;
-}>;
-declare function recoverEIP3009Signer(params: TransferWithAuthorizationParams, signature: {
-    v: number;
-    r: string;
-    s: string;
-}, domain: EIP712Domain): Promise<`0x${string}`>;
-
 /**
  * X402 Client Factory for Ethers
  *
@@ -198,116 +235,68 @@ declare function createX402Client(config: X402ClientConfig & SignerClientConfig
 }): X402Client;
 declare function createX402Client(config: X402ClientConfig & ProviderClientConfig): X402Client;
 
-/**
- * Simple one-line payment API for Armory (Ethers)
- * Focus on DX/UX - "everything just magically works"
- */
+declare function signEIP3009(signer: Signer, params: TransferWithAuthorizationParams, domain: EIP712Domain): Promise<{
+    v: number;
+    r: string;
+    s: string;
+}>;
+declare function signEIP3009WithDomain(signer: Signer, params: TransferWithAuthorizationParams, chainId: number, verifyingContract: `0x${string}`, domainName?: string, domainVersion?: string): Promise<{
+    v: number;
+    r: string;
+    s: string;
+}>;
+declare function signPayment(signer: Signer, from: `0x${string}`, to: `0x${string}`, value: bigint, chainId: number, verifyingContract: `0x${string}`, expirySeconds?: number, domainName?: string, domainVersion?: string): Promise<{
+    v: number;
+    r: string;
+    s: string;
+    nonce: `0x${string}`;
+}>;
+declare function recoverEIP3009Signer(params: TransferWithAuthorizationParams, signature: {
+    v: number;
+    r: string;
+    s: string;
+}, domain: EIP712Domain): Promise<`0x${string}`>;
 
 /**
- * Simple wallet input - accepts wallet directly or wrapped for backward compatibility
- */
-type SimpleWalletInput = Signer | {
-    signer: Signer;
-};
-/**
- * Normalized wallet (internal use)
- */
-type NormalizedWallet = Signer;
-/**
- * Normalize wallet input to internal format
- */
-declare const normalizeWallet: (wallet: SimpleWalletInput) => NormalizedWallet;
-/**
- * Make a payment-protected API request with one line of code
- */
-declare const armoryPay: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: {
-    /** Request method (default: GET) */
-    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-    /** Request body (for POST/PUT/PATCH) */
-    body?: unknown;
-    /** Request headers */
-    headers?: Record<string, string>;
-    /** Protocol version (V2 only) */
-    version?: 2;
-    /** Payment amount in token units (default: from 402 header) */
-    amount?: string;
-    /** Enable debug logging */
-    debug?: boolean;
-}) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Make a GET request with payment
- */
-declare const armoryGet: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: Omit<Parameters<typeof armoryPay>[4], "method">) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Make a POST request with payment
- */
-declare const armoryPost: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Make a PUT request with payment
- */
-declare const armoryPut: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Make a DELETE request with payment
- */
-declare const armoryDelete: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, options?: Omit<Parameters<typeof armoryPay>[4], "method">) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Make a PATCH request with payment
- */
-declare const armoryPatch: <T = unknown>(wallet: SimpleWalletInput, url: string, network: NetworkId, token: TokenId, body?: unknown, options?: Omit<Parameters<typeof armoryPay>[4], "method" | "body">) => Promise<ArmoryPaymentResult<T>>;
-/**
- * Get the wallet address from a SimpleWalletInput
- */
-declare const getWalletAddress: (wallet: SimpleWalletInput) => Promise<string>;
-/**
- * Validate a network identifier without making a request
+ * X402 Protocol Implementation for Ethers Client (V2 Only)
+ *
+ * Handles parsing x402 V2 PAYMENT-REQUIRED headers
+ * and generating x402 V2 PAYMENT-SIGNATURE payloads
  */
-declare const validateNetwork: (network: NetworkId) => ValidationError | {
-    success: true;
-    network: string;
-};
+
 /**
- * Validate a token identifier without making a request
+ * Detect x402 protocol version from response headers
+ * V2-only: Always returns 2
  */
-declare const validateToken: (token: TokenId, network?: NetworkId) => ValidationError | {
-    success: true;
-    token: string;
-    network: string;
-};
+declare function detectX402Version(_response: Response): 2;
 /**
- * Get list of available networks
+ * Get payment header name for protocol version
  */
-declare const getNetworks: () => string[];
+declare function getPaymentHeaderName(_version: 2): string;
+interface ParsedPaymentRequirements {
+    version: 2;
+    accepts: PaymentRequirementsV2[];
+}
 /**
- * Get list of available tokens
+ * Parse x402 PAYMENT-REQUIRED header from response
+ * V2 only
  */
-declare const getTokens: () => string[];
-
+declare function parsePaymentRequired(response: Response): ParsedPaymentRequirements;
 /**
- * Armory API - Simplified payment interface (Ethers)
- * Provides a configurable object with method-based payment functions
+ * Create x402 payment payload (V2-only wrapper)
  */
+declare function createX402Payment(signer: Signer, requirement: PaymentRequirementsV2, fromAddress: Address, nonce?: `0x${string}`, validBefore?: number, domainName?: string, domainVersion?: string): Promise<PaymentPayloadV2>;
 
-type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-interface ArmoryConfig {
-    wallet: SimpleWalletInput;
-    methods?: HttpMethod[] | HttpMethod;
-    tokens?: TokenId[] | TokenId;
-    chains?: NetworkId[] | NetworkId;
-    debug?: boolean;
-}
-interface PaymentOptions {
-    method?: HttpMethod;
-    body?: unknown;
-}
-interface ArmoryInstance {
-    get<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
-    post<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
-    put<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
-    delete<T>(url: string): Promise<ArmoryPaymentResult<T>>;
-    patch<T>(url: string, body?: unknown): Promise<ArmoryPaymentResult<T>>;
-    pay<T>(url: string, options?: PaymentOptions): Promise<ArmoryPaymentResult<T>>;
-    call<T>(url: string): Promise<ArmoryPaymentResult<T>>;
+interface X402Transport {
+    fetch(url: string, init?: X402RequestInit): Promise<Response>;
+    get(url: string, init?: X402RequestInit): Promise<Response>;
+    post(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    put(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    del(url: string, init?: X402RequestInit): Promise<Response>;
+    patch(url: string, body?: unknown, init?: X402RequestInit): Promise<Response>;
+    setSigner(signer: Signer): void;
+    getSigner(): Signer | undefined;
 }
-declare const createArmory: (config: ArmoryConfig) => ArmoryInstance;
+declare const createX402Transport: (config?: X402TransportConfig) => X402Transport;
 
-export { type ArmoryConfig, type ArmoryInstance, AuthorizationError, type ClientConfig, type HttpMethod, type NormalizedWallet, type ParsedPaymentRequirements, PaymentError, type PaymentOptions, ProviderRequiredError, SignerRequiredError, SigningError, type SimpleWalletInput, type X402Client, type X402ClientConfig, X402ClientError, type X402RequestInit, type X402Transport, type X402TransportConfig, armoryDelete, armoryGet, armoryPatch, armoryPay, armoryPost, armoryPut, createArmory, createX402Client, createX402Payment, createX402Transport, detectX402Version, encodeX402Payment, getNetworks, getPaymentHeaderName, getTokens, getWalletAddress, normalizeWallet, parsePaymentRequired, recoverEIP3009Signer, signEIP3009, signEIP3009WithDomain, signPayment, validateNetwork, validateToken };
+export { type ArmoryConfig, type ArmoryInstance, AuthorizationError, type ClientConfig, type HttpMethod, type NormalizedWallet, type ParsedPaymentRequirements, type PaymentOptions, ProviderRequiredError, SignerRequiredError, type SimpleWalletInput, type X402Client, type X402ClientConfig, type X402RequestInit, type X402Transport, type X402TransportConfig, armoryDelete, armoryGet, armoryPatch, armoryPay, armoryPost, armoryPut, createArmory, createX402Client, createX402Payment, createX402Transport, detectX402Version, getNetworks, getPaymentHeaderName, getTokens, getWalletAddress, normalizeWallet, parsePaymentRequired, recoverEIP3009Signer, signEIP3009, signEIP3009WithDomain, signPayment, validateNetwork, validateToken };

package/dist/index.js

@@ -1,5 +1,6 @@
-import { createEIP712Domain, V2_HEADERS, isX402V2PaymentRequired, validatePaymentConfig, isValidationError, resolveNetwork, resolveToken, getNetworkConfig, normalizeNetworkName, decodeSettlementV2 } from '@armory-sh/base';
-export { EIP712_TYPES, ERC20_ABI, NETWORKS, V2_HEADERS, createEIP712Domain, createTransferWithAuthorization, decodePayment, decodePaymentV2, decodeSettlementV2, detectPaymentVersion, encodePaymentV2, encodeSettlementV2, getMainnets, getNetworkByChainId, getNetworkConfig, getTestnets, getTxHash, isCAIP2ChainId, isCAIPAssetId, isPaymentV2, isSettlementSuccessful, isSettlementV2, isX402V2PaymentRequired, safeBase64Decode, validateTransferWithAuthorization } from '@armory-sh/base';
+import { X402ClientError, createEIP712Domain, V2_HEADERS, PaymentException, isX402V2PaymentRequired, validatePaymentConfig, isValidationError, resolveNetwork, resolveToken, normalizeBase64Url, decodeBase64ToUtf8, getNetworkConfig, normalizeNetworkName, encodePaymentV2, decodeSettlementV2 } from '@armory-sh/base';
+export { PaymentException as PaymentError, SigningError, X402ClientError } from '@armory-sh/base';
+import { runOnPaymentRequiredHooks, getRequirementAttemptOrderWithHooks, runBeforeSignPaymentHooks, runAfterPaymentResponseHooks } from '@armory-sh/base/client-hooks-runtime';
 import { ethers } from 'ethers';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
@@ -8,28 +9,6 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-
-// src/errors.ts
-var X402ClientError = class extends Error {
-  cause;
-  constructor(message, cause) {
-    super(message);
-    this.name = "X402ClientError";
-    this.cause = cause;
-  }
-};
-var SigningError = class extends X402ClientError {
-  constructor(message, cause) {
-    super(`Signing failed: ${message}`, cause);
-    this.name = "SigningError";
-  }
-};
-var PaymentError = class extends X402ClientError {
-  constructor(message, cause) {
-    super(`Payment failed: ${message}`, cause);
-    this.name = "PaymentError";
-  }
-};
 var SignerRequiredError = class extends X402ClientError {
   constructor(message = "Signer is required for this operation") {
     super(message);
@@ -48,8 +27,6 @@ var ProviderRequiredError = class extends X402ClientError {
     this.name = "ProviderRequiredError";
   }
 };
-
-// src/eip3009.ts
 var EIP712_TYPES_ETHERS = {
   TransferWithAuthorization: [
     { name: "from", type: "address" },
@@ -70,7 +47,11 @@ async function signEIP3009(signer, params, domain) {
       validBefore: BigInt(params.validBefore),
       nonce: params.nonce
     };
-    const signature = await signer.signTypedData(domain, EIP712_TYPES_ETHERS, message);
+    const signature = await signer.signTypedData(
+      domain,
+      EIP712_TYPES_ETHERS,
+      message
+    );
     const { v, r, s } = ethers.Signature.from(signature);
     return { v: Number(v), r, s };
   } catch (error) {
@@ -82,7 +63,11 @@ async function signEIP3009(signer, params, domain) {
 }
 async function signEIP3009WithDomain(signer, params, chainId, verifyingContract, domainName, domainVersion) {
   const domain = createEIP712Domain(chainId, verifyingContract);
-  const customDomain = domainName || domainVersion ? { ...domain, name: domainName ?? domain.name, version: domainVersion ?? domain.version } : domain;
+  const customDomain = domainName || domainVersion ? {
+    ...domain,
+    name: domainName ?? domain.name,
+    version: domainVersion ?? domain.version
+  } : domain;
   return signEIP3009(signer, params, customDomain);
 }
 async function signPayment(signer, from, to, value, chainId, verifyingContract, expirySeconds = 3600, domainName, domainVersion) {
@@ -90,7 +75,14 @@ async function signPayment(signer, from, to, value, chainId, verifyingContract,
   const nonce = `0x${(now * 1e3).toString(16).padStart(64, "0")}`;
   const signature = await signEIP3009WithDomain(
     signer,
-    { from, to, value, validAfter: 0n, validBefore: BigInt(now + expirySeconds), nonce },
+    {
+      from,
+      to,
+      value,
+      validAfter: 0n,
+      validBefore: BigInt(now + expirySeconds),
+      nonce
+    },
     chainId,
     verifyingContract,
     domainName,
@@ -112,60 +104,15 @@ async function recoverEIP3009Signer(params, signature, domain) {
     r: signature.r,
     s: signature.s
   });
-  const address = ethers.verifyTypedData(domain, EIP712_TYPES_ETHERS, message, sig);
+  const address = ethers.verifyTypedData(
+    domain,
+    EIP712_TYPES_ETHERS,
+    message,
+    sig
+  );
   return address;
 }
 
-// src/bytes.ts
-var textEncoder = new TextEncoder();
-var textDecoder = new TextDecoder();
-function getNodeBuffer() {
-  if ("Buffer" in globalThis) {
-    return globalThis.Buffer;
-  }
-  return void 0;
-}
-function toBase64(bytes) {
-  if (typeof btoa === "function") {
-    let binary = "";
-    for (let index = 0; index < bytes.length; index += 1) {
-      binary += String.fromCharCode(bytes[index]);
-    }
-    return btoa(binary);
-  }
-  const nodeBuffer = getNodeBuffer();
-  if (nodeBuffer) {
-    return nodeBuffer.from(bytes).toString("base64");
-  }
-  throw new Error("No base64 encoder available in this runtime");
-}
-function fromBase64(base64) {
-  if (typeof atob === "function") {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let index = 0; index < binary.length; index += 1) {
-      bytes[index] = binary.charCodeAt(index);
-    }
-    return bytes;
-  }
-  const nodeBuffer = getNodeBuffer();
-  if (nodeBuffer) {
-    return Uint8Array.from(nodeBuffer.from(base64, "base64"));
-  }
-  throw new Error("No base64 decoder available in this runtime");
-}
-function encodeUtf8ToBase64(value) {
-  const bytes = textEncoder.encode(value);
-  return toBase64(bytes);
-}
-function decodeBase64ToUtf8(value) {
-  const bytes = fromBase64(value);
-  return textDecoder.decode(bytes);
-}
-function normalizeBase64Url(value) {
-  return value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
-}
-
 // src/protocol.ts
 function detectX402Version(_response) {
   return 2;
@@ -184,28 +131,27 @@ function parseJsonOrBase64(value) {
 function parsePaymentRequired(response) {
   const v2Header = response.headers.get(V2_HEADERS.PAYMENT_REQUIRED);
   if (!v2Header) {
-    throw new PaymentError("No PAYMENT-REQUIRED header found in V2 response");
+    throw new PaymentException("No PAYMENT-REQUIRED header found in V2 response");
   }
   try {
     const parsed = parseJsonOrBase64(v2Header);
     if (!isX402V2PaymentRequired(parsed)) {
-      throw new PaymentError("Invalid x402 V2 payment required format");
+      throw new PaymentException("Invalid x402 V2 payment required format");
     }
     if (!parsed.accepts || parsed.accepts.length === 0) {
-      throw new PaymentError("No payment requirements found in accepts array");
+      throw new PaymentException("No payment requirements found in accepts array");
     }
     return {
       version: 2,
-      requirements: parsed.accepts[0]
+      accepts: parsed.accepts
     };
   } catch (error) {
-    if (error instanceof PaymentError) throw error;
-    throw new PaymentError(`Failed to parse V2 PAYMENT-REQUIRED header: ${error}`);
+    if (error instanceof PaymentException) throw error;
+    throw new PaymentException(
+      `Failed to parse V2 PAYMENT-REQUIRED header: ${error}`
+    );
   }
 }
-function toAtomicUnits(amount) {
-  return Math.floor(parseFloat(amount) * 1e6).toString();
-}
 function extractChainId(network) {
   if (network.startsWith("eip155:")) {
     return parseInt(network.split(":")[1], 10);
@@ -214,7 +160,7 @@ function extractChainId(network) {
   if (net) {
     return net.chainId;
   }
-  throw new PaymentError(`Unsupported network: ${network}`);
+  throw new PaymentException(`Unsupported network: ${network}`);
 }
 function createNonce() {
   const now = Math.floor(Date.now() / 1e3);
@@ -223,13 +169,18 @@ function createNonce() {
 async function createX402V2Payment(signer, requirements, fromAddress, nonce, validBefore, domainName, domainVersion) {
   const contractAddress = requirements.asset;
   const chainId = extractChainId(requirements.network);
+  const now = Math.floor(Date.now() / 1e3);
   const domain = createEIP712Domain(chainId, contractAddress);
-  const customDomain = domainName || domainVersion ? { ...domain, name: domainName ?? domain.name, version: domainVersion ?? domain.version } : domain;
+  const customDomain = domainName || domainVersion ? {
+    ...domain,
+    name: domainName ?? domain.name,
+    version: domainVersion ?? domain.version
+  } : domain;
   const authorization = {
     from: fromAddress,
     to: requirements.payTo,
-    value: toAtomicUnits(requirements.amount),
-    validAfter: "0",
+    value: requirements.amount,
+    validAfter: (now - 600).toString(),
     validBefore: validBefore.toString(),
     nonce
   };
@@ -253,12 +204,12 @@ async function createX402V2Payment(signer, requirements, fromAddress, nonce, val
     payload
   };
 }
-async function createX402Payment(signer, parsed, fromAddress, nonce, validBefore, domainName, domainVersion) {
+async function createX402Payment(signer, requirement, fromAddress, nonce, validBefore, domainName, domainVersion) {
   const effectiveNonce = nonce ?? createNonce();
   const effectiveValidBefore = validBefore ?? Math.floor(Date.now() / 1e3) + 3600;
   return createX402V2Payment(
     signer,
-    parsed.requirements,
+    requirement,
     fromAddress,
     effectiveNonce,
     effectiveValidBefore,
@@ -266,9 +217,8 @@ async function createX402Payment(signer, parsed, fromAddress, nonce, validBefore
     domainVersion
   );
 }
-function encodeX402Payment(payload) {
-  return encodeUtf8ToBase64(JSON.stringify(payload));
-}
+
+// src/transport.ts
 var defaultConfig = {
   baseURL: "",
   headers: {},
@@ -280,7 +230,8 @@ var defaultConfig = {
   onPaymentSuccess: () => {
   },
   onPaymentError: () => {
-  }
+  },
+  hooks: []
 };
 var createState = (config) => ({
   config: { ...defaultConfig, ...config }
@@ -301,48 +252,161 @@ var fetchWithTimeout = async (url, init, timeout) => {
   }
 };
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var getRequirementDomainOverrides = (_parsed, requirement) => {
+  const extra = requirement.extra;
+  const extraRecord = extra && typeof extra === "object" ? extra : void 0;
+  const extraName = extraRecord && typeof extraRecord.name === "string" ? extraRecord.name : void 0;
+  const extraVersion = extraRecord && typeof extraRecord.version === "string" ? extraRecord.version : void 0;
+  return {
+    domainName: requirement.name ?? extraName,
+    domainVersion: requirement.version ?? extraVersion
+  };
+};
+var getPaymentFailureDetail = async (response) => {
+  const text = (await response.clone().text()).trim();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.message === "string" && parsed.message.trim()) {
+      return parsed.message.trim();
+    }
+    if (typeof parsed.error === "string" && parsed.error.trim()) {
+      return parsed.error.trim();
+    }
+  } catch {
+  }
+  return text;
+};
+var createPaymentVerificationError = async (response) => {
+  const detail = await getPaymentFailureDetail(response);
+  return new Error(
+    detail ? `Payment verification failed: ${detail}` : "Payment verification failed"
+  );
+};
 var handlePaymentRequired = async (state, response) => {
   if (!state.signer) {
-    throw new SignerRequiredError("Cannot handle payment: no signer configured.");
+    throw new SignerRequiredError(
+      "Cannot handle payment: no signer configured."
+    );
   }
   try {
     const parsed = parsePaymentRequired(response);
+    const initialRequirement = parsed.accepts[0];
+    if (!initialRequirement) {
+      throw new Error("No payment requirements found in accepts array");
+    }
     const from = await state.signer.getAddress();
-    const payload = await createX402Payment(state.signer, parsed, from);
-    const encoded = encodeX402Payment(payload);
-    const headerName = getPaymentHeaderName(parsed.version);
-    const paymentResponse = await fetchWithTimeout(
-      response.url,
-      {
-        method: "GET",
-        headers: { ...state.config.headers, [headerName]: encoded }
-      },
-      state.config.timeout
+    const paymentRequiredContext = {
+      url: response.url,
+      requestInit: void 0,
+      accepts: parsed.accepts,
+      requirements: initialRequirement,
+      selectedRequirement: initialRequirement,
+      serverExtensions: void 0,
+      fromAddress: from,
+      nonce: `0x${Date.now().toString(16).padStart(64, "0")}`,
+      validBefore: Math.floor(Date.now() / 1e3) + initialRequirement.maxTimeoutSeconds
+    };
+    await runOnPaymentRequiredHooks(
+      state.config.hooks,
+      paymentRequiredContext
+    );
+    const attemptRequirements = await getRequirementAttemptOrderWithHooks(
+      state.config.hooks,
+      paymentRequiredContext
     );
-    const settlement = decodeSettlementV2(paymentResponse.headers.get(V2_HEADERS.PAYMENT_RESPONSE) || "");
-    return { success: true, settlement };
+    const headerName = getPaymentHeaderName(parsed.version);
+    let lastError;
+    for (const selectedRequirement of attemptRequirements) {
+      try {
+        const validBefore = Math.floor(Date.now() / 1e3) + selectedRequirement.maxTimeoutSeconds;
+        const attemptContext = {
+          ...paymentRequiredContext,
+          requirements: selectedRequirement,
+          selectedRequirement,
+          validBefore
+        };
+        const requirementDomain = getRequirementDomainOverrides(
+          parsed,
+          selectedRequirement
+        );
+        const payload = await createX402Payment(
+          state.signer,
+          selectedRequirement,
+          from,
+          attemptContext.nonce,
+          attemptContext.validBefore,
+          requirementDomain.domainName,
+          requirementDomain.domainVersion
+        );
+        await runBeforeSignPaymentHooks(state.config.hooks, {
+          payload,
+          requirements: selectedRequirement,
+          wallet: state.signer,
+          paymentContext: attemptContext
+        });
+        const encoded = encodePaymentV2(payload);
+        const paymentResponse = await fetchWithTimeout(
+          response.url,
+          {
+            method: "GET",
+            headers: { ...state.config.headers, [headerName]: encoded }
+          },
+          state.config.timeout
+        );
+        await runAfterPaymentResponseHooks(state.config.hooks, {
+          payload,
+          requirements: selectedRequirement,
+          wallet: state.signer,
+          paymentContext: attemptContext,
+          response: paymentResponse
+        });
+        if (paymentResponse.status === 402) {
+          lastError = await createPaymentVerificationError(paymentResponse);
+          continue;
+        }
+        const settlement = decodeSettlementV2(
+          paymentResponse.headers.get(V2_HEADERS.PAYMENT_RESPONSE) || ""
+        );
+        return { success: true, settlement };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+    }
+    throw lastError ?? new Error("Payment verification failed");
   } catch (error) {
-    return { success: false, error: error instanceof Error ? error : new Error(String(error)) };
+    return {
+      success: false,
+      error: error instanceof Error ? error : new Error(String(error))
+    };
   }
 };
 var shouldRetryPayment = async (state, response) => {
   if (!state.config.autoPay) return false;
   const parsed = parsePaymentRequired(response);
-  return await state.config.onPaymentRequired(parsed.requirements);
+  return await state.config.onPaymentRequired(parsed.accepts[0]);
 };
 var x402Fetch = async (state, url, init = {}) => {
   const fullUrl = state.config.baseURL ? new URL(url, state.config.baseURL).toString() : url;
   const headers = new Headers({ ...state.config.headers, ...init.headers });
   for (let attempt = 1; attempt <= state.config.maxRetries; attempt++) {
     try {
-      const response = await fetchWithTimeout(fullUrl, { ...init, headers }, state.config.timeout);
+      const response = await fetchWithTimeout(
+        fullUrl,
+        { ...init, headers },
+        state.config.timeout
+      );
       if (response.status === 402 && !init.skipAutoPay && await shouldRetryPayment(state, response)) {
         const paymentResult = await handlePaymentRequired(state, response);
         if (paymentResult.success) {
           state.config.onPaymentSuccess(paymentResult.settlement);
           continue;
         }
-        state.config.onPaymentError(paymentResult.error ?? new Error("Payment failed"));
+        state.config.onPaymentError(
+          paymentResult.error ?? new Error("Payment failed")
+        );
       }
       return response;
     } catch (error) {
@@ -365,7 +429,7 @@ var createMethod = (state, method) => async (url, bodyOrInit, init) => {
   });
 };
 var createX402Transport = (config) => {
-  let state = createState(config);
+  const state = createState(config);
   return {
     fetch: (url, init) => x402Fetch(state, url, init),
     get: createMethod(state, "GET"),
@@ -380,37 +444,7 @@ var createX402Transport = (config) => {
   };
 };
 
-// src/client.ts
-function createX402Client(config) {
-  const transport = createX402Transport(void 0);
-  if ("signer" in config && config.signer) {
-    transport.setSigner(config.signer);
-  } else if ("provider" in config && config.provider) {
-    const provider = config.provider;
-    if (provider.getSigner) {
-      try {
-        const signer = provider.getSigner();
-        if (signer) {
-          transport.setSigner(signer);
-        }
-      } catch {
-      }
-    }
-  } else {
-    throw new SignerRequiredError(
-      "Either 'signer' or 'provider' with getSigner() must be provided"
-    );
-  }
-  return {
-    get: (url, init) => transport.get(url, init),
-    post: (url, body, init) => transport.post(url, body, init),
-    put: (url, body, init) => transport.put(url, body, init),
-    del: (url, init) => transport.del(url, init),
-    patch: (url, body, init) => transport.patch(url, body, init),
-    setSigner: (signer) => transport.setSigner(signer),
-    getSigner: () => transport.getSigner()
-  };
-}
+// src/payment-api.ts
 var normalizeWallet = (wallet) => {
   if (typeof wallet === "object" && wallet !== null && "signer" in wallet) {
     return wallet.signer;
@@ -472,19 +506,37 @@ var armoryPay = async (wallet, url, network, token, options) => {
   }
 };
 var armoryGet = (wallet, url, network, token, options) => {
-  return armoryPay(wallet, url, network, token, { ...options, method: "GET" });
+  return armoryPay(wallet, url, network, token, {
+    ...options,
+    method: "GET"
+  });
 };
 var armoryPost = (wallet, url, network, token, body, options) => {
-  return armoryPay(wallet, url, network, token, { ...options, method: "POST", body });
+  return armoryPay(wallet, url, network, token, {
+    ...options,
+    method: "POST",
+    body
+  });
 };
 var armoryPut = (wallet, url, network, token, body, options) => {
-  return armoryPay(wallet, url, network, token, { ...options, method: "PUT", body });
+  return armoryPay(wallet, url, network, token, {
+    ...options,
+    method: "PUT",
+    body
+  });
 };
 var armoryDelete = (wallet, url, network, token, options) => {
-  return armoryPay(wallet, url, network, token, { ...options, method: "DELETE" });
+  return armoryPay(wallet, url, network, token, {
+    ...options,
+    method: "DELETE"
+  });
 };
 var armoryPatch = (wallet, url, network, token, body, options) => {
-  return armoryPay(wallet, url, network, token, { ...options, method: "PATCH", body });
+  return armoryPay(wallet, url, network, token, {
+    ...options,
+    method: "PATCH",
+    body
+  });
 };
 var getWalletAddress = async (wallet) => {
   const signer = normalizeWallet(wallet);
@@ -498,7 +550,7 @@ var validateNetwork = (network) => {
   return { success: true, network: resolved.config.name };
 };
 var validateToken = (token, network) => {
-  let resolvedNetwork = void 0;
+  let resolvedNetwork;
   if (network) {
     const networkResult = resolveNetwork(network);
     if (isValidationError(networkResult)) {
@@ -524,7 +576,15 @@ var getTokens = () => {
   const { getAvailableTokens } = __require("@armory-sh/base");
   return getAvailableTokens();
 };
-var ALL_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "DELETE", "PATCH"]);
+
+// src/armory-api.ts
+var ALL_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH"
+]);
 var arrayify = (value) => {
   if (value === void 0) return void 0;
   return Array.isArray(value) ? value : [value];
@@ -592,4 +652,38 @@ var createArmory = (config) => {
   };
 };
 
-export { AuthorizationError, PaymentError, ProviderRequiredError, SignerRequiredError, SigningError, X402ClientError, armoryDelete, armoryGet, armoryPatch, armoryPay, armoryPost, armoryPut, createArmory, createX402Client, createX402Payment, createX402Transport, detectX402Version, encodeX402Payment, getNetworks, getPaymentHeaderName, getTokens, getWalletAddress, normalizeWallet, parsePaymentRequired, recoverEIP3009Signer, signEIP3009, signEIP3009WithDomain, signPayment, validateNetwork, validateToken };
+// src/client.ts
+function createX402Client(config) {
+  const transport = createX402Transport({
+    hooks: config.hooks
+  });
+  if ("signer" in config && config.signer) {
+    transport.setSigner(config.signer);
+  } else if ("provider" in config && config.provider) {
+    const provider = config.provider;
+    if (provider.getSigner) {
+      try {
+        const signer = provider.getSigner();
+        if (signer) {
+          transport.setSigner(signer);
+        }
+      } catch {
+      }
+    }
+  } else {
+    throw new SignerRequiredError(
+      "Either 'signer' or 'provider' with getSigner() must be provided"
+    );
+  }
+  return {
+    get: (url, init) => transport.get(url, init),
+    post: (url, body, init) => transport.post(url, body, init),
+    put: (url, body, init) => transport.put(url, body, init),
+    del: (url, init) => transport.del(url, init),
+    patch: (url, body, init) => transport.patch(url, body, init),
+    setSigner: (signer) => transport.setSigner(signer),
+    getSigner: () => transport.getSigner()
+  };
+}
+
+export { AuthorizationError, ProviderRequiredError, SignerRequiredError, armoryDelete, armoryGet, armoryPatch, armoryPay, armoryPost, armoryPut, createArmory, createX402Client, createX402Payment, createX402Transport, detectX402Version, getNetworks, getPaymentHeaderName, getTokens, getWalletAddress, normalizeWallet, parsePaymentRequired, recoverEIP3009Signer, signEIP3009, signEIP3009WithDomain, signPayment, validateNetwork, validateToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/client-ethers",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "keywords": [
@@ -47,7 +47,7 @@
     "directory": "packages/client-ethers"
   },
   "dependencies": {
-    "@armory-sh/base": "0.2.28",
+    "@armory-sh/base": "0.2.29",
     "ethers": "6.16.0"
   },
   "devDependencies": {
@@ -56,6 +56,8 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsup",
+    "lint": "bun run build",
+    "format": "bun run lint",
     "test": "bun test",
     "example": "bun run examples/"
   }