@owney/sdk 0.7.16 → 0.7.17-beta.1

package/dist/index.d.cts

@@ -65,6 +65,18 @@ type AgentSupportedAssets = {
     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;
+};
 type DailyApyDays = "7D" | "14D" | "30D";
 type HistoryFilters = {
     fromDate?: string;
@@ -174,11 +186,16 @@ interface OwneyMultiDepositResult {
 interface AgentWithdrawResult {
     txHash?: string;
     type: "full" | "partial";
+    /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
     amount: string;
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
-    totalWithdrawn: string;
+    /**
+     * Sum of reported smallest-unit amounts; null when a full withdrawal's
+     * amount is not yet known. An accepted request is not proof of settlement.
+     */
+    totalWithdrawn: string | null;
 }
 interface OwneyToken {
     chain: OwneySupportedChains;
@@ -242,6 +259,10 @@ interface OwneyBalances {
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
     agentBalances: Record<AgentId, AgentBalance>;
+    /** Omitted agents failed to load; they must not be interpreted as zero. */
+    agentErrors?: Record<AgentId, string>;
+    /** Absolute provider cooldown deadlines (Unix milliseconds). */
+    agentRetryAt?: Record<AgentId, number>;
 }
 interface AgentEarnings {
     smartWallet: `0x${string}`;
@@ -445,6 +466,9 @@ declare class OwneySDK {
     private cachedWethSponsoredCallback;
     private paymasterServiceUrl?;
     private cachedSponsoredCallsCallbacks;
+    private readonly agentReads;
+    private readonly activationChecks;
+    private readAgent;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -511,6 +535,11 @@ declare class OwneySDK {
     private applyOrgPolicyTo;
     private ensureAgentsInitialized;
     private createAgent;
+    /**
+     * Discover the agents actually returned by routing for this organization.
+     * Consumers should use this instead of hardcoding a global agent roster.
+     */
+    getAvailableAgents(options?: AvailableAgentsOptions): Promise<AvailableAgent[]>;
     /**
      * 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.
@@ -542,7 +571,7 @@ declare class OwneySDK {
      */
     private activateAgentsInTurn;
     /**
-     * Deposit funds into a specific agent, or split equally across all agents if agentId is omitted.
+     * Deposit into a specific agent, or distribute across all eligible agents.
      * Validates that the asset is supported and amount meets minimums for the target agent(s).
      * @param options - Deposit parameters
      * @param options.amount - Amount to deposit in smallest unit (e.g. "100000000" for 100 USDC)
@@ -550,7 +579,8 @@ declare class OwneySDK {
      * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
      *   When agentId is omitted, this callback is invoked once per eligible agent with that agent's
      *   split amount and smart wallet address — expect multiple wallet prompts.
-     * @param options.agentId - Optional. Target agent. Omit to split equally across all agents.
+     * @param options.agentId - Optional explicit target. Otherwise split equally,
+     *   or fund remaining agents when a recovery deposit cannot meet every minimum.
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
      */
     deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
@@ -692,7 +722,7 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -758,4 +788,4 @@ type OwneySIWXConfig = {
  */
 declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
 
-export { type AccountAgentApy, type AccountApyOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type ConnectionState, type DailyApyDays, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type RebalanceLog, type WithdrawOptions, createOwneySIWX, setOwneyDebug };
+export { type AccountAgentApy, type AccountApyOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type RebalanceLog, type WithdrawOptions, createOwneySIWX, setOwneyDebug };

package/dist/index.d.ts

@@ -65,6 +65,18 @@ type AgentSupportedAssets = {
     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;
+};
 type DailyApyDays = "7D" | "14D" | "30D";
 type HistoryFilters = {
     fromDate?: string;
@@ -174,11 +186,16 @@ interface OwneyMultiDepositResult {
 interface AgentWithdrawResult {
     txHash?: string;
     type: "full" | "partial";
+    /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
     amount: string;
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
-    totalWithdrawn: string;
+    /**
+     * Sum of reported smallest-unit amounts; null when a full withdrawal's
+     * amount is not yet known. An accepted request is not proof of settlement.
+     */
+    totalWithdrawn: string | null;
 }
 interface OwneyToken {
     chain: OwneySupportedChains;
@@ -242,6 +259,10 @@ interface OwneyBalances {
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
     agentBalances: Record<AgentId, AgentBalance>;
+    /** Omitted agents failed to load; they must not be interpreted as zero. */
+    agentErrors?: Record<AgentId, string>;
+    /** Absolute provider cooldown deadlines (Unix milliseconds). */
+    agentRetryAt?: Record<AgentId, number>;
 }
 interface AgentEarnings {
     smartWallet: `0x${string}`;
@@ -445,6 +466,9 @@ declare class OwneySDK {
     private cachedWethSponsoredCallback;
     private paymasterServiceUrl?;
     private cachedSponsoredCallsCallbacks;
+    private readonly agentReads;
+    private readonly activationChecks;
+    private readAgent;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -511,6 +535,11 @@ declare class OwneySDK {
     private applyOrgPolicyTo;
     private ensureAgentsInitialized;
     private createAgent;
+    /**
+     * Discover the agents actually returned by routing for this organization.
+     * Consumers should use this instead of hardcoding a global agent roster.
+     */
+    getAvailableAgents(options?: AvailableAgentsOptions): Promise<AvailableAgent[]>;
     /**
      * 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.
@@ -542,7 +571,7 @@ declare class OwneySDK {
      */
     private activateAgentsInTurn;
     /**
-     * Deposit funds into a specific agent, or split equally across all agents if agentId is omitted.
+     * Deposit into a specific agent, or distribute across all eligible agents.
      * Validates that the asset is supported and amount meets minimums for the target agent(s).
      * @param options - Deposit parameters
      * @param options.amount - Amount to deposit in smallest unit (e.g. "100000000" for 100 USDC)
@@ -550,7 +579,8 @@ declare class OwneySDK {
      * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
      *   When agentId is omitted, this callback is invoked once per eligible agent with that agent's
      *   split amount and smart wallet address — expect multiple wallet prompts.
-     * @param options.agentId - Optional. Target agent. Omit to split equally across all agents.
+     * @param options.agentId - Optional explicit target. Otherwise split equally,
+     *   or fund remaining agents when a recovery deposit cannot meet every minimum.
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
      */
     deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
@@ -692,7 +722,7 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -758,4 +788,4 @@ type OwneySIWXConfig = {
  */
 declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
 
-export { type AccountAgentApy, type AccountApyOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type ConnectionState, type DailyApyDays, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type RebalanceLog, type WithdrawOptions, createOwneySIWX, setOwneyDebug };
+export { type AccountAgentApy, type AccountApyOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type RebalanceLog, type WithdrawOptions, createOwneySIWX, setOwneyDebug };