bulltrackers-module 1.0.171 → 1.0.172

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

@@ -0,0 +1,346 @@
+/**
+ * @fileoverview Math Layer - Single Source of Truth (V3 Final)
+ * Encapsulates Schema Knowledge, Mathematical Primitives, and Signal Extractors.
+ * * STRICT COMPLIANCE:
+ * - Adheres to 'schema.md' definitions for Normal vs Speculator portfolios.
+ * - standardizes access to P&L, Weights, and Rates.
+ * - Provides safe fallbacks for all fields.
+ */
+
+const SCHEMAS = {
+    USER_TYPES: { NORMAL: 'normal', SPECULATOR: 'speculator' }
+};
+
+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 [];
+        
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
+            return portfolio.PublicPositions || [];
+        }
+        
+        // Default to Normal User Schema
+        return portfolio.AggregatedPositions || [];
+    }
+
+    // ========================================================================
+    // 2. IDENTITY & KEYS
+    // ========================================================================
+
+    /**
+     * Extract standardized Instrument ID.
+     */
+    static getInstrumentId(position) {
+        if (!position) return null;
+        // 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;
+        
+        // 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) {
+        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;
+    }
+
+    // ========================================================================
+    // 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)
+        // Logic: Sum(Value - Invested) across the 'InstrumentType' breakdown
+        // This gives the net performance change for the day relative to the portfolio.
+        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;
+    }
+
+    static getOpenRate(position) {
+        return position ? (position.OpenRate || 0) : 0;
+    }
+
+    static getCurrentRate(position) {
+        return position ? (position.CurrentRate || 0) : 0;
+    }
+
+    static getStopLossRate(position) {
+        return position ? (position.StopLossRate || 0) : 0;
+    }
+
+    static getTakeProfitRate(position) {
+        return position ? (position.TakeProfitRate || 0) : 0;
+    }
+
+    static getHasTSL(position) {
+        return position ? (position.HasTrailingStopLoss === true) : false;
+    }
+
+    /**
+     * Extract Open Date Time.
+     * Used for bagholder calculations.
+     */
+    static getOpenDateTime(position) {
+        if (!position || !position.OpenDateTime) return null;
+        return new Date(position.OpenDateTime);
+    }
+}
+
+class HistoryExtractor {
+    // --- Schema Accessor (NEW) ---
+    /**
+     * Extracts the daily history snapshot from the User object.
+     * This decouples the computation from knowing 'user.history.today'.
+     */
+    static getDailyHistory(user) {
+        return user?.history?.today || null;
+    }
+
+    // --- Data Extractors ---
+    static getTradedAssets(historyDoc) {
+        if (!historyDoc || !Array.isArray(historyDoc.assets)) return [];
+        return historyDoc.assets;
+    }
+
+    static getInstrumentId(asset) {
+        return asset ? asset.instrumentId : null;
+    }
+
+    static getAvgHoldingTimeMinutes(asset) {
+        return asset ? (asset.avgHoldingTimeInMinutes || 0) : 0;
+    }
+
+    static getSummary(historyDoc) {
+        const all = historyDoc?.all;
+        if (!all) return null;
+
+        return {
+            totalTrades: all.totalTrades || 0,
+            winRatio: all.winRatio || 0,
+            avgProfitPct: all.avgProfitPct || 0,
+            avgLossPct: all.avgLossPct || 0,
+            avgHoldingTimeInMinutes: all.avgHoldingTimeInMinutes || 0
+        };
+    }
+}
+
+class SignalPrimitives {
+    /**
+     * Safely extracts a specific numeric field for a specific ticker from a dependency.
+     */
+    static getMetric(dependencies, calcName, ticker, fieldName, fallback = 0) {
+        if (!dependencies || !dependencies[calcName]) return fallback;
+        const tickerData = dependencies[calcName][ticker];
+        if (!tickerData) return fallback;
+        
+        const val = tickerData[fieldName];
+        return (typeof val === 'number') ? val : fallback;
+    }
+
+    /**
+     * Creates a unified Set of all keys (tickers) present across multiple dependency results.
+     */
+    static getUnionKeys(dependencies, calcNames) {
+        const keys = new Set();
+        if (!dependencies) return [];
+        
+        for (const name of calcNames) {
+            const resultObj = dependencies[name];
+            if (resultObj && typeof resultObj === 'object') {
+                Object.keys(resultObj).forEach(k => keys.add(k));
+            }
+        }
+        return Array.from(keys);
+    }
+
+    /**
+     * Hyperbolic Tangent Normalization.
+     * Maps inputs to a strict -Scale to +Scale range.
+     */
+    static normalizeTanh(value, scale = 10, sensitivity = 10.0) {
+        if (value === 0) return 0;
+        return Math.tanh(value / sensitivity) * scale;
+    }
+
+    /**
+     * Standard Z-Score normalization.
+     */
+    static normalizeZScore(value, mean, stdDev) {
+        if (!stdDev || stdDev === 0) return 0;
+        return (value - mean) / stdDev;
+    }
+
+    /**
+     * Simple Divergence (A - B).
+     */
+    static divergence(valueA, valueB) {
+        return (valueA || 0) - (valueB || 0);
+    }
+}
+
+class MathPrimitives {
+    static average(values) {
+        if (!values || !values.length) return 0;
+        return values.reduce((a, b) => a + b, 0) / values.length;
+    }
+    
+    static median(values) {
+        if (!values || !values.length) return 0;
+        const sorted = [...values].sort((a, b) => a - b);
+        const mid = Math.floor(sorted.length / 2);
+        return sorted.length % 2 === 0
+            ? (sorted[mid - 1] + sorted[mid]) / 2
+            : sorted[mid];
+    }
+
+    static standardDeviation(values) {
+        if (!values || !values.length) return 0;
+        const avg = this.average(values);
+        const squareDiffs = values.map(val => Math.pow((val || 0) - avg, 2));
+        return Math.sqrt(this.average(squareDiffs));
+    }
+
+    static bucketBinary(value, threshold = 0) {
+        return value > threshold ? 'winner' : 'loser';
+    }
+}
+
+class Aggregators {
+    /**
+     * Helper to bucket users by P&L Status.
+     * Used by legacy systems or specific aggregators.
+     */
+    static bucketUsersByPnlPerAsset(usersData, tickerMap) {
+        const buckets = new Map();
+        for (const [userId, portfolio] of Object.entries(usersData)) {
+            // Auto-detect type if not provided (Legacy compatibility)
+            const userType = portfolio.PublicPositions ? SCHEMAS.USER_TYPES.SPECULATOR : SCHEMAS.USER_TYPES.NORMAL;
+            const positions = DataExtractor.getPositions(portfolio, userType);
+            
+            for (const pos of positions) {
+                const id = DataExtractor.getInstrumentId(pos);
+                const pnl = DataExtractor.getNetProfit(pos);
+                if (!id || pnl === 0) continue;
+                
+                const ticker = tickerMap[id];
+                if (!ticker) continue;
+
+                if (!buckets.has(ticker)) buckets.set(ticker, { winners: [], losers: [] });
+                const b = buckets.get(ticker);
+                
+                if (pnl > 0) b.winners.push(userId);
+                else b.losers.push(userId);
+            }
+        }
+        return Object.fromEntries(buckets);
+    }
+}
+
+class Validators {
+    static validatePortfolio(portfolio, userType) {
+        if (!portfolio) return { valid: false, errors: ['Portfolio is null'] };
+        
+        if (userType === SCHEMAS.USER_TYPES.SPECULATOR) {
+             if (!portfolio.PublicPositions) return { valid: false, errors: ['Missing PublicPositions'] };
+        } else {
+             if (!portfolio.AggregatedPositions) return { valid: false, errors: ['Missing AggregatedPositions'] };
+        }
+        
+        return { valid: true, errors: [] };
+    }
+}
+
+module.exports = { 
+    SCHEMAS, 
+    DataExtractor, 
+    HistoryExtractor, 
+    MathPrimitives, 
+    Aggregators, 
+    Validators, 
+    SignalPrimitives 
+};

package/functions/task-engine/helpers/update_helpers.js

@@ -15,7 +15,7 @@ async function lookupUsernames(cids, { logger, headerManager, proxyManager }, co
     if (!cids?.length) return [];
     logger.log('INFO', `[lookupUsernames] Looking up usernames for ${cids.length} CIDs.`);
     
-    // --- Set concurrency to 1 because appscript gets really fuckmed up with undocumented rate limits if we try spam it concurrently, a shame but that's life. DO NOT CHANGE THIS
+    // --- Set concurrency to 1 because appscript gets really fucked up with undocumented rate limits if we try spam it concurrently, a shame but that's life. DO NOT CHANGE THIS
     const limit = pLimit(1);
     const { USERNAME_LOOKUP_BATCH_SIZE, ETORO_API_RANKINGS_URL } = config;
     const batches = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.171",
+  "version": "1.0.172",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [