@cygnus-wealth/data-models 0.0.2 → 1.0.0

package/dist/interfaces/IntegrationCredentials.d.ts

@@ -1,11 +1,65 @@
 import { IntegrationSource } from '../enums/IntegrationSource';
 import { Metadata } from './Metadata';
+/**
+ * Encrypted credentials for CEX/brokerage API integration.
+ *
+ * Stores connection credentials for read-only API access to centralized exchanges,
+ * brokerages, and blockchain wallets. Designed for client-side encryption and
+ * secure storage patterns.
+ *
+ * **Security Pattern:** Credentials stored in this interface should be encrypted
+ * before persistence using Web Crypto API or similar client-side encryption.
+ * NEVER store private keys - only read-only API keys for data fetching.
+ *
+ * **Design Pattern:** Flexible credential structure supporting both API key-based
+ * authentication (CEX) and address-based read-only access (wallets).
+ *
+ * @example
+ * ```typescript
+ * import { IntegrationCredentials, IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // Kraken CEX credentials (API key + secret)
+ * const krakenCreds: IntegrationCredentials = {
+ *   source: IntegrationSource.KRAKEN,
+ *   apiKey: 'encrypted_api_key_here',
+ *   apiSecret: 'encrypted_api_secret_here'
+ * };
+ *
+ * // Coinbase Pro credentials (with passphrase)
+ * const coinbaseCreds: IntegrationCredentials = {
+ *   source: IntegrationSource.COINBASE,
+ *   apiKey: 'encrypted_api_key',
+ *   apiSecret: 'encrypted_secret',
+ *   passphrase: 'encrypted_passphrase'
+ * };
+ *
+ * // MetaMask wallet (address-based read-only)
+ * const walletCreds: IntegrationCredentials = {
+ *   source: IntegrationSource.METAMASK,
+ *   walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ *   chainId: '1'  // Ethereum mainnet
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link IntegrationSource} for supported sources
+ * @see {@link Account} for credential usage in data fetching
+ */
 export interface IntegrationCredentials {
+    /** Integration source requiring these credentials */
     source: IntegrationSource;
+    /** API key for CEX/brokerage authentication (should be encrypted) */
     apiKey?: string;
+    /** API secret for CEX/brokerage authentication (should be encrypted) */
     apiSecret?: string;
+    /** Additional passphrase for some exchanges (Coinbase Pro, etc.) (should be encrypted) */
     passphrase?: string;
+    /** Wallet address for read-only blockchain queries (NOT private key) */
     walletAddress?: string;
+    /** Blockchain network ID for wallet connections (e.g., '1' for Ethereum mainnet) */
     chainId?: string;
+    /** Source-specific metadata (permissions, connection settings, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/LendingPosition.d.ts

@@ -1,18 +1,103 @@
 import { Chain } from '../enums/Chain';
+import { LendingPositionType } from '../enums/LendingPositionType';
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * DeFi money market positions for lending and borrowing.
+ *
+ * Represents user positions in lending protocols (Aave, Compound, etc.) where
+ * users can supply assets to earn interest (SUPPLY) or borrow assets against
+ * collateral (BORROW). Tracks amounts, interest rates, health factors, and
+ * liquidation thresholds critical for position management.
+ *
+ * **Design Pattern:** DeFi position entity discriminated by type (SUPPLY vs BORROW).
+ * Health factor and liquidation threshold are essential for monitoring borrow
+ * position safety and preventing liquidations.
+ *
+ * @example
+ * ```typescript
+ * import { LendingPosition, LendingPositionType, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // Aave supply position (earning interest)
+ * const supplyPosition: LendingPosition = {
+ *   id: 'aave-supply-usdc-123',
+ *   protocol: 'Aave V3',
+ *   chain: Chain.ETHEREUM,
+ *   type: LendingPositionType.SUPPLY,
+ *   asset: {
+ *     id: 'ethereum-usdc',
+ *     symbol: 'USDC',
+ *     name: 'USD Coin',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 6
+ *   },
+ *   amount: '50000',  // $50k supplied
+ *   apy: 3.5,  // 3.5% APY
+ *   accruedInterest: 125.50,
+ *   value: {
+ *     value: 50125.50,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ *
+ * // Aave borrow position (paying interest)
+ * const borrowPosition: LendingPosition = {
+ *   id: 'aave-borrow-dai-456',
+ *   protocol: 'Aave V3',
+ *   chain: Chain.ETHEREUM,
+ *   type: LendingPositionType.BORROW,
+ *   asset: {
+ *     id: 'ethereum-dai',
+ *     symbol: 'DAI',
+ *     name: 'Dai Stablecoin',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 18
+ *   },
+ *   amount: '30000',  // $30k borrowed
+ *   apy: 5.2,  // 5.2% borrow rate
+ *   accruedInterest: -85.30,  // Interest owed
+ *   healthFactor: 2.5,  // > 1.0 = safe
+ *   liquidationThreshold: 0.85,  // 85% LTV
+ *   value: {
+ *     value: -30085.30,  // Negative for debt
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability extended
+ *
+ * @see {@link LendingPositionType} for SUPPLY vs BORROW discrimination
+ * @see {@link Asset} for lent/borrowed asset definition
+ * @see {@link Account} for position aggregation
+ */
 export interface LendingPosition {
+    /** Unique identifier for this lending position */
     id: string;
+    /** Lending protocol name (e.g., 'Aave V3', 'Compound', 'Venus') */
     protocol: string;
+    /** Blockchain network where the lending position exists */
     chain: Chain;
-    type: 'SUPPLY' | 'BORROW';
+    /** Position type: SUPPLY (lender) or BORROW (borrower) */
+    type: LendingPositionType;
+    /** Asset being supplied or borrowed */
     asset: Asset;
+    /** Amount supplied or borrowed (as string for precision) */
     amount: string;
+    /** Annual Percentage Yield (for supply) or Rate (for borrow) (e.g., 3.5 = 3.5%) */
     apy?: number;
-    accrued_interest?: number;
-    health_factor?: number;
-    liquidation_threshold?: number;
+    /** Interest accrued (positive for supply, negative for borrow) */
+    accruedInterest?: number;
+    /** Health factor for borrow positions (ratio of collateral to debt, \>1.0 = safe) */
+    healthFactor?: number;
+    /** Liquidation threshold as ratio (0.0-1.0, e.g., 0.85 = 85% LTV before liquidation) */
+    liquidationThreshold?: number;
+    /** Current total value of position (positive for supply, negative for borrow debt) */
     value?: Price;
+    /** Protocol-specific metadata (collateral assets, liquidation price, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/LiquidityPosition.d.ts

@@ -2,17 +2,81 @@ import { Chain } from '../enums/Chain';
 import { Balance } from './Balance';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * DEX liquidity pool position tracking LP tokens and performance.
+ *
+ * Represents user's position in automated market maker (AMM) liquidity pools
+ * across various DEX protocols (Uniswap, Curve, Balancer, etc.). Tracks deposited
+ * tokens, LP token ownership, pool share, earned fees, and impermanent loss.
+ *
+ * **Design Pattern:** DeFi position entity capturing both the underlying tokens
+ * deposited and the LP token representation, along with performance metrics
+ * specific to liquidity provision.
+ *
+ * @example
+ * ```typescript
+ * import { LiquidityPosition, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // Uniswap V2 ETH/USDC pool position
+ * const uniswapPosition: LiquidityPosition = {
+ *   id: 'uniswap-eth-usdc-123',
+ *   protocol: 'Uniswap V2',
+ *   poolAddress: '0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc',
+ *   poolName: 'ETH/USDC',
+ *   chain: Chain.ETHEREUM,
+ *   tokens: [
+ *     {
+ *       assetId: 'ethereum-eth',
+ *       asset: {...},
+ *       amount: '5.0'
+ *     },
+ *     {
+ *       assetId: 'ethereum-usdc',
+ *       asset: {...},
+ *       amount: '10000'
+ *     }
+ *   ],
+ *   lpTokenBalance: '707.106781186548',  // LP token amount
+ *   share: 0.05,  // 5% of the pool
+ *   value: {
+ *     value: 20000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   feesEarned: 150.50,  // $150.50 earned in fees
+ *   impermanentLoss: -25.30  // -$25.30 IL
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability extended
+ *
+ * @see {@link Balance} for token balance structure
+ * @see {@link Account} for position aggregation
+ */
 export interface LiquidityPosition {
+    /** Unique identifier for this liquidity position */
     id: string;
+    /** DEX protocol name (e.g., 'Uniswap V3', 'Curve', 'Balancer V2') */
     protocol: string;
+    /** Smart contract address of the liquidity pool */
     poolAddress: string;
+    /** Human-readable pool name (e.g., 'ETH/USDC', 'stETH/ETH') */
     poolName: string;
+    /** Blockchain network where the pool exists */
     chain: Chain;
+    /** Array of token balances deposited in the pool (typically 2-8 tokens) */
     tokens: Balance[];
+    /** Amount of LP tokens held (represents pool share) */
     lpTokenBalance?: string;
+    /** Percentage of total pool owned (0.0-1.0, e.g., 0.05 = 5%) */
     share?: number;
+    /** Current total value of the position (sum of all tokens) */
     value?: Price;
-    fees_earned?: number;
-    impermanent_loss?: number;
+    /** Total trading fees earned from this position (in value.currency) */
+    feesEarned?: number;
+    /** Impermanent loss compared to holding tokens (negative = loss, positive = gain) */
+    impermanentLoss?: number;
+    /** Protocol-specific metadata (pool version, fee tier, range bounds, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/MarketData.d.ts

@@ -1,14 +1,67 @@
 import { Price } from './Price';
+/**
+ * Extended market data for analytics and research features.
+ *
+ * Comprehensive market information including price, market cap, trading volume,
+ * supply metrics, price changes, and 24-hour price range. Used for advanced
+ * analytics, market research, and detailed asset views.
+ *
+ * **Design Pattern:** Extends basic Price with market-specific metrics from
+ * CoinGecko, CoinMarketCap, or other market data providers. All fields except
+ * assetId, currentPrice, and lastUpdated are optional to handle varying data
+ * availability.
+ *
+ * @example
+ * ```typescript
+ * import { MarketData } from '@cygnus-wealth/data-models';
+ *
+ * // Comprehensive market data for analytics
+ * const ethMarketData: MarketData = {
+ *   assetId: 'ethereum-eth',
+ *   currentPrice: {
+ *     value: 2000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   marketCap: 240000000000,  // $240B
+ *   volume24h: 12000000000,    // $12B daily volume
+ *   priceChange24h: 50,
+ *   priceChangePercentage24h: 2.5,
+ *   high24h: 2050,
+ *   low24h: 1950,
+ *   circulatingSupply: 120000000,
+ *   totalSupply: 120000000,
+ *   lastUpdated: new Date()
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Price} for base price structure
+ * @see {@link Asset} for asset definitions
+ */
 export interface MarketData {
+    /** Reference to Asset.id for this market data */
     assetId: string;
+    /** Current market price with timestamp */
     currentPrice: Price;
+    /** Total market capitalization (price * circulating supply) */
     marketCap?: number;
+    /** Trading volume in last 24 hours */
     volume24h?: number;
+    /** Absolute price change in last 24 hours (in currentPrice.currency) */
     priceChange24h?: number;
+    /** Percentage price change in last 24 hours (e.g., 2.5 = 2.5%) */
     priceChangePercentage24h?: number;
+    /** Highest price in last 24 hours */
     high24h?: number;
+    /** Lowest price in last 24 hours */
     low24h?: number;
+    /** Number of tokens in circulation (available for trading) */
     circulatingSupply?: number;
+    /** Total number of tokens that currently exist (including locked) */
     totalSupply?: number;
+    /** Timestamp when this market data was last updated */
     lastUpdated: Date;
 }

package/dist/interfaces/Metadata.d.ts

@@ -1,3 +1,89 @@
+/**
+ * Extensible metadata container for source-specific and custom data.
+ *
+ * Metadata provides a flexible mechanism for storing additional information that
+ * doesn't fit into standardized model fields. This pattern enables the core data
+ * models to remain clean and source-agnostic while allowing integration domains
+ * to preserve source-specific details.
+ *
+ * **Design Pattern: Extension Object**
+ * The Metadata interface implements the Extension Object pattern, allowing models
+ * to be extended without modifying their core structure. This maintains backward
+ * compatibility while enabling forward extensibility.
+ *
+ * **Use Cases**:
+ * - Source-specific identifiers (e.g., Robinhood internal IDs, CEX trade IDs)
+ * - Integration-specific flags or configuration
+ * - Experimental data during feature development
+ * - Custom tags or labels added by consuming domains
+ * - Raw response data for debugging
+ *
+ * **Guidelines**:
+ * - Keys should be namespaced to avoid conflicts (e.g., `"robinhood:accountId"`)
+ * - Values should be JSON-serializable
+ * - Do NOT store sensitive data (API keys, private keys, passwords)
+ * - Document custom metadata keys in consuming domain documentation
+ *
+ * @example
+ * ```typescript
+ * // Asset with Coinbase-specific metadata
+ * const asset: Asset = {
+ *   id: "btc-bitcoin",
+ *   symbol: "BTC",
+ *   name: "Bitcoin",
+ *   type: AssetType.CRYPTOCURRENCY,
+ *   metadata: {
+ *     "coinbase:currencyCode": "BTC",
+ *     "coinbase:tradingPair": "BTC-USD",
+ *     "coinbase:minSize": "0.00000001",
+ *     "tags": ["major", "layer1"],
+ *     "lastSyncedAt": "2025-01-15T10:30:00Z"
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Transaction with chain-specific metadata
+ * const transaction: Transaction = {
+ *   id: "txn_123",
+ *   hash: "0xabc...",
+ *   type: TransactionType.SWAP,
+ *   // ... other fields
+ *   metadata: {
+ *     "ethereum:gasUsed": "21000",
+ *     "ethereum:gasPrice": "50000000000",
+ *     "ethereum:blockNumber": "18500000",
+ *     "uniswap:poolAddress": "0xdef...",
+ *     "uniswap:fee": "0.003"
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability core
+ *
+ * @see {@link Asset} for usage in asset models
+ * @see {@link Transaction} for usage in transaction models
+ */
 export interface Metadata {
+    /**
+     * Arbitrary key-value pairs for extensibility.
+     *
+     * Keys should follow namespacing convention: `"source:field"` or `"domain:field"`
+     * to prevent collisions between different integration sources.
+     *
+     * Values must be JSON-serializable types (string, number, boolean, object, array, null).
+     * Avoid storing functions, circular references, or non-serializable types.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   "robinhood:accountId": "RH_ACC_123",
+     *   "robinhood:isFractional": true,
+     *   "custom:tags": ["watchlist", "high-priority"]
+     * }
+     * ```
+     */
     [key: string]: unknown;
 }

package/dist/interfaces/NFT.d.ts

@@ -1,14 +1,69 @@
 import { Asset } from './Asset';
+/**
+ * NFT-specific asset extensions including token IDs and metadata.
+ *
+ * Extends the base Asset interface with NFT-specific fields for collection
+ * information, unique token identification, visual content URIs, and trait
+ * attributes. Supports ERC-721, ERC-1155, SPL NFTs, and SUI Move NFTs.
+ *
+ * **Design Pattern:** Inherits all Asset fields (id, symbol, name, etc.) and
+ * adds NFT-specific data. The Asset.type should be AssetType.NFT for proper
+ * classification.
+ *
+ * @example
+ * ```typescript
+ * import { NFT, AssetType, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // ERC-721 NFT from OpenSea
+ * const nft: NFT = {
+ *   // Asset base fields
+ *   id: 'bayc-1234',
+ *   symbol: 'BAYC',
+ *   name: 'Bored Ape Yacht Club #1234',
+ *   type: AssetType.NFT,
+ *   chain: Chain.ETHEREUM,
+ *   contractAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
+ *
+ *   // NFT-specific fields
+ *   tokenId: '1234',
+ *   collectionAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
+ *   collectionName: 'Bored Ape Yacht Club',
+ *   tokenUri: 'ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/1234',
+ *   imageUrl: 'https://example.com/bayc-1234.png',
+ *   attributes: [
+ *     { trait_type: 'Background', value: 'Blue' },
+ *     { trait_type: 'Fur', value: 'Brown' },
+ *     { trait_type: 'Rarity Score', value: 125.5, display_type: 'number' }
+ *   ]
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Asset} for inherited base fields
+ * @see {@link AssetType} - use AssetType.NFT for NFTs
+ */
 export interface NFT extends Asset {
+    /** Unique token identifier within the collection (e.g., '1234', '0x5f') */
     tokenId: string;
+    /** Smart contract address of the NFT collection */
     collectionAddress: string;
+    /** Human-readable name of the NFT collection */
     collectionName: string;
+    /** URI pointing to token metadata (IPFS, HTTP, or on-chain) */
     tokenUri?: string;
+    /** Direct URL to the NFT image for display */
     imageUrl?: string;
+    /** URL to animation or video content (MP4, GIF, etc.) */
     animationUrl?: string;
+    /** Array of trait attributes defining NFT characteristics and rarity */
     attributes?: Array<{
+        /** Category or type of the trait (e.g., 'Background', 'Fur', 'Eyes') */
         trait_type: string;
+        /** Value of the trait (can be text or numeric) */
         value: string | number;
+        /** Optional display hint for numeric traits (e.g., 'number', 'boost_percentage') */
         display_type?: string;
     }>;
 }

package/dist/interfaces/PaginatedResponse.d.ts

@@ -1,7 +1,66 @@
+/**
+ * Paginated response wrapper for large datasets.
+ *
+ * Standard structure for paginated API responses enabling efficient handling
+ * of large collections (transactions, assets, etc.). Uses 1-indexed pages and
+ * provides hasMore flag for infinite scroll implementations.
+ *
+ * **Design Pattern:** Cursor-based pagination pattern with metadata for UI
+ * pagination controls and infinite scroll detection.
+ *
+ * @template T - Type of items in the collection
+ *
+ * @example
+ * ```typescript
+ * import { PaginatedResponse, Transaction } from '@cygnus-wealth/data-models';
+ *
+ * // First page of transactions
+ * const page1: PaginatedResponse<Transaction> = {
+ *   items: [
+ *     { id: 'tx-1', type: TransactionType.BUY, ... },
+ *     { id: 'tx-2', type: TransactionType.SELL, ... },
+ *     // ... 48 more items
+ *   ],
+ *   total: 523,
+ *   page: 1,
+ *   pageSize: 50,
+ *   hasMore: true  // (1 * 50) < 523
+ * };
+ *
+ * // Last page calculation
+ * const lastPage: PaginatedResponse<Transaction> = {
+ *   items: [ ... 23 items ... ],
+ *   total: 523,
+ *   page: 11,
+ *   pageSize: 50,
+ *   hasMore: false  // (11 * 50) >= 523
+ * };
+ *
+ * // Empty result set
+ * const emptyPage: PaginatedResponse<Transaction> = {
+ *   items: [],
+ *   total: 0,
+ *   page: 1,
+ *   pageSize: 50,
+ *   hasMore: false
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link ApiResponse} for response wrapping
+ * @see {@link Transaction} for common paginated type
+ */
 export interface PaginatedResponse<T> {
+    /** Array of items for the current page */
     items: T[];
+    /** Total number of items across all pages */
     total: number;
+    /** Current page number (1-indexed) */
     page: number;
+    /** Number of items per page */
     pageSize: number;
+    /** Whether more pages exist after the current page (page * pageSize \< total) */
     hasMore: boolean;
 }

package/dist/interfaces/Portfolio.d.ts

@@ -1,21 +1,123 @@
 import { Account } from './Account';
 import { Price } from './Price';
+import { PortfolioAsset } from './PortfolioAsset';
+import { Metadata } from './Metadata';
+/**
+ * Complete user portfolio aggregating all accounts and holdings.
+ *
+ * Top-level aggregate combining all user accounts, positions, and assets into
+ * a unified portfolio view. Calculates total value, tracks historical performance,
+ * and maintains deduplicated asset lists across accounts.
+ *
+ * **Design Pattern:** Aggregate root pattern at portfolio level, composing multiple
+ * Account aggregates. Supports both account-based view (accounts array) and
+ * asset-based view (items array) for flexible UI rendering.
+ *
+ * **Aggregation Rules:**
+ * - totalValue = sum of all Account.totalValue
+ * - items = deduplicated PortfolioAssets across all accounts (same asset, different accounts)
+ * - performance = calculated from totalValueHistory changes
+ *
+ * @example
+ * ```typescript
+ * import { Portfolio } from '@cygnus-wealth/data-models';
+ *
+ * // Complete portfolio with multiple accounts
+ * const userPortfolio: Portfolio = {
+ *   id: 'portfolio-user-123',
+ *   userId: 'user-123',
+ *   name: 'My Portfolio',
+ *   accounts: [
+ *     {
+ *       id: 'metamask-wallet-1',
+ *       name: 'Main Wallet',
+ *       type: AccountType.WALLET,
+ *       source: IntegrationSource.METAMASK,
+ *       balances: [...],
+ *       totalValue: { value: 50000, currency: 'USD', timestamp: new Date() }
+ *     },
+ *     {
+ *       id: 'kraken-spot-1',
+ *       name: 'Kraken Trading',
+ *       type: AccountType.SPOT,
+ *       source: IntegrationSource.KRAKEN,
+ *       balances: [...],
+ *       totalValue: { value: 30000, currency: 'USD', timestamp: new Date() }
+ *     }
+ *   ],
+ *   items: [
+ *     {
+ *       id: 'portfolio-eth',
+ *       assetId: 'ethereum-eth',
+ *       asset: { symbol: 'ETH', name: 'Ethereum', ... },
+ *       balance: { amount: '10.0', ... },
+ *       value: { value: 20000, currency: 'USD', timestamp: new Date() },
+ *       allocation: 0.25  // 25% of portfolio
+ *     },
+ *     // ... more assets
+ *   ],
+ *   totalValue: {
+ *     value: 80000,  // Sum of all accounts
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   totalValueHistory: [
+ *     { timestamp: new Date('2025-09-11'), value: { value: 75000, currency: 'USD', ... } },
+ *     { timestamp: new Date('2025-10-11'), value: { value: 80000, currency: 'USD', ... } }
+ *   ],
+ *   performance: {
+ *     day: 2.5,      // +2.5% today
+ *     week: 5.0,     // +5.0% this week
+ *     month: 6.67,   // +6.67% this month
+ *     year: 45.0,    // +45% this year
+ *     all_time: 60.0 // +60% all-time
+ *   },
+ *   lastUpdated: new Date()
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Account} for individual account aggregation
+ * @see {@link PortfolioAsset} for asset composition
+ * @see {@link Price} for valuation structure
+ */
 export interface Portfolio {
+    /** Unique identifier for this portfolio */
     id: string;
-    userId: string;
+    /** User ID owning this portfolio (for multi-user systems) */
+    userId?: string;
+    /** User-friendly portfolio name */
     name: string;
-    accounts: Account[];
+    /** Array of all accounts in this portfolio */
+    accounts?: Account[];
+    /** Deduplicated array of all assets across accounts */
+    items?: PortfolioAsset[];
+    /** Total value of entire portfolio (sum of all account values) */
     totalValue: Price;
+    /** Historical value snapshots for performance tracking */
     totalValueHistory?: Array<{
+        /** Timestamp of the snapshot */
         timestamp: Date;
+        /** Portfolio value at that time */
         value: Price;
     }>;
+    /** Performance metrics as percentage changes (positive = gain, negative = loss) */
     performance?: {
+        /** 24-hour performance change percentage */
         day: number;
+        /** 7-day performance change percentage */
         week: number;
+        /** 30-day performance change percentage */
         month: number;
+        /** 365-day performance change percentage */
         year: number;
+        /** All-time performance change percentage */
         all_time: number;
     };
+    /** Timestamp of last portfolio data update */
     lastUpdated: Date;
+    /** Portfolio-specific metadata (theme, display preferences, etc.) */
+    metadata?: Metadata;
 }