@cygnus-wealth/data-models 0.0.1

package/README.md

@@ -0,0 +1,117 @@
+# @cygnus-wealth/data-models
+
+TypeScript type definitions for standardizing financial data across the CygnusWealth ecosystem.
+
+## Overview
+
+This package provides a unified type system for financial data from various sources including:
+- Centralized exchanges (CEX) - Robinhood, Kraken, Coinbase
+- Decentralized exchanges (DEX) and on-chain data
+- Multi-chain wallets - MetaMask, Phantom, Sui Wallet
+- Manual entries and external financial platforms
+
+## Installation
+
+```bash
+npm install @cygnus-wealth/data-models
+```
+
+## Usage
+
+```typescript
+import { 
+  Portfolio, 
+  Asset, 
+  Transaction, 
+  MarketData 
+} from '@cygnus-wealth/data-models';
+
+// Example: Working with portfolio data
+const portfolio: Portfolio = {
+  id: 'portfolio-123',
+  name: 'Main Portfolio',
+  assets: [],
+  totalValue: 50000,
+  source: 'kraken',
+  lastUpdated: new Date()
+};
+```
+
+## Core Types
+
+### Financial Data Types
+- `Portfolio` - Complete portfolio representation
+- `Asset` - Individual asset holdings
+- `Transaction` - Transaction records across platforms
+- `MarketData` - Real-time and historical market data
+- `Position` - Trading positions and holdings
+- `Balance` - Account and wallet balances
+
+### Source Identifiers
+- `DataSource` - Union type for all supported data sources
+- `ChainId` - Blockchain network identifiers
+- `AssetType` - Asset classification (crypto, stock, NFT, etc.)
+
+## Type Design Principles
+
+1. **Multi-source compatibility** - Types accommodate data from various financial platforms
+2. **Optional fields** - Prefer optional properties over provider-specific interfaces
+3. **Source tracking** - Include identifiers to track data origin
+4. **Normalization-ready** - Structured for easy data transformation
+5. **Type safety** - Leverage TypeScript's type system for compile-time guarantees
+
+## Development
+
+### Prerequisites
+- Node.js 18+
+- npm or yarn
+
+### Setup
+```bash
+# Install dependencies
+npm install
+
+# Build type declarations
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+```
+
+### Project Structure
+```
+src/
+├── index.ts        # Main entry point with all type exports
+└── index.test.ts   # Type definition tests
+
+dist/               # Generated TypeScript declarations (gitignored)
+```
+
+### Testing
+Tests ensure type consistency and proper structure:
+```bash
+npm test              # Run tests in watch mode
+npm test -- --run     # Run tests once
+```
+
+## Contributing
+
+When adding new types:
+1. Define types in `src/index.ts`
+2. Add corresponding tests in `src/index.test.ts`
+3. Follow existing naming conventions
+4. Document complex types with JSDoc comments
+5. Run tests and linting before submitting
+
+## License
+
+Part of the CygnusWealth project. See LICENSE file for details.
+
+## Related Packages
+
+- `@cygnus-wealth/web-app` - Main web application
+- `@cygnus-wealth/crypto-utils` - Blockchain utilities
+- `@cygnus-wealth/api-clients` - Exchange API integrations

package/dist/enums/AccountType.d.ts

@@ -0,0 +1,12 @@
+export declare enum AccountType {
+    SPOT = "SPOT",
+    MARGIN = "MARGIN",
+    FUTURES = "FUTURES",
+    SAVINGS = "SAVINGS",
+    STAKING = "STAKING",
+    WALLET = "WALLET",
+    DEFI = "DEFI",
+    BROKERAGE = "BROKERAGE",
+    RETIREMENT = "RETIREMENT",
+    OTHER = "OTHER"
+}

package/dist/enums/AssetType.d.ts

@@ -0,0 +1,15 @@
+export declare enum AssetType {
+    CRYPTOCURRENCY = "CRYPTOCURRENCY",
+    STOCK = "STOCK",
+    ETF = "ETF",
+    MUTUAL_FUND = "MUTUAL_FUND",
+    BOND = "BOND",
+    COMMODITY = "COMMODITY",
+    FIAT = "FIAT",
+    NFT = "NFT",
+    DERIVATIVE = "DERIVATIVE",
+    LIQUIDITY_POOL = "LIQUIDITY_POOL",
+    STAKED_POSITION = "STAKED_POSITION",
+    LENDING_POSITION = "LENDING_POSITION",
+    OTHER = "OTHER"
+}

package/dist/enums/Chain.d.ts

@@ -0,0 +1,12 @@
+export declare enum Chain {
+    ETHEREUM = "ETHEREUM",
+    POLYGON = "POLYGON",
+    ARBITRUM = "ARBITRUM",
+    OPTIMISM = "OPTIMISM",
+    AVALANCHE = "AVALANCHE",
+    BSC = "BSC",
+    SOLANA = "SOLANA",
+    SUI = "SUI",
+    BITCOIN = "BITCOIN",
+    OTHER = "OTHER"
+}

package/dist/enums/IntegrationSource.d.ts

@@ -0,0 +1,18 @@
+export declare enum IntegrationSource {
+    ROBINHOOD = "ROBINHOOD",
+    KRAKEN = "KRAKEN",
+    COINBASE = "COINBASE",
+    BINANCE = "BINANCE",
+    UNISWAP = "UNISWAP",
+    SUSHISWAP = "SUSHISWAP",
+    PANCAKESWAP = "PANCAKESWAP",
+    CURVE = "CURVE",
+    BALANCER = "BALANCER",
+    METAMASK = "METAMASK",
+    RABBY = "RABBY",
+    PHANTOM = "PHANTOM",
+    SLUSH = "SLUSH",
+    MANUAL_ENTRY = "MANUAL_ENTRY",
+    BLOCKCHAIN_DIRECT = "BLOCKCHAIN_DIRECT",
+    OTHER = "OTHER"
+}

package/dist/enums/TransactionType.d.ts

@@ -0,0 +1,21 @@
+export declare enum TransactionType {
+    BUY = "BUY",
+    SELL = "SELL",
+    TRANSFER_IN = "TRANSFER_IN",
+    TRANSFER_OUT = "TRANSFER_OUT",
+    SWAP = "SWAP",
+    STAKE = "STAKE",
+    UNSTAKE = "UNSTAKE",
+    CLAIM_REWARD = "CLAIM_REWARD",
+    PROVIDE_LIQUIDITY = "PROVIDE_LIQUIDITY",
+    REMOVE_LIQUIDITY = "REMOVE_LIQUIDITY",
+    BORROW = "BORROW",
+    REPAY = "REPAY",
+    LIQUIDATION = "LIQUIDATION",
+    MINT = "MINT",
+    BURN = "BURN",
+    FEE = "FEE",
+    DIVIDEND = "DIVIDEND",
+    INTEREST = "INTEREST",
+    OTHER = "OTHER"
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export { AssetType } from './enums/AssetType';
+export { Chain } from './enums/Chain';
+export { IntegrationSource } from './enums/IntegrationSource';
+export { TransactionType } from './enums/TransactionType';
+export { AccountType } from './enums/AccountType';
+export { BaseEntity } from './interfaces/BaseEntity';
+export { Metadata } from './interfaces/Metadata';
+export { Asset } from './interfaces/Asset';
+export { NFT } from './interfaces/NFT';
+export { Price } from './interfaces/Price';
+export { MarketData } from './interfaces/MarketData';
+export { Balance } from './interfaces/Balance';
+export { LiquidityPosition } from './interfaces/LiquidityPosition';
+export { StakedPosition } from './interfaces/StakedPosition';
+export { LendingPosition } from './interfaces/LendingPosition';
+export { Account } from './interfaces/Account';
+export { Portfolio } from './interfaces/Portfolio';
+export { Transaction } from './interfaces/Transaction';
+export { IntegrationCredentials } from './interfaces/IntegrationCredentials';
+export { SyncStatus } from './interfaces/SyncStatus';
+export { ApiResponse } from './interfaces/ApiResponse';
+export { ApiError } from './interfaces/ApiError';
+export { PaginatedResponse } from './interfaces/PaginatedResponse';
+export { AssetIdentifier } from './types/AssetIdentifier';
+export { TimeRange } from './types/TimeRange';
+export { SortOrder } from './types/SortOrder';
+export { FilterOptions } from './interfaces/FilterOptions';
+export { PortfolioItem } from './interfaces/PortfolioItem';

package/dist/index.test.d.ts

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

package/dist/interfaces/Account.d.ts

@@ -0,0 +1,24 @@
+import { AccountType } from '../enums/AccountType';
+import { IntegrationSource } from '../enums/IntegrationSource';
+import { Balance } from './Balance';
+import { LiquidityPosition } from './LiquidityPosition';
+import { StakedPosition } from './StakedPosition';
+import { LendingPosition } from './LendingPosition';
+import { NFT } from './NFT';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface Account {
+    id: string;
+    name: string;
+    type: AccountType;
+    source: IntegrationSource;
+    sourceAccountId?: string;
+    balances: Balance[];
+    liquidityPositions?: LiquidityPosition[];
+    stakedPositions?: StakedPosition[];
+    lendingPositions?: LendingPosition[];
+    nfts?: NFT[];
+    totalValue?: Price;
+    lastSynced?: Date;
+    metadata?: Metadata;
+}

package/dist/interfaces/ApiError.d.ts

@@ -0,0 +1,5 @@
+export interface ApiError {
+    code: string;
+    message: string;
+    details?: unknown;
+}

package/dist/interfaces/ApiResponse.d.ts

@@ -0,0 +1,7 @@
+import { ApiError } from './ApiError';
+export interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: ApiError;
+    timestamp: Date;
+}

package/dist/interfaces/Asset.d.ts

@@ -0,0 +1,18 @@
+import { AssetType } from '../enums/AssetType';
+import { Chain } from '../enums/Chain';
+import { Metadata } from './Metadata';
+export interface Asset {
+    id: string;
+    symbol: string;
+    name: string;
+    type: AssetType;
+    decimals?: number;
+    contractAddress?: string;
+    chain?: Chain;
+    logoUrl?: string;
+    coingeckoId?: string;
+    cmc_id?: string;
+    cusip?: string;
+    isin?: string;
+    metadata?: Metadata;
+}

package/dist/interfaces/Balance.d.ts

@@ -0,0 +1,13 @@
+import { Asset } from './Asset';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface Balance {
+    assetId: string;
+    asset: Asset;
+    amount: string;
+    value?: Price;
+    cost_basis?: number;
+    realized_pnl?: number;
+    unrealized_pnl?: number;
+    metadata?: Metadata;
+}

package/dist/interfaces/BaseEntity.d.ts

@@ -0,0 +1,5 @@
+export interface BaseEntity {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/interfaces/FilterOptions.d.ts

@@ -0,0 +1,12 @@
+import { Chain } from '../enums/Chain';
+import { AssetType } from '../enums/AssetType';
+import { IntegrationSource } from '../enums/IntegrationSource';
+import { TimeRange } from '../types/TimeRange';
+export interface FilterOptions {
+    chains?: Chain[];
+    assetTypes?: AssetType[];
+    sources?: IntegrationSource[];
+    timeRange?: TimeRange;
+    minValue?: number;
+    maxValue?: number;
+}

package/dist/interfaces/IntegrationCredentials.d.ts

@@ -0,0 +1,11 @@
+import { IntegrationSource } from '../enums/IntegrationSource';
+import { Metadata } from './Metadata';
+export interface IntegrationCredentials {
+    source: IntegrationSource;
+    apiKey?: string;
+    apiSecret?: string;
+    passphrase?: string;
+    walletAddress?: string;
+    chainId?: string;
+    metadata?: Metadata;
+}

package/dist/interfaces/LendingPosition.d.ts

@@ -0,0 +1,18 @@
+import { Chain } from '../enums/Chain';
+import { Asset } from './Asset';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface LendingPosition {
+    id: string;
+    protocol: string;
+    chain: Chain;
+    type: 'SUPPLY' | 'BORROW';
+    asset: Asset;
+    amount: string;
+    apy?: number;
+    accrued_interest?: number;
+    health_factor?: number;
+    liquidation_threshold?: number;
+    value?: Price;
+    metadata?: Metadata;
+}

package/dist/interfaces/LiquidityPosition.d.ts

@@ -0,0 +1,18 @@
+import { Chain } from '../enums/Chain';
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface LiquidityPosition {
+    id: string;
+    protocol: string;
+    poolAddress: string;
+    poolName: string;
+    chain: Chain;
+    tokens: Balance[];
+    lpTokenBalance?: string;
+    share?: number;
+    value?: Price;
+    fees_earned?: number;
+    impermanent_loss?: number;
+    metadata?: Metadata;
+}

package/dist/interfaces/MarketData.d.ts

@@ -0,0 +1,14 @@
+import { Price } from './Price';
+export interface MarketData {
+    assetId: string;
+    currentPrice: Price;
+    marketCap?: number;
+    volume24h?: number;
+    priceChange24h?: number;
+    priceChangePercentage24h?: number;
+    high24h?: number;
+    low24h?: number;
+    circulatingSupply?: number;
+    totalSupply?: number;
+    lastUpdated: Date;
+}

package/dist/interfaces/Metadata.d.ts

@@ -0,0 +1,3 @@
+export interface Metadata {
+    [key: string]: unknown;
+}

package/dist/interfaces/NFT.d.ts

@@ -0,0 +1,14 @@
+import { Asset } from './Asset';
+export interface NFT extends Asset {
+    tokenId: string;
+    collectionAddress: string;
+    collectionName: string;
+    tokenUri?: string;
+    imageUrl?: string;
+    animationUrl?: string;
+    attributes?: Array<{
+        trait_type: string;
+        value: string | number;
+        display_type?: string;
+    }>;
+}

package/dist/interfaces/PaginatedResponse.d.ts

@@ -0,0 +1,7 @@
+export interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+}

package/dist/interfaces/Portfolio.d.ts

@@ -0,0 +1,21 @@
+import { Account } from './Account';
+import { Price } from './Price';
+export interface Portfolio {
+    id: string;
+    userId: string;
+    name: string;
+    accounts: Account[];
+    totalValue: Price;
+    totalValueHistory?: Array<{
+        timestamp: Date;
+        value: Price;
+    }>;
+    performance?: {
+        day: number;
+        week: number;
+        month: number;
+        year: number;
+        all_time: number;
+    };
+    lastUpdated: Date;
+}

package/dist/interfaces/PortfolioItem.d.ts

@@ -0,0 +1,4 @@
+export interface PortfolioItem {
+    id: string;
+    balance: number;
+}

package/dist/interfaces/Price.d.ts

@@ -0,0 +1,7 @@
+import { IntegrationSource } from '../enums/IntegrationSource';
+export interface Price {
+    value: number;
+    currency: string;
+    timestamp: Date;
+    source: IntegrationSource;
+}

package/dist/interfaces/StakedPosition.d.ts

@@ -0,0 +1,19 @@
+import { Chain } from '../enums/Chain';
+import { Asset } from './Asset';
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface StakedPosition {
+    id: string;
+    protocol: string;
+    validator?: string;
+    chain: Chain;
+    asset: Asset;
+    stakedAmount: string;
+    rewards: Balance[];
+    lockupPeriod?: number;
+    unlockDate?: Date;
+    apr?: number;
+    value?: Price;
+    metadata?: Metadata;
+}

package/dist/interfaces/SyncStatus.d.ts

@@ -0,0 +1,11 @@
+import { IntegrationSource } from '../enums/IntegrationSource';
+import { Metadata } from './Metadata';
+export interface SyncStatus {
+    source: IntegrationSource;
+    accountId: string;
+    status: 'IDLE' | 'SYNCING' | 'SUCCESS' | 'ERROR';
+    lastSyncTime?: Date;
+    lastError?: string;
+    itemsSynced?: number;
+    metadata?: Metadata;
+}

package/dist/interfaces/Transaction.d.ts

@@ -0,0 +1,35 @@
+import { TransactionType } from '../enums/TransactionType';
+import { Chain } from '../enums/Chain';
+import { Asset } from './Asset';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+export interface Transaction {
+    id: string;
+    accountId: string;
+    type: TransactionType;
+    status: 'PENDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+    hash?: string;
+    chain?: Chain;
+    from?: string;
+    to?: string;
+    timestamp: Date;
+    blockNumber?: number;
+    assets_in?: Array<{
+        asset: Asset;
+        amount: string;
+        value?: Price;
+    }>;
+    assets_out?: Array<{
+        asset: Asset;
+        amount: string;
+        value?: Price;
+    }>;
+    fees?: Array<{
+        asset: Asset;
+        amount: string;
+        value?: Price;
+    }>;
+    protocol?: string;
+    method?: string;
+    metadata?: Metadata;
+}

package/dist/types/AssetIdentifier.d.ts

@@ -0,0 +1,7 @@
+import { Chain } from '../enums/Chain';
+export type AssetIdentifier = {
+    symbol?: string;
+    contractAddress?: string;
+    chain?: Chain;
+    assetId?: string;
+};

package/dist/types/SortOrder.d.ts

@@ -0,0 +1 @@
+export type SortOrder = 'ASC' | 'DESC';

package/dist/types/TimeRange.d.ts

@@ -0,0 +1,4 @@
+export type TimeRange = {
+    start: Date;
+    end: Date;
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cygnus-wealth/data-models",
+  "version": "0.0.1",
+  "description": "Shared TypeScript data models for CygnusWealth project",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "lint": "eslint . --ext .ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.32.0",
+    "globals": "^16.3.0",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0",
+    "vitest": "^3.2.4"
+  }
+}