feat: add multi-wallet multi-account identity types

etc/data-models.api.md

@@ -22,6 +22,88 @@ export interface Account {
     vaultPositions?: VaultPosition[];
 }
 
+// @public
+export interface AccountAssetEntry {
+    accountId: AccountId;
+    accountLabel: string;
+    connectionLabel: string;
+    percentage: number;
+    quantity: Balance;
+    value: Price;
+}
+
+// @public
+export interface AccountBalance {
+    accountId: AccountId;
+    address: string;
+    chainId: Chain;
+    nativeBalance: Balance;
+    tokenBalances: Balance[];
+}
+
+// @public
+export interface AccountBalanceList {
+    balances: AccountBalance[];
+    errors: AccountError[];
+    timestamp: string;
+}
+
+// @public
+export interface AccountError {
+    accountId: AccountId;
+    chainId: Chain;
+    code?: string;
+    message: string;
+}
+
+// @public
+export interface AccountGroup {
+    accountIds: AccountId[];
+    createdAt: string;
+    groupId: string;
+    groupName: string;
+}
+
+// @public
+export type AccountId = string;
+
+// @public
+export interface AccountMetadata {
+    accountId: AccountId;
+    accountLabel: string;
+    address: string;
+    connectionLabel: string;
+    discoveredAt: string;
+    groups: string[];
+    isActive: boolean;
+    isStale: boolean;
+    providerId: WalletProviderId | 'watch';
+    walletConnectionId: WalletConnectionId | 'watch';
+}
+
+// @public
+export interface AccountPortfolio {
+    accountId: AccountId;
+    accountLabel: string;
+    assets: Asset[];
+    lastUpdated: string;
+    providerName: string;
+    totalValue: Price;
+    walletConnectionId: WalletConnectionId | 'watch';
+}
+
+// @public
+export interface AccountSummary {
+    accountId: AccountId;
+    accountLabel: string;
+    assetCount: number;
+    chains: Chain[];
+    connectionLabel: string;
+    lastUpdated: string;
+    providerId: WalletProviderId | 'watch';
+    totalValue: Price;
+}
+
 // @public
 export enum AccountType {
     BROKERAGE = "BROKERAGE",
@@ -36,6 +118,13 @@ export enum AccountType {
     WALLET = "WALLET"
 }
 
+// @public
+export interface AddressRequest {
+    accountId: AccountId;
+    address: string;
+    chainScope: Chain[];
+}
+
 // @public
 export interface ApiError {
     code: string;
@@ -53,6 +142,7 @@ export interface ApiResponse<T extends object> {
 
 // @public
 export interface Asset {
+    accountId?: AccountId;
     chain?: Chain;
     cmc_id?: string;
     coingeckoId?: string;
@@ -66,6 +156,15 @@ export interface Asset {
     name: string;
     symbol: string;
     type: AssetType;
+    walletConnectionId?: WalletConnectionId | 'watch';
+}
+
+// @public
+export interface AssetDistribution {
+    distribution: AccountAssetEntry[];
+    symbol: string;
+    totalQuantity: Balance;
+    totalValue: Price;
 }
 
 // @public
@@ -144,6 +243,18 @@ export interface CircuitBreakerConfig {
     openDurationMs: number;
 }
 
+// @public
+export interface ConnectedAccount {
+    accountId: AccountId;
+    accountLabel: string;
+    address: string;
+    chainScope: Chain[];
+    discoveredAt: string;
+    isActive: boolean;
+    isStale: boolean;
+    source: 'provider' | 'manual';
+}
+
 // @public
 export enum DeFiDiscoverySource {
     CONTRACT_QUERY = "CONTRACT_QUERY",
@@ -152,6 +263,7 @@ export enum DeFiDiscoverySource {
 
 // @public
 export interface DeFiPosition {
+    accountId?: AccountId;
     apy?: number;
     chain: Chain;
     discoverySource?: DeFiDiscoverySource;
@@ -199,12 +311,24 @@ export interface EnvironmentConfig {
 
 // @public
 export interface FilterOptions {
+    accountIds?: AccountId[];
     assetTypes?: AssetType[];
     chains?: Chain[];
+    groupIds?: string[];
     maxValue?: number;
     minValue?: number;
     sources?: IntegrationSource[];
     timeRange?: TimeRange;
+    walletConnectionIds?: WalletConnectionId[];
+}
+
+// @public
+export interface GroupPortfolio {
+    accounts: AccountPortfolio[];
+    groupId: string;
+    groupName: string;
+    lastUpdated: string;
+    totalValue: Price;
 }
 
 // @public
@@ -216,6 +340,7 @@ export interface HealthCheckConfig {
 
 // @public
 export interface IntegrationCredentials {
+    accountId?: AccountId;
     apiKey?: string;
     apiSecret?: string;
     chainId?: string;
@@ -335,6 +460,7 @@ export interface PaginatedResponse<T> {
 
 // @public
 export interface Portfolio {
+    accountBreakdown?: Map<AccountId, AccountPortfolio>;
     accounts?: Account[];
     id: string;
     items?: PortfolioAsset[];
@@ -354,6 +480,7 @@ export interface Portfolio {
         value: Price;
     }>;
     userId?: string;
+    walletBreakdown?: Map<WalletConnectionId, WalletPortfolio>;
 }
 
 // @public
@@ -462,6 +589,17 @@ export type TimeRange = {
     end: Date;
 };
 
+// @public
+export interface TrackedAddress {
+    accountId: AccountId;
+    accountLabel: string;
+    address: string;
+    chainScope: Chain[];
+    connectionLabel: string;
+    providerId: WalletProviderId | 'watch';
+    walletConnectionId: WalletConnectionId | 'watch';
+}
+
 // @public
 export interface Transaction {
     accountId: string;
@@ -492,6 +630,7 @@ export interface Transaction {
     timestamp: Date;
     to?: string;
     type: TransactionType;
+    walletConnectionId?: WalletConnectionId | 'watch';
 }
 
 // @public
@@ -544,6 +683,45 @@ export enum VaultStrategyType {
     YIELD_AGGREGATOR = "YIELD_AGGREGATOR"
 }
 
+// @public
+export interface WalletConnection {
+    accounts: ConnectedAccount[];
+    activeAccountAddress: string | null;
+    connectedAt: string;
+    connectionId: WalletConnectionId;
+    connectionLabel: string;
+    lastActiveAt: string;
+    providerIcon: string;
+    providerId: WalletProviderId;
+    providerName: string;
+    sessionStatus: 'active' | 'stale' | 'disconnected';
+    supportedChains: Chain[];
+}
+
+// @public
+export type WalletConnectionId = string;
+
+// @public
+export interface WalletPortfolio {
+    accounts: AccountPortfolio[];
+    connectionLabel: string;
+    providerName: string;
+    totalValue: Price;
+    walletConnectionId: WalletConnectionId;
+}
+
+// @public
+export type WalletProviderId = 'metamask' | 'rabby' | 'walletconnect' | 'coinbase-wallet' | 'trust-wallet' | 'frame' | 'crypto-com-onchain' | 'phantom' | 'solflare' | 'backpack' | 'exodus' | 'manual';
+
+// @public
+export interface WatchAddress {
+    accountId: AccountId;
+    addedAt: string;
+    address: string;
+    addressLabel: string;
+    chainScope: Chain[];
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

src/index.ts

@@ -37,6 +37,31 @@ export { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
 export { PortfolioAsset } from './interfaces/PortfolioAsset';
 
+// Multi-Wallet Identity Types
+export type { WalletProviderId } from './types/WalletProviderId';
+export type { WalletConnectionId } from './types/WalletConnectionId';
+export type { AccountId } from './types/AccountId';
+
+// Multi-Wallet Connection Models
+export type { WalletConnection } from './interfaces/WalletConnection';
+export type { ConnectedAccount } from './interfaces/ConnectedAccount';
+export type { WatchAddress } from './interfaces/WatchAddress';
+export type { AccountGroup } from './interfaces/AccountGroup';
+
+// Multi-Wallet Portfolio Models
+export type { AccountPortfolio } from './interfaces/AccountPortfolio';
+export type { WalletPortfolio } from './interfaces/WalletPortfolio';
+export type { GroupPortfolio } from './interfaces/GroupPortfolio';
+export type { AccountSummary } from './interfaces/AccountSummary';
+export type { AssetDistribution } from './interfaces/AssetDistribution';
+export type { AccountAssetEntry } from './interfaces/AccountAssetEntry';
+
+// Multi-Wallet Integration Models
+export type { TrackedAddress } from './interfaces/TrackedAddress';
+export type { AccountMetadata } from './interfaces/AccountMetadata';
+export type { AddressRequest } from './interfaces/AddressRequest';
+export type { AccountBalanceList, AccountBalance, AccountError } from './interfaces/AccountBalanceList';
+
 // Transaction Models
 export { Transaction } from './interfaces/Transaction';
 
@@ -67,4 +92,4 @@ export { RpcProviderConfig } from './interfaces/RpcProviderConfig';
 export { NetworkEnvironment, EnvironmentConfig } from './types/NetworkEnvironment';
 
 // Backward Compatibility
-export { PortfolioItem } from './interfaces/PortfolioItem';
+export { PortfolioItem } from './interfaces/PortfolioItem';

src/interfaces/AccountAssetEntry.ts

@@ -0,0 +1,48 @@
+import { AccountId } from '../types/AccountId';
+import { Balance } from './Balance';
+import { Price } from './Price';
+
+/**
+ * A single account's holding of an asset within an asset distribution.
+ *
+ * Used as part of {@link AssetDistribution} to show how much of a specific
+ * asset is held in each account and what percentage of the total it represents.
+ *
+ * @example
+ * ```typescript
+ * import { AccountAssetEntry } from '@cygnus-wealth/data-models';
+ *
+ * const entry: AccountAssetEntry = {
+ *   accountId: 'metamask:a1b2:0xAbc',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   quantity: { assetId: 'eth', asset: ethAsset, amount: '7.0' },
+ *   value: { value: 14000, currency: 'USD', timestamp: new Date() },
+ *   percentage: 66.67
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AssetDistribution} for the parent distribution context
+ */
+export interface AccountAssetEntry {
+  /** Account holding this portion of the asset */
+  accountId: AccountId;
+
+  /** User-assigned account label */
+  accountLabel: string;
+
+  /** Label of the parent wallet connection */
+  connectionLabel: string;
+
+  /** Quantity of the asset in this account */
+  quantity: Balance;
+
+  /** Value of this account's holding */
+  value: Price;
+
+  /** Percentage of total for this asset (e.g., 66.67 = 66.67%) */
+  percentage: number;
+}