@owney/sdk 0.7.7 → 0.7.9

package/README.md

@@ -263,6 +263,25 @@ console.log(allEarnings.agentEarnings.zyfai.lifetimeEarnings); // 42.5
 console.log(allEarnings.agentEarnings.zyfai.tokens); // per-chain, per-asset breakdown
 ```
 
+### `refreshEarnings(agentId?)`
+
+Refresh earnings for agents whose earnings data may be outdated. If the latest
+snapshot is less than one hour old, the SDK returns it without recalculating.
+
+| Param     | Type                 | Description                          |
+| --------- | -------------------- | ------------------------------------ |
+| `agentId` | `"zyfai"` (optional) | Agent to refresh. Omit for all agents. |
+
+Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
+
+```typescript
+// Single agent
+const refreshed = await sdk.refreshEarnings("zyfai");
+
+// All agents
+const allRefreshed = await sdk.refreshEarnings();
+```
+
 ### `getAccountApy({ agentId?, days })`
 
 Get the weighted APY for the user's account. When querying all agents, the total APY is a balance-weighted average.

package/dist/index.cjs

@@ -250,9 +250,10 @@ function mapBalances(raw, _chainId, smartWallet) {
   const tokens = [];
   for (const [chainIdKey, tokensBySymbol] of Object.entries(portfolioByChain)) {
     const positionChainId = Number(chainIdKey);
-    for (const [symbol, { balance, balanceWithFee, decimals }] of Object.entries(
-      tokensBySymbol ?? {}
-    )) {
+    for (const [
+      symbol,
+      { balance, balanceWithFee, decimals }
+    ] of Object.entries(tokensBySymbol ?? {})) {
       const amount = hexToDecimal(balanceWithFee ?? balance ?? "0", decimals);
       totalBalance += amount;
       tokens.push({
@@ -391,6 +392,11 @@ function mapEntries(rawEntries, chainId) {
     "Top up wallet": "Top up",
     "Partial withdraw from protocol": "Withdraw",
     "Withdraw from protocol": "Withdraw",
+    // The agent's own leg of a top up: the funds the user sent moving into the
+    // pool that earns the APY. Zyfai emits it as a separate entry seconds after
+    // "Top up wallet" and for slightly less (gas). `Deposit` already exists in
+    // the public HistoryAction union, so no consumer type change is needed.
+    "Deposit to protocol": "Deposit",
     Rebalance: "Rebalance"
   };
   void chainId;
@@ -431,12 +437,19 @@ function mapEntries(rawEntries, chainId) {
     const mappedAction = (entry.action ? actionMap[entry.action] : void 0) ?? entry.action;
     const rawAmount = entry?.positions?.[0]?.amount;
     const hasAmount = mappedAction !== "Withdraw" && typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
+    const mappedPositions = positions.filter((p) => p.protocol_name).map((p) => ({
+      protocol: p.protocol_name,
+      pool: p.pool ?? void 0,
+      tokenSymbol: p.token_symbol ?? void 0,
+      amount: mappedAction !== "Withdraw" && typeof p.amount === "string" && p.amount !== "" && p.amount !== "0x" ? String(hexToDecimal(p.amount, tokenDecimals(p.token_symbol))) : void 0
+    }));
     return {
       agent: "zyfai",
       action: mappedAction,
       date: entry.date || "",
       newApy: newApy === null ? null : String(newApy),
       oldApy: oldApy === null ? null : String(oldApy),
+      ...mappedPositions.length ? { positions: mappedPositions } : {},
       transactions: [
         {
           txHashes: entry.transactionHash ? [entry.transactionHash] : [],
@@ -871,6 +884,7 @@ var WETH_ADDRESS_BY_CHAIN = {
 var VIEM_CHAIN = { 8453: import_chains.base, 42161: import_chains.arbitrum, 1: import_chains.mainnet };
 var SPLITTING_ASSETS = ["USDC", "WETH"];
 var POOL_POLICY_CHAIN_IDS = [8453, 42161, 1];
+var EARNINGS_REFRESH_COOLDOWN_MS = 60 * 60 * 1e3;
 var ZyfaiAgent = class {
   id = "zyfai";
   supportedChainIds = [8453, 42161, 1];
@@ -922,6 +936,7 @@ var ZyfaiAgent = class {
   // successful decode is cached forever; failures are NOT cached so a transient
   // RPC error retries on the next fetch.
   withdrawAmountCache = /* @__PURE__ */ new Map();
+  earningsRefreshInFlight = null;
   constructor(apiKey, rpcUrls, referralSource) {
     this.rpcUrls = rpcUrls ?? DEFAULT_ZYFAI_RPC_URLS;
     this.sdk = new import_sdk.ZyfaiSDK({
@@ -1719,6 +1734,22 @@ var ZyfaiAgent = class {
     const raw = await this.sdk.getOnchainEarnings(smartWallet);
     return mapEarnings(raw, smartWallet);
   }
+  async refreshEarnings(state, chainId) {
+    if (this.earningsRefreshInFlight) return this.earningsRefreshInFlight;
+    this.earningsRefreshInFlight = (async () => {
+      const { smartWallet } = await this.resolveSmartWallet(state, chainId);
+      const current = await this.sdk.getOnchainEarnings(smartWallet);
+      const lastCheck = current.data.lastCheckTimestamp ? Date.parse(current.data.lastCheckTimestamp) : Number.NaN;
+      const isFresh = Number.isFinite(lastCheck) && Date.now() - lastCheck < EARNINGS_REFRESH_COOLDOWN_MS;
+      const earnings = isFresh ? current : await this.sdk.calculateOnchainEarnings(smartWallet);
+      return mapEarnings(earnings, smartWallet);
+    })();
+    try {
+      return await this.earningsRefreshInFlight;
+    } finally {
+      this.earningsRefreshInFlight = null;
+    }
+  }
   async getAccountApy(state, chainId, days, tokenSymbol) {
     const { smartWallet } = await this.resolveSmartWallet(state, chainId);
     const raw = await this.sdk.getDailyApyHistory(smartWallet, days);
@@ -1743,7 +1774,7 @@ var ZyfaiAgent = class {
         toDate
       });
       raw.data.forEach((entry, idx) => {
-        if (entry.chainId === validChainId && entry.action !== "Deposit to protocol") {
+        if (entry.chainId === validChainId) {
           matched.push({ entry, rawIdx: offset + idx });
         }
       });
@@ -3419,6 +3450,28 @@ var OwneySDK = class {
       agentEarnings: results
     };
   }
+  /**
+   * Return refreshed earnings while letting each agent own its refresh policy.
+   * Agents without a refresh capability fall back to their current snapshot.
+   */
+  async refreshEarnings(agentId) {
+    const state = this.requireState();
+    const chainId = this.requireChainId();
+    const refreshAgent = (agent) => agent.refreshEarnings?.(state, chainId) ?? agent.getEarnings(state, chainId);
+    if (agentId) return refreshAgent(this.getAgent(agentId));
+    let totalEarnings = 0;
+    const agentEarnings = {};
+    const refreshed = await Promise.all(
+      [...this.getActiveAgents().entries()].map(
+        async ([id, agent]) => [id, await refreshAgent(agent)]
+      )
+    );
+    for (const [id, earnings] of refreshed) {
+      agentEarnings[id] = earnings;
+      totalEarnings += Number(earnings.lifetimeEarnings);
+    }
+    return { totalEarnings: String(totalEarnings), agentEarnings };
+  }
   /**
    * Get the weighted APY for the user's account over a time period.
    * When querying all agents, the total APY is a balance-weighted average.

package/dist/index.d.cts

@@ -383,6 +383,11 @@ interface IAgent {
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
     getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    /**
+     * Refresh the agent's earnings snapshot when its backend supports doing so.
+     * Implementations own freshness and request-deduplication policy.
+     */
+    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
     getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
     /**
      * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
@@ -581,6 +586,11 @@ declare class OwneySDK {
      * @returns {AgentEarnings} for a single agent, or {OwneyEarnings} with totalEarnings and per-agent breakdown
      */
     getEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
+    /**
+     * Return refreshed earnings while letting each agent own its refresh policy.
+     * Agents without a refresh capability fall back to their current snapshot.
+     */
+    refreshEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
     /**
      * Get the weighted APY for the user's account over a time period.
      * When querying all agents, the total APY is a balance-weighted average.

package/dist/index.d.ts

@@ -383,6 +383,11 @@ interface IAgent {
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
     getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    /**
+     * Refresh the agent's earnings snapshot when its backend supports doing so.
+     * Implementations own freshness and request-deduplication policy.
+     */
+    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
     getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
     /**
      * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
@@ -581,6 +586,11 @@ declare class OwneySDK {
      * @returns {AgentEarnings} for a single agent, or {OwneyEarnings} with totalEarnings and per-agent breakdown
      */
     getEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
+    /**
+     * Return refreshed earnings while letting each agent own its refresh policy.
+     * Agents without a refresh capability fall back to their current snapshot.
+     */
+    refreshEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
     /**
      * Get the weighted APY for the user's account over a time period.
      * When querying all agents, the total APY is a balance-weighted average.

package/dist/index.js

@@ -217,9 +217,10 @@ function mapBalances(raw, _chainId, smartWallet) {
   const tokens = [];
   for (const [chainIdKey, tokensBySymbol] of Object.entries(portfolioByChain)) {
     const positionChainId = Number(chainIdKey);
-    for (const [symbol, { balance, balanceWithFee, decimals }] of Object.entries(
-      tokensBySymbol ?? {}
-    )) {
+    for (const [
+      symbol,
+      { balance, balanceWithFee, decimals }
+    ] of Object.entries(tokensBySymbol ?? {})) {
       const amount = hexToDecimal(balanceWithFee ?? balance ?? "0", decimals);
       totalBalance += amount;
       tokens.push({
@@ -358,6 +359,11 @@ function mapEntries(rawEntries, chainId) {
     "Top up wallet": "Top up",
     "Partial withdraw from protocol": "Withdraw",
     "Withdraw from protocol": "Withdraw",
+    // The agent's own leg of a top up: the funds the user sent moving into the
+    // pool that earns the APY. Zyfai emits it as a separate entry seconds after
+    // "Top up wallet" and for slightly less (gas). `Deposit` already exists in
+    // the public HistoryAction union, so no consumer type change is needed.
+    "Deposit to protocol": "Deposit",
     Rebalance: "Rebalance"
   };
   void chainId;
@@ -398,12 +404,19 @@ function mapEntries(rawEntries, chainId) {
     const mappedAction = (entry.action ? actionMap[entry.action] : void 0) ?? entry.action;
     const rawAmount = entry?.positions?.[0]?.amount;
     const hasAmount = mappedAction !== "Withdraw" && typeof rawAmount === "string" && rawAmount !== "" && rawAmount !== "0x" && rawAmount !== "0x0" && rawAmount !== "0";
+    const mappedPositions = positions.filter((p) => p.protocol_name).map((p) => ({
+      protocol: p.protocol_name,
+      pool: p.pool ?? void 0,
+      tokenSymbol: p.token_symbol ?? void 0,
+      amount: mappedAction !== "Withdraw" && typeof p.amount === "string" && p.amount !== "" && p.amount !== "0x" ? String(hexToDecimal(p.amount, tokenDecimals(p.token_symbol))) : void 0
+    }));
     return {
       agent: "zyfai",
       action: mappedAction,
       date: entry.date || "",
       newApy: newApy === null ? null : String(newApy),
       oldApy: oldApy === null ? null : String(oldApy),
+      ...mappedPositions.length ? { positions: mappedPositions } : {},
       transactions: [
         {
           txHashes: entry.transactionHash ? [entry.transactionHash] : [],
@@ -838,6 +851,7 @@ var WETH_ADDRESS_BY_CHAIN = {
 var VIEM_CHAIN = { 8453: base, 42161: arbitrum, 1: mainnet };
 var SPLITTING_ASSETS = ["USDC", "WETH"];
 var POOL_POLICY_CHAIN_IDS = [8453, 42161, 1];
+var EARNINGS_REFRESH_COOLDOWN_MS = 60 * 60 * 1e3;
 var ZyfaiAgent = class {
   id = "zyfai";
   supportedChainIds = [8453, 42161, 1];
@@ -889,6 +903,7 @@ var ZyfaiAgent = class {
   // successful decode is cached forever; failures are NOT cached so a transient
   // RPC error retries on the next fetch.
   withdrawAmountCache = /* @__PURE__ */ new Map();
+  earningsRefreshInFlight = null;
   constructor(apiKey, rpcUrls, referralSource) {
     this.rpcUrls = rpcUrls ?? DEFAULT_ZYFAI_RPC_URLS;
     this.sdk = new ZyfaiSDK({
@@ -1686,6 +1701,22 @@ var ZyfaiAgent = class {
     const raw = await this.sdk.getOnchainEarnings(smartWallet);
     return mapEarnings(raw, smartWallet);
   }
+  async refreshEarnings(state, chainId) {
+    if (this.earningsRefreshInFlight) return this.earningsRefreshInFlight;
+    this.earningsRefreshInFlight = (async () => {
+      const { smartWallet } = await this.resolveSmartWallet(state, chainId);
+      const current = await this.sdk.getOnchainEarnings(smartWallet);
+      const lastCheck = current.data.lastCheckTimestamp ? Date.parse(current.data.lastCheckTimestamp) : Number.NaN;
+      const isFresh = Number.isFinite(lastCheck) && Date.now() - lastCheck < EARNINGS_REFRESH_COOLDOWN_MS;
+      const earnings = isFresh ? current : await this.sdk.calculateOnchainEarnings(smartWallet);
+      return mapEarnings(earnings, smartWallet);
+    })();
+    try {
+      return await this.earningsRefreshInFlight;
+    } finally {
+      this.earningsRefreshInFlight = null;
+    }
+  }
   async getAccountApy(state, chainId, days, tokenSymbol) {
     const { smartWallet } = await this.resolveSmartWallet(state, chainId);
     const raw = await this.sdk.getDailyApyHistory(smartWallet, days);
@@ -1710,7 +1741,7 @@ var ZyfaiAgent = class {
         toDate
       });
       raw.data.forEach((entry, idx) => {
-        if (entry.chainId === validChainId && entry.action !== "Deposit to protocol") {
+        if (entry.chainId === validChainId) {
           matched.push({ entry, rawIdx: offset + idx });
         }
       });
@@ -3390,6 +3421,28 @@ var OwneySDK = class {
       agentEarnings: results
     };
   }
+  /**
+   * Return refreshed earnings while letting each agent own its refresh policy.
+   * Agents without a refresh capability fall back to their current snapshot.
+   */
+  async refreshEarnings(agentId) {
+    const state = this.requireState();
+    const chainId = this.requireChainId();
+    const refreshAgent = (agent) => agent.refreshEarnings?.(state, chainId) ?? agent.getEarnings(state, chainId);
+    if (agentId) return refreshAgent(this.getAgent(agentId));
+    let totalEarnings = 0;
+    const agentEarnings = {};
+    const refreshed = await Promise.all(
+      [...this.getActiveAgents().entries()].map(
+        async ([id, agent]) => [id, await refreshAgent(agent)]
+      )
+    );
+    for (const [id, earnings] of refreshed) {
+      agentEarnings[id] = earnings;
+      totalEarnings += Number(earnings.lifetimeEarnings);
+    }
+    return { totalEarnings: String(totalEarnings), agentEarnings };
+  }
   /**
    * Get the weighted APY for the user's account over a time period.
    * When querying all agents, the total APY is a balance-weighted average.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owney/sdk",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",