@owney/sdk 0.2.6 → 0.2.8

package/README.md

@@ -603,13 +603,83 @@ type DepositCallback = (
 ) => Promise<`0x${string}`> | `0x${string}`;
 ```
 
-### Error Classes
+### Error Handling
 
-| Error | Thrown when |
-|-------|------------|
-| `NotConnectedError` | A wallet-dependent method is called before `connect()` |
-| `AgentNotFoundError` | An unknown agent ID is passed (e.g. a typo) |
-| `AgentChainIncompatibleError` | `activateAgent` is called with agents that don't support the given chain. Exposes `incompatibleAgents` and `connectedChainId` properties for programmatic handling. |
+All errors thrown by the SDK are instances of `OwneyError` (which extends `Error`), each carrying a stable `code` string and optional `details` object for programmatic handling.
+
+```typescript
+import { OwneyError } from "@owney/sdk";
+
+try {
+  await sdk.getBalances();
+} catch (error) {
+  if (error instanceof OwneyError) {
+    switch (error.code) {
+      case "NOT_CONNECTED":
+        // prompt user to connect wallet
+        break;
+      case "NO_ACTIVE_CHAIN":
+        // prompt user to activate an agent
+        break;
+      case "BALANCE_ALL_FAILED":
+        // all agents failed to return balances
+        break;
+      default:
+        console.error(`[${error.code}] ${error.message}`, error.details);
+    }
+  }
+}
+```
+
+```typescript
+type OwneyErrorCode =
+  // Connection & wallet
+  | "NOT_CONNECTED"           // Wallet-dependent method called before connect()
+  | "NO_ACTIVE_CHAIN"         // Method called before activateAgent()
+  | "WALLET_NO_ACCOUNTS"      // Provider returned no accounts during connect()
+  | "WALLET_ADDRESS_REQUIRED" // Wallet address missing during agent auth
+  // Agent resolution
+  | "AGENT_NOT_FOUND"          // Unknown agent ID passed
+  | "AGENT_CHAIN_INCOMPATIBLE" // Agent(s) don't support the given chain
+  | "AGENT_EMPTY_LIST"         // Empty agentId array passed to activateAgent()
+  // Chain
+  | "CHAIN_UNSUPPORTED"           // Chain ID not in supported list (8453, 42161)
+  | "CHAIN_NO_COMPATIBLE_AGENTS"  // No agents support the given chain
+  // Asset
+  | "ASSET_UNSUPPORTED"           // Agent doesn't support the asset on the active chain
+  | "ASSET_NO_COMPATIBLE_AGENTS"  // No agents support the asset on the active chain
+  // Deposit
+  | "DEPOSIT_AMOUNT_TOO_SMALL"    // Amount too small to split across agents
+  | "DEPOSIT_CALLBACK_REQUIRED"   // Sail agent requires a depositCallback
+  | "DEPOSIT_CALLBACK_INVALID"    // depositCallback didn't return a tx hash
+  | "DEPOSIT_NO_PERMITTED_TOKENS" // No permitted tokens available for deposit
+  // Withdraw
+  | "WITHDRAW_NO_PERMITTED_TOKENS" // No permitted tokens available for withdrawal
+  // API
+  | "API_ROUTING_ERROR"  // Routing API returned a non-OK HTTP status
+  | "API_ROUTING_FAILED" // Routing API returned { success: false }
+  | "API_SAIL_ERROR"     // Sail API returned a non-OK HTTP status
+  | "API_SAIL_TIMEOUT"   // Sail API request timed out
+  | "API_NO_AGENTS"      // No supported agents returned by routing API
+  // Aggregation
+  | "BALANCE_ALL_FAILED"     // All agents failed to return balances
+  | "ALLOCATION_ALL_FAILED"  // All agents failed to return allocation data
+  // Validation
+  | "VALIDATION_INVALID_DAYS"; // Invalid days value (expected "7D", "14D", or "30D")
+
+class OwneyError extends Error {
+  readonly code: OwneyErrorCode;
+  readonly details?: Record<string, unknown>;
+}
+```
+
+The three convenience subclasses extend `OwneyError` and remain backwards-compatible:
+
+| Class | Code | Extra properties |
+|-------|------|------------------|
+| `NotConnectedError` | `NOT_CONNECTED` | — |
+| `AgentNotFoundError` | `AGENT_NOT_FOUND` | — |
+| `AgentChainIncompatibleError` | `AGENT_CHAIN_INCOMPATIBLE` | `incompatibleAgents`, `connectedChainId` |
 
 ## License