@owney/sdk 0.7.28-beta.3 → 0.7.32-beta.1

package/README.md

@@ -14,12 +14,15 @@ npm install @owney/sdk
 import { OwneySDK } from "@owney/sdk";
 
 // Create the SDK instance
-const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
 
 // Connect with an EIP-1193 wallet provider
 await sdk.connect(provider);
 
-// Activate agents on Base (fetches agent keys on first call)
+// Activate agents on Base (creates and initializes provider wallets as needed)
 await sdk.activateAgent(8453);
 
 // Get balances across all agents
@@ -32,36 +35,79 @@ const balances = await sdk.getBalances();
 
 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 |
-| `config.zyfaiRpcUrls` | `{ 8453?: string; 42161?: string }` (optional) | Per-chain RPC URL overrides used by Zyfai SDK network calls                                 |
+| Param                                   | Type                                                        | Description                                                                                       |
+| --------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `config.apiKey`                         | `string`                                                    | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys       |
+| `config.routingApiBaseUrl`              | `string` (optional)                                         | Routing API URL; required for proxy reads unless the SDK build has `OWNEY_ROUTING_API_BASE_URL` or all `rpcUrls` are set |
+| `config.rpcUrls`                        | `{ 1?: string; 8453?: string; 42161?: string }` (optional)  | Per-chain RPC overrides used by agent reads and transaction-receipt polling                       |
+| `config.zyfaiRpcUrls`                   | Same as `rpcUrls` (deprecated)                              | Legacy Zyfai-only override; use `rpcUrls` for all application-owned reads                         |
 
 ```typescript
 import { OwneySDK } from "@owney/sdk";
 
-const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
 ```
 
-#### Custom Zyfai RPC URLs
+#### Dedicated RPC URLs
+
+Use `rpcUrls` for application-owned chain reads and transaction-receipt
+polling. The connected wallet provider remains responsible for accounts, chain
+switching, signatures, and transaction submission.
 
-Use `zyfaiRpcUrls` to override Zyfai SDK RPC endpoints (for example, to avoid public endpoint rate limits).
+`rpcUrls` is optional. The SDK resolves an endpoint independently for each
+supported chain using this precedence:
+
+1. The caller-provided `rpcUrls[chainId]`, when present and non-empty.
+2. The Owney routing API read-only RPC proxy for that chain.
+
+The Alchemy credential stays on the routing API server. The SDK sends its
+existing organization key to the proxy for per-organization rate limiting.
+The proxy base URL must be provided through `routingApiBaseUrl` or the SDK
+build's `OWNEY_ROUTING_API_BASE_URL`; there is no hardcoded production fallback.
 
 ```typescript
+// All supported chains use the Owney routing API proxy.
 const sdk = new OwneySDK({
   apiKey: "your-owney-api-key",
-  zyfaiRpcUrls: {
-    8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
-    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
+  routingApiBaseUrl: "https://your-routing-api.example",
+});
+```
+
+Overrides can be complete or partial:
+
+```typescript
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  routingApiBaseUrl: "https://your-routing-api.example",
+  rpcUrls: {
+    // Ethereum and Arbitrum continue using the routing API proxy.
+    8453: "https://your-own-rpc.example/rpc",
   },
 });
 ```
 
+The resolved URLs are shared across Owney-owned reads and agent integrations:
+
+- Wagmi or application transports remain the consuming application's
+  responsibility; Owney mini-apps configure them from the same URL map.
+- Zyfai receives the resolved Owney URL map, so its internal provider defaults
+  do not determine routing for Owney SDK consumers.
+- Yieldseeker uses the resolved Base URL for transaction-receipt polling.
+- Balance, allowance, module-state, and receipt reads use the resolved RPC.
+- Account access, chain switching, signatures, approvals, and transaction
+  submission continue through the connected wallet provider.
+
 Notes:
 
-- These overrides are used by Zyfai SDK flows only.
-- If omitted, Zyfai SDK uses its default RPC endpoints.
-- Other app-level RPC clients (for example, direct viem calls outside Zyfai) are configured separately.
+- Owney mini-apps pass the same routing API proxy URLs to Wagmi and the SDK.
+- SDK consumers may override endpoints if they operate their own RPC provider.
+- Partial maps override only the supplied chains; missing chains use Owney's
+  routing API proxy.
+- HTTP reads use bounded retries and honor provider `Retry-After` responses.
+- `zyfaiRpcUrls` remains available for compatibility but applies only to Zyfai.
 
 ### `connect(provider)`
 
@@ -108,7 +154,7 @@ if (chainId) {
 
 ### `activateAgent(chainId, agentId?)`
 
-Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Smart wallets are pre-deployed by the underlying providers, so activation only performs authentication and profile syncing — no deploy or session-key signatures. Saves the chainId for use by all subsequent SDK calls.
+Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Activation performs each provider's required setup before deposits are allowed. For Yieldseeker, this creates the user and agent when needed and calls the agent `/deploy` endpoint before any funding transfer. Saves the chainId for use by all subsequent SDK calls.
 
 | Param     | Type                   | Description                                                                   |
 | --------- | ---------------------- | ----------------------------------------------------------------------------- |
@@ -125,7 +171,7 @@ 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, and per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) are taken into account. When splitting across agents, `depositCallback` is invoked once per final valid agent with that agent's split amount and smart wallet address — expect multiple wallet prompts.
+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, and per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) are taken into account. Custom `depositCallback` implementations run once per final valid agent. The default Permit2 flow signs one recipient-bound batch authorization for every agent share. On the first Base USDC deposit, the SDK first requests an ERC-2612 signature; the relayer then submits the Permit2 approval and deposit as two sponsored transactions. Later deposits need only the batch signature.
 
 | Param                     | Type                 | Description                                                     |
 | ------------------------- | -------------------- | --------------------------------------------------------------- |
@@ -134,6 +180,13 @@ Deposit funds into a specific agent, or split equally across all agents if `agen
 | `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.          |
 
+Zyfai's native transfer path uses `sendDeposit()`. It returns after the token
+transfer confirms and the deposit is registered, while balance credit may still
+be queued. Balance reads reflect subsequent credit and allocation; the deposit
+call does not wait for `waitForDepositCredit()`.
+A successful deposit result confirms the transfer; it does not guarantee that
+the funds are already credited or earning yield.
+
 Returns: `OwneyDepositResult` (single agent) or `OwneyMultiDepositResult` (all agents)
 
 ```typescript
@@ -218,6 +271,10 @@ Balances are shown after any applicable performance fees have been deducted.
 
 Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
 
+Aggregate reads keep successful agents when another agent fails. The response
+includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
+The SDK throws `BALANCE_ALL_FAILED` when every active agent fails.
+
 ```typescript
 // Single agent
 const balance = await sdk.getBalances("zyfai");
@@ -245,6 +302,10 @@ Earnings are shown after any applicable performance fees have been deducted.
 
 Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
 
+Aggregate reads keep successful agents when another agent fails. The response
+includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
+The SDK throws `EARNINGS_ALL_FAILED` when every active agent fails.
+
 ```typescript
 // Single agent
 const earnings = await sdk.getEarnings("zyfai");
@@ -274,6 +335,9 @@ snapshot is less than one hour old, the SDK returns it without recalculating.
 
 Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
 
+Aggregate refreshes use the same partial-result and all-failed behavior as
+`getEarnings()`.
+
 ```typescript
 // Single agent
 const refreshed = await sdk.refreshEarnings("zyfai");
@@ -439,8 +503,8 @@ console.log(usdcBaseApy.agentApy.zyfai.averageApy); // APY scoped to USDC on Bas
 type AgentId = "zyfai";
 type Asset = string;
 type DailyApyDays = "7D" | "14D" | "30D";
-type OwneySupportedChainId = 8453 | 42161;
-type OwneySupportedChains = "BASE" | "ARBITRUM";
+type OwneySupportedChainId = 1 | 8453 | 42161;
+type OwneySupportedChains = "ETHEREUM" | "BASE" | "ARBITRUM";
 type OwneySupportedTokens = "USDC" | "WETH";
 
 type AgentSupportedAsset = {
@@ -457,7 +521,14 @@ type AgentSupportedAssets = {
 
 interface OwneySDKConfig {
   apiKey: string;
+  rpcUrls?: {
+    1?: string;
+    8453?: string;
+    42161?: string;
+  };
+  /** @deprecated Use rpcUrls. */
   zyfaiRpcUrls?: {
+    1?: string;
     8453?: string;
     42161?: string;
   };
@@ -572,12 +643,14 @@ interface AccountAgentApy {
   weightedApyAfterFee?: number;
   weightedApyAfterFeeDetails?: AgentApyDetails;
   apyByChainAndAsset?: ApyByChainAndAsset;
+  history?: ApyHistoryPoint[];
 }
 
 interface OwneyAccountApy {
   totalApy: string;
   agentApy: Record<AgentId, AccountAgentApy>;
   apyByChainAndAsset: ApyByChainAndAsset;
+  history?: ApyHistoryPoint[]; // balance-weighted aggregate daily series
 }
 
 type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
@@ -719,6 +792,7 @@ type OwneyErrorCode =
   | "API_NO_AGENTS" // No supported agents returned by routing API
   // Aggregation
   | "BALANCE_ALL_FAILED" // All agents failed to return balances
+  | "EARNINGS_ALL_FAILED" // All agents failed to return earnings
   | "ALLOCATION_ALL_FAILED" // All agents failed to return allocation data
   // Validation
   | "VALIDATION_INVALID_DAYS"; // Invalid days value (expected "7D", "14D", or "30D")