@cygnus-wealth/data-models 0.0.2 → 1.0.0

package/dist/enums/TransactionType.js

@@ -1,22 +1,72 @@
+/**
+ * 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
+ */
 export 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 || (TransactionType = {}));

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { Chain } from './enums/Chain';
 export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
+export { LendingPositionType } from './enums/LendingPositionType';
 export { BaseEntity } from './interfaces/BaseEntity';
 export { Metadata } from './interfaces/Metadata';
 export { Asset } from './interfaces/Asset';
@@ -15,6 +16,7 @@ export { StakedPosition } from './interfaces/StakedPosition';
 export { LendingPosition } from './interfaces/LendingPosition';
 export { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
+export { PortfolioAsset } from './interfaces/PortfolioAsset';
 export { Transaction } from './interfaces/Transaction';
 export { IntegrationCredentials } from './interfaces/IntegrationCredentials';
 export { SyncStatus } from './interfaces/SyncStatus';

package/dist/index.js

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

package/dist/interfaces/Account.d.ts

@@ -7,18 +7,110 @@ import { LendingPosition } from './LendingPosition';
 import { NFT } from './NFT';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * Aggregate container for all holdings from a single source.
+ *
+ * Represents a complete account (wallet, CEX account, brokerage, etc.) with all
+ * associated balances, DeFi positions, and NFTs. Central aggregation point for
+ * calculating total account value and tracking synchronization state.
+ *
+ * **Design Pattern:** Aggregate root pattern collecting all holdings from one
+ * source. Supports flexible position types (balances, liquidity, staking, lending)
+ * to accommodate diverse account types (spot, DeFi, wallet).
+ *
+ * @example
+ * ```typescript
+ * import { Account, AccountType, IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // MetaMask wallet account with balances and DeFi positions
+ * const walletAccount: Account = {
+ *   id: 'metamask-wallet-1',
+ *   name: 'Main Wallet',
+ *   type: AccountType.WALLET,
+ *   source: IntegrationSource.METAMASK,
+ *   sourceAccountId: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+ *   balances: [
+ *     {
+ *       assetId: 'ethereum-eth',
+ *       asset: {...},
+ *       amount: '5.0',
+ *       value: { value: 10000, currency: 'USD', timestamp: new Date() }
+ *     },
+ *     {
+ *       assetId: 'ethereum-usdc',
+ *       asset: {...},
+ *       amount: '15000'
+ *     }
+ *   ],
+ *   liquidityPositions: [
+ *     {
+ *       id: 'uniswap-eth-usdc-1',
+ *       protocol: 'Uniswap V2',
+ *       poolName: 'ETH/USDC',
+ *       tokens: [...]
+ *     }
+ *   ],
+ *   stakedPositions: [
+ *     {
+ *       id: 'lido-steth-1',
+ *       protocol: 'Lido',
+ *       stakedAmount: '2.0',
+ *       rewards: [...]
+ *     }
+ *   ],
+ *   totalValue: {
+ *     value: 30000,  // Sum of all positions
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   lastSynced: new Date()
+ * };
+ *
+ * // Kraken CEX spot account
+ * const cexAccount: Account = {
+ *   id: 'kraken-spot-1',
+ *   name: 'Kraken Spot Trading',
+ *   type: AccountType.SPOT,
+ *   source: IntegrationSource.KRAKEN,
+ *   balances: [...],
+ *   totalValue: { value: 50000, currency: 'USD', timestamp: new Date() },
+ *   lastSynced: new Date()
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link AccountType} for account classification
+ * @see {@link IntegrationSource} for source identification
+ * @see {@link Balance} for asset holdings
+ * @see {@link Portfolio} for multi-account aggregation
+ */
 export interface Account {
+    /** Unique identifier for this account */
     id: string;
+    /** User-friendly account name (e.g., 'Main Wallet', 'Trading Account') */
     name: string;
+    /** Type of account for categorization and specialized processing */
     type: AccountType;
+    /** Data source providing this account's information */
     source: IntegrationSource;
+    /** Source-specific account identifier (wallet address, exchange account ID, etc.) */
     sourceAccountId?: string;
+    /** Array of asset balances held in this account */
     balances: Balance[];
+    /** Array of DEX liquidity positions (for DeFi accounts) */
     liquidityPositions?: LiquidityPosition[];
+    /** Array of staking positions (for PoS and liquid staking) */
     stakedPositions?: StakedPosition[];
+    /** Array of lending/borrowing positions (for DeFi money markets) */
     lendingPositions?: LendingPosition[];
+    /** Array of NFTs held in this account */
     nfts?: NFT[];
+    /** Total value of all holdings in this account (sum of all positions) */
     totalValue?: Price;
+    /** Timestamp of last successful data synchronization */
     lastSynced?: Date;
+    /** Source-specific metadata (connection status, permissions, etc.) */
     metadata?: Metadata;
 }

package/dist/interfaces/ApiError.d.ts

@@ -1,5 +1,66 @@
+/**
+ * Standardized error structure for API responses.
+ *
+ * Provides machine-readable error codes and human-readable messages for
+ * consistent error handling across all integrations. Details field allows
+ * source-specific error information like stack traces or validation errors.
+ *
+ * **Design Pattern:** Structured error with code for programmatic handling
+ * and message for display. Details field accommodates varying error contexts.
+ *
+ * @example
+ * ```typescript
+ * import { ApiError } from '@cygnus-wealth/data-models';
+ *
+ * // Simple error
+ * const simpleError: ApiError = {
+ *   code: 'UNAUTHORIZED',
+ *   message: 'Invalid API key'
+ * };
+ *
+ * // Error with validation details
+ * const validationError: ApiError = {
+ *   code: 'VALIDATION_ERROR',
+ *   message: 'Request validation failed',
+ *   details: {
+ *     fields: {
+ *       amount: 'Must be positive number',
+ *       symbol: 'Required field'
+ *     }
+ *   }
+ * };
+ *
+ * // Error with stack trace (development)
+ * const serverError: ApiError = {
+ *   code: 'INTERNAL_ERROR',
+ *   message: 'An unexpected error occurred',
+ *   details: {
+ *     stack: 'Error: ...',
+ *     timestamp: new Date().toISOString()
+ *   }
+ * };
+ *
+ * // Common error codes
+ * const errorCodes = {
+ *   RATE_LIMIT: 'Too many requests',
+ *   NOT_FOUND: 'Resource not found',
+ *   UNAUTHORIZED: 'Authentication required',
+ *   FORBIDDEN: 'Insufficient permissions',
+ *   TIMEOUT: 'Request timeout',
+ *   NETWORK_ERROR: 'Network connection failed'
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link ApiResponse} for error usage in responses
+ */
 export interface ApiError {
+    /** Machine-readable error code (e.g., 'RATE_LIMIT', 'UNAUTHORIZED') */
     code: string;
+    /** Human-readable error message for display */
     message: string;
+    /** Optional error-specific details (stack trace, field errors, etc.) */
     details?: unknown;
 }

package/dist/interfaces/ApiResponse.d.ts

@@ -1,7 +1,66 @@
 import { ApiError } from './ApiError';
-export interface ApiResponse<T> {
+/**
+ * Generic API response wrapper with success/error discrimination.
+ *
+ * Standard envelope for all API responses providing consistent structure for
+ * success and error handling. Mutually exclusive data/error pattern ensures
+ * type-safe response processing.
+ *
+ * **Design Pattern:** Result monad pattern with discriminated union - exactly
+ * one of data or error is present based on success flag. Timestamp enables
+ * response caching and freshness tracking.
+ *
+ * @template T - Response data type (should be object, not primitive)
+ *
+ * @example
+ * ```typescript
+ * import { ApiResponse, Account } from '@cygnus-wealth/data-models';
+ *
+ * // Successful response
+ * const successResponse: ApiResponse<Account> = {
+ *   success: true,
+ *   data: {
+ *     id: 'wallet-1',
+ *     name: 'Main Wallet',
+ *     type: AccountType.WALLET,
+ *     balances: [...]
+ *   },
+ *   timestamp: new Date()
+ * };
+ *
+ * // Error response
+ * const errorResponse: ApiResponse<Account> = {
+ *   success: false,
+ *   error: {
+ *     code: 'RATE_LIMIT',
+ *     message: 'Rate limit exceeded. Retry after 60 seconds.'
+ *   },
+ *   timestamp: new Date()
+ * };
+ *
+ * // Type-safe handling
+ * function handleResponse(response: ApiResponse<Account>) {
+ *   if (response.success && response.data) {
+ *     console.log('Account:', response.data.name);
+ *   } else if (response.error) {
+ *     console.error('Error:', response.error.message);
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link ApiError} for error structure
+ * @see {@link PaginatedResponse} for paginated data
+ */
+export interface ApiResponse<T extends object> {
+    /** Indicates whether the API call succeeded */
     success: boolean;
+    /** Response data (present if success === true) */
     data?: T;
+    /** Error details (present if success === false) */
     error?: ApiError;
+    /** Timestamp when the response was generated */
     timestamp: Date;
 }

package/dist/interfaces/Asset.d.ts

@@ -1,18 +1,77 @@
 import { AssetType } from '../enums/AssetType';
 import { Chain } from '../enums/Chain';
 import { Metadata } from './Metadata';
+/**
+ * Universal asset representation normalizing data from multiple sources.
+ *
+ * Core entity representing any tradeable or holdable financial instrument including
+ * cryptocurrencies, stocks, ETFs, NFTs, bonds, fiat currencies, and commodities.
+ * Designed to accommodate data from CEX APIs, DEX subgraphs, blockchain RPCs,
+ * and traditional finance systems.
+ *
+ * **Design Pattern:** Flexible field set supports source-specific identifiers
+ * (contractAddress for tokens, cusip/isin for securities, coingeckoId for market data)
+ * while maintaining consistent core identity (id, symbol, name, type).
+ *
+ * @example
+ * ```typescript
+ * import { Asset, AssetType, Chain } from '@cygnus-wealth/data-models';
+ *
+ * // ERC-20 token from blockchain
+ * const usdcAsset: Asset = {
+ *   id: 'ethereum-usdc',
+ *   symbol: 'USDC',
+ *   name: 'USD Coin',
+ *   type: AssetType.CRYPTOCURRENCY,
+ *   decimals: 6,
+ *   contractAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   chain: Chain.ETHEREUM,
+ *   coingeckoId: 'usd-coin'
+ * };
+ *
+ * // Traditional stock from brokerage
+ * const appleStock: Asset = {
+ *   id: 'us-aapl',
+ *   symbol: 'AAPL',
+ *   name: 'Apple Inc.',
+ *   type: AssetType.STOCK,
+ *   cusip: '037833100',
+ *   isin: 'US0378331005'
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link AssetType} for classification values
+ * @see {@link Chain} for blockchain identifiers
+ * @see {@link NFT} for NFT-specific extensions
+ */
 export interface Asset {
+    /** Unique identifier across all sources (e.g., 'ethereum-usdc', 'us-aapl') */
     id: string;
+    /** Trading symbol or ticker (e.g., 'USDC', 'AAPL', 'BTC') */
     symbol: string;
+    /** Human-readable asset name (e.g., 'USD Coin', 'Apple Inc.') */
     name: string;
+    /** Asset classification for filtering and display logic */
     type: AssetType;
+    /** Decimal places for balance precision (e.g., 18 for ETH, 6 for USDC, 2 for USD) */
     decimals?: number;
+    /** Smart contract address for blockchain tokens (ERC-20, SPL, etc.) */
     contractAddress?: string;
+    /** Blockchain network for token assets */
     chain?: Chain;
+    /** URL to asset logo or icon for UI display */
     logoUrl?: string;
+    /** CoinGecko API identifier for market data integration */
     coingeckoId?: string;
+    /** CoinMarketCap API identifier for market data integration */
     cmc_id?: string;
+    /** CUSIP identifier for North American securities */
     cusip?: string;
+    /** ISIN identifier for international securities */
     isin?: string;
+    /** Source-specific additional data and custom fields */
     metadata?: Metadata;
 }

package/dist/interfaces/Balance.d.ts

@@ -1,13 +1,65 @@
 import { Asset } from './Asset';
 import { Price } from './Price';
 import { Metadata } from './Metadata';
+/**
+ * Asset quantity with market value and profit/loss tracking.
+ *
+ * Represents the amount of an asset held in an account along with valuation
+ * and performance metrics. Uses string for amount to preserve precision beyond
+ * JavaScript number limits (e.g., for high-decimal tokens or very large quantities).
+ *
+ * **Design Pattern:** Composition of Asset reference, quantity, current value,
+ * and historical cost basis for P&L calculations. The amount field stores raw
+ * quantity respecting the asset's decimal places.
+ *
+ * @example
+ * ```typescript
+ * import { Balance, Asset, AssetType } from '@cygnus-wealth/data-models';
+ *
+ * // Cryptocurrency balance with P&L
+ * const ethBalance: Balance = {
+ *   assetId: 'ethereum-eth',
+ *   asset: {
+ *     id: 'ethereum-eth',
+ *     symbol: 'ETH',
+ *     name: 'Ethereum',
+ *     type: AssetType.CRYPTOCURRENCY,
+ *     decimals: 18
+ *   },
+ *   amount: '2.5',  // 2.5 ETH
+ *   value: {
+ *     value: 5000,
+ *     currency: 'USD',
+ *     timestamp: new Date()
+ *   },
+ *   cost_basis: 4000,  // Purchased for $4000
+ *   unrealized_pnl: 1000,  // Current profit
+ *   realized_pnl: 0
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Asset} for asset definition
+ * @see {@link Price} for valuation structure
+ * @see {@link PortfolioAsset} for composed portfolio view
+ */
 export interface Balance {
+    /** Reference to the Asset.id being held */
     assetId: string;
+    /** Complete asset details for display and calculations */
     asset: Asset;
+    /** Quantity held as string to preserve precision (respects asset.decimals) */
     amount: string;
+    /** Current market value of the balance (amount * current price) */
     value?: Price;
+    /** Total cost paid to acquire this balance (in value.currency) */
     cost_basis?: number;
+    /** Profit/loss from realized sales (in value.currency) */
     realized_pnl?: number;
+    /** Profit/loss from current market value vs cost basis (value.value - cost_basis) */
     unrealized_pnl?: number;
+    /** Source-specific additional data and custom fields */
     metadata?: Metadata;
 }

package/dist/interfaces/BaseEntity.d.ts

@@ -1,5 +1,66 @@
+/**
+ * Base entity interface providing common identity and timestamp fields.
+ *
+ * BaseEntity serves as the foundational building block for all entity types in the
+ * CygnusWealth system. It establishes the pattern for entity identity and audit
+ * tracking across all bounded contexts.
+ *
+ * In Domain-Driven Design terms, this represents the common characteristics of all
+ * Entities (objects with identity), as distinguished from Value Objects (objects
+ * defined by their attributes).
+ *
+ * @example
+ * ```typescript
+ * interface Account extends BaseEntity {
+ *   name: string;
+ *   type: AccountType;
+ * }
+ *
+ * const account: Account = {
+ *   id: "acc_123",
+ *   createdAt: new Date("2025-01-01T00:00:00Z"),
+ *   updatedAt: new Date("2025-01-01T00:00:00Z"),
+ *   name: "Main Wallet",
+ *   type: AccountType.WALLET
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability core
+ *
+ * @see {@link Account} for an example entity using BaseEntity
+ * @see {@link Portfolio} for another example entity
+ */
 export interface BaseEntity {
+    /**
+     * Unique identifier for the entity.
+     *
+     * Format varies by entity type but must be globally unique within the entity's
+     * bounded context. Common patterns include:
+     * - UUID v4: `"550e8400-e29b-41d4-a716-446655440000"`
+     * - Prefixed ID: `"acc_123"`, `"txn_abc"`
+     * - Composite ID: `"eth-ethereum"`, `"btc-mainnet"`
+     *
+     * Consumers should treat IDs as opaque strings and not parse or derive meaning
+     * from their structure, as ID formats may evolve.
+     */
     id: string;
+    /**
+     * Timestamp when the entity was first created.
+     *
+     * Must be in UTC timezone. Immutable after initial creation.
+     * Used for audit trails and chronological sorting.
+     *
+     * @example new Date("2025-01-01T00:00:00Z")
+     */
     createdAt: Date;
+    /**
+     * Timestamp when the entity was last modified.
+     *
+     * Must be in UTC timezone. Updated on every mutation.
+     * Used for cache invalidation and optimistic locking.
+     *
+     * @example new Date("2025-01-15T14:30:00Z")
+     */
     updatedAt: Date;
 }

package/dist/interfaces/FilterOptions.d.ts

@@ -2,11 +2,79 @@ import { Chain } from '../enums/Chain';
 import { AssetType } from '../enums/AssetType';
 import { IntegrationSource } from '../enums/IntegrationSource';
 import { TimeRange } from '../types/TimeRange';
+/**
+ * Flexible filtering criteria for portfolio and transaction queries.
+ *
+ * Composable filter interface supporting multi-dimensional filtering across
+ * chains, asset types, sources, time ranges, and value thresholds. All filters
+ * use AND logic between different filter types and OR logic within array filters.
+ *
+ * **Filter Logic:**
+ * - Multiple filter types are combined with AND
+ * - Array values within a filter type are combined with OR
+ * - Example: chains=[ETHEREUM, POLYGON] AND assetTypes=[CRYPTOCURRENCY]
+ *
+ * @example
+ * ```typescript
+ * import { FilterOptions, Chain, AssetType, IntegrationSource } from '@cygnus-wealth/data-models';
+ *
+ * // Filter for Ethereum/Polygon crypto assets
+ * const cryptoFilter: FilterOptions = {
+ *   chains: [Chain.ETHEREUM, Chain.POLYGON],
+ *   assetTypes: [AssetType.CRYPTOCURRENCY]
+ * };
+ *
+ * // Filter for high-value positions in last 30 days
+ * const recentHighValueFilter: FilterOptions = {
+ *   minValue: 10000,  // >= $10k
+ *   timeRange: {
+ *     start: new Date('2025-09-11'),
+ *     end: new Date('2025-10-11')
+ *   }
+ * };
+ *
+ * // Filter for wallet assets only
+ * const walletFilter: FilterOptions = {
+ *   sources: [
+ *     IntegrationSource.METAMASK,
+ *     IntegrationSource.RABBY,
+ *     IntegrationSource.PHANTOM
+ *   ]
+ * };
+ *
+ * // Complex multi-dimensional filter
+ * const complexFilter: FilterOptions = {
+ *   chains: [Chain.ETHEREUM],
+ *   assetTypes: [AssetType.CRYPTOCURRENCY, AssetType.NFT],
+ *   sources: [IntegrationSource.METAMASK],
+ *   minValue: 1000,
+ *   maxValue: 50000,
+ *   timeRange: {
+ *     start: new Date('2025-01-01'),
+ *     end: new Date()
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.0.1
+ * @stability standard
+ *
+ * @see {@link Chain} for blockchain filtering
+ * @see {@link AssetType} for asset classification filtering
+ * @see {@link IntegrationSource} for source filtering
+ * @see {@link TimeRange} for time-based filtering
+ */
 export interface FilterOptions {
+    /** Filter by blockchain networks (OR within array) */
     chains?: Chain[];
+    /** Filter by asset types (OR within array) */
     assetTypes?: AssetType[];
+    /** Filter by data sources (OR within array) */
     sources?: IntegrationSource[];
+    /** Filter by time range (inclusive start and end) */
     timeRange?: TimeRange;
+    /** Minimum value threshold (inclusive, in base currency like USD) */
     minValue?: number;
+    /** Maximum value threshold (inclusive, in base currency like USD) */
     maxValue?: number;
 }