@cygnus-wealth/data-models 1.1.1 → 1.2.0

package/dist/cjs/enums/AccountType.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountType = void 0;
+/**
+ * Classification of account types.
+ *
+ * Categorizes account containers for display, grouping, and business logic.
+ * Enables specialized UI components and processing based on account purpose
+ * and characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { AccountType } from '@cygnus-wealth/data-models';
+ *
+ * // Route account to specialized handler
+ * function processAccount(type: AccountType) {
+ *   switch(type) {
+ *     case AccountType.SPOT:
+ *       return processCEXSpotAccount();
+ *     case AccountType.WALLET:
+ *       return processWalletAccount();
+ *     case AccountType.DEFI:
+ *       return processDeFiPositions();
+ *     case AccountType.RETIREMENT:
+ *       return processTaxAdvantaged();
+ *     default:
+ *       return processGenericAccount();
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ */
+var AccountType;
+(function (AccountType) {
+    /** Spot trading account on centralized exchange */
+    AccountType["SPOT"] = "SPOT";
+    /** Margin trading account with leverage */
+    AccountType["MARGIN"] = "MARGIN";
+    /** Futures or derivatives trading account */
+    AccountType["FUTURES"] = "FUTURES";
+    /** Savings or interest-earning account */
+    AccountType["SAVINGS"] = "SAVINGS";
+    /** Staking account for proof-of-stake rewards */
+    AccountType["STAKING"] = "STAKING";
+    /** Self-custody blockchain wallet */
+    AccountType["WALLET"] = "WALLET";
+    /** DeFi protocol positions (lending, liquidity, etc.) */
+    AccountType["DEFI"] = "DEFI";
+    /** Traditional brokerage account */
+    AccountType["BROKERAGE"] = "BROKERAGE";
+    /** Tax-advantaged retirement account (IRA, 401k, etc.) */
+    AccountType["RETIREMENT"] = "RETIREMENT";
+    /** Other or unclassified account type */
+    AccountType["OTHER"] = "OTHER";
+})(AccountType || (exports.AccountType = AccountType = {}));

package/dist/cjs/enums/AssetType.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetType = void 0;
+/**
+ * Classification of financial asset types across all integration sources.
+ *
+ * AssetType provides standardized categorization for all tradeable, holdable, or
+ * stakeable instruments within the CygnusWealth ecosystem. This enum serves as
+ * the primary taxonomy for asset classification across CEX, DEX, traditional
+ * finance, and DeFi sources.
+ *
+ * **Design Rationale:**
+ * - Covers both traditional finance (stocks, bonds) and crypto (tokens, NFTs, DeFi positions)
+ * - Distinguishes between base assets and derivative/yield-generating positions
+ * - Extensible via OTHER for edge cases without breaking existing types
+ *
+ * **Integration Guidance:**
+ * - Integration domains should map external classifications to these types
+ * - When in doubt between similar types, prefer more specific (e.g., NFT over CRYPTOCURRENCY)
+ * - Use metadata field for preserving source-specific asset classifications
+ *
+ * @example
+ * ```typescript
+ * // Mapping external asset types
+ * function mapRobinhoodAsset(rhAsset: any): AssetType {
+ *   switch (rhAsset.type) {
+ *     case 'stock': return AssetType.STOCK;
+ *     case 'cryptocurrency': return AssetType.CRYPTOCURRENCY;
+ *     case 'etp': return AssetType.ETF;
+ *     default: return AssetType.OTHER;
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability core
+ *
+ * @see {@link Asset} for usage in asset models
+ */
+var AssetType;
+(function (AssetType) {
+    /**
+     * Fungible digital currencies and tokens (BTC, ETH, ERC-20 tokens, SPL tokens).
+     *
+     * Includes all blockchain-based fungible assets that serve as currencies or
+     * utility tokens. Does not include NFTs or DeFi positions (use specific types for those).
+     */
+    AssetType["CRYPTOCURRENCY"] = "CRYPTOCURRENCY";
+    /**
+     * Equity securities in publicly traded companies (AAPL, TSLA, etc.).
+     *
+     * Represents ownership shares in corporations. Sourced from traditional
+     * exchanges (NYSE, NASDAQ) via brokerages like Robinhood or Kraken.
+     */
+    AssetType["STOCK"] = "STOCK";
+    /**
+     * Exchange-Traded Funds - baskets of securities trading on exchanges (SPY, QQQ).
+     *
+     * Investment funds that track indices, commodities, or asset baskets and
+     * trade like stocks on traditional exchanges.
+     */
+    AssetType["ETF"] = "ETF";
+    /**
+     * Mutual funds - professionally managed investment portfolios.
+     *
+     * Pooled investment vehicles typically accessed through brokerages,
+     * not traded on exchanges. Examples: VTSAX, FXAIX.
+     */
+    AssetType["MUTUAL_FUND"] = "MUTUAL_FUND";
+    /**
+     * Fixed-income debt securities (government bonds, corporate bonds).
+     *
+     * Instruments representing loans to governments or corporations with
+     * defined interest payments and maturity dates.
+     */
+    AssetType["BOND"] = "BOND";
+    /**
+     * Physical goods or raw materials (gold, oil, wheat).
+     *
+     * Tangible assets traded on commodity exchanges or held as commodities-backed
+     * instruments. Includes precious metals, energy, agricultural products.
+     */
+    AssetType["COMMODITY"] = "COMMODITY";
+    /**
+     * Government-issued currencies (USD, EUR, JPY).
+     *
+     * Traditional fiat money held in brokerage cash accounts or wallets.
+     * Represents purchasing power in sovereign currencies.
+     */
+    AssetType["FIAT"] = "FIAT";
+    /**
+     * Non-fungible tokens - unique digital assets (ERC-721, ERC-1155, Solana NFTs).
+     *
+     * Blockchain-based unique or semi-fungible assets with distinct identities.
+     * Includes art, collectibles, gaming assets, membership tokens.
+     */
+    AssetType["NFT"] = "NFT";
+    /**
+     * Financial instruments deriving value from underlying assets (options, futures).
+     *
+     * Contracts whose value depends on underlying securities, indices, or commodities.
+     * Includes options, futures, swaps, and structured products.
+     */
+    AssetType["DERIVATIVE"] = "DERIVATIVE";
+    /**
+     * DeFi liquidity pool positions (Uniswap V2/V3 LP, Curve LP tokens).
+     *
+     * Represents shares in automated market maker (AMM) liquidity pools.
+     * These are yield-generating positions, not base assets.
+     */
+    AssetType["LIQUIDITY_POOL"] = "LIQUIDITY_POOL";
+    /**
+     * Staked cryptocurrency positions (ETH 2.0 staking, validator delegations).
+     *
+     * Assets locked in proof-of-stake protocols to earn rewards.
+     * Includes direct staking and delegated staking positions.
+     */
+    AssetType["STAKED_POSITION"] = "STAKED_POSITION";
+    /**
+     * DeFi lending protocol positions (Aave deposits, Compound supplies).
+     *
+     * Assets supplied to lending protocols to earn interest.
+     * Represents yield-generating positions in money markets.
+     */
+    AssetType["LENDING_POSITION"] = "LENDING_POSITION";
+    /**
+     * Catch-all for assets not fitting standard categories.
+     *
+     * Use sparingly for genuinely novel asset types. Document the specific
+     * type in the asset's metadata field for future classification refinement.
+     */
+    AssetType["OTHER"] = "OTHER";
+})(AssetType || (exports.AssetType = AssetType = {}));

package/dist/cjs/enums/Chain.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Chain = void 0;
+/**
+ * Blockchain network identifiers for multi-chain asset tracking.
+ *
+ * Provides standardized identifiers for all supported blockchain networks.
+ * Enables consistent asset identification across EVM chains, alternative L1s,
+ * and traditional finance systems.
+ *
+ * **Design Rationale:**
+ * - Covers major EVM chains (Ethereum, Polygon, Arbitrum, Optimism, Avalanche, BSC, Base)
+ * - Includes alternative L1s (Solana, SUI, Bitcoin)
+ * - Extensible via OTHER for new chains without breaking changes
+ * - Chain-agnostic operations use Chain type for abstraction
+ *
+ * **Integration Guidance:**
+ * - Map chain IDs (1, 137, 42161) to these enum values in integration domains
+ * - Use Chain.OTHER for unsupported chains, document actual chain in metadata
+ * - Testnets should be distinguished in metadata, not separate enum values
+ *
+ * @example
+ * ```typescript
+ * function getChainFromId(chainId: number): Chain {
+ *   const chainMap: Record<number, Chain> = {
+ *     1: Chain.ETHEREUM,
+ *     137: Chain.POLYGON,
+ *     42161: Chain.ARBITRUM,
+ *     10: Chain.OPTIMISM,
+ *     43114: Chain.AVALANCHE,
+ *     56: Chain.BSC,
+ *     8453: Chain.BASE
+ *   };
+ *   return chainMap[chainId] || Chain.OTHER;
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability core
+ *
+ * @see {@link Asset} for usage in asset identification
+ * @see {@link Transaction} for usage in transaction tracking
+ */
+var Chain;
+(function (Chain) {
+    /** Ethereum mainnet (Chain ID: 1) - Primary EVM L1 */
+    Chain["ETHEREUM"] = "ETHEREUM";
+    /** Polygon PoS (Chain ID: 137) - EVM sidechain for Ethereum */
+    Chain["POLYGON"] = "POLYGON";
+    /** Arbitrum One (Chain ID: 42161) - Optimistic rollup L2 for Ethereum */
+    Chain["ARBITRUM"] = "ARBITRUM";
+    /** Optimism (Chain ID: 10) - Optimistic rollup L2 for Ethereum */
+    Chain["OPTIMISM"] = "OPTIMISM";
+    /** Avalanche C-Chain (Chain ID: 43114) - EVM-compatible L1 */
+    Chain["AVALANCHE"] = "AVALANCHE";
+    /** Binance Smart Chain (Chain ID: 56) - EVM-compatible chain */
+    Chain["BSC"] = "BSC";
+    /** Base (Chain ID: 8453) - Coinbase's Optimistic rollup L2 */
+    Chain["BASE"] = "BASE";
+    /** Solana mainnet - High-performance L1, non-EVM */
+    Chain["SOLANA"] = "SOLANA";
+    /** SUI mainnet - Move-based L1, non-EVM */
+    Chain["SUI"] = "SUI";
+    /** Bitcoin mainnet - Original blockchain, UTXO model */
+    Chain["BITCOIN"] = "BITCOIN";
+    /**
+     * Unsupported or emerging chains.
+     *
+     * Use for chains not yet explicitly enumerated. Store actual chain
+     * identifier in asset metadata for future classification.
+     */
+    Chain["OTHER"] = "OTHER";
+})(Chain || (exports.Chain = Chain = {}));

package/dist/cjs/enums/IntegrationSource.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrationSource = void 0;
+/**
+ * Data source identifiers for integration traceability.
+ *
+ * Tracks origin of data flowing through the system, enabling source-specific
+ * logic, validation, and troubleshooting. This comprehensive enum covers centralized
+ * exchanges (CEXs), decentralized exchanges (DEXs), wallet providers, and manual entries.
+ *
+ * @example
+ * ```typescript
+ * import { IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // Identify data source for routing logic
+ * function processAccountData(source: IntegrationSource) {
+ *   switch(source) {
+ *     case IntegrationSource.ROBINHOOD:
+ *       return fetchCEXData();
+ *     case IntegrationSource.UNISWAP:
+ *       return fetchDEXData();
+ *     case IntegrationSource.METAMASK:
+ *       return fetchWalletData();
+ *     default:
+ *       return fetchGenericData();
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ */
+var IntegrationSource;
+(function (IntegrationSource) {
+    /** Robinhood centralized exchange */
+    IntegrationSource["ROBINHOOD"] = "ROBINHOOD";
+    /** Kraken centralized exchange */
+    IntegrationSource["KRAKEN"] = "KRAKEN";
+    /** Coinbase centralized exchange */
+    IntegrationSource["COINBASE"] = "COINBASE";
+    /** Binance centralized exchange */
+    IntegrationSource["BINANCE"] = "BINANCE";
+    /** Uniswap decentralized exchange */
+    IntegrationSource["UNISWAP"] = "UNISWAP";
+    /** SushiSwap decentralized exchange */
+    IntegrationSource["SUSHISWAP"] = "SUSHISWAP";
+    /** PancakeSwap decentralized exchange */
+    IntegrationSource["PANCAKESWAP"] = "PANCAKESWAP";
+    /** Curve Finance decentralized exchange */
+    IntegrationSource["CURVE"] = "CURVE";
+    /** Balancer decentralized exchange */
+    IntegrationSource["BALANCER"] = "BALANCER";
+    /** MetaMask wallet provider */
+    IntegrationSource["METAMASK"] = "METAMASK";
+    /** Rabby wallet provider */
+    IntegrationSource["RABBY"] = "RABBY";
+    /** Phantom wallet provider (Solana) */
+    IntegrationSource["PHANTOM"] = "PHANTOM";
+    /** Slush wallet provider (SUI) */
+    IntegrationSource["SLUSH"] = "SLUSH";
+    /** Suiet wallet provider (SUI) */
+    IntegrationSource["SUIET"] = "SUIET";
+    /** Manually entered data by user */
+    IntegrationSource["MANUAL_ENTRY"] = "MANUAL_ENTRY";
+    /** Data fetched directly from blockchain via RPC */
+    IntegrationSource["BLOCKCHAIN_DIRECT"] = "BLOCKCHAIN_DIRECT";
+    /** Other or unclassified data source */
+    IntegrationSource["OTHER"] = "OTHER";
+})(IntegrationSource || (exports.IntegrationSource = IntegrationSource = {}));

package/dist/cjs/enums/LendingPositionType.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LendingPositionType = void 0;
+/**
+ * Type of lending position: supply (lender) or borrow (borrower).
+ *
+ * Discriminates between assets deposited to earn interest (SUPPLY) and
+ * assets borrowed while paying interest (BORROW) in DeFi lending protocols.
+ *
+ * @example
+ * ```typescript
+ * import { LendingPositionType } from '@cygnus-wealth/data-models';
+ *
+ * const supplyType = LendingPositionType.SUPPLY;
+ * const borrowType = LendingPositionType.BORROW;
+ * ```
+ *
+ * @since 0.2.0
+ * @stability core
+ *
+ * @see {@link LendingPosition} for usage in lending positions
+ */
+var LendingPositionType;
+(function (LendingPositionType) {
+    /** User supplied assets earning interest (lender) */
+    LendingPositionType["SUPPLY"] = "SUPPLY";
+    /** User borrowed assets paying interest (borrower) */
+    LendingPositionType["BORROW"] = "BORROW";
+})(LendingPositionType || (exports.LendingPositionType = LendingPositionType = {}));

package/dist/cjs/enums/TransactionType.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionType = void 0;
+/**
+ * Standardized transaction type classification.
+ *
+ * Unified categorization for all financial operations across CEX, DEX,
+ * blockchain transfers, and DeFi protocols. Enables consistent transaction
+ * history and analytics across all integration sources.
+ *
+ * @example
+ * ```typescript
+ * import { TransactionType } from '@cygnus-wealth/data-models';
+ *
+ * // Classify transaction based on operation
+ * function getTransactionIcon(type: TransactionType): string {
+ *   switch(type) {
+ *     case TransactionType.BUY:
+ *       return '📈';
+ *     case TransactionType.SELL:
+ *       return '📉';
+ *     case TransactionType.STAKE:
+ *       return '🔒';
+ *     case TransactionType.SWAP:
+ *       return '🔄';
+ *     default:
+ *       return '📄';
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ */
+var TransactionType;
+(function (TransactionType) {
+    /** Purchase of an asset with fiat or another asset */
+    TransactionType["BUY"] = "BUY";
+    /** Sale of an asset for fiat or another asset */
+    TransactionType["SELL"] = "SELL";
+    /** Incoming transfer of assets to account */
+    TransactionType["TRANSFER_IN"] = "TRANSFER_IN";
+    /** Outgoing transfer of assets from account */
+    TransactionType["TRANSFER_OUT"] = "TRANSFER_OUT";
+    /** Exchange of one asset for another via DEX or CEX */
+    TransactionType["SWAP"] = "SWAP";
+    /** Locking assets for staking rewards */
+    TransactionType["STAKE"] = "STAKE";
+    /** Unlocking previously staked assets */
+    TransactionType["UNSTAKE"] = "UNSTAKE";
+    /** Claiming earned staking or liquidity rewards */
+    TransactionType["CLAIM_REWARD"] = "CLAIM_REWARD";
+    /** Adding assets to a liquidity pool */
+    TransactionType["PROVIDE_LIQUIDITY"] = "PROVIDE_LIQUIDITY";
+    /** Removing assets from a liquidity pool */
+    TransactionType["REMOVE_LIQUIDITY"] = "REMOVE_LIQUIDITY";
+    /** Borrowing assets from a lending protocol */
+    TransactionType["BORROW"] = "BORROW";
+    /** Repaying borrowed assets to a lending protocol */
+    TransactionType["REPAY"] = "REPAY";
+    /** Forced liquidation of collateralized position */
+    TransactionType["LIQUIDATION"] = "LIQUIDATION";
+    /** Creation of new tokens (NFT minting, token minting) */
+    TransactionType["MINT"] = "MINT";
+    /** Destruction of tokens */
+    TransactionType["BURN"] = "BURN";
+    /** Transaction fee payment */
+    TransactionType["FEE"] = "FEE";
+    /** Dividend payment received */
+    TransactionType["DIVIDEND"] = "DIVIDEND";
+    /** Interest payment received or paid */
+    TransactionType["INTEREST"] = "INTEREST";
+    /** Other or unclassified transaction type */
+    TransactionType["OTHER"] = "OTHER";
+})(TransactionType || (exports.TransactionType = TransactionType = {}));

package/dist/cjs/enums/VaultStrategyType.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultStrategyType = void 0;
+/**
+ * Strategy type for yield vault positions.
+ *
+ * Classifies the underlying strategy used by a yield vault to generate returns.
+ * Different strategy types carry different risk profiles and return characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { VaultStrategyType } from '@cygnus-wealth/data-models';
+ *
+ * const strategyType = VaultStrategyType.YIELD_AGGREGATOR;
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for usage in vault positions
+ */
+var VaultStrategyType;
+(function (VaultStrategyType) {
+    /** Auto-compounding yield aggregator (e.g., Yearn, Beefy) */
+    VaultStrategyType["YIELD_AGGREGATOR"] = "YIELD_AGGREGATOR";
+    /** Single-asset lending vault (e.g., Yearn USDC vault lending on Aave) */
+    VaultStrategyType["LENDING"] = "LENDING";
+    /** Liquidity provision strategy (vault deposits into LP pools) */
+    VaultStrategyType["LIQUIDITY_PROVISION"] = "LIQUIDITY_PROVISION";
+    /** Delta-neutral or options-based structured product */
+    VaultStrategyType["STRUCTURED_PRODUCT"] = "STRUCTURED_PRODUCT";
+    /** Strategy type not covered by other categories */
+    VaultStrategyType["OTHER"] = "OTHER";
+})(VaultStrategyType || (exports.VaultStrategyType = VaultStrategyType = {}));

package/dist/cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultStrategyType = exports.LendingPositionType = exports.AccountType = exports.TransactionType = exports.IntegrationSource = exports.Chain = exports.AssetType = void 0;
+// Enums
+var AssetType_1 = require("./enums/AssetType");
+Object.defineProperty(exports, "AssetType", { enumerable: true, get: function () { return AssetType_1.AssetType; } });
+var Chain_1 = require("./enums/Chain");
+Object.defineProperty(exports, "Chain", { enumerable: true, get: function () { return Chain_1.Chain; } });
+var IntegrationSource_1 = require("./enums/IntegrationSource");
+Object.defineProperty(exports, "IntegrationSource", { enumerable: true, get: function () { return IntegrationSource_1.IntegrationSource; } });
+var TransactionType_1 = require("./enums/TransactionType");
+Object.defineProperty(exports, "TransactionType", { enumerable: true, get: function () { return TransactionType_1.TransactionType; } });
+var AccountType_1 = require("./enums/AccountType");
+Object.defineProperty(exports, "AccountType", { enumerable: true, get: function () { return AccountType_1.AccountType; } });
+var LendingPositionType_1 = require("./enums/LendingPositionType");
+Object.defineProperty(exports, "LendingPositionType", { enumerable: true, get: function () { return LendingPositionType_1.LendingPositionType; } });
+var VaultStrategyType_1 = require("./enums/VaultStrategyType");
+Object.defineProperty(exports, "VaultStrategyType", { enumerable: true, get: function () { return VaultStrategyType_1.VaultStrategyType; } });

package/dist/cjs/interfaces/Account.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/ApiError.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/ApiResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Asset.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Balance.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/BaseEntity.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/FilterOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/IntegrationCredentials.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/LendingPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/LiquidityPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/MarketData.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Metadata.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/NFT.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/PaginatedResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Portfolio.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/PortfolioAsset.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/PortfolioItem.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Price.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/StakedPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/SyncStatus.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/Transaction.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interfaces/VaultPosition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types/AssetIdentifier.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/NetworkEnvironment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/SortOrder.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types/TimeRange.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/enums/VaultStrategyType.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Strategy type for yield vault positions.
+ *
+ * Classifies the underlying strategy used by a yield vault to generate returns.
+ * Different strategy types carry different risk profiles and return characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { VaultStrategyType } from '@cygnus-wealth/data-models';
+ *
+ * const strategyType = VaultStrategyType.YIELD_AGGREGATOR;
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for usage in vault positions
+ */
+export declare enum VaultStrategyType {
+    /** Auto-compounding yield aggregator (e.g., Yearn, Beefy) */
+    YIELD_AGGREGATOR = "YIELD_AGGREGATOR",
+    /** Single-asset lending vault (e.g., Yearn USDC vault lending on Aave) */
+    LENDING = "LENDING",
+    /** Liquidity provision strategy (vault deposits into LP pools) */
+    LIQUIDITY_PROVISION = "LIQUIDITY_PROVISION",
+    /** Delta-neutral or options-based structured product */
+    STRUCTURED_PRODUCT = "STRUCTURED_PRODUCT",
+    /** Strategy type not covered by other categories */
+    OTHER = "OTHER"
+}

package/dist/enums/VaultStrategyType.js

@@ -0,0 +1,31 @@
+/**
+ * Strategy type for yield vault positions.
+ *
+ * Classifies the underlying strategy used by a yield vault to generate returns.
+ * Different strategy types carry different risk profiles and return characteristics.
+ *
+ * @example
+ * ```typescript
+ * import { VaultStrategyType } from '@cygnus-wealth/data-models';
+ *
+ * const strategyType = VaultStrategyType.YIELD_AGGREGATOR;
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for usage in vault positions
+ */
+export var VaultStrategyType;
+(function (VaultStrategyType) {
+    /** Auto-compounding yield aggregator (e.g., Yearn, Beefy) */
+    VaultStrategyType["YIELD_AGGREGATOR"] = "YIELD_AGGREGATOR";
+    /** Single-asset lending vault (e.g., Yearn USDC vault lending on Aave) */
+    VaultStrategyType["LENDING"] = "LENDING";
+    /** Liquidity provision strategy (vault deposits into LP pools) */
+    VaultStrategyType["LIQUIDITY_PROVISION"] = "LIQUIDITY_PROVISION";
+    /** Delta-neutral or options-based structured product */
+    VaultStrategyType["STRUCTURED_PRODUCT"] = "STRUCTURED_PRODUCT";
+    /** Strategy type not covered by other categories */
+    VaultStrategyType["OTHER"] = "OTHER";
+})(VaultStrategyType || (VaultStrategyType = {}));

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
+export { VaultStrategyType } from './enums/VaultStrategyType';
 export { BaseEntity } from './interfaces/BaseEntity';
 export { Metadata } from './interfaces/Metadata';
 export { Asset } from './interfaces/Asset';
@@ -14,6 +15,7 @@ export { Balance } from './interfaces/Balance';
 export { LiquidityPosition } from './interfaces/LiquidityPosition';
 export { StakedPosition } from './interfaces/StakedPosition';
 export { LendingPosition } from './interfaces/LendingPosition';
+export { VaultPosition } from './interfaces/VaultPosition';
 export { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
 export { PortfolioAsset } from './interfaces/PortfolioAsset';

package/dist/index.js

@@ -5,3 +5,4 @@ export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
+export { VaultStrategyType } from './enums/VaultStrategyType';

package/dist/interfaces/Account.d.ts

@@ -4,6 +4,7 @@ import { Balance } from './Balance';
 import { LiquidityPosition } from './LiquidityPosition';
 import { StakedPosition } from './StakedPosition';
 import { LendingPosition } from './LendingPosition';
+import { VaultPosition } from './VaultPosition';
 import { NFT } from './NFT';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
@@ -105,6 +106,8 @@ export interface Account {
     stakedPositions?: StakedPosition[];
     /** Array of lending/borrowing positions (for DeFi money markets) */
     lendingPositions?: LendingPosition[];
+    /** Array of yield vault positions (for vault deposits) */
+    vaultPositions?: VaultPosition[];
     /** Array of NFTs held in this account */
     nfts?: NFT[];
     /** Total value of all holdings in this account (sum of all positions) */

package/dist/interfaces/VaultPosition.d.ts

@@ -0,0 +1,110 @@
+import { Chain } from '../enums/Chain';
+import { VaultStrategyType } from '../enums/VaultStrategyType';
+import { Asset } from './Asset';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+/**
+ * Yield vault deposit position tracking shares and performance.
+ *
+ * Represents user deposits in yield-generating vaults (Yearn, Beefy, Harvest,
+ * Sommelier, etc.) where assets are deposited into a vault contract that
+ * executes automated strategies. Tracks deposited amount, vault share tokens,
+ * APY, and underlying asset.
+ *
+ * **Design Pattern:** DeFi position entity for vault operations. Vaults issue
+ * share tokens representing proportional ownership. The share price (pricePerShare)
+ * increases over time as the vault earns yield, meaning the same number of shares
+ * becomes redeemable for more underlying tokens.
+ *
+ * @example
+ * ```typescript
+ * import { VaultPosition, VaultStrategyType, Chain, AssetType } from '@cygnus-wealth/data-models';
+ *
+ * // Yearn USDC vault deposit
+ * const yearnPosition: VaultPosition = {
+ *   id: 'yearn-usdc-vault-123',
+ *   protocol: 'Yearn V3',
+ *   vaultAddress: '0xa354F35829Ae975e850e23e9615b11Da1B3dC4DE',
+ *   vaultName: 'USDC yVault',
+ *   chain: Chain.ETHEREUM,
+ *   strategyType: VaultStrategyType.YIELD_AGGREGATOR,
+ *   depositAsset: {
+ *     id: 'ethereum-usdc',
+ *     symbol: 'USDC',
+ *     name: 'USD Coin',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 6
+ *   },
+ *   depositedAmount: '50000.000000',
+ *   shareBalance: '48500.000000',
+ *   pricePerShare: 1.0309,
+ *   apy: 8.5,
+ *   value: {
+ *     value: 50000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ *
+ * // Beefy auto-compounder on Arbitrum
+ * const beefyPosition: VaultPosition = {
+ *   id: 'beefy-arb-eth-usdc-456',
+ *   protocol: 'Beefy',
+ *   vaultAddress: '0xDeadBeef...',
+ *   vaultName: 'mooArbETH-USDC',
+ *   chain: Chain.ARBITRUM,
+ *   strategyType: VaultStrategyType.LIQUIDITY_PROVISION,
+ *   depositAsset: {
+ *     id: 'arbitrum-eth',
+ *     symbol: 'ETH',
+ *     name: 'Ethereum',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 18
+ *   },
+ *   depositedAmount: '2.5',
+ *   shareBalance: '2.35',
+ *   pricePerShare: 1.0638,
+ *   apy: 12.3,
+ *   value: {
+ *     value: 5000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ * ```
+ *
+ * @since 1.2.0
+ * @stability extended
+ *
+ * @see {@link VaultStrategyType} for vault strategy classification
+ * @see {@link Asset} for deposit asset definition
+ * @see {@link Account} for position aggregation
+ */
+export interface VaultPosition {
+    /** Unique identifier for this vault position */
+    id: string;
+    /** Vault protocol name (e.g., 'Yearn V3', 'Beefy', 'Harvest', 'Sommelier') */
+    protocol: string;
+    /** Smart contract address of the vault */
+    vaultAddress: string;
+    /** Human-readable vault name (e.g., 'USDC yVault', 'mooArbETH-USDC') */
+    vaultName: string;
+    /** Blockchain network where the vault exists */
+    chain: Chain;
+    /** Classification of the vault's underlying strategy */
+    strategyType: VaultStrategyType;
+    /** Asset deposited into the vault (the underlying token) */
+    depositAsset: Asset;
+    /** Amount of underlying asset deposited (as string for precision) */
+    depositedAmount: string;
+    /** Amount of vault share tokens held (as string for precision) */
+    shareBalance?: string;
+    /** Current price per share in terms of deposit asset (e.g., 1.03 means 3% profit) */
+    pricePerShare?: number;
+    /** Annual Percentage Yield for the vault (e.g., 8.5 = 8.5%) */
+    apy?: number;
+    /** Current total value of the vault position */
+    value?: Price;
+    /** Protocol-specific metadata (strategy details, harvest frequency, TVL, etc.) */
+    metadata?: Metadata;
+}

package/dist/interfaces/VaultPosition.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,49 +1,59 @@
 {
   "name": "@cygnus-wealth/data-models",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Shared TypeScript data models for CygnusWealth project",
-  "main": "dist/index.js",
+  "main": "dist/cjs/index.js",
+  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
     },
     "./enums/AssetType": {
       "types": "./dist/enums/AssetType.d.ts",
-      "import": "./dist/enums/AssetType.js"
+      "import": "./dist/enums/AssetType.js",
+      "require": "./dist/cjs/enums/AssetType.js"
     },
     "./enums/Chain": {
       "types": "./dist/enums/Chain.d.ts",
-      "import": "./dist/enums/Chain.js"
+      "import": "./dist/enums/Chain.js",
+      "require": "./dist/cjs/enums/Chain.js"
     },
     "./enums/IntegrationSource": {
       "types": "./dist/enums/IntegrationSource.d.ts",
-      "import": "./dist/enums/IntegrationSource.js"
+      "import": "./dist/enums/IntegrationSource.js",
+      "require": "./dist/cjs/enums/IntegrationSource.js"
     },
     "./enums/TransactionType": {
       "types": "./dist/enums/TransactionType.d.ts",
-      "import": "./dist/enums/TransactionType.js"
+      "import": "./dist/enums/TransactionType.js",
+      "require": "./dist/cjs/enums/TransactionType.js"
     },
     "./enums/AccountType": {
       "types": "./dist/enums/AccountType.d.ts",
-      "import": "./dist/enums/AccountType.js"
+      "import": "./dist/enums/AccountType.js",
+      "require": "./dist/cjs/enums/AccountType.js"
     },
     "./enums/LendingPositionType": {
       "types": "./dist/enums/LendingPositionType.d.ts",
-      "import": "./dist/enums/LendingPositionType.js"
+      "import": "./dist/enums/LendingPositionType.js",
+      "require": "./dist/cjs/enums/LendingPositionType.js"
     },
     "./interfaces/*": {
       "types": "./dist/interfaces/*.d.ts",
-      "import": "./dist/interfaces/*.js"
+      "import": "./dist/interfaces/*.js",
+      "require": "./dist/cjs/interfaces/*.js"
     },
     "./types/*": {
       "types": "./dist/types/*.d.ts",
-      "import": "./dist/types/*.js"
+      "import": "./dist/types/*.js",
+      "require": "./dist/cjs/types/*.js"
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "test": "vitest",
     "test:run": "vitest --run",
     "test:coverage": "vitest --coverage --run",