@armory-sh/client-ethers 0.2.26-alpha.23.82 → 0.2.27-alpha.23.83

package/README.md

@@ -79,10 +79,12 @@ const client = createX402Client({
 ```
 
 `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.js

@@ -1,6 +1,6 @@
 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, selectRequirementWithHooks, runBeforeSignPaymentHooks, runAfterPaymentResponseHooks } from '@armory-sh/base/client-hooks-runtime';
+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, {
@@ -262,6 +262,29 @@ var getRequirementDomainOverrides = (_parsed, requirement) => {
     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(
@@ -286,51 +309,73 @@ var handlePaymentRequired = async (state, response) => {
       nonce: `0x${Date.now().toString(16).padStart(64, "0")}`,
       validBefore: Math.floor(Date.now() / 1e3) + initialRequirement.maxTimeoutSeconds
     };
-    await runOnPaymentRequiredHooks(state.config.hooks, paymentRequiredContext);
-    const selectedRequirement = await selectRequirementWithHooks(
+    await runOnPaymentRequiredHooks(
       state.config.hooks,
       paymentRequiredContext
     );
-    const requirementDomain = getRequirementDomainOverrides(
-      parsed,
-      selectedRequirement
-    );
-    const payload = await createX402Payment(
-      state.signer,
-      selectedRequirement,
-      from,
-      paymentRequiredContext.nonce,
-      paymentRequiredContext.validBefore,
-      requirementDomain.domainName,
-      requirementDomain.domainVersion
+    const attemptRequirements = await getRequirementAttemptOrderWithHooks(
+      state.config.hooks,
+      paymentRequiredContext
     );
-    await runBeforeSignPaymentHooks(state.config.hooks, {
-      payload,
-      requirements: selectedRequirement,
-      wallet: state.signer,
-      paymentContext: paymentRequiredContext
-    });
-    const encoded = encodePaymentV2(payload);
     const headerName = getPaymentHeaderName(parsed.version);
-    const paymentResponse = await fetchWithTimeout(
-      response.url,
-      {
-        method: "GET",
-        headers: { ...state.config.headers, [headerName]: encoded }
-      },
-      state.config.timeout
-    );
-    const settlement = decodeSettlementV2(
-      paymentResponse.headers.get(V2_HEADERS.PAYMENT_RESPONSE) || ""
-    );
-    await runAfterPaymentResponseHooks(state.config.hooks, {
-      payload,
-      requirements: selectedRequirement,
-      wallet: state.signer,
-      paymentContext: paymentRequiredContext,
-      response: paymentResponse
-    });
-    return { success: true, settlement };
+    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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armory-sh/client-ethers",
-  "version": "0.2.26-alpha.23.82",
+  "version": "0.2.27-alpha.23.83",
   "license": "MIT",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
   "keywords": [
@@ -47,7 +47,7 @@
     "directory": "packages/client-ethers"
   },
   "dependencies": {
-    "@armory-sh/base": "0.2.27-alpha.23.82",
+    "@armory-sh/base": "0.2.28-alpha.23.83",
     "ethers": "6.16.0"
   },
   "devDependencies": {