@owney/sdk 0.2.9 → 0.2.11

package/README.md

@@ -167,6 +167,14 @@ console.log(results.agentResults.sail.amount); // "50000000"
 
 Withdraw funds from a specific agent, or all agents that support the active chain+asset if `agentId` is omitted. Validates that the asset is supported.
 
+When `agentId` is omitted with a partial `amount`, the SDK splits the requested amount proportionally across eligible agents based on each agent's per-asset balance. If an agent's withdraw fails, its share is redistributed to remaining not-yet-attempted agents (capped by their headroom). Throws:
+
+- `WITHDRAW_INSUFFICIENT_BALANCE` — total available across agents is less than `amount`.
+- `WITHDRAW_ALL_FAILED` — every agent's withdraw call failed.
+- `WITHDRAW_PARTIAL_FAILURE` — some agents succeeded but total withdrawn is less than `amount`. Successful txs are surfaced via `error.details.partialResults`; per-agent failure messages via `error.details.agentErrors`.
+
+`WITHDRAW_ALL_FAILED` also carries per-agent failure messages via `error.details.agentErrors` (a `Record<agentId, string>`). Any error originating from a specific agent also has `error.agentId` set and a `[agent:<id>]` prefix on `error.message`.
+
 | Param             | Type                 | Description                                   |
 | ----------------- | -------------------- | --------------------------------------------- |
 | `options.asset`   | `string`             | Asset symbol (e.g. `"USDC"`)                  |
@@ -185,6 +193,12 @@ const result = await sdk.withdraw({
 console.log(result.type); // "partial"
 console.log(result.amount); // "50000000"
 
+// Partial withdrawal split proportionally across all agents
+// e.g. zyfai=$5, sail=$2, amount=$4 → zyfai withdraws $3, sail withdraws $1
+const split = await sdk.withdraw({ asset: "USDC", amount: "4000000" });
+console.log(split.agentResult.zyfai.amount); // "3000000"
+console.log(split.agentResult.sail.amount); // "1000000"
+
 // Full withdrawal from all agents
 const results = await sdk.withdraw({ asset: "USDC" });
 console.log(results.agentResult.zyfai.type); // "full"
@@ -608,11 +622,6 @@ interface OwneyAgentApy {
   agentApy: Record<AgentId, AgentApy>;
 }
 
-interface OwneyRouteResponse {
-  agent: AgentId;
-  chainId: number;
-}
-
 interface OwneyAgentAllocation {
   agentAllocation: Record<AgentId, number>;
 }
@@ -630,7 +639,7 @@ type DepositCallback = (
 
 ### Error 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.
+All errors thrown by the SDK are instances of `OwneyError` (which extends `Error`), each carrying a stable `code` string, optional `details` object, and optional `agentId` identifying the originating agent. When `agentId` is set, `error.message` is also prefixed with `[agent:<id>]` for logs.
 
 ```typescript
 import { OwneyError } from "@owney/sdk";
@@ -680,6 +689,9 @@ type OwneyErrorCode =
   | "DEPOSIT_NO_PERMITTED_TOKENS" // No permitted tokens available for deposit
   // Withdraw
   | "WITHDRAW_NO_PERMITTED_TOKENS" // No permitted tokens available for withdrawal
+  | "WITHDRAW_INSUFFICIENT_BALANCE" // Requested amount exceeds total available across agents
+  | "WITHDRAW_ALL_FAILED" // Every eligible agent's withdraw call failed
+  | "WITHDRAW_PARTIAL_FAILURE" // Some agents succeeded; total withdrawn < requested
   // API
   | "API_ROUTING_ERROR" // Routing API returned a non-OK HTTP status
   | "API_ROUTING_FAILED" // Routing API returned { success: false }
@@ -695,6 +707,7 @@ type OwneyErrorCode =
 class OwneyError extends Error {
   readonly code: OwneyErrorCode;
   readonly details?: Record<string, unknown>;
+  readonly agentId?: string;
 }
 ```