@cygnus-wealth/data-models 0.0.2 → 1.0.0

package/dist/interfaces/PortfolioAsset.d.ts

@@ -0,0 +1,76 @@
+import { Asset } from './Asset';
+import { Balance } from './Balance';
+import { Price } from './Price';
+/**
+ * Asset with balance and market valuation for portfolio display.
+ *
+ * Composed view combining asset details, quantity held, current market value,
+ * and portfolio allocation percentage. Primary interface for displaying assets
+ * in portfolio dashboards and aggregation views.
+ *
+ * **Design Pattern:** Composition of Asset + Balance + Price + allocation metrics
+ * to provide a complete, ready-to-render portfolio item. Simplifies UI logic by
+ * pre-joining related data.
+ *
+ * @example
+ * ```typescript
+ * import { PortfolioAsset } from '@cygnus-wealth/data-models';
+ *
+ * // Complete portfolio asset ready for display
+ * const portfolioAsset: PortfolioAsset = {
+ *   id: 'portfolio-item-1',
+ *   accountId: 'metamask-wallet-1',
+ *   assetId: 'ethereum-usdc',
+ *   asset: {
+ *     id: 'ethereum-usdc',
+ *     symbol: 'USDC',
+ *     name: 'USD Coin',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 6
+ *   },
+ *   balance: {
+ *     assetId: 'ethereum-usdc',
+ *     asset: {...},  // Same as above
+ *     amount: '10000',
+ *     value: {
+ *       value: 10000,
+ *       currency: 'USD',
+ *       timestamp: new Date()
+ *     }
+ *   },
+ *   value: {
+ *     value: 10000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   allocation: 0.25,  // 25% of total portfolio
+ *   lastUpdated: new Date()
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Asset} for asset details
+ * @see {@link Balance} for quantity and P&L
+ * @see {@link Price} for valuation
+ * @see {@link Portfolio} for aggregated portfolio view
+ */
+export interface PortfolioAsset {
+    /** Unique identifier for this portfolio item */
+    id: string;
+    /** Reference to the account holding this asset */
+    accountId: string;
+    /** Reference to the Asset.id */
+    assetId: string;
+    /** Complete asset definition including symbol, name, type, etc. */
+    asset: Asset;
+    /** Balance details including amount, cost basis, and P&L */
+    balance: Balance;
+    /** Current total market value of this position */
+    value: Price;
+    /** Percentage of total portfolio value (0.0-1.0, e.g., 0.25 = 25%) */
+    allocation: number;
+    /** Timestamp of last data update for this asset */
+    lastUpdated: Date;
+}

package/dist/interfaces/PortfolioAsset.js

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

package/dist/interfaces/PortfolioItem.d.ts

@@ -1,4 +1,17 @@
+/**
+ * Legacy portfolio item interface.
+ *
+ * @deprecated Since v0.2.0. Use {@link PortfolioAsset} instead.
+ * Will be removed in v2.0.0.
+ *
+ * @since 0.0.1
+ * @stability core
+ *
+ * @see {@link PortfolioAsset} for replacement interface
+ */
 export interface PortfolioItem {
+    /** Legacy identifier */
     id: string;
+    /** Legacy balance field (replaced by Balance.amount) */
     balance: number;
 }

package/dist/interfaces/Price.d.ts

@@ -1,7 +1,50 @@
 import { IntegrationSource } from '../enums/IntegrationSource';
+/**
+ * Point-in-time asset price with currency and timestamp.
+ *
+ * Essential for portfolio valuation, historical tracking, and performance
+ * calculations. Supports multiple price representations (value and amount)
+ * to accommodate different data sources.
+ *
+ * **Design Pattern:** Simple value object with timestamp for price history
+ * and source attribution for data quality tracking. Either value or amount
+ * should be present.
+ *
+ * @example
+ * ```typescript
+ * import { Price, IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // Market price from price feed
+ * const currentPrice: Price = {
+ *   value: 2000.00,
+ *   currency: 'USD',
+ *   timestamp: new Date('2025-10-11T10:30:00Z'),
+ *   source: IntegrationSource.BLOCKCHAIN_DIRECT
+ * };
+ *
+ * // Historical price for performance calculation
+ * const historicalPrice: Price = {
+ *   amount: 1800.00,
+ *   currency: 'USD',
+ *   timestamp: new Date('2025-09-11T10:30:00Z')
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link MarketData} for extended market information
+ * @see {@link Balance} for asset valuation usage
+ */
 export interface Price {
-    value: number;
+    /** Price value (primary field for current prices) */
+    value?: number;
+    /** Alternative price field (used by some data sources) */
+    amount?: number;
+    /** Currency code (ISO 4217 for fiat, symbol for crypto, e.g., 'USD', 'ETH') */
     currency: string;
+    /** Timestamp when this price was recorded or fetched */
     timestamp: Date;
-    source: IntegrationSource;
+    /** Data source providing this price (for quality tracking) */
+    source?: IntegrationSource;
 }

package/dist/interfaces/StakedPosition.d.ts

@@ -3,17 +3,94 @@ import { Asset } from './Asset';
 import { Balance } from './Balance';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * Proof-of-stake and staking derivative positions with rewards tracking.
+ *
+ * Represents staked assets in proof-of-stake networks (direct validation) or
+ * liquid staking protocols (derivative tokens). Tracks staked amount, earned
+ * rewards, lockup periods, APR, and validator information.
+ *
+ * **Design Pattern:** DeFi position entity for staking operations, supporting
+ * both direct staking (ETH validators) and liquid staking (stETH, rETH).
+ * Rewards array handles multiple reward tokens common in DeFi protocols.
+ *
+ * @example
+ * ```typescript
+ * import { StakedPosition, Chain, AssetType } from '@cygnus-wealth/data-models';
+ *
+ * // Lido stETH liquid staking position
+ * const lidoPosition: StakedPosition = {
+ *   id: 'lido-steth-123',
+ *   protocol: 'Lido',
+ *   chain: Chain.ETHEREUM,
+ *   asset: {
+ *     id: 'ethereum-eth',
+ *     symbol: 'ETH',
+ *     name: 'Ethereum',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 18
+ *   },
+ *   stakedAmount: '32.0',  // 32 ETH staked
+ *   rewards: [
+ *     {
+ *       assetId: 'ethereum-steth',
+ *       asset: {...},
+ *       amount: '0.45'  // Accrued staking rewards
+ *     }
+ *   ],
+ *   apr: 4.2,  // 4.2% annual percentage rate
+ *   value: {
+ *     value: 64000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   }
+ * };
+ *
+ * // Direct validator staking with lockup
+ * const validatorPosition: StakedPosition = {
+ *   id: 'validator-eth-456',
+ *   protocol: 'Ethereum 2.0',
+ *   validator: '0x123abc...',
+ *   chain: Chain.ETHEREUM,
+ *   asset: {...},
+ *   stakedAmount: '32.0',
+ *   rewards: [],
+ *   lockupPeriod: 2592000,  // 30 days in seconds
+ *   unlockDate: new Date('2025-11-10'),
+ *   apr: 3.8
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability extended
+ *
+ * @see {@link Asset} for staked asset definition
+ * @see {@link Balance} for reward balance structure
+ * @see {@link Account} for position aggregation
+ */
 export interface StakedPosition {
+    /** Unique identifier for this staking position */
     id: string;
+    /** Staking protocol or platform name (e.g., 'Lido', 'Rocket Pool', 'Ethereum 2.0') */
     protocol: string;
+    /** Validator address or ID (for direct staking, optional for liquid staking) */
     validator?: string;
+    /** Blockchain network where assets are staked */
     chain: Chain;
+    /** Asset being staked (e.g., ETH, SOL, MATIC) */
     asset: Asset;
+    /** Amount of asset staked (as string for precision) */
     stakedAmount: string;
+    /** Array of reward balances (can be multiple tokens in some protocols) */
     rewards: Balance[];
+    /** Lockup period in seconds before unstaking is allowed */
     lockupPeriod?: number;
+    /** Date when the lockup expires and unstaking becomes available */
     unlockDate?: Date;
+    /** Annual Percentage Rate for rewards (e.g., 4.2 = 4.2%) */
     apr?: number;
+    /** Current total value of staked position plus rewards */
     value?: Price;
+    /** Protocol-specific metadata (validator performance, slashing history, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/SyncStatus.d.ts

@@ -1,11 +1,66 @@
 import { IntegrationSource } from '../enums/IntegrationSource';
 import { Metadata } from './Metadata';
+/**
+ * Track data synchronization state for accounts and integrations.
+ *
+ * Monitors the status and history of data synchronization operations from external
+ * sources (CEX, DEX, wallets). Essential for UI loading states, error handling,
+ * and determining data freshness.
+ *
+ * **Design Pattern:** State machine pattern with four states (IDLE, SYNCING, SUCCESS, ERROR)
+ * tracking both current status and historical sync information for troubleshooting.
+ *
+ * @example
+ * ```typescript
+ * import { SyncStatus, IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // Successful sync status
+ * const successStatus: SyncStatus = {
+ *   source: IntegrationSource.KRAKEN,
+ *   accountId: 'kraken-spot-1',
+ *   status: 'SUCCESS',
+ *   lastSyncTime: new Date('2025-10-11T10:30:00Z'),
+ *   itemsSynced: 150  // 150 items fetched
+ * };
+ *
+ * // Active syncing status
+ * const syncingStatus: SyncStatus = {
+ *   source: IntegrationSource.METAMASK,
+ *   accountId: 'wallet-1',
+ *   status: 'SYNCING',
+ *   lastSyncTime: new Date('2025-10-11T10:25:00Z')
+ * };
+ *
+ * // Error status with details
+ * const errorStatus: SyncStatus = {
+ *   source: IntegrationSource.COINBASE,
+ *   accountId: 'coinbase-spot-1',
+ *   status: 'ERROR',
+ *   lastSyncTime: new Date('2025-10-11T10:20:00Z'),
+ *   lastError: 'Rate limit exceeded. Retry after 60 seconds.',
+ *   itemsSynced: 0
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link IntegrationSource} for data source identification
+ * @see {@link Account} for account synchronization
+ */
 export interface SyncStatus {
+    /** Data source being synchronized */
     source: IntegrationSource;
+    /** Reference to Account.id being synchronized */
     accountId: string;
+    /** Current synchronization status */
     status: 'IDLE' | 'SYNCING' | 'SUCCESS' | 'ERROR';
+    /** Timestamp of last sync attempt (successful or failed) */
     lastSyncTime?: Date;
+    /** Error message from last failed sync attempt */
     lastError?: string;
+    /** Number of items successfully fetched in last sync */
     itemsSynced?: number;
+    /** Source-specific metadata (retry count, rate limit info, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/Transaction.d.ts

@@ -3,33 +3,145 @@ import { Chain } from '../enums/Chain';
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * Universal transaction representation across all sources.
+ *
+ * Normalized transaction model supporting blockchain transfers, CEX trades,
+ * DEX swaps, DeFi operations, and traditional finance transactions. Uses
+ * asset flow pattern (assetsIn/assetsOut) to handle complex multi-asset
+ * operations like swaps, liquidity provision, and protocol interactions.
+ *
+ * **Design Pattern:** Event sourcing pattern with asset flow arrays supporting
+ * 1:1 transfers, 1:N distributions, N:1 swaps, and N:M complex operations.
+ * Status field enables tracking pending and failed transactions.
+ *
+ * @example
+ * ```typescript
+ * import { Transaction, TransactionType, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // Simple blockchain transfer
+ * const transfer: Transaction = {
+ *   id: 'tx-0x123abc',
+ *   accountId: 'wallet-1',
+ *   type: TransactionType.TRANSFER_OUT,
+ *   status: 'COMPLETED',
+ *   hash: '0x123abc...',
+ *   chain: Chain.ETHEREUM,
+ *   from: '0xSender...',
+ *   to: '0xRecipient...',
+ *   timestamp: new Date('2025-10-11T10:30:00Z'),
+ *   blockNumber: 18500000,
+ *   assetsOut: [{
+ *     asset: { id: 'ethereum-eth', symbol: 'ETH', ... },
+ *     amount: '1.5',
+ *     value: { value: 3000, currency: 'USD', timestamp: new Date() }
+ *   }],
+ *   fees: [{
+ *     asset: { id: 'ethereum-eth', symbol: 'ETH', ... },
+ *     amount: '0.002',
+ *     value: { value: 4, currency: 'USD', timestamp: new Date() }
+ *   }]
+ * };
+ *
+ * // DEX swap (ETH -> USDC)
+ * const swap: Transaction = {
+ *   id: 'tx-0x456def',
+ *   accountId: 'wallet-1',
+ *   type: TransactionType.SWAP,
+ *   status: 'COMPLETED',
+ *   hash: '0x456def...',
+ *   chain: Chain.ETHEREUM,
+ *   timestamp: new Date(),
+ *   blockNumber: 18500123,
+ *   assetsOut: [{
+ *     asset: { id: 'ethereum-eth', symbol: 'ETH', ... },
+ *     amount: '2.0'
+ *   }],
+ *   assetsIn: [{
+ *     asset: { id: 'ethereum-usdc', symbol: 'USDC', ... },
+ *     amount: '4000'
+ *   }],
+ *   protocol: 'Uniswap V3',
+ *   method: 'swapExactTokensForTokens'
+ * };
+ *
+ * // CEX trade
+ * const trade: Transaction = {
+ *   id: 'kraken-trade-789',
+ *   accountId: 'kraken-spot-1',
+ *   type: TransactionType.BUY,
+ *   status: 'COMPLETED',
+ *   timestamp: new Date(),
+ *   assetsOut: [{
+ *     asset: { id: 'fiat-usd', symbol: 'USD', ... },
+ *     amount: '5000'
+ *   }],
+ *   assetsIn: [{
+ *     asset: { id: 'bitcoin-btc', symbol: 'BTC', ... },
+ *     amount: '0.1'
+ *   }]
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link TransactionType} for operation classification
+ * @see {@link Asset} for asset definitions in flows
+ * @see {@link Account} for transaction aggregation
+ */
 export interface Transaction {
+    /** Unique transaction identifier (blockchain hash, CEX order ID, etc.) */
     id: string;
+    /** Reference to the Account.id where this transaction occurred */
     accountId: string;
+    /** Type of transaction operation */
     type: TransactionType;
+    /** Transaction status for lifecycle tracking */
     status: 'PENDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+    /** Blockchain transaction hash (for on-chain transactions) */
     hash?: string;
+    /** Blockchain network where transaction occurred (for on-chain transactions) */
     chain?: Chain;
+    /** Sender address (for blockchain transfers) */
     from?: string;
+    /** Recipient address (for blockchain transfers) */
     to?: string;
+    /** Timestamp when transaction was created or executed */
     timestamp: Date;
+    /** Block number where transaction was included (for on-chain transactions) */
     blockNumber?: number;
-    assets_in?: Array<{
+    /** Assets received in this transaction */
+    assetsIn?: Array<{
+        /** Asset received */
         asset: Asset;
+        /** Amount received (as string for precision) */
         amount: string;
+        /** Value at transaction time (optional) */
         value?: Price;
     }>;
-    assets_out?: Array<{
+    /** Assets sent or consumed in this transaction */
+    assetsOut?: Array<{
+        /** Asset sent */
         asset: Asset;
+        /** Amount sent (as string for precision) */
         amount: string;
+        /** Value at transaction time (optional) */
         value?: Price;
     }>;
+    /** Transaction fees paid (gas, network fees, exchange fees) */
     fees?: Array<{
+        /** Fee asset (ETH for gas, native token for network fees) */
         asset: Asset;
+        /** Fee amount (as string for precision) */
         amount: string;
+        /** Fee value at transaction time (optional) */
         value?: Price;
     }>;
+    /** DeFi protocol or platform involved (e.g., 'Uniswap V3', 'Aave V2') */
     protocol?: string;
+    /** Smart contract method called (for on-chain transactions) */
     method?: string;
+    /** Source-specific additional data (confirmations, memo, etc.) */
     metadata?: Metadata;
 }

package/dist/types/AssetIdentifier.d.ts

@@ -1,7 +1,68 @@
 import { Chain } from '../enums/Chain';
+/**
+ * Flexible asset lookup criteria requiring at least one identifier.
+ *
+ * Used for asset resolution and lookup operations where different identification
+ * methods may be available (symbol, contract address, database ID). At least
+ * one field must be provided for successful asset identification.
+ *
+ * **Design Pattern:** Partial type enabling flexible asset lookup based on
+ * available information. Useful for user input, API queries, and data normalization.
+ *
+ * @example
+ * ```typescript
+ * import { AssetIdentifier, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // Lookup by symbol only
+ * const symbolLookup: AssetIdentifier = {
+ *   symbol: 'ETH'
+ * };
+ *
+ * // Lookup by contract address (most precise)
+ * const contractLookup: AssetIdentifier = {
+ *   contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   chain: Chain.ETHEREUM
+ * };
+ *
+ * // Lookup by symbol + chain (for disambiguation)
+ * const chainedLookup: AssetIdentifier = {
+ *   symbol: 'USDC',
+ *   chain: Chain.POLYGON  // Distinguish from Ethereum USDC
+ * };
+ *
+ * // Lookup by internal ID
+ * const idLookup: AssetIdentifier = {
+ *   assetId: 'ethereum-usdc'
+ * };
+ *
+ * // Asset resolution function example
+ * async function findAsset(identifier: AssetIdentifier): Promise<Asset | null> {
+ *   if (identifier.assetId) {
+ *     return await db.assets.findById(identifier.assetId);
+ *   }
+ *   if (identifier.contractAddress && identifier.chain) {
+ *     return await db.assets.findByContract(identifier.contractAddress, identifier.chain);
+ *   }
+ *   if (identifier.symbol) {
+ *     return await db.assets.findBySymbol(identifier.symbol, identifier.chain);
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Asset} for full asset structure
+ * @see {@link Chain} for blockchain identification
+ */
 export type AssetIdentifier = {
+    /** Asset trading symbol (e.g., 'ETH', 'USDC', 'BTC') */
     symbol?: string;
+    /** Smart contract address for on-chain assets */
     contractAddress?: string;
+    /** Blockchain network for contract-based assets */
     chain?: Chain;
+    /** Internal database asset ID */
     assetId?: string;
 };

package/dist/types/SortOrder.d.ts

@@ -1 +1,51 @@
+/**
+ * Sort direction for query results.
+ *
+ * Standard sort order specification for ordering collections in ascending
+ * or descending order. Used in query parameters, API requests, and UI controls.
+ *
+ * @example
+ * ```typescript
+ * import { SortOrder, Transaction } from '@cygnus-wealth/data-models';
+ *
+ * // Sort transactions by timestamp descending (newest first)
+ * function sortTransactions(
+ *   transactions: Transaction[],
+ *   order: SortOrder = 'DESC'
+ * ): Transaction[] {
+ *   return [...transactions].sort((a, b) => {
+ *     const comparison = a.timestamp.getTime() - b.timestamp.getTime();
+ *     return order === 'ASC' ? comparison : -comparison;
+ *   });
+ * }
+ *
+ * // Sort assets by value ascending (smallest first)
+ * function sortAssetsByValue(
+ *   assets: PortfolioAsset[],
+ *   order: SortOrder = 'ASC'
+ * ): PortfolioAsset[] {
+ *   return [...assets].sort((a, b) => {
+ *     const comparison = (a.value.value || 0) - (b.value.value || 0);
+ *     return order === 'ASC' ? comparison : -comparison;
+ *   });
+ * }
+ *
+ * // API query with sort order
+ * interface QueryParams {
+ *   sortBy: 'timestamp' | 'value' | 'symbol';
+ *   order: SortOrder;
+ * }
+ *
+ * const query: QueryParams = {
+ *   sortBy: 'timestamp',
+ *   order: 'DESC'  // Most recent first
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link PaginatedResponse} for paginated sorting
+ * @see {@link FilterOptions} for combined filtering and sorting
+ */
 export type SortOrder = 'ASC' | 'DESC';

package/dist/types/TimeRange.d.ts

@@ -1,4 +1,55 @@
+/**
+ * Time range specification for filtering and queries.
+ *
+ * Defines an inclusive time range with start and end boundaries in UTC.
+ * Used for filtering transactions, performance calculations, and historical
+ * data queries.
+ *
+ * **Validation:** start must be less than or equal to end.
+ * **Timezone:** All timestamps should be in UTC for consistency.
+ *
+ * @example
+ * ```typescript
+ * import { TimeRange } from '@cygnus-wealth/data-models';
+ *
+ * // Last 30 days
+ * const last30Days: TimeRange = {
+ *   start: new Date('2025-09-11T00:00:00Z'),
+ *   end: new Date('2025-10-11T23:59:59Z')
+ * };
+ *
+ * // Specific month
+ * const september2025: TimeRange = {
+ *   start: new Date('2025-09-01T00:00:00Z'),
+ *   end: new Date('2025-09-30T23:59:59Z')
+ * };
+ *
+ * // Year to date
+ * const ytd: TimeRange = {
+ *   start: new Date('2025-01-01T00:00:00Z'),
+ *   end: new Date()
+ * };
+ *
+ * // Usage in filtering
+ * function filterTransactionsByTime(
+ *   transactions: Transaction[],
+ *   range: TimeRange
+ * ): Transaction[] {
+ *   return transactions.filter(tx =>
+ *     tx.timestamp >= range.start && tx.timestamp <= range.end
+ *   );
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link FilterOptions} for usage in filtering
+ * @see {@link Portfolio} for performance period calculations
+ */
 export type TimeRange = {
+    /** Range start time (inclusive, UTC) */
     start: Date;
+    /** Range end time (inclusive, UTC) */
     end: Date;
 };