bulltrackers-module 1.0.733 → 1.0.734

package/functions/computation-system-v2/rules/portfolio.js

@@ -0,0 +1,534 @@
+/**
+ * @fileoverview Portfolio Business Rules
+ * 
+ * For extracting and analyzing portfolio_snapshots data.
+ * 
+ * Portfolio data structure (portfolio_data JSON):
+ * - AggregatedPositions: Array of positions per instrument
+ * - AggregatedMirrors: Array of copied positions
+ * - AggregatedPositionsByInstrumentTypeID: Positions by asset class
+ * - CreditByRealizedEquity: % cash relative to invested sum
+ * - CreditByUnrealizedEquity: % cash relative to current balance
+ * 
+ * Position data (percentages, not absolute values):
+ * - Direction: 'Buy' or 'Sell'
+ * - InstrumentID: Asset ID
+ * - Invested: % of initial investment
+ * - NetProfit: % P&L
+ * - Value: % of unrealized portfolio value
+ * 
+ * Usage in computation:
+ * ```javascript
+ * const data = rules.portfolio.extractPortfolioData(row);
+ * const positions = rules.portfolio.extractPositions(data);
+ * const totalValue = rules.portfolio.calculateTotalValue(positions);
+ * ```
+ */
+
+// =============================================================================
+// DATA EXTRACTION
+// =============================================================================
+
+/**
+ * Extract portfolio_data from a portfolio_snapshots row.
+ * @param {Object} row - portfolio_snapshots row
+ * @returns {Object|null}
+ */
+function extractPortfolioData(row) {
+    if (!row) return null;
+    
+    let data = row.portfolio_data;
+    
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return null;
+        }
+    }
+    
+    return data || null;
+}
+
+/**
+ * Get user ID from portfolio row.
+ * @param {Object} row - portfolio_snapshots row
+ * @returns {string|null}
+ */
+function getUserId(row) {
+    if (!row) return null;
+    
+    if (row.user_id) return String(row.user_id);
+    
+    const data = extractPortfolioData(row);
+    return data?.cid ? String(data.cid) : null;
+}
+
+/**
+ * Get username from portfolio data.
+ * @param {Object} data - portfolio_data object
+ * @returns {string|null}
+ */
+function getUsername(data) {
+    return data?.username || null;
+}
+
+/**
+ * Extract positions from portfolio data.
+ * Handles different portfolio data structures.
+ * 
+ * @param {Object|Array} portfolioData - Raw portfolio data from BigQuery
+ * @returns {Array} Array of position objects
+ */
+function extractPositions(portfolioData) {
+    if (!portfolioData) return [];
+    
+    // Handle array directly
+    if (Array.isArray(portfolioData)) return portfolioData;
+    
+    // Handle nested structures (actual data structure)
+    if (portfolioData.AggregatedPositions) return portfolioData.AggregatedPositions;
+    if (portfolioData.Positions) return portfolioData.Positions;
+    if (portfolioData.positions) return portfolioData.positions;
+    
+    // Handle JSON string
+    if (typeof portfolioData === 'string') {
+        try {
+            const parsed = JSON.parse(portfolioData);
+            return extractPositions(parsed);
+        } catch (e) {
+            return [];
+        }
+    }
+    
+    return [];
+}
+
+/**
+ * Extract mirrored (copied) positions.
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {Array}
+ */
+function extractMirrors(portfolioData) {
+    if (!portfolioData) return [];
+    return portfolioData.AggregatedMirrors || [];
+}
+
+/**
+ * Extract positions by instrument type/asset class.
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {Array}
+ */
+function extractPositionsByType(portfolioData) {
+    if (!portfolioData) return [];
+    return portfolioData.AggregatedPositionsByInstrumentTypeID || [];
+}
+
+/**
+ * Extract positions by stock industry.
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {Array}
+ */
+function extractPositionsByIndustry(portfolioData) {
+    if (!portfolioData) return [];
+    return portfolioData.AggregatedPositionsByStockIndustryID || [];
+}
+
+// =============================================================================
+// CASH BALANCE
+// =============================================================================
+
+/**
+ * Get cash balance as % of realized equity (invested sum).
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {number}
+ */
+function getCreditByRealizedEquity(portfolioData) {
+    return portfolioData?.CreditByRealizedEquity ?? 0;
+}
+
+/**
+ * Get cash balance as % of unrealized equity (current balance).
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {number}
+ */
+function getCreditByUnrealizedEquity(portfolioData) {
+    return portfolioData?.CreditByUnrealizedEquity ?? 0;
+}
+
+/**
+ * Calculate exposure percentage (100 - cash %).
+ * @param {Object} portfolioData - portfolio_data object
+ * @returns {number}
+ */
+function getExposure(portfolioData) {
+    return 100 - getCreditByUnrealizedEquity(portfolioData);
+}
+
+// =============================================================================
+// POSITION ACCESSORS
+// =============================================================================
+
+/**
+ * Get the instrument ID from a position.
+ * Handles different field names.
+ * 
+ * @param {Object} position - Position object
+ * @returns {string|number|null} Instrument ID
+ */
+function getInstrumentId(position) {
+    return position?.InstrumentID || 
+           position?.instrumentId || 
+           position?.instrument_id || 
+           null;
+}
+
+/**
+ * Get the instrument type ID from a position.
+ * @param {Object} position - Position object
+ * @returns {number|null}
+ */
+function getInstrumentTypeId(position) {
+    return position?.InstrumentTypeID || null;
+}
+
+/**
+ * Get the direction of a position ('Buy' or 'Sell').
+ * @param {Object} position - Position object
+ * @returns {string}
+ */
+function getDirection(position) {
+    return position?.Direction || 'Buy';
+}
+
+/**
+ * Check if position is long (Buy).
+ * @param {Object} position - Position object
+ * @returns {boolean}
+ */
+function isLong(position) {
+    return getDirection(position) === 'Buy';
+}
+
+/**
+ * Check if position is short (Sell).
+ * @param {Object} position - Position object
+ * @returns {boolean}
+ */
+function isShort(position) {
+    return getDirection(position) === 'Sell';
+}
+
+/**
+ * Get the invested percentage (% of initial investment).
+ * NOTE: This is a percentage, not an absolute value.
+ * 
+ * @param {Object} position - Position object
+ * @returns {number} Invested percentage
+ */
+function getInvested(position) {
+    return position?.Invested || 
+           position?.Amount || 
+           position?.amount || 
+           position?.invested || 
+           position?.Investment ||
+           0;
+}
+
+/**
+ * Get the net profit percentage (% P&L).
+ * NOTE: This is a percentage, not an absolute value.
+ * 
+ * @param {Object} position - Position object
+ * @returns {number} Net profit percentage
+ */
+function getNetProfit(position) {
+    return position?.NetProfit || 
+           position?.netProfit || 
+           position?.net_profit || 
+           position?.Profit ||
+           0;
+}
+
+/**
+ * Get the current value of a position.
+ * 
+ * @param {Object} position - Position object
+ * @returns {number} Current value
+ */
+function getValue(position) {
+    const value = position?.Value || position?.value;
+    if (value) return value;
+    
+    // Calculate from invested + profit
+    const invested = getInvested(position);
+    const profit = getNetProfit(position);
+    return invested + (invested * profit / 100);
+}
+
+/**
+ * Calculate total portfolio value.
+ * 
+ * @param {Array} positions - Array of positions
+ * @returns {number} Total portfolio value
+ */
+function calculateTotalValue(positions) {
+    if (!Array.isArray(positions)) return 0;
+    return positions.reduce((sum, pos) => sum + getValue(pos), 0);
+}
+
+/**
+ * Calculate total invested amount.
+ * 
+ * @param {Array} positions - Array of positions
+ * @returns {number} Total invested
+ */
+function calculateTotalInvested(positions) {
+    if (!Array.isArray(positions)) return 0;
+    return positions.reduce((sum, pos) => sum + getInvested(pos), 0);
+}
+
+/**
+ * Calculate weighted average profit percentage.
+ * 
+ * @param {Array} positions - Array of positions
+ * @returns {number} Weighted average profit percentage
+ */
+function calculateWeightedProfitPercent(positions) {
+    if (!Array.isArray(positions) || positions.length === 0) return 0;
+    
+    let totalWeightedProfit = 0;
+    let totalInvested = 0;
+    
+    for (const pos of positions) {
+        const invested = getInvested(pos);
+        const profit = getNetProfit(pos);
+        
+        if (invested > 0) {
+            totalWeightedProfit += invested * (profit / 100);
+            totalInvested += invested;
+        }
+    }
+    
+    return totalInvested > 0 
+        ? (totalWeightedProfit / totalInvested) * 100 
+        : 0;
+}
+
+/**
+ * Group positions by sector.
+ * 
+ * @param {Array} positions - Array of positions
+ * @param {Object} sectorMap - Map of instrument ID -> sector name
+ * @returns {Object} Map of sector -> [positions]
+ */
+function groupBySector(positions, sectorMap) {
+    const groups = {};
+    
+    for (const pos of (positions || [])) {
+        const instrumentId = getInstrumentId(pos);
+        const sector = sectorMap?.[String(instrumentId)] || 'Unknown';
+        
+        if (!groups[sector]) groups[sector] = [];
+        groups[sector].push(pos);
+    }
+    
+    return groups;
+}
+
+/**
+ * Calculate sector exposure percentages.
+ * 
+ * @param {Array} positions - Array of positions
+ * @param {Object} sectorMap - Map of instrument ID -> sector name
+ * @returns {Object} Map of sector -> percentage
+ */
+function calculateSectorExposure(positions, sectorMap) {
+    const groups = groupBySector(positions, sectorMap);
+    const totalValue = calculateTotalValue(positions);
+    
+    if (totalValue === 0) return {};
+    
+    const exposure = {};
+    for (const [sector, sectorPositions] of Object.entries(groups)) {
+        const sectorValue = calculateTotalValue(sectorPositions);
+        exposure[sector] = Number(((sectorValue / totalValue) * 100).toFixed(2));
+    }
+    
+    return exposure;
+}
+
+/**
+ * Get top N positions by value.
+ * 
+ * @param {Array} positions - Array of positions
+ * @param {number} n - Number of top positions to return
+ * @returns {Array} Top N positions sorted by value descending
+ */
+function getTopPositions(positions, n = 10) {
+    if (!Array.isArray(positions)) return [];
+    
+    return [...positions]
+        .sort((a, b) => getValue(b) - getValue(a))
+        .slice(0, n);
+}
+
+/**
+ * Get profitable positions.
+ * 
+ * @param {Array} positions - Array of positions
+ * @returns {Array} Positions with positive net profit
+ */
+function getProfitablePositions(positions) {
+    if (!Array.isArray(positions)) return [];
+    return positions.filter(pos => getNetProfit(pos) > 0);
+}
+
+/**
+ * Calculate win ratio (% of profitable positions).
+ * 
+ * @param {Array} positions - Array of positions
+ * @returns {number} Win ratio between 0 and 1
+ */
+function calculateWinRatio(positions) {
+    if (!Array.isArray(positions) || positions.length === 0) return 0;
+    
+    const profitable = getProfitablePositions(positions);
+    return profitable.length / positions.length;
+}
+
+/**
+ * Filter long positions.
+ * @param {Array} positions - Array of positions
+ * @returns {Array}
+ */
+function filterLong(positions) {
+    if (!Array.isArray(positions)) return [];
+    return positions.filter(isLong);
+}
+
+/**
+ * Filter short positions.
+ * @param {Array} positions - Array of positions
+ * @returns {Array}
+ */
+function filterShort(positions) {
+    if (!Array.isArray(positions)) return [];
+    return positions.filter(isShort);
+}
+
+/**
+ * Calculate long/short exposure breakdown.
+ * @param {Array} positions - Array of positions
+ * @returns {Object} { longPct, shortPct, longCount, shortCount }
+ */
+function getLongShortBreakdown(positions) {
+    if (!Array.isArray(positions) || positions.length === 0) {
+        return { longPct: 0, shortPct: 0, longCount: 0, shortCount: 0 };
+    }
+    
+    const long = filterLong(positions);
+    const short = filterShort(positions);
+    
+    const longValue = calculateTotalValue(long);
+    const shortValue = calculateTotalValue(short);
+    const totalValue = longValue + shortValue;
+    
+    return {
+        longPct: totalValue > 0 ? (longValue / totalValue) * 100 : 0,
+        shortPct: totalValue > 0 ? (shortValue / totalValue) * 100 : 0,
+        longCount: long.length,
+        shortCount: short.length
+    };
+}
+
+/**
+ * Summarize portfolio snapshot.
+ * @param {Object} row - portfolio_snapshots row
+ * @returns {Object}
+ */
+function summarize(row) {
+    const data = extractPortfolioData(row);
+    if (!data) return null;
+    
+    const positions = extractPositions(data);
+    const longShort = getLongShortBreakdown(positions);
+    
+    return {
+        userId: getUserId(row),
+        username: getUsername(data),
+        
+        // Positions
+        positionCount: positions.length,
+        totalValue: calculateTotalValue(positions),
+        totalInvested: calculateTotalInvested(positions),
+        
+        // Performance
+        profitPercent: calculateWeightedProfitPercent(positions),
+        winRatio: calculateWinRatio(positions),
+        
+        // Exposure
+        exposure: getExposure(data),
+        cashPercent: getCreditByUnrealizedEquity(data),
+        
+        // Direction
+        longPct: longShort.longPct,
+        shortPct: longShort.shortPct,
+        
+        // Top holdings
+        topPositions: getTopPositions(positions, 5).map(pos => ({
+            instrumentId: getInstrumentId(pos),
+            value: getValue(pos),
+            profit: getNetProfit(pos),
+            direction: getDirection(pos)
+        }))
+    };
+}
+
+module.exports = {
+    // Data extraction
+    extractPortfolioData,
+    getUserId,
+    getUsername,
+    extractPositions,
+    extractMirrors,
+    extractPositionsByType,
+    extractPositionsByIndustry,
+    
+    // Cash balance
+    getCreditByRealizedEquity,
+    getCreditByUnrealizedEquity,
+    getExposure,
+    
+    // Position accessors
+    getInstrumentId,
+    getInstrumentTypeId,
+    getDirection,
+    isLong,
+    isShort,
+    getInvested,
+    getNetProfit,
+    getValue,
+    
+    // Calculations
+    calculateTotalValue,
+    calculateTotalInvested,
+    calculateWeightedProfitPercent,
+    calculateWinRatio,
+    
+    // Grouping
+    groupBySector,
+    calculateSectorExposure,
+    
+    // Filtering
+    filterLong,
+    filterShort,
+    getLongShortBreakdown,
+    
+    // Ranking
+    getTopPositions,
+    getProfitablePositions,
+    
+    // Summary
+    summarize
+};