feat: propagate structured error classes across payment module

Introduce ValidationError and PaymentError classes and apply them
consistently across the entire payment module, replacing raw
throw new Error() calls with structured, actionable errors.

Changes:
- Add sdkErrors.ts with ValidationError and PaymentError classes
- Replace 18 raw Error throws across 10 payment files:
  - validation.ts: ValidationError with field metadata
  - sendUserOpAndWait.ts: PaymentError with error codes
  - validateUSDCBasePermission.ts: ValidationError for chain/token
  - getPaymentStatus.ts: PaymentError for RPC and transfer errors
  - getExistingSmartWalletOrThrow.ts: PaymentError for wallet lookup
  - sdkManager.ts: PaymentError for response format issues
  - subscribe.ts: ValidationError + PaymentError
  - createCdpClientOrThrow.ts: PaymentError for CDP init
  - prepareCharge.ts / prepareRevoke.ts: PaymentError
  - getSubscriptionStatus.ts: reuse validateUSDCBasePermission()
  - getOrCreateSubscriptionOwnerWallet.ts: PaymentError
- Export both error classes from public API entry points
- Refactor getSubscriptionStatus to reuse validateUSDCBasePermission
  instead of duplicating validation logic inline
- Update all affected tests to match new error messages

Developers can now use instanceof checks for programmatic error
handling:
  import { PaymentError, ValidationError } from '@base-org/account';

  try { await pay(...) } catch (e) {
    if (e instanceof ValidationError) { /* fix input */ }
    if (e instanceof PaymentError) { /* retry or report */ }
  }

Addresses #231

Author: mehmetkr-31

packages/account-sdk/src/core/error/sdkErrors.ts

@@ -0,0 +1,37 @@
+/**
+ * Custom error classes for the Account SDK.
+ *
+ * These provide structured, actionable error messages to help developers
+ * quickly identify what went wrong and how to fix it.
+ */
+
+/**
+ * Thrown when user-provided input fails validation (amounts, addresses, parameters).
+ */
+export class ValidationError extends Error {
+  readonly name = 'ValidationError';
+
+  constructor(
+    message: string,
+    public readonly field?: string,
+    public readonly providedValue?: unknown,
+    public readonly expectedFormat?: string
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when a payment operation fails (user ops, charge, subscribe).
+ */
+export class PaymentError extends Error {
+  readonly name = 'PaymentError';
+
+  constructor(
+    message: string,
+    public readonly code?: string,
+    public readonly retryable: boolean = false
+  ) {
+    super(message);
+  }
+}

packages/account-sdk/src/index.node.ts

@@ -13,6 +13,8 @@ export { PACKAGE_VERSION as VERSION } from './core/constants.js';
 export {
   CHAIN_IDS,
   TOKENS,
+  PaymentError,
+  ValidationError,
   base,
   charge,
   getOrCreateSubscriptionOwnerWallet,

packages/account-sdk/src/index.ts

@@ -20,9 +20,11 @@ export {
   getPaymentStatus,
   getSubscriptionStatus,
   pay,
+  PaymentError,
   prepareCharge,
   subscribe,
   TOKENS,
+  ValidationError,
 } from './interface/payment/index.js';
 export type {
   ChargeOptions,

packages/account-sdk/src/interface/payment/charge.test.ts

@@ -495,7 +495,7 @@ describe('charge', () => {
       };
 
       await expect(charge(options)).rejects.toThrow(
-        'Failed to execute charge transaction with smart wallet: Insufficient funds'
+        'Failed to execute charge transaction: Insufficient funds'
       );
     });
 
@@ -515,9 +515,7 @@ describe('charge', () => {
         cdpWalletSecret: 'test-wallet-secret',
       };
 
-      await expect(charge(options)).rejects.toThrow(
-        'User operation failed: 0x9876543210987654321098765432109876543210987654321098765432109876'
-      );
+      await expect(charge(options)).rejects.toThrow('charge user operation was rejected on-chain');
     });
   });
 

packages/account-sdk/src/interface/payment/getOrCreateSubscriptionOwnerWallet.ts

@@ -1,4 +1,6 @@
 import { CdpClient } from '@coinbase/cdp-sdk';
+
+import { PaymentError } from ':core/error/sdkErrors.js';
 import type {
   GetOrCreateSubscriptionOwnerWalletOptions,
   GetOrCreateSubscriptionOwnerWalletResult,
@@ -25,7 +27,7 @@ import type {
  * @param options.cdpWalletSecret - CDP wallet secret. Falls back to CDP_WALLET_SECRET env var
  * @param options.walletName - Custom wallet name. Defaults to "subscription owner"
  * @returns Promise<GetOrCreateSubscriptionOwnerWalletResult> - The smart wallet address and metadata
- * @throws Error if CDP credentials are missing or invalid
+ * @throws PaymentError if CDP credentials are missing or invalid
  *
  * @example
  * ```typescript
@@ -78,8 +80,10 @@ export async function getOrCreateSubscriptionOwnerWallet(
   } catch (error) {
     // Re-throw with more context about what credentials are missing
     const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Failed to initialize CDP client for subscription owner wallet. ${errorMessage}\n\nPlease ensure you have set the required CDP credentials either:\n1. As environment variables: CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET\n2. As function parameters: cdpApiKeyId, cdpApiKeySecret, cdpWalletSecret\n\nYou can get these credentials from https://portal.cdp.coinbase.com/projects/api-keys`
+    throw new PaymentError(
+      `Failed to initialize CDP client for subscription owner wallet. ${errorMessage}\n\nPlease ensure you have set the required CDP credentials either:\n1. As environment variables: CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET\n2. As function parameters: cdpApiKeyId, cdpApiKeySecret, cdpWalletSecret\n\nYou can get these credentials from https://portal.cdp.coinbase.com/projects/api-keys`,
+      'CDP_INIT_FAILED',
+      false
     );
   }
 
@@ -106,10 +110,16 @@ export async function getOrCreateSubscriptionOwnerWallet(
       eoaAddress: eoaAccount.address, // Include EOA address for reference
     };
   } catch (error) {
+    // If the error is already our custom error, re-throw it
+    if (error instanceof PaymentError) {
+      throw error;
+    }
     // Handle CDP API errors
     const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Failed to get or create subscription owner smart wallet "${walletName}": ${errorMessage}`
+    throw new PaymentError(
+      `Failed to get or create subscription owner smart wallet "${walletName}": ${errorMessage}`,
+      'WALLET_CREATION_FAILED',
+      true
     );
   }
 }

packages/account-sdk/src/interface/payment/getPaymentStatus.ts

@@ -1,6 +1,7 @@
 import type { Address, Hex } from 'viem';
 import { decodeEventLog, formatUnits, getAddress, isAddressEqual } from 'viem';
 
+import { PaymentError } from ':core/error/sdkErrors.js';
 import {
   logPaymentStatusCheckCompleted,
   logPaymentStatusCheckError,
@@ -86,7 +87,7 @@ export async function getPaymentStatus(options: PaymentStatusOptions): Promise<P
         logPaymentStatusCheckError({ testnet, correlationId, errorMessage });
       }
       // Re-throw error for RPC failures
-      throw new Error(`RPC error: ${errorMessage}`);
+      throw new PaymentError(`RPC error: ${errorMessage}`, 'RPC_ERROR', true);
     }
 
     // If no result, payment is still pending or not found
@@ -208,18 +209,22 @@ export async function getPaymentStatus(options: PaymentStatusOptions): Promise<P
 
           if (senderTransfers.length === 0) {
             // No transfer from the sender wallet was found
-            throw new Error(
+            throw new PaymentError(
               `Unable to find USDC transfer from sender wallet ${receipt.result.sender}. ` +
-                `Found ${usdcTransfers.length} USDC transfer(s) but none originated from the sender wallet.`
+                `Found ${usdcTransfers.length} USDC transfer(s) but none originated from the sender wallet.`,
+              'NO_TRANSFER_FOUND',
+              false
             );
           }
           if (senderTransfers.length > 1) {
             // Multiple transfers from the sender wallet found
             const transferDetails = senderTransfers
               .map((t) => `${t.formattedAmount} USDC to ${t.to}`)
               .join(', ');
-            throw new Error(
-              `Found multiple USDC transfers from sender wallet ${receipt.result.sender}: ${transferDetails}. Expected exactly one transfer.`
+            throw new PaymentError(
+              `Found multiple USDC transfers from sender wallet ${receipt.result.sender}: ${transferDetails}. Expected exactly one transfer.`,
+              'MULTIPLE_TRANSFERS',
+              false
             );
           }
           // Exactly one transfer from sender found

packages/account-sdk/src/interface/payment/getSubscriptionStatus.ts

@@ -4,8 +4,9 @@ import {
   getPermissionStatus,
 } from '../public-utilities/spend-permission/index.js';
 import { timestampInSecondsToDate } from '../public-utilities/spend-permission/utils.js';
-import { CHAIN_IDS, TOKENS } from './constants.js';
+import { PaymentError } from ':core/error/sdkErrors.js';
 import type { SubscriptionStatus, SubscriptionStatusOptions } from './types.js';
+import { validateUSDCBasePermission } from './utils/validateUSDCBasePermission.js';
 
 /**
  * Gets the current status and details of a subscription.
@@ -18,7 +19,8 @@ import type { SubscriptionStatus, SubscriptionStatusOptions } from './types.js';
  * @param options.testnet - Whether to check on testnet (Base Sepolia). Defaults to false (mainnet)
  * @param options.rpcUrl - Optional custom RPC URL to use for blockchain queries. Useful for avoiding rate limits on public endpoints.
  * @returns Promise<SubscriptionStatus> - Subscription status information
- * @throws Error if the subscription cannot be found or if fetching fails
+ * @throws ValidationError if the subscription chain or token doesn't match expected values
+ * @throws PaymentError if the subscription has not started yet or if fetching fails
  *
  * @example
  * ```typescript
@@ -63,36 +65,7 @@ export async function getSubscriptionStatus(
   }
 
   // Validate this is a USDC permission on Base/Base Sepolia
-  const expectedChainId = testnet ? CHAIN_IDS.baseSepolia : CHAIN_IDS.base;
-  const expectedTokenAddress = testnet
-    ? TOKENS.USDC.addresses.baseSepolia.toLowerCase()
-    : TOKENS.USDC.addresses.base.toLowerCase();
-
-  if (permission.chainId !== expectedChainId) {
-    // Determine if the subscription is on mainnet or testnet
-    const isSubscriptionOnMainnet = permission.chainId === CHAIN_IDS.base;
-    const isSubscriptionOnTestnet = permission.chainId === CHAIN_IDS.baseSepolia;
-
-    let errorMessage: string;
-    if (testnet && isSubscriptionOnMainnet) {
-      errorMessage =
-        'The subscription was requested on testnet but is actually a mainnet subscription';
-    } else if (!testnet && isSubscriptionOnTestnet) {
-      errorMessage =
-        'The subscription was requested on mainnet but is actually a testnet subscription';
-    } else {
-      // Fallback for unexpected chain IDs
-      errorMessage = `Subscription is on chain ${permission.chainId}, expected ${expectedChainId} (${testnet ? 'Base Sepolia' : 'Base'})`;
-    }
-
-    throw new Error(errorMessage);
-  }
-
-  if (permission.permission.token.toLowerCase() !== expectedTokenAddress) {
-    throw new Error(
-      `Subscription is not for USDC token. Got ${permission.permission.token}, expected ${expectedTokenAddress}`
-    );
-  }
+  validateUSDCBasePermission(permission, testnet);
 
   // Get the current permission status (includes period info and active state)
   const status = await getPermissionStatus(permission, { rpcUrl });
@@ -108,8 +81,10 @@ export async function getSubscriptionStatus(
   const permissionStart = Number(permission.permission.start);
 
   if (currentTime < permissionStart) {
-    throw new Error(
-      `Subscription has not started yet. It will begin at ${new Date(permissionStart * 1000).toISOString()}`
+    throw new PaymentError(
+      `Subscription has not started yet. It will begin at ${new Date(permissionStart * 1000).toISOString()}`,
+      'SUBSCRIPTION_NOT_STARTED',
+      false
     );
   }
 

packages/account-sdk/src/interface/payment/index.node.ts

@@ -44,3 +44,6 @@ export type {
 
 // Export constants
 export { CHAIN_IDS, TOKENS } from './constants.js';
+
+// Export error classes for programmatic error handling
+export { PaymentError, ValidationError } from ':core/error/sdkErrors.js';

packages/account-sdk/src/interface/payment/index.ts

@@ -36,3 +36,6 @@ export type {
 
 // Export constants
 export { CHAIN_IDS, TOKENS } from './constants.js';
+
+// Export error classes for programmatic error handling
+export { PaymentError, ValidationError } from ':core/error/sdkErrors.js';

packages/account-sdk/src/interface/payment/pay.test.ts

@@ -215,7 +215,7 @@ describe('pay', () => {
         to: '0xFe21034794A5a574B94fE4fDfD16e005F1C96e51',
         dataSuffix: 'not-hex' as any,
       })
-    ).rejects.toThrow('Invalid dataSuffix: expected a 0x-prefixed hex string');
+    ).rejects.toThrow('Invalid dataSuffix');
   });
 
   it('should handle SDK execution errors', async () => {