@owney/sdk 0.7.25-beta.6 → 0.7.25-beta.8

package/dist/index.d.ts

@@ -8,7 +8,8 @@ interface OwneySDKConfig {
     apiKey: string;
     /**
      * Optional per-chain RPC overrides used for application-owned reads and
-     * transaction receipt polling. Missing chains use Owney SDK defaults.
+     * transaction receipt polling. Missing chains use the Owney routing API's
+     * read-only RPC proxy. No upstream RPC credentials are included in the SDK.
      * Wallet providers remain responsible for account access, chain switching,
      * signatures, and transaction submission.
      */
@@ -25,9 +26,9 @@ interface OwneySDKConfig {
     yieldseekerSiweOrigin?: string;
     /**
      * Optional override for the Owney routing API base URL used by all routing
-     * calls (defaults to the OWNEY_ROUTING_API_BASE_URL env var, then the
-     * production URL). Set this to point at a local/staging routing API,
-     * e.g. "http://localhost:3000", when testing sponsor changes.
+     * calls. RPC proxy requests use OWNEY_ROUTING_API_BASE_URL when this is
+     * omitted; without either value, all rpcUrls must be configured.
+     * Set this to a local/staging routing API when testing sponsor changes.
      */
     routingApiBaseUrl?: string;
     /**
@@ -69,148 +70,6 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
-type AgentId = "zyfai" | "yieldseeker";
-type Asset = string;
-type AgentSupportedAsset = {
-    readonly symbol: string;
-    readonly minDepositAmount: string;
-};
-type AgentSupportedAssets = {
-    readonly chainId: number;
-    readonly chain?: string;
-    readonly assets: readonly AgentSupportedAsset[];
-};
-type AvailableAgent = {
-    id: AgentId;
-    isEnabled: boolean;
-    supportedChainIds: readonly number[];
-    supportedAssets: readonly AgentSupportedAssets[];
-};
-type AvailableAgentsOptions = {
-    chainId?: number;
-    asset?: Asset;
-    /** Disabled agents are omitted by default because they cannot accept funds. */
-    includeDisabled?: boolean;
-};
-/**
- * A lookback window for any "last N days" read — the APY series, the daily
- * earnings series. Named for the window itself, so nothing borrows the APY's
- * name to ask for something else.
- */
-type LookbackDays = "7D" | "14D" | "30D";
-/** Kept so existing callers keep compiling. Prefer `LookbackDays`. */
-type DailyApyDays = LookbackDays;
-type HistoryFilters = {
-    fromDate?: string;
-    toDate?: string;
-    /** Max entries returned per call. Defaults to 10. */
-    limit?: number;
-    /** Opaque cursor returned by a previous getHistory call. */
-    cursor?: string;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the history to a
-     * single asset. Without it the page blends every asset on the chain, so a
-     * consumer showing one asset at a time has to filter client-side — and a
-     * page whose entries all belong to the *other* asset then renders empty
-     * even though matching entries exist further back. Agents whose backends
-     * cannot filter by asset ignore this and return the whole chain's history.
-     */
-    tokenSymbol?: string;
-};
-type HistoryOptions = {
-    agentId?: AgentId;
-    filters?: HistoryFilters;
-};
-type WithdrawOptions = {
-    asset: Asset;
-    amount?: string;
-    agentId?: AgentId;
-};
-type AccountApyOptions = {
-    agentId?: AgentId;
-    days: LookbackDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
-     * to a specific asset on the active chain. Without it the series blends every
-     * position on the chain, so two assets sharing a chain (USDC and WETH on
-     * Base/Arbitrum) would render one merged line. Agents whose backends do not
-     * expose per-asset positions ignore this. (ROUT-186)
-     */
-    tokenSymbol?: string;
-};
-/**
- * Options for the daily earnings series. Same shape as `AccountApyOptions` and
- * deliberately its own type: the two reads answer different questions and are
- * free to diverge.
- */
-type DailyEarningsOptions = {
-    agentId?: AgentId;
-    days: LookbackDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
-     * asset on the active chain.
-     */
-    tokenSymbol?: string;
-};
-type AllocationApyOptions = {
-    agentId?: AgentId;
-};
-type AgentsApyOptions = {
-    agentId?: AgentId;
-    days: DailyApyDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
-     * specific asset+chain. Ignored by agents whose backends do not yet
-     * support per-asset APY.
-     */
-    tokenSymbol?: string;
-    /**
-     * Optional chain id for per-asset APY lookups. Typically paired with
-     * `tokenSymbol`.
-     */
-    chainId?: number;
-};
-type DepositOptions = {
-    amount: string;
-    asset: Asset;
-    depositCallback?: DepositCallback;
-    agentId?: AgentId;
-    onApproved?: () => void;
-};
-
-/**
- * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
- * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
- * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
- * must not be normalised anywhere.
- *
- * An empty array means "no usable pools on this chain".
- */
-type OrgPoolSelection = {
-    protocolId: string;
-    chainId: number;
-    pools: string[];
-};
-/**
- * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
- * narrowed appear. Optional so an older routing API, which does not return the
- * field, still parses; undefined and null both mean "change nothing".
- */
-type OrgPoolPolicy = {
-    autoApproveProtocols: boolean;
-    autoApprovePools: boolean;
-    selections: OrgPoolSelection[];
-};
-/**
- * The organization's agent execution policy, or null when the partner has never
- * configured one — in which case the agents leave the user's profile alone.
- */
-type OrgAgentConfig = {
-    splittingMode: "none" | "automatic" | "force";
-    minSplits: number | null;
-    poolPolicy?: OrgPoolPolicy | null;
-};
-
 interface OwneyDepositResult {
     txHash: string;
     smartWallet: string;
@@ -247,8 +106,10 @@ interface OwneyPosition {
     pool?: string;
     asset: string;
     amount: string;
-    /** Smallest-unit amount when the provider exposes it alongside `amount`. */
+    /** Provider-native raw quantity; may represent vault shares, not the underlying asset. */
     amountRaw?: string;
+    /** Withdrawable underlying asset amount in that asset's smallest units. */
+    withdrawableAmountRaw?: string;
     apy?: number;
     tvl?: number;
     /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
@@ -481,6 +342,150 @@ interface AccountDailyEarnings {
     assets: AssetDailyEarnings[];
 }
 
+type AgentId = "zyfai" | "yieldseeker";
+type Asset = string;
+type AgentSupportedAsset = {
+    readonly symbol: string;
+    readonly minDepositAmount: string;
+};
+type AgentSupportedAssets = {
+    readonly chainId: number;
+    readonly chain?: string;
+    readonly assets: readonly AgentSupportedAsset[];
+};
+type AvailableAgent = {
+    id: AgentId;
+    isEnabled: boolean;
+    supportedChainIds: readonly number[];
+    supportedAssets: readonly AgentSupportedAssets[];
+};
+type AvailableAgentsOptions = {
+    chainId?: number;
+    asset?: Asset;
+    /** Disabled agents are omitted by default because they cannot accept funds. */
+    includeDisabled?: boolean;
+};
+/**
+ * A lookback window for any "last N days" read — the APY series, the daily
+ * earnings series. Named for the window itself, so nothing borrows the APY's
+ * name to ask for something else.
+ */
+type LookbackDays = "7D" | "14D" | "30D";
+/** Kept so existing callers keep compiling. Prefer `LookbackDays`. */
+type DailyApyDays = LookbackDays;
+type HistoryFilters = {
+    fromDate?: string;
+    toDate?: string;
+    /** Max entries returned per call. Defaults to 10. */
+    limit?: number;
+    /** Opaque cursor returned by a previous getHistory call. */
+    cursor?: string;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the history to a
+     * single asset. Without it the page blends every asset on the chain, so a
+     * consumer showing one asset at a time has to filter client-side — and a
+     * page whose entries all belong to the *other* asset then renders empty
+     * even though matching entries exist further back. Agents whose backends
+     * cannot filter by asset ignore this and return the whole chain's history.
+     */
+    tokenSymbol?: string;
+};
+type HistoryOptions = {
+    agentId?: AgentId;
+    filters?: HistoryFilters;
+};
+type WithdrawOptions = {
+    asset: Asset;
+    amount?: string;
+    agentId?: AgentId;
+    /** Called after each agent returns; callback failures never change a financial result. */
+    onAgentResult?: (agentId: AgentId, result: AgentWithdrawResult) => void;
+};
+type AccountApyOptions = {
+    agentId?: AgentId;
+    days: LookbackDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
+     * to a specific asset on the active chain. Without it the series blends every
+     * position on the chain, so two assets sharing a chain (USDC and WETH on
+     * Base/Arbitrum) would render one merged line. Agents whose backends do not
+     * expose per-asset positions ignore this. (ROUT-186)
+     */
+    tokenSymbol?: string;
+};
+/**
+ * Options for the daily earnings series. Same shape as `AccountApyOptions` and
+ * deliberately its own type: the two reads answer different questions and are
+ * free to diverge.
+ */
+type DailyEarningsOptions = {
+    agentId?: AgentId;
+    days: LookbackDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
+     * asset on the active chain.
+     */
+    tokenSymbol?: string;
+};
+type AllocationApyOptions = {
+    agentId?: AgentId;
+};
+type AgentsApyOptions = {
+    agentId?: AgentId;
+    days: DailyApyDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
+     * specific asset+chain. Ignored by agents whose backends do not yet
+     * support per-asset APY.
+     */
+    tokenSymbol?: string;
+    /**
+     * Optional chain id for per-asset APY lookups. Typically paired with
+     * `tokenSymbol`.
+     */
+    chainId?: number;
+};
+type DepositOptions = {
+    amount: string;
+    asset: Asset;
+    depositCallback?: DepositCallback;
+    agentId?: AgentId;
+    onApproved?: () => void;
+};
+
+/**
+ * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
+ * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
+ * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
+ * must not be normalised anywhere.
+ *
+ * An empty array means "no usable pools on this chain".
+ */
+type OrgPoolSelection = {
+    protocolId: string;
+    chainId: number;
+    pools: string[];
+};
+/**
+ * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
+ * narrowed appear. Optional so an older routing API, which does not return the
+ * field, still parses; undefined and null both mean "change nothing".
+ */
+type OrgPoolPolicy = {
+    autoApproveProtocols: boolean;
+    autoApprovePools: boolean;
+    selections: OrgPoolSelection[];
+};
+/**
+ * The organization's agent execution policy, or null when the partner has never
+ * configured one — in which case the agents leave the user's profile alone.
+ */
+type OrgAgentConfig = {
+    splittingMode: "none" | "automatic" | "force";
+    minSplits: number | null;
+    poolPolicy?: OrgPoolPolicy | null;
+};
+
 type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
 interface IAgent {
     readonly id: string;
@@ -909,6 +914,13 @@ declare class YieldseekerAgent implements IAgent {
     private readonly readCache;
     private readonly pendingReads;
     private readGeneration;
+    private readonly portfolioVersions;
+    private readonly snapshotFailures;
+    private readonly standardReadFailures;
+    private readonly reconcileUntil;
+    private readonly activityRefreshUntil;
+    private readonly snapshotMovements;
+    private readonly movementEpochs;
     private readonly yieldOptions;
     private readonly pendingYieldOptions;
     constructor(owneyApiKey: string, options?: YieldseekerAgentOptions);
@@ -926,6 +938,7 @@ declare class YieldseekerAgent implements IAgent {
     private loadYieldOptions;
     private userKey;
     private contextKey;
+    private assertSession;
     private cachedRead;
     private agentListKey;
     private listAgents;
@@ -936,6 +949,12 @@ declare class YieldseekerAgent implements IAgent {
     private findAgent;
     private resolveAgent;
     private loadPortfolio;
+    private portfolioVersion;
+    private portfolioCacheMs;
+    private snapshotMovement;
+    private advancePortfolioVersion;
+    private requestPortfolioSnapshot;
+    private portfolioSnapshot;
     private loadPortfolioContext;
     private deployAgent;
     private refreshSnapshotAfterMovement;