@owney/sdk 0.2.5

package/README.md

@@ -0,0 +1,584 @@
+# @owney/sdk
+
+A TypeScript SDK for interacting with DeFi yield agents. Supports multiple agent backends (Zyfai, Sail) through a unified interface.
+
+## Installation
+
+```bash
+npm install @owney/sdk
+```
+
+## Quick Start
+
+```typescript
+import { OwneySDK } from "@owney/sdk";
+
+// Create the SDK instance
+const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+
+// Connect with an EIP-1193 wallet provider
+await sdk.connect(provider);
+
+// Activate agents on Base (fetches agent keys on first call)
+await sdk.activateAgent(8453);
+
+// Get balances across all agents
+const balances = await sdk.getBalances();
+```
+
+## SDK Functions
+
+### `new OwneySDK(config)`
+
+Create a new SDK instance.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `config.apiKey` | `string` | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys |
+
+```typescript
+import { OwneySDK } from "@owney/sdk";
+
+const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+```
+
+### `connect(provider)`
+
+Establish connection state. Must be called before any wallet-dependent operation.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `provider` | EIP-1193 provider | Wallet provider (e.g. MetaMask, WalletConnect) |
+
+```typescript
+await sdk.connect(window.ethereum);
+```
+
+### `disconnect()`
+
+Disconnect from all agents and clear connection state.
+
+```typescript
+await sdk.disconnect();
+```
+
+### `isConnected()`
+
+Check if the SDK has an active connection.
+
+```typescript
+if (sdk.isConnected()) {
+  // safe to call wallet-dependent methods
+}
+```
+
+### `getActiveChainId()`
+
+Get the currently active chain ID, set by `activateAgent`.
+
+Returns: `number | null`
+
+```typescript
+const chainId = sdk.getActiveChainId();
+if (chainId) {
+  console.log(`Active on chain ${chainId}`);
+}
+```
+
+### `activateAgent(chainId, agentId?)`
+
+Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Deploys the Safe contract and creates a session key if not already set up. Saves the chainId for use by all subsequent SDK calls.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `chainId` | `number` | Target chain ID (e.g. `8453` for Base, `42161` for Arbitrum) |
+| `agentId` | `AgentId[]` (optional) | Agents to activate. Omit to activate all agents that support the given chain. |
+
+```typescript
+// Activate specific agents on Base
+await sdk.activateAgent(8453, ["zyfai", "sail"]);
+
+// Activate all agents that support Arbitrum
+await sdk.activateAgent(42161);
+```
+
+### `deposit(options)`
+
+Deposit funds into a specific agent, or split equally across all agents if `agentId` is omitted. Validates that the asset is supported by the target agent(s) on the active chain. When splitting across agents, `depositCallback` is invoked once per agent with that agent's split amount and smart wallet address — expect multiple wallet prompts.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `options.amount` | `string` | Amount in smallest unit (e.g. `"100000000"` for 100 USDC) |
+| `options.asset` | `string` | Asset symbol (e.g. `"USDC"`) |
+| `options.depositCallback` | `DepositCallback` | Callback that performs the token transfer and returns a tx hash |
+| `options.agentId` | `AgentId` (optional) | Target agent. Omit to split equally across all agents. |
+
+Returns: `OwneyDepositResult` (single agent) or `OwneyMultiDepositResult` (all agents)
+
+```typescript
+// Deposit to a specific agent
+const result = await sdk.deposit({
+  agentId: "zyfai",
+  amount: "100000000",
+  asset: "USDC",
+  depositCallback: async (smartWallet, chainId, amount) => {
+    const txHash = await transferTokens(smartWallet, amount);
+    return txHash;
+  },
+});
+console.log(result.txHash);       // "0x..."
+console.log(result.smartWallet);  // "0x..."
+console.log(result.amount);       // "100000000"
+
+// Split equally across all agents
+const results = await sdk.deposit({
+  amount: "100000000",
+  asset: "USDC",
+  depositCallback: async (smartWallet, chainId, amount) => {
+    return await transferTokens(smartWallet, amount);
+  },
+});
+console.log(results.agentResults.zyfai.amount);  // "50000000"
+console.log(results.agentResults.sail.amount);    // "50000000"
+```
+
+### `withdraw(options)`
+
+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.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `options.asset` | `string` | Asset symbol (e.g. `"USDC"`) |
+| `options.amount` | `string` (optional) | Amount to withdraw. Omit for full withdrawal. |
+| `options.agentId` | `AgentId` (optional) | Target agent. Omit to withdraw from all. |
+
+Returns: `AgentWithdrawResult` (single agent) or `OwneyWithdrawResult` (all agents)
+
+```typescript
+// Partial withdrawal from one agent
+const result = await sdk.withdraw({
+  asset: "USDC",
+  agentId: "zyfai",
+  amount: "50000000",
+});
+console.log(result.type);    // "partial"
+console.log(result.amount);  // "50000000"
+
+// Full withdrawal from all agents
+const results = await sdk.withdraw({ asset: "USDC" });
+console.log(results.agentResult.zyfai.type);  // "full"
+console.log(results.agentResult.sail.type);   // "full"
+```
+
+### `getBalances(agentId?)`
+
+Get the user's balances for a specific agent, or aggregated across all agents.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+
+Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
+
+```typescript
+// Single agent
+const balance = await sdk.getBalances("zyfai");
+console.log(balance.totalBalance);  // "150.25"
+console.log(balance.smartWallet);   // "0x..."
+console.log(balance.tokens);       // [{ chain: "BASE", chainId: 8453, asset: "USDC", amount: "150.25" }]
+
+// All agents
+const allBalances = await sdk.getBalances();
+console.log(allBalances.totalBalance);                    // "300.50"
+console.log(allBalances.agentBalances.zyfai.totalBalance); // "150.25"
+console.log(allBalances.agentBalances.sail.totalBalance);  // "150.25"
+```
+
+### `getEarnings(agentId?)`
+
+Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+
+Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
+
+```typescript
+// Single agent
+const earnings = await sdk.getEarnings("zyfai");
+console.log(earnings.smartWallet);       // "0x..."
+console.log(earnings.lifetimeEarnings);  // 42.5
+
+// All agents
+const allEarnings = await sdk.getEarnings();
+console.log(allEarnings.totalEarnings);                      // "85.0"
+console.log(allEarnings.agentEarnings.zyfai.lifetimeEarnings); // 42.5
+```
+
+### `getAccountApy({ agentId?, days })`
+
+Get the weighted APY for the user's account. When querying all agents, the total APY is a balance-weighted average.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for balance-weighted total. |
+| `days` | `"7D" \| "14D" \| "30D"` | Lookback period |
+
+Returns: `AccountAgentApy` (single agent) or `OwneyAccountApy` (all agents)
+
+```typescript
+// Single agent
+const apy = await sdk.getAccountApy({ agentId: "zyfai", days: "30D" });
+console.log(apy.walletAddress);       // "0x..."
+console.log(apy.weightedApyAfterFee); // 5.2
+
+// All agents (balance-weighted)
+const allApy = await sdk.getAccountApy({ days: "30D" });
+console.log(allApy.totalApy);                        // "5.6"
+console.log(allApy.agentApy.zyfai.weightedApyAfterFee); // 6.0
+console.log(allApy.agentApy.sail.weightedApyAfterFee);  // 4.0
+```
+
+### `getHistory({ agentId?, filters? })`
+
+Get transaction history for a specific agent, or all agents. When querying all agents, results are merged into a single list sorted by date (newest first). Each entry includes the originating `agent` and a `transactions` array with typed on-chain transaction details.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+| `filters.fromDate` | `string` (optional) | Start date (`YYYY-MM-DD`) |
+| `filters.toDate` | `string` (optional) | End date (`YYYY-MM-DD`) |
+
+Returns: `OwneyAgentHistory`
+
+```typescript
+// Single agent with filters
+const history = await sdk.getHistory({
+  agentId: "zyfai",
+  filters: { fromDate: "2025-01-01" },
+});
+console.log(history.total);                              // 42
+console.log(history.data[0].agent);                      // "zyfai"
+console.log(history.data[0].action);                     // "Rebalance"
+console.log(history.data[0].date);                       // "2025-03-15T12:00:00Z"
+console.log(history.data[0].transactions[0].txHashes);   // ["0x..."]
+console.log(history.data[0].transactions[0].amount);     // "100.00"
+console.log(history.data[0].transactions[0].tokenSymbol); // "USDC"
+
+// Rebalance logs show fund movement between protocols
+console.log(history.data[0].rebalanceLog[0].fromProtocol); // "Aave V3"
+console.log(history.data[0].rebalanceLog[0].toProtocol);   // "Morpho Blue"
+console.log(history.data[0].rebalanceLog[0].tokenSymbol);  // "USDC"
+console.log(history.data[0].rebalanceLog[0].amount);       // "100.00"
+console.log(history.data[0].rebalanceLog[0].status);       // "success"
+
+// All agents (merged and sorted by date)
+const allHistory = await sdk.getHistory();
+console.log(allHistory.total);            // 57
+console.log(allHistory.data[0].agent);    // "sail" (most recent entry)
+console.log(allHistory.data[0].action);   // "Rebalance"
+```
+
+### `pauseAgent(agentId)`
+
+Pause an agent's automated operations. The agent will stop rebalancing until resumed.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` | Agent to pause |
+
+Returns: `OwneyAgentStatus`
+
+```typescript
+const status = await sdk.pauseAgent("zyfai");
+console.log(status.success);  // true
+```
+
+### `resumeAgent(agentId)`
+
+Resume an agent's automated operations.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` | Agent to resume |
+
+Returns: `OwneyAgentStatus`
+
+```typescript
+const status = await sdk.resumeAgent("zyfai");
+console.log(status.success);    // true
+console.log(status.protocols);  // ["aave", "compound"]
+```
+
+### `getUserProfile(agentId?)`
+
+Get the user's profile for a specific agent, or all agents.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+
+Returns: `AgentUserProfile` (single agent) or `OwneyUserProfile` (all agents)
+
+```typescript
+// Single agent
+const profile = await sdk.getUserProfile("zyfai");
+console.log(profile.address);             // "0x..."
+console.log(profile.smartWallet);         // "0x..."
+console.log(profile.chains);             // [8453]
+console.log(profile.hasActiveSessionKey); // true
+console.log(profile.protocols);          // ["aave", "compound"]
+
+// All agents
+const allProfiles = await sdk.getUserProfile();
+console.log(allProfiles.agentUserProfile.zyfai.smartWallet); // "0x..."
+console.log(allProfiles.agentUserProfile.sail.smartWallet);  // "0x..."
+```
+
+### `getAgentApy({ agentId?, days })`
+
+Get the agent's average APY performance over a time period. Does not require a wallet connection.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+| `days` | `"7D" \| "14D" \| "30D"` | Lookback period |
+
+Returns: `AgentApy` (single agent) or `OwneyAgentApy` (all agents)
+
+```typescript
+// Single agent
+const apy = await sdk.getAgentApy({ agentId: "zyfai", days: "30D" });
+console.log(apy.averageApy);  // 8.5
+
+// All agents
+const allApy = await sdk.getAgentApy({ days: "30D" });
+console.log(allApy.agentApy.zyfai.averageApy); // 8.5
+console.log(allApy.agentApy.sail.averageApy);  // 6.2
+```
+
+### `getAgentAllocation()`
+
+Get the current fund allocation percentages across agents.
+
+Returns: `OwneyAgentAllocation`
+
+```typescript
+const allocation = await sdk.getAgentAllocation();
+console.log(allocation.agentAllocation);  // { zyfai: 75, sail: 25 }
+```
+
+## Types
+
+### Configuration
+
+```typescript
+type AgentId = "zyfai" | "sail";
+type Asset = string;
+type DailyApyDays = "7D" | "14D" | "30D";
+type OwneySupportedChainId = 8453 | 42161;
+type OwneySupportedChains = "BASE" | "ARBITRUM";
+type OwneySupportedTokens = "USDC" | "USDT";
+
+type AgentSupportedAssets = {
+  readonly chainId: number;
+  readonly chain?: string;
+  readonly assets: readonly string[];
+};
+
+interface OwneySDKConfig {
+  apiKey: string;
+}
+
+interface ConnectionState {
+  provider: any;
+  walletAddress: `0x${string}`;
+  chainId: number | null;
+}
+
+type HistoryFilters = {
+  fromDate?: string;  // YYYY-MM-DD
+  toDate?: string;    // YYYY-MM-DD
+};
+
+type HistoryOptions = {
+  agentId?: AgentId;
+  filters?: HistoryFilters;
+};
+
+type DepositOptions = {
+  amount: string;
+  asset: Asset;
+  depositCallback: DepositCallback;
+  agentId?: AgentId;
+};
+
+type WithdrawOptions = {
+  asset: Asset;
+  amount?: string;
+  agentId?: AgentId;
+};
+
+type AccountApyOptions = {
+  agentId?: AgentId;
+  days: DailyApyDays;
+};
+
+type AgentsApyOptions = {
+  agentId?: AgentId;
+  days: DailyApyDays;
+};
+```
+
+### Response Types
+
+```typescript
+interface OwneyDepositResult {
+  txHash: string;
+  smartWallet: string;
+  amount: string;
+}
+
+interface OwneyMultiDepositResult {
+  agentResults: Record<string, OwneyDepositResult>;
+}
+
+interface AgentWithdrawResult {
+  txHash?: string;
+  type: "full" | "partial";
+  amount: string;
+}
+
+interface OwneyWithdrawResult {
+  agentResult: Record<AgentId, AgentWithdrawResult>;
+}
+
+interface OwneyToken {
+  chain: OwneySupportedChains;
+  chainId: OwneySupportedChainId;
+  asset: OwneySupportedTokens;
+  amount: string;
+}
+
+interface AgentBalance {
+  smartWallet?: `0x${string}`;
+  totalBalance: string;
+  tokens: OwneyToken[];
+}
+
+interface OwneyBalances {
+  totalBalance: string;
+  agentBalances: Record<AgentId, AgentBalance>;
+}
+
+interface AgentEarnings {
+  smartWallet: `0x${string}`;
+  lifetimeEarnings: number;
+}
+
+interface OwneyEarnings {
+  totalEarnings: string;
+  agentEarnings: Record<AgentId, AgentEarnings>;
+}
+
+interface AccountAgentApy {
+  walletAddress: string;
+  weightedApyAfterFee?: number;
+}
+
+interface OwneyAccountApy {
+  totalApy: string;
+  agentApy: Record<AgentId, AccountAgentApy>;
+}
+
+type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
+
+interface HistoryTransaction {
+  txHashes: string[];
+  chainId?: number;
+  tokenSymbol?: string;
+  amount?: string;
+}
+
+interface RebalanceLog {
+  fromProtocol: string;
+  toProtocol: string;
+  tokenSymbol: string;
+  amount: string;
+  status: "success" | "failed";
+}
+
+interface AgentHistoryEntry {
+  agent: AgentId;
+  action: HistoryAction;
+  date: string;
+  oldApy: string | null;
+  newApy: string | null;
+  transactions: HistoryTransaction[];
+  rebalanceLog: RebalanceLog[];
+}
+
+interface OwneyAgentHistory {
+  data: AgentHistoryEntry[];
+  total: number;
+}
+
+interface OwneyAgentStatus {
+  success: boolean;
+  strategy?: string;
+  protocols?: string[];
+}
+
+interface AgentUserProfile {
+  address: string;
+  smartWallet: string;
+  chains: number[];
+  strategy?: string;
+  hasActiveSessionKey: boolean;
+  protocols: string[];
+}
+
+interface OwneyUserProfile {
+  agentUserProfile: Record<AgentId, AgentUserProfile>;
+}
+
+interface AgentApy {
+  averageApy: number;
+}
+
+interface OwneyAgentApy {
+  agentApy: Record<AgentId, AgentApy>;
+}
+
+interface OwneyRouteResponse {
+  agent: AgentId;
+  chainId: number;
+}
+
+interface OwneyAgentAllocation {
+  agentAllocation: Record<AgentId, number>;
+}
+```
+
+### Callback Types
+
+```typescript
+type DepositCallback = (
+  smartWalletAddress: string,
+  chainId: number,
+  amount: string
+) => Promise<`0x${string}`> | `0x${string}`;
+```
+
+### Error Classes
+
+| 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. |
+
+## License
+
+MIT