@owney/sdk 0.7.0 → 0.7.1

package/dist/index.d.cts

@@ -21,6 +21,15 @@ interface OwneySDKConfig {
      * `createOwneySIWX` for apps that don't use the AppKit SIWX modal.
      */
     referralSource?: string;
+    /**
+     * Turn on the SDK's debug logging (default false). Traces the decisions that
+     * are otherwise invisible — notably how the organization's agent policy is
+     * compared against each user's Zyfai profile and whether it writes.
+     *
+     * Also switchable at runtime without a rebuild, which is what you want on an
+     * already-deployed app: set `globalThis.__OWNEY_DEBUG__ = true` in devtools.
+     */
+    debug?: boolean;
 }
 interface ConnectionState {
     provider: any;
@@ -101,6 +110,39 @@ type DepositOptions = {
     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;
@@ -253,6 +295,19 @@ interface AgentUserProfile {
     strategy?: string;
     hasActiveSessionKey: boolean;
     protocols: string[];
+    /**
+     * Capital splitting, as the agent currently has it (ROUT-229). Optional
+     * because not every agent has the concept — Sail omits both.
+     *
+     * `minSplits` is the field that carries the meaning: 1 means "split only when
+     * it beats a single pool", 2-4 means "force a split for diversification".
+     *
+     * Zyfai stores these PER ASSET. This profile read does not pass an asset, so
+     * these reflect the USDC bucket; a WETH-only user's real setting is not shown
+     * here.
+     */
+    splitting?: boolean;
+    minSplits?: number;
 }
 interface OwneyUserProfile {
     agentUserProfile: Record<AgentId, AgentUserProfile>;
@@ -275,6 +330,19 @@ interface IAgent {
     readonly supportedAssets: readonly AgentSupportedAssets[];
     disconnect(): Promise<void>;
     activateAgent(state: ConnectionState, chainId: number): Promise<void>;
+    /**
+     * Apply the organization's agent policy to this user's account.
+     *
+     * Optional: an agent that has no equivalent knob simply omits it, which is why
+     * this is not part of `activateAgent`'s signature. Declared on the interface
+     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
+     * ticket asks for a design that can also cover Surf, which has no adapter yet.
+     *
+     * Implementations must be **non-fatal**: this runs during activation as a side
+     * effect, so a failure has to leave the user connected and their profile
+     * unchanged rather than break the connect.
+     */
+    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
     deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
@@ -318,6 +386,8 @@ declare class OwneySDK {
     private disabledAgents;
     private state;
     private apiKey;
+    private orgAgentConfig;
+    private orgAgentConfigPromise;
     private zyfaiRpcUrls?;
     private routingApiBaseUrl?;
     private referralSource?;
@@ -366,6 +436,20 @@ declare class OwneySDK {
     private getDefaultWethSponsoredCallback;
     private getAgent;
     private getActiveAgents;
+    /**
+     * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
+     * throws — it degrades to null — so this cannot break activation.
+     */
+    private getOrgAgentConfig;
+    /**
+     * Apply the org policy to one agent, after it has activated.
+     *
+     * Sequenced after activation rather than alongside it because applying the
+     * policy needs the authenticated session activation establishes. Every failure
+     * mode is swallowed: a partner's splitting preference is not worth failing a
+     * user's connect over.
+     */
+    private applyOrgPolicyTo;
     private ensureAgentsInitialized;
     private createAgent;
     /**
@@ -555,6 +639,29 @@ declare class InvalidHistoryCursorError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Opt-in debug logging.
+ *
+ * The SDK is deliberately quiet: before this, `src/` contained no `console.log`
+ * at all, only `console.warn`/`console.error` for genuine faults. That is worth
+ * preserving — this runs inside every partner's app, on every user's connect, so
+ * unconditional chatter would land in end users' consoles forever.
+ *
+ * Two ways to turn it on:
+ *
+ *   1. From the app:        new OwneySDK({ apiKey, debug: true })
+ *   2. From devtools, live: globalThis.__OWNEY_DEBUG__ = true
+ *
+ * (2) is the useful one when diagnosing something on an already-deployed app:
+ * the flag is read on every call, not captured once, so flipping it in the
+ * console takes effect on the next action without a rebuild or a republish.
+ */
+declare global {
+    var __OWNEY_DEBUG__: boolean | undefined;
+}
+/** Enable/disable debug logging programmatically. */
+declare function setOwneyDebug(enabled: boolean): void;
+
 type OwneySIWXConfig = {
     /** Owney/Zyfai API key — same value passed to `new OwneySDK({ apiKey })`. */
     apiKey: string;
@@ -568,4 +675,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 };
+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 };

package/dist/index.d.ts

@@ -21,6 +21,15 @@ interface OwneySDKConfig {
      * `createOwneySIWX` for apps that don't use the AppKit SIWX modal.
      */
     referralSource?: string;
+    /**
+     * Turn on the SDK's debug logging (default false). Traces the decisions that
+     * are otherwise invisible — notably how the organization's agent policy is
+     * compared against each user's Zyfai profile and whether it writes.
+     *
+     * Also switchable at runtime without a rebuild, which is what you want on an
+     * already-deployed app: set `globalThis.__OWNEY_DEBUG__ = true` in devtools.
+     */
+    debug?: boolean;
 }
 interface ConnectionState {
     provider: any;
@@ -101,6 +110,39 @@ type DepositOptions = {
     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;
@@ -253,6 +295,19 @@ interface AgentUserProfile {
     strategy?: string;
     hasActiveSessionKey: boolean;
     protocols: string[];
+    /**
+     * Capital splitting, as the agent currently has it (ROUT-229). Optional
+     * because not every agent has the concept — Sail omits both.
+     *
+     * `minSplits` is the field that carries the meaning: 1 means "split only when
+     * it beats a single pool", 2-4 means "force a split for diversification".
+     *
+     * Zyfai stores these PER ASSET. This profile read does not pass an asset, so
+     * these reflect the USDC bucket; a WETH-only user's real setting is not shown
+     * here.
+     */
+    splitting?: boolean;
+    minSplits?: number;
 }
 interface OwneyUserProfile {
     agentUserProfile: Record<AgentId, AgentUserProfile>;
@@ -275,6 +330,19 @@ interface IAgent {
     readonly supportedAssets: readonly AgentSupportedAssets[];
     disconnect(): Promise<void>;
     activateAgent(state: ConnectionState, chainId: number): Promise<void>;
+    /**
+     * Apply the organization's agent policy to this user's account.
+     *
+     * Optional: an agent that has no equivalent knob simply omits it, which is why
+     * this is not part of `activateAgent`'s signature. Declared on the interface
+     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
+     * ticket asks for a design that can also cover Surf, which has no adapter yet.
+     *
+     * Implementations must be **non-fatal**: this runs during activation as a side
+     * effect, so a failure has to leave the user connected and their profile
+     * unchanged rather than break the connect.
+     */
+    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
     deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
@@ -318,6 +386,8 @@ declare class OwneySDK {
     private disabledAgents;
     private state;
     private apiKey;
+    private orgAgentConfig;
+    private orgAgentConfigPromise;
     private zyfaiRpcUrls?;
     private routingApiBaseUrl?;
     private referralSource?;
@@ -366,6 +436,20 @@ declare class OwneySDK {
     private getDefaultWethSponsoredCallback;
     private getAgent;
     private getActiveAgents;
+    /**
+     * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
+     * throws — it degrades to null — so this cannot break activation.
+     */
+    private getOrgAgentConfig;
+    /**
+     * Apply the org policy to one agent, after it has activated.
+     *
+     * Sequenced after activation rather than alongside it because applying the
+     * policy needs the authenticated session activation establishes. Every failure
+     * mode is swallowed: a partner's splitting preference is not worth failing a
+     * user's connect over.
+     */
+    private applyOrgPolicyTo;
     private ensureAgentsInitialized;
     private createAgent;
     /**
@@ -555,6 +639,29 @@ declare class InvalidHistoryCursorError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Opt-in debug logging.
+ *
+ * The SDK is deliberately quiet: before this, `src/` contained no `console.log`
+ * at all, only `console.warn`/`console.error` for genuine faults. That is worth
+ * preserving — this runs inside every partner's app, on every user's connect, so
+ * unconditional chatter would land in end users' consoles forever.
+ *
+ * Two ways to turn it on:
+ *
+ *   1. From the app:        new OwneySDK({ apiKey, debug: true })
+ *   2. From devtools, live: globalThis.__OWNEY_DEBUG__ = true
+ *
+ * (2) is the useful one when diagnosing something on an already-deployed app:
+ * the flag is read on every call, not captured once, so flipping it in the
+ * console takes effect on the next action without a rebuild or a republish.
+ */
+declare global {
+    var __OWNEY_DEBUG__: boolean | undefined;
+}
+/** Enable/disable debug logging programmatically. */
+declare function setOwneyDebug(enabled: boolean): void;
+
 type OwneySIWXConfig = {
     /** Owney/Zyfai API key — same value passed to `new OwneySDK({ apiKey })`. */
     apiKey: string;
@@ -568,4 +675,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 };
+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 };