bulltrackers-module 1.0.733 → 1.0.734

package/functions/computation-system-v2/computations/PopularInvestorProfileMetrics.js

@@ -0,0 +1,720 @@
+/**
+ * @fileoverview Popular Investor Profile Metrics - v2 Adaptation
+ * 
+ * This is the most complex computation, migrated to demonstrate the v2 framework.
+ * 
+ * Original v1 features preserved:
+ * - Profile page metrics for Popular Investors
+ * - Social engagement (7-day accumulation)
+ * - Profitable positions from trade history
+ * - Sector/asset exposure analysis
+ * - Rankings, ratings, page views, watchlist data
+ * - Alert history with 7-day metrics
+ * - Exposure over time (historical continuity)
+ * 
+ * v2 Changes:
+ * - Uses `getConfig()` instead of `getMetadata()` + `getDependencies()`
+ * - Directly references BigQuery table names in `requires`
+ * - Data accessed via `context.data['table_name']`
+ * - Simplified series handling through lookback configuration
+ */
+
+const { Computation } = require('../framework');
+
+class PopularInvestorProfileMetrics extends Computation {
+    
+    /**
+     * v2 Configuration - Single source of truth for computation requirements.
+     */
+    static getConfig() {
+        return {
+            name: 'PopularInvestorProfileMetrics',
+            category: 'popular_investor',
+            
+            // Direct table references with lookback configuration
+            requires: {
+                // Core data - mandatory for execution
+                'portfolio_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                'trade_history_snapshots': {
+                    lookback: 0,
+                    mandatory: true,
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                
+                // Rankings - for AUM, risk score, gain, copiers
+                'pi_rankings': {
+                    lookback: 7,  // Self-healing: use latest available
+                    mandatory: false
+                },
+                
+                // Ratings - 30-day average
+                'pi_ratings': {
+                    lookback: 30,
+                    mandatory: false
+                },
+                
+                // Page views - 7-day accumulation
+                'pi_page_views': {
+                    lookback: 7,
+                    mandatory: false
+                },
+                
+                // Watchlist - 30-day trend
+                'watchlist_membership': {
+                    lookback: 30,
+                    mandatory: false
+                },
+                
+                // Alert history - 7-day metrics
+                'pi_alert_history': {
+                    lookback: 7,
+                    mandatory: false
+                },
+                
+                // Social posts - 7-day engagement
+                'social_post_snapshots': {
+                    lookback: 7,
+                    mandatory: false,
+                    filter: { user_type: 'POPULAR_INVESTOR' }
+                },
+                
+                // Ticker mappings for display names
+                'ticker_mappings': {
+                    lookback: 0,  // Not date-partitioned
+                    mandatory: false
+                }
+            },
+            
+            // No computation dependencies
+            dependencies: [],
+            
+            // Runs per user
+            type: 'per-entity',
+            
+            // Needs previous day's result for exposure over time
+            isHistorical: true,
+            
+            // Output config
+            ttlDays: 60
+        };
+    }
+    
+    static getSchema() {
+        return {
+            type: 'object',
+            properties: {
+                username: { type: 'string' },
+                socialEngagement: { type: 'object' },
+                profitablePositions: { type: 'object' },
+                topWinningPositions: { type: 'object' },
+                sectorPerformance: { type: 'object' },
+                sectorExposure: { type: 'object' },
+                assetExposure: { type: 'object' },
+                portfolioSummary: { type: 'object' },
+                rankingsData: { type: 'object' },
+                ratingsData: { type: 'object' },
+                pageViewsData: { type: 'object' },
+                watchlistData: { type: 'object' },
+                alertHistoryData: { type: 'object' },
+                sectorExposureOverTime: { type: 'object' },
+                assetExposureOverTime: { type: 'object' },
+                alertMetrics: { type: 'object' }
+            }
+        };
+    }
+    
+    static getWeight() {
+        return 10.0;  // Complex per-user computation
+    }
+    
+    /**
+     * Process a single user's profile metrics.
+     */
+    async process(context) {
+        const { date, entityId: userId, data, previousResult } = context;
+        
+        // Extract data from context
+        const portfolio = data['portfolio_snapshots'];
+        const historyDoc = data['trade_history_snapshots'];
+        const rankings = data['pi_rankings'];
+        const ratings = data['pi_ratings'];
+        const pageViews = data['pi_page_views'];
+        const watchlist = data['watchlist_membership'];
+        const alerts = data['pi_alert_history'];
+        const social = data['social_post_snapshots'];
+        const tickerMappings = data['ticker_mappings'];
+        
+        // Build instrument mappings
+        const mappings = this._buildMappings(tickerMappings);
+        
+        // Initialize result structure
+        const result = this._initializeResult();
+        
+        // ==========================================================================================
+        // 1. Social Engagement (7-Day Accumulation + Chart)
+        // ==========================================================================================
+        this._processSocialEngagement(result, social, userId);
+        
+        // ==========================================================================================
+        // 2. Profitable Positions (From Trade History)
+        // ==========================================================================================
+        this._processProfitablePositions(result, historyDoc);
+        
+        // ==========================================================================================
+        // 3. Top Winning Positions
+        // ==========================================================================================
+        this._processTopWinningPositions(result, portfolio, historyDoc, mappings);
+        
+        // ==========================================================================================
+        // 4. Sector Performance
+        // ==========================================================================================
+        this._processSectorPerformance(result, portfolio, mappings);
+        
+        // ==========================================================================================
+        // 5. & 6. Exposure & Portfolio Summary
+        // ==========================================================================================
+        this._processExposureAndSummary(result, portfolio, mappings);
+        
+        // ==========================================================================================
+        // 7. Rankings Data
+        // ==========================================================================================
+        this._processRankingsData(result, rankings, userId);
+        
+        // ==========================================================================================
+        // 8. Username (from rankings)
+        // ==========================================================================================
+        if (rankings) {
+            const rankEntry = this._findLatestRankEntry(rankings, userId);
+            if (rankEntry) {
+                result.username = rankEntry.UserName || rankEntry.username || null;
+            }
+        }
+        
+        // ==========================================================================================
+        // 9. Ratings Data (30-Day Average + Trend)
+        // ==========================================================================================
+        this._processRatingsData(result, ratings, userId);
+        
+        // ==========================================================================================
+        // 10. Page Views Data (7-Day Sum + Daily Chart)
+        // ==========================================================================================
+        this._processPageViewsData(result, pageViews, userId);
+        
+        // ==========================================================================================
+        // 11. Watchlist Data (Latest Snapshot + 30-Day Trend)
+        // ==========================================================================================
+        this._processWatchlistData(result, watchlist, userId);
+        
+        // ==========================================================================================
+        // 12. Alert History (Accumulation + Metrics)
+        // ==========================================================================================
+        this._processAlertHistory(result, alerts, userId);
+        
+        // ==========================================================================================
+        // 13. Exposure Over Time (Requires Previous State)
+        // ==========================================================================================
+        this._processExposureOverTime(result, previousResult, date);
+        
+        // Store result
+        this.setResult(userId, result);
+    }
+    
+    // =========================================================================
+    // PRIVATE METHODS
+    // =========================================================================
+    
+    _initializeResult() {
+        return {
+            username: null,
+            socialEngagement: { chartType: 'line', data: [] },
+            profitablePositions: { chartType: 'bar', data: [] },
+            topWinningPositions: { chartType: 'table', data: [] },
+            sectorPerformance: { bestSector: null, worstSector: null, bestSectorProfit: 0, worstSectorProfit: 0 },
+            sectorExposure: { chartType: 'pie', data: {} },
+            assetExposure: { chartType: 'pie', data: {} },
+            portfolioSummary: { totalInvested: 0, totalProfit: 0, profitPercent: 0 },
+            rankingsData: { aum: 0, riskScore: 0, gain: 0, copiers: 0, winRatio: 0, trades: 0 },
+            ratingsData: { 
+                averageRating: 0,
+                totalRatings: 0,
+                ratingsOverTime: { chartType: 'line', data: [] } 
+            },
+            pageViewsData: { 
+                totalViews: 0,
+                uniqueViewers: 0,
+                viewsOverTime: { chartType: 'bar', data: [] } 
+            },
+            watchlistData: { 
+                totalUsers: 0,
+                publicWatchlistCount: 0, 
+                privateWatchlistCount: 0,
+                watchlistOverTime: { chartType: 'line', data: [] } 
+            },
+            alertHistoryData: { triggeredAlerts: [], alertCountsOverTime: { chartType: 'bar', data: [] } },
+            sectorExposureOverTime: { chartType: 'line', data: [] },
+            assetExposureOverTime: { chartType: 'line', data: [] },
+            alertMetrics: { totalLast7Days: 0, breakdown: {} }
+        };
+    }
+    
+    _buildMappings(tickerMappings) {
+        const mappings = {
+            instrumentToTicker: {},
+            instrumentToSector: {}
+        };
+        
+        if (!tickerMappings) return mappings;
+        
+        // Handle different data structures
+        if (Array.isArray(tickerMappings)) {
+            for (const row of tickerMappings) {
+                const id = row.instrument_id || row.instrumentId;
+                if (id) {
+                    mappings.instrumentToTicker[String(id)] = row.ticker || row.symbol || `ID${id}`;
+                    if (row.sector) mappings.instrumentToSector[String(id)] = row.sector;
+                }
+            }
+        } else if (typeof tickerMappings === 'object') {
+            for (const [id, data] of Object.entries(tickerMappings)) {
+                if (typeof data === 'string') {
+                    mappings.instrumentToTicker[id] = data;
+                } else if (typeof data === 'object') {
+                    mappings.instrumentToTicker[id] = data.ticker || data.symbol || `ID${id}`;
+                    if (data.sector) mappings.instrumentToSector[id] = data.sector;
+                }
+            }
+        }
+        
+        return mappings;
+    }
+    
+    _processSocialEngagement(result, social, userId) {
+        if (!social) return;
+        
+        // social is date-keyed: { "2026-01-24": [...], "2026-01-23": [...] }
+        const dates = Object.keys(social).sort();
+        
+        for (const dateStr of dates) {
+            const dailyData = social[dateStr];
+            if (!dailyData) continue;
+            
+            // Find user's posts
+            let userPosts = [];
+            if (Array.isArray(dailyData)) {
+                userPosts = dailyData.filter(p => String(p.user_id || p.userId) === String(userId));
+            } else if (dailyData[userId]) {
+                userPosts = Array.isArray(dailyData[userId]) ? dailyData[userId] : [dailyData[userId]];
+            }
+            
+            if (userPosts.length > 0) {
+                let likes = 0, comments = 0;
+                for (const post of userPosts) {
+                    likes += (post.LikesCount || post.likes || 0);
+                    comments += (post.CommentsCount || post.comments || 0);
+                }
+                result.socialEngagement.data.push({ date: dateStr, likes, comments });
+            }
+        }
+    }
+    
+    _processProfitablePositions(result, historyDoc) {
+        if (!historyDoc) return;
+        
+        const trades = this._extractTrades(historyDoc);
+        const profitableMap = new Map();
+        
+        for (const trade of trades) {
+            const closeDateTime = trade.CloseDateTime || trade.closeDateTime || trade.close_date;
+            if (!closeDateTime) continue;
+            
+            const closeDate = new Date(closeDateTime);
+            if (isNaN(closeDate.getTime())) continue;
+            
+            const dateKey = closeDate.toISOString().split('T')[0];
+            const existing = profitableMap.get(dateKey) || { date: dateKey, profitableCount: 0, totalCount: 0 };
+            existing.totalCount++;
+            
+            const netProfit = trade.NetProfit || trade.netProfit || trade.net_profit || 0;
+            if (netProfit > 0) existing.profitableCount++;
+            
+            profitableMap.set(dateKey, existing);
+        }
+        
+        result.profitablePositions.data = Array.from(profitableMap.values())
+            .sort((a, b) => a.date.localeCompare(b.date))
+            .slice(-30);
+    }
+    
+    _processTopWinningPositions(result, portfolio, historyDoc, mappings) {
+        const topWinning = [];
+        
+        // From current portfolio
+        if (portfolio) {
+            const positions = this._extractPositions(portfolio);
+            for (const pos of positions) {
+                const instrumentId = pos.InstrumentID || pos.instrumentId || pos.instrument_id;
+                const netProfit = pos.NetProfit || pos.netProfit || pos.net_profit || 0;
+                const invested = pos.Amount || pos.amount || pos.invested || 0;
+                const value = pos.Value || pos.value || invested + netProfit;
+                
+                if (netProfit > 0 && instrumentId) {
+                    const ticker = mappings.instrumentToTicker[String(instrumentId)] || `ID${instrumentId}`;
+                    topWinning.push({ instrumentId, ticker, netProfit, invested, value, isCurrent: true, closeDate: null });
+                }
+            }
+        }
+        
+        // From trade history
+        if (historyDoc) {
+            const trades = this._extractTrades(historyDoc);
+            for (const trade of trades) {
+                const netProfit = trade.NetProfit || trade.netProfit || trade.net_profit || 0;
+                const instrumentId = trade.InstrumentID || trade.instrumentId || trade.instrument_id;
+                
+                if (netProfit > 0 && instrumentId) {
+                    const ticker = mappings.instrumentToTicker[String(instrumentId)] || `ID${instrumentId}`;
+                    const closeDate = trade.CloseDateTime || trade.closeDateTime || trade.close_date || null;
+                    topWinning.push({ instrumentId, ticker, netProfit, invested: 0, value: 0, isCurrent: false, closeDate });
+                }
+            }
+        }
+        
+        result.topWinningPositions.data = topWinning
+            .sort((a, b) => b.netProfit - a.netProfit)
+            .slice(0, 20);
+    }
+    
+    _processSectorPerformance(result, portfolio, mappings) {
+        if (!portfolio || !mappings.instrumentToSector || Object.keys(mappings.instrumentToSector).length === 0) {
+            return;
+        }
+        
+        const positions = this._extractPositions(portfolio);
+        const sectorProfits = new Map();
+        
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID || pos.instrumentId || pos.instrument_id;
+            const netProfit = pos.NetProfit || pos.netProfit || pos.net_profit || 0;
+            const invested = pos.Amount || pos.amount || pos.invested || 0;
+            
+            if (instrumentId && invested > 0) {
+                const sector = mappings.instrumentToSector[String(instrumentId)] || 'Unknown';
+                const weightedProfit = invested * (netProfit / 100);
+                const existing = sectorProfits.get(sector) || { totalProfit: 0, totalInvested: 0 };
+                existing.totalProfit += weightedProfit;
+                existing.totalInvested += invested;
+                sectorProfits.set(sector, existing);
+            }
+        }
+        
+        let bestSector = null, worstSector = null;
+        let bestProfit = -Infinity, worstProfit = Infinity;
+        
+        for (const [sector, data] of sectorProfits.entries()) {
+            const profitPercent = data.totalInvested > 0 ? (data.totalProfit / data.totalInvested) * 100 : 0;
+            if (profitPercent > bestProfit) { bestProfit = profitPercent; bestSector = sector; }
+            if (profitPercent < worstProfit) { worstProfit = profitPercent; worstSector = sector; }
+        }
+        
+        result.sectorPerformance = {
+            bestSector,
+            worstSector,
+            bestSectorProfit: bestProfit !== -Infinity ? bestProfit : 0,
+            worstSectorProfit: worstProfit !== Infinity ? worstProfit : 0
+        };
+    }
+    
+    _processExposureAndSummary(result, portfolio, mappings) {
+        if (!portfolio) return;
+        
+        const positions = this._extractPositions(portfolio);
+        const sectorMap = {};
+        const assetMap = {};
+        let total = 0, totalInvested = 0, totalProfit = 0;
+        
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID || pos.instrumentId || pos.instrument_id;
+            const invested = pos.Amount || pos.amount || pos.invested || 0;
+            const netProfit = pos.NetProfit || pos.netProfit || pos.net_profit || 0;
+            const value = pos.Value || pos.value || invested + netProfit;
+            
+            total += value;
+            totalInvested += invested;
+            totalProfit += invested * (netProfit / 100);
+            
+            const sector = mappings.instrumentToSector[String(instrumentId)] || 'Unknown';
+            sectorMap[sector] = (sectorMap[sector] || 0) + value;
+            
+            const ticker = mappings.instrumentToTicker[String(instrumentId)] || `ID${instrumentId}`;
+            assetMap[ticker] = (assetMap[ticker] || 0) + value;
+        }
+        
+        if (total > 0) {
+            Object.keys(sectorMap).forEach(k => {
+                result.sectorExposure.data[k] = Number(((sectorMap[k] / total) * 100).toFixed(2));
+            });
+            
+            Object.entries(assetMap)
+                .sort(([, a], [, b]) => b - a)
+                .slice(0, 10)
+                .forEach(([k, v]) => {
+                    result.assetExposure.data[k] = Number(((v / total) * 100).toFixed(2));
+                });
+        }
+        
+        result.portfolioSummary = {
+            totalInvested: Number(totalInvested.toFixed(2)),
+            totalProfit: Number(totalProfit.toFixed(2)),
+            profitPercent: totalInvested > 0 ? Number(((totalProfit / totalInvested) * 100).toFixed(2)) : 0
+        };
+    }
+    
+    _processRankingsData(result, rankings, userId) {
+        const rankEntry = this._findLatestRankEntry(rankings, userId);
+        if (!rankEntry) return;
+        
+        result.rankingsData = {
+            aum: rankEntry.AUMTierDesc || rankEntry.Aum || rankEntry.aum || 0,
+            riskScore: rankEntry.RiskScore || rankEntry.riskScore || 0,
+            gain: rankEntry.Gain || rankEntry.gain || 0,
+            copiers: rankEntry.Copiers || rankEntry.copiers || 0,
+            winRatio: rankEntry.WinRatio || rankEntry.winRatio || 0,
+            trades: rankEntry.Trades || rankEntry.trades || 0
+        };
+    }
+    
+    _findLatestRankEntry(rankings, userId) {
+        if (!rankings) return null;
+        
+        // rankings is date-keyed: { "2026-01-24": [...], ... }
+        if (typeof rankings === 'object' && !Array.isArray(rankings)) {
+            const dates = Object.keys(rankings).sort().reverse();
+            for (const dateStr of dates) {
+                const dayRankings = rankings[dateStr];
+                if (Array.isArray(dayRankings)) {
+                    const entry = dayRankings.find(r => 
+                        String(r.CustomerId || r.pi_id || r.userId) === String(userId)
+                    );
+                    if (entry) return entry;
+                }
+            }
+        }
+        
+        // Direct array
+        if (Array.isArray(rankings)) {
+            return rankings.find(r => 
+                String(r.CustomerId || r.pi_id || r.userId) === String(userId)
+            );
+        }
+        
+        return null;
+    }
+    
+    _processRatingsData(result, ratings, userId) {
+        if (!ratings) return;
+        
+        const dates = Object.keys(ratings).sort();
+        let sumRatings = 0, countRatings = 0;
+        
+        for (const dateStr of dates) {
+            const dayRatings = ratings[dateStr];
+            const userRating = this._findUserData(dayRatings, userId);
+            
+            if (userRating) {
+                const avg = userRating.average_rating || userRating.avgRating || 0;
+                const total = userRating.total_ratings || userRating.totalRatings || 0;
+                
+                result.ratingsData.ratingsOverTime.data.push({
+                    date: dateStr,
+                    rating: avg,
+                    count: total
+                });
+                
+                if (avg > 0) {
+                    sumRatings += avg;
+                    countRatings++;
+                }
+                
+                result.ratingsData.totalRatings = total;
+            }
+        }
+        
+        if (countRatings > 0) {
+            result.ratingsData.averageRating = Number((sumRatings / countRatings).toFixed(2));
+        }
+    }
+    
+    _processPageViewsData(result, pageViews, userId) {
+        if (!pageViews) return;
+        
+        const dates = Object.keys(pageViews).sort();
+        
+        for (const dateStr of dates) {
+            const dayViews = pageViews[dateStr];
+            const userViews = this._findUserData(dayViews, userId);
+            
+            if (userViews) {
+                const views = userViews.total_views || userViews.totalViews || 0;
+                const uniques = userViews.unique_viewers || userViews.uniqueViewers || 0;
+                
+                result.pageViewsData.viewsOverTime.data.push({
+                    date: dateStr,
+                    views: views
+                });
+                
+                result.pageViewsData.totalViews += views;
+                result.pageViewsData.uniqueViewers = uniques;
+            }
+        }
+    }
+    
+    _processWatchlistData(result, watchlist, userId) {
+        if (!watchlist) return;
+        
+        const dates = Object.keys(watchlist).sort();
+        
+        for (const dateStr of dates) {
+            const dayWatchlist = watchlist[dateStr];
+            const userWatchlist = this._findUserData(dayWatchlist, userId);
+            
+            if (userWatchlist) {
+                const total = userWatchlist.total_users || userWatchlist.totalUsers || 0;
+                
+                result.watchlistData.watchlistOverTime.data.push({
+                    date: dateStr,
+                    count: total
+                });
+                
+                result.watchlistData.totalUsers = total;
+                result.watchlistData.publicWatchlistCount = userWatchlist.public_watchlist_count || userWatchlist.publicCount || 0;
+                result.watchlistData.privateWatchlistCount = userWatchlist.private_watchlist_count || userWatchlist.privateCount || 0;
+            }
+        }
+    }
+    
+    _processAlertHistory(result, alerts, userId) {
+        if (!alerts) return;
+        
+        const dates = Object.keys(alerts).sort();
+        let totalAlertsLast7Days = 0;
+        const alertBreakdown = {};
+        
+        for (const dateStr of dates) {
+            const dayAlerts = alerts[dateStr];
+            const userAlerts = this._findUserData(dayAlerts, userId);
+            
+            if (userAlerts && typeof userAlerts === 'object') {
+                let dayCount = 0;
+                
+                for (const [alertType, data] of Object.entries(userAlerts)) {
+                    if (alertType.toLowerCase().includes('test')) continue;
+                    
+                    const count = data.count || data.trigger_count || 1;
+                    totalAlertsLast7Days += count;
+                    dayCount += count;
+                    
+                    alertBreakdown[alertType] = (alertBreakdown[alertType] || 0) + count;
+                }
+                
+                if (dayCount > 0) {
+                    result.alertHistoryData.alertCountsOverTime.data.push({
+                        date: dateStr,
+                        count: dayCount
+                    });
+                }
+            }
+        }
+        
+        result.alertMetrics.totalLast7Days = totalAlertsLast7Days;
+        result.alertMetrics.breakdown = alertBreakdown;
+        
+        // Sort chart
+        result.alertHistoryData.alertCountsOverTime.data.sort((a, b) => a.date.localeCompare(b.date));
+    }
+    
+    _processExposureOverTime(result, previousResult, currentDate) {
+        // Restore from previous day
+        if (previousResult) {
+            if (previousResult.sectorExposureOverTime?.data) {
+                result.sectorExposureOverTime.data = [...previousResult.sectorExposureOverTime.data];
+            }
+            if (previousResult.assetExposureOverTime?.data) {
+                result.assetExposureOverTime.data = [...previousResult.assetExposureOverTime.data];
+            }
+        }
+        
+        // Add today's exposure
+        if (Object.keys(result.sectorExposure.data).length > 0) {
+            const todaySectorEntry = { date: currentDate, sectors: result.sectorExposure.data };
+            const idx = result.sectorExposureOverTime.data.findIndex(d => d.date === currentDate);
+            if (idx >= 0) {
+                result.sectorExposureOverTime.data[idx] = todaySectorEntry;
+            } else {
+                result.sectorExposureOverTime.data.push(todaySectorEntry);
+            }
+        }
+        
+        if (Object.keys(result.assetExposure.data).length > 0) {
+            const todayAssetEntry = { date: currentDate, assets: result.assetExposure.data };
+            const idx = result.assetExposureOverTime.data.findIndex(d => d.date === currentDate);
+            if (idx >= 0) {
+                result.assetExposureOverTime.data[idx] = todayAssetEntry;
+            } else {
+                result.assetExposureOverTime.data.push(todayAssetEntry);
+            }
+        }
+        
+        // Limit to 30 days
+        if (result.sectorExposureOverTime.data.length > 30) {
+            result.sectorExposureOverTime.data = result.sectorExposureOverTime.data.slice(-30);
+        }
+        if (result.assetExposureOverTime.data.length > 30) {
+            result.assetExposureOverTime.data = result.assetExposureOverTime.data.slice(-30);
+        }
+    }
+    
+    // =========================================================================
+    // DATA EXTRACTION HELPERS
+    // =========================================================================
+    
+    _extractPositions(portfolio) {
+        if (!portfolio) return [];
+        if (Array.isArray(portfolio)) return portfolio;
+        if (portfolio.AggregatedPositions) return portfolio.AggregatedPositions;
+        if (portfolio.Positions) return portfolio.Positions;
+        if (portfolio.positions) return portfolio.positions;
+        return [];
+    }
+    
+    _extractTrades(historyDoc) {
+        if (!historyDoc) return [];
+        if (Array.isArray(historyDoc)) return historyDoc;
+        if (historyDoc.Trades) return historyDoc.Trades;
+        if (historyDoc.trades) return historyDoc.trades;
+        if (historyDoc.History) return historyDoc.History;
+        return [];
+    }
+    
+    _findUserData(dayData, userId) {
+        if (!dayData) return null;
+        
+        // Direct lookup by user ID
+        if (dayData[userId]) return dayData[userId];
+        if (dayData[String(userId)]) return dayData[String(userId)];
+        
+        // Array - find by user ID field
+        if (Array.isArray(dayData)) {
+            return dayData.find(item => 
+                String(item.pi_id || item.user_id || item.userId) === String(userId)
+            );
+        }
+        
+        return null;
+    }
+}
+
+module.exports = PopularInvestorProfileMetrics;