bulltrackers-module 1.0.731 → 1.0.733

package/functions/computation-system/layers/extractors.js

@@ -1,1097 +0,0 @@
-/**
- * @fileoverview Extractors Layer
- * Core access methods to raw data schemas (Social, Portfolio, History, Rankings, Verification).
- * UPDATED: Aligned with corrected schemas for PublicHistoryPositions and Deep PublicPositions.
- */
-
-const { SCHEMAS } = require('./profiling');
-
-class TradeSeriesBuilder {
-    static buildReturnSeries(historyTrades) {
-        if (!historyTrades || !Array.isArray(historyTrades)) return [];
-        // Sort by Close Date Ascending
-        const closedTrades = [...historyTrades].sort((a, b) => new Date(a.CloseDateTime) - new Date(b.CloseDateTime));
-        return closedTrades.map(t => t.NetProfit);
-    }
-
-    static buildCumulativeCurve(returnSeries, startValue = 100) {
-        const curve = [startValue];
-        let current = startValue;
-        for (const ret of returnSeries) {
-            // Assuming returns are absolute $ values here based on schema "NetProfit": 73.1666
-            current += ret; 
-            curve.push(current);
-        }
-        return curve;
-    }
-
-    static calculateMaxDrawdown(curve) {
-        if (!curve || curve.length < 2) return { maxDrawdownPct: 0, peakIndex: 0, troughIndex: 0 };
-        
-        let maxDrawdown = 0;
-        let peakValue = curve[0];
-        let peakIndex = 0;
-        let tempPeakIndex = 0;
-        let troughIndex = 0;
-
-        for (let i = 1; i < curve.length; i++) {
-            const currentVal = curve[i];
-            
-            if (currentVal > peakValue) {
-                peakValue = currentVal;
-                tempPeakIndex = i;
-            } else {
-                if (peakValue === 0) continue; 
-                const drawdown = (peakValue - currentVal) / peakValue;
-                if (drawdown > maxDrawdown) {
-                    maxDrawdown = drawdown;
-                    peakIndex = tempPeakIndex;
-                    troughIndex = i;
-                }
-            }
-        }
-        return { maxDrawdownPct: maxDrawdown * 100, peakIndex, troughIndex };
-    }
-}
-
-
-class SocialExtractor {
-    static getDiscussions(socialData) {
-        return socialData?.discussions || [];
-    }
-
-    static getPostId(discussion) {
-        return discussion?.post?.id || discussion?.id || null;
-    }
-
-    static getMessage(discussion) {
-        return discussion?.post?.message?.text || "";
-    }
-
-    static getLanguage(discussion) {
-        return discussion?.post?.message?.languageCode || "en";
-    }
-
-    static getCreatedDate(discussion) {
-        const dateStr = discussion?.post?.created;
-        return dateStr ? new Date(dateStr) : null;
-    }
-
-    static getOwner(discussion) {
-        return discussion?.post?.owner || null;
-    }
-
-    static getOwnerUsername(discussion) {
-        return discussion?.post?.owner?.username || "Unknown";
-    }
-
-    static isOwnerVerified(discussion) {
-        const roles = discussion?.post?.owner?.roles || [];
-        return roles.includes('Verified') || roles.includes('PopularInvestor');
-    }
-
-    static getPostContextType(discussion) {
-        if (discussion?.post?.tags && discussion.post.tags.length > 0) return 'INSTRUMENT_TAGGED';
-        if (discussion?.reason) return 'USER_TIMELINE'; 
-        return 'UNKNOWN';
-    }
-
-    static getRelatedInstruments(discussion) {
-        const tags = discussion?.post?.tags || [];
-        return tags.map(t => ({
-            id: t.market?.internalId || t.market?.id,
-            symbol: t.market?.symbolName,
-            displayName: t.market?.displayName
-        })).filter(i => i.id);
-    }
-
-    static getFeedReason(discussion) {
-        if (!discussion?.reason) return null;
-        return {
-            type: discussion.reason.type, 
-            sourceId: discussion.reason.sourceId
-        };
-    }
-
-    static getCommentCount(discussion) {
-        return discussion?.summary?.totalCommentsAndReplies || 0;
-    }
-
-    static getLikeCount(discussion) {
-        return discussion?.emotionsData?.like?.paging?.totalCount || 0;
-    }
-
-    // [NEW] Added for social accuracy calcs
-    static getQualityScore(discussion) {
-        return discussion?.aiAnalysis?.qualityScore || 0.5; // Default neutral
-    }
-
-    static getAccuracyFromAnalysis(discussion) {
-        return discussion?.aiAnalysis?.accuracyScore || null;
-    }
-}
-
-class PopularInvestorExtractor {
-    static getPositions(data) {
-        // [FIX] Prioritize DeepPositions (merged from deep shard)
-        if (data && Array.isArray(data.DeepPositions)) {
-            return data.DeepPositions;
-        }
-        
-        if (data && Array.isArray(data.PublicPositions)) {
-            return data.PublicPositions; 
-        }
-        
-        if (data && Array.isArray(data.AggregatedPositions)) {
-            return data.AggregatedPositions;
-        }
-
-        return [];
-    }
-
-    static getEquity(data) {
-        return data.Equity || data.CreditByRealizedEquity || 0;
-    }
-}
-
-class DataExtractor { 
-    static getPositions(portfolio, userType) {
-        if (!portfolio) return []; 
-        
-        // Speculators/PIs might have the Deep Schema
-        if (userType === 'POPULAR_INVESTOR' || userType === SCHEMAS.USER_TYPES.SPECULATOR) {
-            return PopularInvestorExtractor.getPositions(portfolio);
-        }
-        
-        // Standard/Signed-In Users usually have the Overall Schema
-        return portfolio.AggregatedPositions || [];
-    }
-
-    static getInstrumentId(position) {
-        if (!position) return null; 
-        return position.InstrumentID || position.instrumentId || null;
-    }
-
-    static getPositionId(position) {
-        if (!position) return null; 
-        // Deep Schema: PositionID
-        if (position.PositionID) return String(position.PositionID);
-        
-        // Overall Schema: InstrumentID + Direction (Proxy ID)
-        const instId = this.getInstrumentId(position);
-        const dir    = this.getDirection(position);
-        if (instId) return `${instId}_${dir}`;
-        return null;
-    }
-
-    static getNetProfit(position) { 
-        return position ? (position.NetProfit || 0) : 0;
-    }
-
-    static getPositionWeight(position) { 
-        if (!position) return 0;
-        // Deep: Amount / Invested? Schema shows 'Amount' and 'Invested' at top level. 
-        // Inside PublicPositions (Deep), it uses 'Amount'. 
-        // Inside AggregatedPositions (Overall), it uses 'Invested'.
-        return position.Invested || position.Amount || 0;
-    }
-
-    static getPositionValue(position) {            
-        return position.Value || 0; 
-    }
-
-    static getDirection(position) {
-        if (!position) return "Buy";
-        if (position.Direction) return position.Direction;
-        if (typeof position.IsBuy === 'boolean') return position.IsBuy ? "Buy" : "Sell";
-        return "Buy"; 
-    }
-
-    static getLeverage(position)    { return position ? (position.Leverage || 1) : 1; }
-    static getOpenRate(position)    { return position ? (position.OpenRate || 0) : 0; }
-    static getCurrentRate(position) { return position ? (position.CurrentRate || 0) : 0; }
-    
-    static getStopLossRate(position) {
-        const rate = position ? (position.StopLossRate || 0) : 0; 
-        if (rate > 0 && rate <= 0.01) return 0; 
-        if (rate < 0) return 0;
-        return rate;
-    }                                                       
-
-    static getTakeProfitRate(position) {
-        const rate = position ? (position.TakeProfitRate || 0) : 0;
-        if (rate > 0 && rate <= 0.01) return 0; 
-        return rate;
-    }
-
-    static getOpenDateTime(position) { 
-        return (!position || !position.OpenDateTime) ? null : new Date(position.OpenDateTime); 
-    }
-
-    /**
-     * Extract current sectors from portfolio positions.
-     * @param {Object} portfolio - Portfolio data
-     * @param {Object} mappings - Context mappings containing instrumentToSector
-     * @param {string} userType - User type
-     * @returns {string[]} Array of unique sector names
-     */
-    static getCurrentSectors(portfolio, mappings, userType) {
-        const positions = this.getPositions(portfolio, userType);
-        const sectors = new Set();
-        const sectorMap = mappings?.instrumentToSector || {};
-        
-        for (const pos of positions) {
-            const instId = this.getInstrumentId(pos);
-            if (instId) {
-                const sector = sectorMap[instId] || 'Unknown';
-                sectors.add(sector);
-            }
-        }
-        return Array.from(sectors);
-    }
-
-    /**
-     * Extract AUM per asset from portfolio.
-     * @param {Object} portfolio - Portfolio data
-     * @param {string} userType - User type
-     * @returns {Object} Map of instrumentId -> AUM value
-     */
-    static getAUMPerAsset(portfolio, userType) {
-        const positions = this.getPositions(portfolio, userType);
-        const assetMap = new Map();
-        
-        for (const pos of positions) {
-            const instId = this.getInstrumentId(pos);
-            if (instId) {
-                const current = assetMap.get(instId) || 0;
-                assetMap.set(instId, current + this.getPositionValue(pos));
-            }
-        }
-        
-        const result = {};
-        for (const [instId, value] of assetMap.entries()) {
-            result[instId] = value;
-        }
-        return result;
-    }
-}
-
-class CopyTradingExtractor {
-    static getAggregatedMirrors(portfolio) {
-        if (!portfolio) return [];
-        return portfolio.AggregatedMirrors || [];
-    }
-
-    static getMirrorId(mirror) { return mirror?.MirrorID; }
-    static getParentCID(mirror) { return mirror?.ParentCID || null; }
-    static getParentUsername(mirror) { return mirror?.ParentUsername; }
-    static getInvested(mirror) { return mirror?.Invested || 0; }
-    static getNetProfit(mirror) { return mirror?.NetProfit || 0; }
-}
-
-class RankingsExtractor {
-    static getItems(rankingsData) {
-        if (!rankingsData) return [];
-        if (rankingsData.Items && Array.isArray(rankingsData.Items)) return rankingsData.Items;
-        // Sometimes the root object IS the array in other schemas
-        if (Array.isArray(rankingsData)) return rankingsData;
-        return [];
-    }
-
-    static getEntry(rankingsData, userId) {
-        const items = this.getItems(rankingsData);
-        return items.find(r => String(r.CustomerId) === String(userId)) || null;
-    }
-
-    static getGain(entry) { return entry?.Gain || 0; }
-    static getRiskScore(entry) { return entry?.RiskScore || 0; }
-    static getMaxDailyRiskScore(entry) { return entry?.MaxDailyRiskScore || 0; }
-    static getMaxMonthlyRiskScore(entry) { return entry?.MaxMonthlyRiskScore || 0; }
-    static getCopiers(entry) { return entry?.Copiers || 0; }
-    static getAUMTierDesc(entry) { return entry?.AUMTierDesc || "N/A"; }
-    // [NEW]
-    static getAUMValue(entry) { return entry?.AUMValue || 0; }
-    static getTags(entry) { return entry?.Tags || []; }
-}
-
-class VerificationExtractor {
-    static getProfile(verificationMap, userId) {
-        if (!verificationMap) return null;
-        return verificationMap[userId] || null;
-    }
-    
-    // [FIX] Now relies on normalized data from loader
-    static isVerified(profile) {
-        return profile?.isVerified === true;
-    }
-
-    static getRealCID(profile) {
-        return profile?.cid || null;
-    }
-
-    static getUsername(profile) {
-        return profile?.username || null;
-    }
-
-    static getAboutMe(profile) {
-        return profile?.aboutMe || "";
-    }
-    
-    static getAboutMeShort(profile) {
-        return profile?.aboutMeShort || "";
-    }
-
-    static getRestrictions(profile) {
-        return profile?.restrictions || [];
-    }
-    
-    static hasRestriction(profile, typeId) {
-         const restrictions = this.getRestrictions(profile);
-         return restrictions.some(r => r.RestrictionTypeID === typeId);
-    }
-}
-
-class priceExtractor {
-    static getHistory(pricesContext, tickerOrId) {
-        if (!pricesContext || !pricesContext.history) return [];
-        let assetData = pricesContext.history[tickerOrId];
-        if (!assetData) {
-            const id = Object.keys(pricesContext.history).find(key => {
-                const data = pricesContext.history[key];
-                return data.ticker === tickerOrId;
-            });
-            if (id) assetData = pricesContext.history[id];
-        }
-        if (!assetData || !assetData.prices) return [];
-        const priceMap = assetData.prices;
-        const sortedDates = Object.keys(priceMap).sort((a, b) => a.localeCompare(b));
-        return sortedDates.map(date => ({
-            date: date,
-            price: priceMap[date]
-        })).filter(item => item.price > 0);
-    }
-}
-
-class HistoryExtractor {
-    static getTrades(historyDoc) {
-        if (historyDoc && Array.isArray(historyDoc.PublicHistoryPositions)) {
-            return historyDoc.PublicHistoryPositions;
-        }
-        return [];
-    }
-
-    static getRealizedEquity(historyDoc) {
-        return historyDoc?.CreditByRealizedEquity || 0;
-    }
-
-    // --- [RESTORED METHOD] ---
-    static getDailyHistory(historyDoc) {
-        const trades = this.getTrades(historyDoc);
-        if (!trades.length) return [];
-
-        const dailyMap = new Map();
-
-        for (const t of trades) {
-            if (!t.CloseDateTime) continue;
-            // Extract YYYY-MM-DD
-            const date = new Date(t.CloseDateTime).toISOString().slice(0, 10);
-            const pnl = t.NetProfit || 0;
-            const invested = t.Amount || t.Invested || 0; // Handle schema variance
-
-            if (!dailyMap.has(date)) {
-                dailyMap.set(date, { 
-                    date: date, 
-                    netProfit: 0, 
-                    investedVolume: 0, 
-                    tradesCount: 0 
-                });
-            }
-            
-            const entry = dailyMap.get(date);
-            entry.netProfit += pnl;
-            entry.investedVolume += invested;
-            entry.tradesCount++;
-        }
-
-        // Return sorted array
-        return Array.from(dailyMap.values()).sort((a, b) => a.date.localeCompare(b.date));
-    }
-    // -------------------------
-
-    static getTradedAssets(historyDoc) {
-        const trades = this.getTrades(historyDoc);
-        if (!trades.length) return [];
-
-        const assetsMap = new Map();
-        for (const t of trades) {
-            const instId = t.InstrumentID;
-            if (!instId) continue;
-            
-            if (!assetsMap.has(instId)) {
-                assetsMap.set(instId, { instrumentId: instId, totalDuration: 0, count: 0 });
-            }
-            const asset = assetsMap.get(instId);
-            
-            if (t.OpenDateTime && t.CloseDateTime) {
-                const open  = new Date(t.OpenDateTime);
-                const close = new Date(t.CloseDateTime);
-                const durationMins = (close - open) / 60000;
-                if (durationMins > 0) {
-                    asset.totalDuration += durationMins;
-                    asset.count++;
-                }
-            }
-        }
-        
-        return Array.from(assetsMap.values()).map(a => ({
-            instrumentId: a.instrumentId,
-            avgHoldingTimeInMinutes: a.count > 0 ? (a.totalDuration / a.count) : 0
-        }));
-    }
-
-    static getSummary(historyDoc) { 
-        const trades = this.getTrades(historyDoc);
-        if (!trades.length) return null;
-
-        let totalTrades = trades.length;
-        let wins = 0;
-        let totalProf = 0;
-        let totalLoss = 0;
-        let profCount = 0;
-        let lossCount = 0;
-        let totalDur = 0;
-        let validDurCount = 0;
-
-        for (const t of trades) {
-            const netProfit = t.NetProfit || 0;
-            
-            if (netProfit > 0) {
-                wins++;
-                totalProf += netProfit;
-                profCount++;
-            } else if (netProfit < 0) {
-                totalLoss += netProfit;
-                lossCount++;
-            }
-
-            if (t.OpenDateTime && t.CloseDateTime) {
-                const open = new Date(t.OpenDateTime);
-                const close = new Date(t.CloseDateTime);
-                totalDur += (close - open) / 60000;
-                validDurCount++;
-            }
-        }
-
-        return { 
-            totalTrades:             totalTrades,
-            winRatio:                totalTrades > 0 ? (wins / totalTrades) * 100 : 0,
-            avgProfit:               profCount > 0 ? totalProf / profCount : 0,
-            avgLoss:                 lossCount > 0 ? totalLoss / lossCount : 0,
-            avgHoldingTimeInMinutes: validDurCount > 0 ? totalDur / validDurCount : 0
-        };
-    }
-
-    /**
-     * Extract sectors from historical trades.
-     * @param {Object} historyDoc - Trade history document
-     * @param {Object} mappings - Context mappings containing instrumentToSector
-     * @returns {string[]} Array of unique sector names
-     */
-    static getTradedSectors(historyDoc, mappings) {
-        const trades = this.getTrades(historyDoc);
-        const sectors = new Set();
-        const sectorMap = mappings?.instrumentToSector || {};
-        
-        for (const trade of trades) {
-            const instId = trade.InstrumentID;
-            if (instId) {
-                const sector = sectorMap[instId] || 'Unknown';
-                sectors.add(sector);
-            }
-        }
-        return Array.from(sectors);
-    }
-
-    /**
-     * Extract list of Popular Investors that user has copied (from trade history).
-     * @param {Object} historyDoc - Trade history document
-     * @returns {number[]} Array of ParentCID values
-     */
-    static getCopiedUsers(historyDoc) {
-        const trades = this.getTrades(historyDoc);
-        const copiedUsers = new Set();
-        
-        for (const trade of trades) {
-            if (trade.ParentCID && trade.ParentCID > 0) {
-                copiedUsers.add(trade.ParentCID);
-            }
-        }
-        return Array.from(copiedUsers);
-    }
-}
-
-class InsightsExtractor {
-    static getInsights(context, timeframe = 'today') {
-        const insightsData = context.insights;
-        if (!insightsData) return [];
-        const doc = insightsData[timeframe];
-        if (!doc) return [];
-        if (doc.insights && Array.isArray(doc.insights)) { return doc.insights; }
-        return [];
-    }
-
-    static getInsightForInstrument(insights, instrumentId) {
-        if (!insights || !Array.isArray(insights)) return null;
-        return insights.find(i => i.instrumentId === instrumentId) || null;
-    }
-
-    static getTotalOwners(insight)   { return insight ? (insight.total  || 0) : 0; }
-    static getLongPercent(insight)   { return insight ? (insight.buy    || 0) : 0; }
-    static getShortPercent(insight)  { return insight ? (insight.sell   || 0) : 0; }
-    static getGrowthPercent(insight) { return insight ? (insight.growth || 0) : 0; }
-}
-
-/**
- * [NEW] Extractor for PI Ratings Data
- * Access via: context.globalData.ratings
- * Schema: { piCid: { averageRating, totalRatings, ratingsByUser: { userId: rating } } }
- */
-class RatingsExtractor {
-    /**
-     * Get ratings data for a specific PI
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object|null} PI ratings data or null if not found
-     */
-    static getPIRatings(ratingsData, piCid) {
-        if (!ratingsData || !piCid) return null;
-        return ratingsData[String(piCid)] || null;
-    }
-
-    /**
-     * Get average rating for a PI
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Average rating (0-5) or 0 if not available
-     */
-    static getAverageRating(ratingsData, piCid) {
-        const piRatings = this.getPIRatings(ratingsData, piCid);
-        return piRatings?.averageRating || 0;
-    }
-
-    /**
-     * Get total number of ratings for a PI
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Total ratings count or 0 if not available
-     */
-    static getTotalRatings(ratingsData, piCid) {
-        const piRatings = this.getPIRatings(ratingsData, piCid);
-        return piRatings?.totalRatings || 0;
-    }
-
-    /**
-     * Get ratings by user map for a PI
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object} Map of userId -> rating, or empty object if not available
-     */
-    static getRatingsByUser(ratingsData, piCid) {
-        const piRatings = this.getPIRatings(ratingsData, piCid);
-        return piRatings?.ratingsByUser || {};
-    }
-
-    /**
-     * Get a specific user's rating for a PI
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string|number} userId - User CID
-     * @returns {number|null} User's rating (1-5) or null if not found
-     */
-    static getUserRating(ratingsData, piCid, userId) {
-        const ratingsByUser = this.getRatingsByUser(ratingsData, piCid);
-        const rating = ratingsByUser[String(userId)];
-        return rating !== undefined ? rating : null;
-    }
-
-    /**
-     * Get all PIs with ratings data
-     * @param {Object} ratingsData - The ratings data from context.globalData.ratings
-     * @returns {string[]} Array of PI CIDs that have ratings
-     */
-    static getAllPIs(ratingsData) {
-        if (!ratingsData || typeof ratingsData !== 'object') return [];
-        return Object.keys(ratingsData).filter(key => key !== 'date' && key !== 'lastUpdated');
-    }
-}
-
-/**
- * [NEW] Extractor for PI Page Views Data
- * Access via: context.globalData.pageViews
- * Schema: { piCid: { totalViews, uniqueViewers, viewsByUser: { userId: { viewCount, lastViewed } } } }
- */
-class PageViewsExtractor {
-    /**
-     * Get page views data for a specific PI
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object|null} PI page views data or null if not found
-     */
-    static getPIPageViews(pageViewsData, piCid) {
-        if (!pageViewsData || !piCid) return null;
-        return pageViewsData[String(piCid)] || null;
-    }
-
-    /**
-     * Get total page views for a PI
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Total views count or 0 if not available
-     */
-    static getTotalViews(pageViewsData, piCid) {
-        const piViews = this.getPIPageViews(pageViewsData, piCid);
-        return piViews?.totalViews || 0;
-    }
-
-    /**
-     * Get unique viewers count for a PI
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Unique viewers count or 0 if not available
-     */
-    static getUniqueViewers(pageViewsData, piCid) {
-        const piViews = this.getPIPageViews(pageViewsData, piCid);
-        return piViews?.uniqueViewers || 0;
-    }
-
-    /**
-     * Get views by user map for a PI
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object} Map of userId -> { viewCount, lastViewed }, or empty object if not available
-     */
-    static getViewsByUser(pageViewsData, piCid) {
-        const piViews = this.getPIPageViews(pageViewsData, piCid);
-        return piViews?.viewsByUser || {};
-    }
-
-    /**
-     * Get a specific user's view data for a PI
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string|number} userId - User CID
-     * @returns {Object|null} User's view data { viewCount, lastViewed } or null if not found
-     */
-    static getUserViews(pageViewsData, piCid, userId) {
-        const viewsByUser = this.getViewsByUser(pageViewsData, piCid);
-        return viewsByUser[String(userId)] || null;
-    }
-
-    /**
-     * Get view count for a specific user
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string|number} userId - User CID
-     * @returns {number} User's view count or 0 if not found
-     */
-    static getUserViewCount(pageViewsData, piCid, userId) {
-        const userViews = this.getUserViews(pageViewsData, piCid, userId);
-        return userViews?.viewCount || 0;
-    }
-
-    /**
-     * Get last viewed timestamp for a specific user
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string|number} userId - User CID
-     * @returns {Date|null} Last viewed date or null if not found
-     */
-    static getUserLastViewed(pageViewsData, piCid, userId) {
-        const userViews = this.getUserViews(pageViewsData, piCid, userId);
-        if (!userViews || !userViews.lastViewed) return null;
-        return userViews.lastViewed.toDate ? userViews.lastViewed.toDate() : new Date(userViews.lastViewed);
-    }
-
-    /**
-     * Get all PIs with page views data
-     * @param {Object} pageViewsData - The page views data from context.globalData.pageViews
-     * @returns {string[]} Array of PI CIDs that have page views
-     */
-    static getAllPIs(pageViewsData) {
-        if (!pageViewsData || typeof pageViewsData !== 'object') return [];
-        return Object.keys(pageViewsData).filter(key => key !== 'date' && key !== 'lastUpdated');
-    }
-}
-
-/**
- * [NEW] Extractor for Watchlist Membership Data
- * Access via: context.globalData.watchlistMembership
- * Schema: { piCid: { totalUsers, users: [userId], publicWatchlistCount, privateWatchlistCount } }
- */
-class WatchlistMembershipExtractor {
-    /**
-     * Get watchlist membership data for a specific PI
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object|null} PI watchlist membership data or null if not found
-     */
-    static getPIMembership(watchlistData, piCid) {
-        if (!watchlistData || !piCid) return null;
-        return watchlistData[String(piCid)] || null;
-    }
-
-    /**
-     * Get total users who have this PI in their watchlist
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Total users count or 0 if not available
-     */
-    static getTotalUsers(watchlistData, piCid) {
-        const membership = this.getPIMembership(watchlistData, piCid);
-        return membership?.totalUsers || 0;
-    }
-
-    /**
-     * Get array of user CIDs who have this PI in their watchlist
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {string[]} Array of user CIDs, or empty array if not available
-     */
-    static getUsers(watchlistData, piCid) {
-        const membership = this.getPIMembership(watchlistData, piCid);
-        if (!membership || !Array.isArray(membership.users)) return [];
-        return membership.users.map(u => String(u));
-    }
-
-    /**
-     * Check if a specific user has this PI in their watchlist
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string|number} userId - User CID
-     * @returns {boolean} True if user has PI in watchlist
-     */
-    static hasUser(watchlistData, piCid, userId) {
-        const users = this.getUsers(watchlistData, piCid);
-        return users.includes(String(userId));
-    }
-
-    /**
-     * Get public watchlist count for a PI
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Public watchlist count or 0 if not available
-     */
-    static getPublicWatchlistCount(watchlistData, piCid) {
-        const membership = this.getPIMembership(watchlistData, piCid);
-        return membership?.publicWatchlistCount || 0;
-    }
-
-    /**
-     * Get private watchlist count for a PI
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {number} Private watchlist count or 0 if not available
-     */
-    static getPrivateWatchlistCount(watchlistData, piCid) {
-        const membership = this.getPIMembership(watchlistData, piCid);
-        return membership?.privateWatchlistCount || 0;
-    }
-
-    /**
-     * Get all PIs with watchlist membership data
-     * @param {Object} watchlistData - The watchlist data from context.globalData.watchlistMembership
-     * @returns {string[]} Array of PI CIDs that have watchlist membership
-     */
-    static getAllPIs(watchlistData) {
-        if (!watchlistData || typeof watchlistData !== 'object') return [];
-        return Object.keys(watchlistData).filter(key => key !== 'date' && key !== 'lastUpdated');
-    }
-}
-
-/**
- * [NEW] Extractor for PI-Centric Watchlist Data
- * Access via: loader.loadPIWatchlistData(piCid) or context-specific loading
- * Schema: { totalUsers, userCids: [], dailyAdditions: { date: { count, userCids: [], timestamp } }, lastUpdated }
- */
-class PIWatchlistDataExtractor {
-    /**
-     * Get total users who have this PI in their watchlist
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @returns {number} Total users count or 0 if not available
-     */
-    static getTotalUsers(piWatchlistData) {
-        if (!piWatchlistData) return 0;
-        return piWatchlistData.totalUsers || 0;
-    }
-
-    /**
-     * Get array of user CIDs who have this PI in their watchlist
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @returns {string[]} Array of user CIDs, or empty array if not available
-     */
-    static getUserCids(piWatchlistData) {
-        if (!piWatchlistData || !Array.isArray(piWatchlistData.userCids)) return [];
-        return piWatchlistData.userCids.map(cid => String(cid));
-    }
-
-    /**
-     * Check if a specific user has this PI in their watchlist
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @param {string|number} userId - User CID
-     * @returns {boolean} True if user has PI in watchlist
-     */
-    static hasUser(piWatchlistData, userId) {
-        const userCids = this.getUserCids(piWatchlistData);
-        return userCids.includes(String(userId));
-    }
-
-    /**
-     * Get daily additions data for a specific date
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @param {string} date - Date string in YYYY-MM-DD format
-     * @returns {Object|null} Daily addition data { count, userCids: [], timestamp } or null if not found
-     */
-    static getDailyAdditions(piWatchlistData, date) {
-        if (!piWatchlistData || !piWatchlistData.dailyAdditions || typeof piWatchlistData.dailyAdditions !== 'object') {
-            return null;
-        }
-        return piWatchlistData.dailyAdditions[date] || null;
-    }
-
-    /**
-     * Get count of users who added this PI to their watchlist on a specific date
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @param {string} date - Date string in YYYY-MM-DD format
-     * @returns {number} Count of users who added on this date, or 0 if not available
-     */
-    static getDailyAdditionCount(piWatchlistData, date) {
-        const dailyData = this.getDailyAdditions(piWatchlistData, date);
-        return dailyData?.count || 0;
-    }
-
-    /**
-     * Get user CIDs who added this PI to their watchlist on a specific date
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @param {string} date - Date string in YYYY-MM-DD format
-     * @returns {string[]} Array of user CIDs who added on this date, or empty array if not available
-     */
-    static getDailyAdditionUserCids(piWatchlistData, date) {
-        const dailyData = this.getDailyAdditions(piWatchlistData, date);
-        if (!dailyData || !Array.isArray(dailyData.userCids)) return [];
-        return dailyData.userCids.map(cid => String(cid));
-    }
-
-    /**
-     * Get all dates with daily addition data
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @returns {string[]} Array of date strings (YYYY-MM-DD format), or empty array if not available
-     */
-    static getAllDates(piWatchlistData) {
-        if (!piWatchlistData || !piWatchlistData.dailyAdditions || typeof piWatchlistData.dailyAdditions !== 'object') {
-            return [];
-        }
-        return Object.keys(piWatchlistData.dailyAdditions);
-    }
-
-    /**
-     * Get last updated timestamp
-     * @param {Object} piWatchlistData - The PI watchlist data from PopularInvestors/{piCid}/watchlistData/current
-     * @returns {Object|null} Timestamp object or null if not available
-     */
-    static getLastUpdated(piWatchlistData) {
-        if (!piWatchlistData) return null;
-        return piWatchlistData.lastUpdated || null;
-    }
-}
-
-/**
- * [NEW] Extractor for PI Alert History Data
- * Access via: context.globalData.alertHistory
- * Schema: { piCid: { alertType: { triggered, count, triggeredFor: [userId], metadata: {...}, lastTriggered } } }
- */
-class AlertHistoryExtractor {
-    /**
-     * Get alert history data for a specific PI
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {Object|null} PI alert history data or null if not found
-     */
-    static getPIAlertHistory(alertHistoryData, piCid) {
-        if (!alertHistoryData || !piCid) return null;
-        return alertHistoryData[String(piCid)] || null;
-    }
-
-    /**
-     * Get all alert types for a PI
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {string[]} Array of alert type names, or empty array if not available
-     */
-    static getAlertTypes(alertHistoryData, piCid) {
-        const piAlerts = this.getPIAlertHistory(alertHistoryData, piCid);
-        if (!piAlerts || typeof piAlerts !== 'object') return [];
-        return Object.keys(piAlerts).filter(key => key !== 'date' && key !== 'lastUpdated');
-    }
-
-    /**
-     * Get alert data for a specific alert type
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name (e.g., "RiskScoreIncrease")
-     * @returns {Object|null} Alert data or null if not found
-     */
-    static getAlertData(alertHistoryData, piCid, alertType) {
-        const piAlerts = this.getPIAlertHistory(alertHistoryData, piCid);
-        if (!piAlerts || !alertType) return null;
-        return piAlerts[alertType] || null;
-    }
-
-    /**
-     * Check if an alert type was triggered for a PI
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @returns {boolean} True if alert was triggered
-     */
-    static isTriggered(alertHistoryData, piCid, alertType) {
-        const alertData = this.getAlertData(alertHistoryData, piCid, alertType);
-        return alertData?.triggered === true;
-    }
-
-    /**
-     * Get trigger count for an alert type
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @returns {number} Trigger count or 0 if not available
-     */
-    static getTriggerCount(alertHistoryData, piCid, alertType) {
-        const alertData = this.getAlertData(alertHistoryData, piCid, alertType);
-        return alertData?.count || 0;
-    }
-
-    /**
-     * Get array of user CIDs for whom the alert was triggered
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @returns {string[]} Array of user CIDs, or empty array if not available
-     */
-    static getTriggeredFor(alertHistoryData, piCid, alertType) {
-        const alertData = this.getAlertData(alertHistoryData, piCid, alertType);
-        if (!alertData || !Array.isArray(alertData.triggeredFor)) return [];
-        return alertData.triggeredFor.map(u => String(u));
-    }
-
-    /**
-     * Check if alert was triggered for a specific user
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @param {string|number} userId - User CID
-     * @returns {boolean} True if alert was triggered for this user
-     */
-    static isTriggeredForUser(alertHistoryData, piCid, alertType, userId) {
-        const triggeredFor = this.getTriggeredFor(alertHistoryData, piCid, alertType);
-        return triggeredFor.includes(String(userId));
-    }
-
-    /**
-     * Get metadata for an alert type
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @returns {Object} Alert metadata or empty object if not available
-     */
-    static getMetadata(alertHistoryData, piCid, alertType) {
-        const alertData = this.getAlertData(alertHistoryData, piCid, alertType);
-        return alertData?.metadata || {};
-    }
-
-    /**
-     * Get last triggered timestamp for an alert type
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @param {string} alertType - Alert type name
-     * @returns {Date|null} Last triggered date or null if not found
-     */
-    static getLastTriggered(alertHistoryData, piCid, alertType) {
-        const alertData = this.getAlertData(alertHistoryData, piCid, alertType);
-        if (!alertData || !alertData.lastTriggered) return null;
-        return alertData.lastTriggered.toDate ? alertData.lastTriggered.toDate() : new Date(alertData.lastTriggered);
-    }
-
-    /**
-     * Get all triggered alerts for a PI
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @param {string|number} piCid - Popular Investor CID
-     * @returns {string[]} Array of alert type names that were triggered
-     */
-    static getTriggeredAlerts(alertHistoryData, piCid) {
-        const alertTypes = this.getAlertTypes(alertHistoryData, piCid);
-        return alertTypes.filter(type => this.isTriggered(alertHistoryData, piCid, type));
-    }
-
-    /**
-     * Get all PIs with alert history data
-     * @param {Object} alertHistoryData - The alert history data from context.globalData.alertHistory
-     * @returns {string[]} Array of PI CIDs that have alert history
-     */
-    static getAllPIs(alertHistoryData) {
-        if (!alertHistoryData || typeof alertHistoryData !== 'object') return [];
-        return Object.keys(alertHistoryData).filter(key => key !== 'date' && key !== 'lastUpdated');
-    }
-}
-
-/**
- * [NEW] Extractor for Popular Investor Master List (Global Backup)
- * Access via: context.globalData.piMasterList
- */
-class PIMasterListExtractor {
-    /**
-     * Get the master record for a PI
-     * @param {Object} masterList - context.globalData.piMasterList
-     * @param {string} cid - The User CID
-     */
-    static getRecord(masterList, cid) {
-        if (!masterList || !cid) return null;
-        return masterList[String(cid)] || null;
-    }
-
-    /**
-     * Resolve Username from Master List
-     * @param {Object} masterList 
-     * @param {string} cid 
-     */
-    static getUsername(masterList, cid) {
-        const record = this.getRecord(masterList, cid);
-        return record ? record.username : null;
-    }
-
-    /**
-     * Check if CID exists in master list
-     */
-    static exists(masterList, cid) {
-        return !!this.getRecord(masterList, cid);
-    }
-}
-
-module.exports = { 
-    DataExtractor, 
-    priceExtractor, 
-    HistoryExtractor, 
-    InsightsExtractor, 
-    TradeSeriesBuilder, 
-    PopularInvestorExtractor,
-    CopyTradingExtractor,
-    RankingsExtractor,
-    VerificationExtractor,
-    SocialExtractor,
-    // [NEW] New Root Data Extractors
-    RatingsExtractor,
-    PageViewsExtractor,
-    WatchlistMembershipExtractor,
-    PIWatchlistDataExtractor,
-    AlertHistoryExtractor,
-    PIMasterListExtractor
-};