bulltrackers-module 1.0.210 → 1.0.212

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

@@ -0,0 +1,415 @@
+/**
+ * @fileoverview Extractors Layer
+ * Core access methods to raw data (Portfolio, History, Prices, Insights).
+ */
+
+const { SCHEMAS } = require('./profiling');
+
+class TradeSeriesBuilder {
+    /**
+     * Converts raw trade history into a time-series of Strategy Returns.
+     * Assumes a "Flat Bet" model (equal sizing) because absolute position size is not available in history.
+     * This creates a normalized performance curve for the user's *decisions*.
+     * @param {Array} historyTrades - PublicHistoryPositions array.
+     * @returns {Array<number>} Array of NetProfit% values sorted by close date.
+     */
+    static buildReturnSeries(historyTrades) {
+        if (!historyTrades || !Array.isArray(historyTrades)) return [];
+        
+        // 1. Filter valid closed trades
+        const closedTrades = historyTrades.filter(t => t.CloseDateTime && typeof t.NetProfit === 'number');
+        
+        // 2. Sort by Close Date (Ascending)
+        closedTrades.sort((a, b) => new Date(a.CloseDateTime) - new Date(b.CloseDateTime));
+        
+        // 3. Extract the PnL sequence
+        return closedTrades.map(t => t.NetProfit);
+    }
+
+    /**
+     * Builds a cumulative equity curve (starting at 100) based on compounding trade returns.
+     * Useful for visualising the trajectory of the strategy.
+     */
+    static buildCumulativeCurve(returnSeries, startValue = 100) {
+        const curve = [startValue];
+        let current = startValue;
+        
+        for (const ret of returnSeries) {
+            // Apply return (e.g. 5% profit -> * 1.05)
+            // Note: NetProfit in eToro history is usually percentage (e.g. 5.4954).
+            // We treat this as the return on *that specific position*.
+            // In a flat-bet model, we assume that position was X% of the portfolio.
+            // Simplified: We just accumulate the "points" captured.
+            current = current * (1 + (ret / 100));
+            curve.push(current);
+        }
+        return curve;
+    }
+}
+
+class DataExtractor { 
+    // ========================================================================
+    // 1. COLLECTION ACCESSORS
+    // ========================================================================
+    
+    /**
+     * Extract positions array based on User Type.
+     * - Normal: Uses 'AggregatedPositions' (Grouped by Asset + Direction)
+     * - Speculator: Uses 'PublicPositions' (Individual Trades)
+     */
+    static getPositions(portfolio, userType) {
+        if (!portfolio) return []; // Handle empty portfolio
+        
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) { 
+            return portfolio.PublicPositions || []; // SPECULATOR SCHEMA
+        }
+        
+        // Default to Normal User Schema
+        return portfolio.AggregatedPositions || [];
+    }
+
+    // ========================================================================
+    // 2. IDENTITY & KEYS
+    // ========================================================================
+
+    /**
+     * Extract standardized Instrument ID.
+     */
+    static getInstrumentId(position) {
+        if (!position) return null; // Handle empty position data
+        // Handle string or number variations safely
+        return position.InstrumentID || position.instrumentId || null;
+    }
+
+    /**
+     * Extract a unique Identifier for the position.
+     * - Speculator: Uses 'PositionID'.
+     * - Normal: Generates Composite Key (InstrumentID_Direction) since they lack unique Trade IDs.
+     */
+    static getPositionId(position) {
+        if (!position) return null; // Handle empty position data
+        
+        // 1. Try Explicit ID (Speculators)
+        if (position.PositionID) return String(position.PositionID);
+        if (position.PositionId) return String(position.PositionId);
+
+        // 2. Fallback to Composite Key (Normal Users)
+        const instId = this.getInstrumentId(position);
+        const dir    = this.getDirection(position);
+        if (instId) return `${instId}_${dir}`;
+
+        return null;
+    }
+
+    // ========================================================================
+    // 3. FINANCIAL METRICS (WEIGHTS & P&L)
+    // ========================================================================
+
+    /**
+     * Extract Net Profit %.
+     * Schema: 'NetProfit' is the percentage profit relative to invested capital.
+     */
+    static getNetProfit(position) { 
+        return position ? (position.NetProfit || 0) : 0;
+    }
+
+    /**
+     * Extract Position Weight (Allocation %).
+     * Schema: 
+     * - Normal: 'Invested' is % of initial capital.
+     * - Speculator: 'Invested' (or 'Amount' in some contexts) is % of initial capital.
+     */
+    static getPositionWeight(position, userType) { // Agnostic on user type, unused.
+        if (!position) return 0;
+        
+        // Both schemas use 'Invested' to represent the allocation percentage.
+        // Speculators might optionally have 'Amount', we prioritize 'Invested' for consistency.
+        return position.Invested || position.Amount || 0;
+    }
+
+    /**
+     * Extract Current Equity Value %.
+     * Schema: 'Value' is the current value as a % of total portfolio equity.
+     */
+    static getPositionValuePct(position) {            
+        return position ? (position.Value || 0) : 0; 
+    }
+
+    /**
+     * --- NEW PRIMITIVE ---
+     * Derives the approximate Entry Price of a position based on Current Price and Net Profit %.
+     * Formula: Entry = Current / (1 + (NetProfit / 100))
+     * @param {number} currentPrice - The current market price of the asset.
+     * @param {number} netProfitPct - The Net Profit percentage (e.g., -20.5).
+     * @returns {number} Estimated Entry Price.
+     */
+    static deriveEntryPrice(currentPrice, netProfitPct) {
+        if (!currentPrice || currentPrice <= 0) return 0;
+        // Avoid division by zero if P&L is -100% (unlikely but possible in crypto/options)
+        if (netProfitPct <= -100) return Number.MAX_SAFE_INTEGER; // Effectively infinite entry price (lost everything)
+        return currentPrice / (1 + (netProfitPct / 100.0));
+    }
+
+    // ========================================================================
+    // 4. PORTFOLIO LEVEL SUMMARY
+    // ========================================================================
+
+    /**
+     * Calculate/Extract Daily Portfolio P&L %.
+     */
+    static getPortfolioDailyPnl(portfolio, userType) {
+        if (!portfolio) return 0;
+        
+        // 1. Speculator (Explicit 'NetProfit' field on root)
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {       
+            return portfolio.NetProfit || 0;                    
+        }
+        
+        // 2. Normal (Aggregated Calculation)
+        if (portfolio.AggregatedPositionsByInstrumentTypeID) {
+            return portfolio.AggregatedPositionsByInstrumentTypeID.reduce((sum, agg) => {
+                return sum + ((agg.Value || 0) - (agg.Invested || 0));
+            }, 0);
+        }
+        
+        return 0;
+    }
+
+    // ========================================================================
+    // 5. TRADE DETAILS (SPECULATOR SPECIFIC)
+    // ========================================================================
+
+    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"; // Default
+    }
+
+    static getLeverage(position) {
+        return position ? (position.Leverage || 1) : 1; // Default 1 IF NOT FOUND
+    }
+
+    static getOpenRate(position) {
+        return position ? (position.OpenRate || 0) : 0; // Default 0 IF NOT FOUND
+    }
+
+    static getCurrentRate(position) {
+        return position ? (position.CurrentRate || 0) : 0; // Default 0 IF NOT FOUND
+    }
+
+    static getStopLossRate(position) {
+        const rate = position ? (position.StopLossRate || 0) : 0; 
+        if (rate > 0 && rate <= 0.01) return 0; // Normalizes bug value to 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; // Normalizes bug value to 0
+        return rate;
+    }
+
+    static getHasTSL(position) {
+        return position ? (position.HasTrailingStopLoss === true) : false; // Default false IF NOT FOUND
+    }
+
+    static getOpenDateTime(position) {
+        if (!position || !position.OpenDateTime) return null;        
+        return new Date(position.OpenDateTime);
+    }
+}
+
+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);
+    }
+
+    static getAllHistories(pricesContext) {
+        if (!pricesContext || !pricesContext.history) return new Map();
+        
+        const results = new Map();
+        for (const [id, data] of Object.entries(pricesContext.history)) {
+            const ticker = data.ticker || id;
+            const history = this.getHistory(pricesContext, id);
+            if (history.length > 0) {
+                results.set(ticker, history);
+            }
+        }
+        return results;
+    }
+}
+
+class HistoryExtractor {
+    static getDailyHistory(user) {
+        return user?.history?.today || null;
+    }
+
+    static getTradedAssets(historyDoc) {
+        const trades = historyDoc?.PublicHistoryPositions || [];
+        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);
+            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 getInstrumentId(asset) { 
+        return asset ? asset.instrumentId : null;
+    }
+
+    static getAvgHoldingTimeMinutes(asset) { 
+        return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
+    }
+
+    static getSummary(historyDoc) { 
+        const trades = historyDoc?.PublicHistoryPositions || [];
+        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;
+
+        for (const t of trades) {
+            if (t.NetProfit > 0) {
+                wins++;
+                totalProf += t.NetProfit;
+                profCount++;
+            } else if (t.NetProfit < 0) {
+                totalLoss += t.NetProfit;
+                lossCount++;
+            }
+            
+            const open = new Date(t.OpenDateTime);
+            const close = new Date(t.CloseDateTime);
+            totalDur += (close - open) / 60000;
+        }
+
+        return { 
+            totalTrades:             totalTrades,
+            winRatio:                totalTrades > 0 ? (wins / totalTrades) * 100 : 0,
+            avgProfitPct:            profCount > 0 ? totalProf / profCount : 0,
+            avgLossPct:              lossCount > 0 ? totalLoss / lossCount : 0,
+            avgHoldingTimeInMinutes: totalTrades > 0 ? totalDur / totalTrades : 0
+        };
+    }
+}
+
+class InsightsExtractor {
+    /**
+     * Extracts the raw array of insight objects from the context.
+     * Checks for standard context injection paths.
+     */
+    static getInsights(context) {
+        // Support multiple potential injection paths depending on controller version
+        return context.insights || context.daily_instrument_insights || [];
+    }
+
+    /**
+     * returns the specific insight object for a given instrument ID.
+     */
+    static getInsightForInstrument(insights, instrumentId) {
+        if (!insights || !Array.isArray(insights)) return null;
+        return insights.find(i => i.instrumentId === instrumentId) || null;
+    }
+
+    // --- Standard Metrics ---
+
+    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;
+    }
+
+    // --- Derived Counts (Estimated) ---
+
+    static getLongCount(insight) {
+        const total = this.getTotalOwners(insight);
+        const buyPct = this.getLongPercent(insight);
+        return Math.floor(total * (buyPct / 100));
+    }
+
+    static getShortCount(insight) {
+        const total = this.getTotalOwners(insight);
+        const sellPct = this.getShortPercent(insight);
+        return Math.floor(total * (sellPct / 100));
+    }
+
+    /**
+     * Calculates the net change in users from yesterday based on growth %.
+     * Formula: NetChange = Total - (Total / (1 + Growth/100))
+     */
+    static getNetOwnershipChange(insight) {
+        const total = this.getTotalOwners(insight);
+        const growth = this.getGrowthPercent(insight);
+        if (total === 0) return 0;
+        
+        // Reverse engineer yesterday's count
+        // Today = Yesterday * (1 + growth)
+        // Yesterday = Today / (1 + growth)
+        const prevTotal = total / (1 + (growth / 100)); // TODO: Check precision issues
+        return Math.round(total - prevTotal);
+    }
+}
+
+module.exports = { DataExtractor, priceExtractor, HistoryExtractor, InsightsExtractor, TradeSeriesBuilder };

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Layers Barrel File
+ * Aggregates all mathematical, extractor, and profiling primitives.
+ * Utilizes require-all to dynamically load new modules added to this directory.
+ */
+
+const requireAll = require('require-all');
+
+// 1. Manually Require Core Modules to ensure order and presence
+const profiling   = require('./profiling');
+const extractors  = require('./extractors');
+const mathematics = require('./mathematics');
+const validators  = require('./validators');
+
+// 2. Aggregate explicit exports
+const coreExports = {
+    ...profiling,
+    ...extractors,
+    ...mathematics,
+    ...validators
+};
+
+// 3. Dynamic Loading (Optional/Future-Proofing)
+// This loads any OTHER file in this directory that wasn't manually required above.
+const dynamicModules = requireAll({
+    dirname: __dirname,
+    filter: /^(?!index\.js$|profiling\.js$|extractors\.js$|mathematics\.js$|validators\.js$).+\.js$/, 
+    resolve: (mod) => mod
+});
+
+// Flatten dynamic modules into the export object
+const dynamicExports = {};
+Object.values(dynamicModules).forEach(moduleExports => {
+    Object.assign(dynamicExports, moduleExports);
+});
+
+module.exports = {
+    ...coreExports,
+    ...dynamicExports
+};