bulltrackers-module 1.0.733 → 1.0.734

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

@@ -0,0 +1,465 @@
+/**
+ * @fileoverview Instrument & Price Business Rules
+ * 
+ * For working with:
+ * - instrument_insights (sentiment data)
+ * - asset_prices (price data)
+ * - ticker_mappings (instrument ID <-> ticker)
+ * 
+ * Usage in computation:
+ * ```javascript
+ * const sentiment = rules.instruments.extractInsightsData(row);
+ * const buyPercent = rules.instruments.getBuyPercent(sentiment);
+ * const price = rules.instruments.getPrice(priceRow);
+ * ```
+ */
+
+// =============================================================================
+// INSTRUMENT INSIGHTS - sentiment data
+// =============================================================================
+
+/**
+ * Extract insights_data from an instrument_insights row.
+ * @param {Object} row - instrument_insights row
+ * @returns {Object|null}
+ */
+function extractInsightsData(row) {
+    if (!row) return null;
+    
+    let data = row.insights_data;
+    
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return null;
+        }
+    }
+    
+    return data || null;
+}
+
+/**
+ * Get instrument ID from insights row.
+ * @param {Object} row - instrument_insights row
+ * @returns {number|null}
+ */
+function getInsightsInstrumentId(row) {
+    return row?.instrument_id || extractInsightsData(row)?.instrumentId || null;
+}
+
+/**
+ * Get buy percentage (% of owners in buy positions).
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getBuyPercent(data) {
+    return data?.buy ?? 0;
+}
+
+/**
+ * Get sell percentage (% of owners in short positions).
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getSellPercent(data) {
+    return data?.sell ?? 0;
+}
+
+/**
+ * Get growth percentage (% change in owners vs yesterday).
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getGrowth(data) {
+    return data?.growth ?? 0;
+}
+
+/**
+ * Get platform percentage (% of platform that owns this asset).
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getPlatformPercentage(data) {
+    return data?.percentage ?? 0;
+}
+
+/**
+ * Get total owners count.
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getTotalOwners(data) {
+    return data?.total ?? 0;
+}
+
+/**
+ * Get previous buy percentage.
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getPrevBuy(data) {
+    return data?.prevBuy ?? 0;
+}
+
+/**
+ * Get previous sell percentage.
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getPrevSell(data) {
+    return data?.prevSell ?? 0;
+}
+
+/**
+ * Calculate sentiment score (-100 to +100).
+ * Positive = bullish, Negative = bearish.
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function calculateSentimentScore(data) {
+    const buy = getBuyPercent(data);
+    const sell = getSellPercent(data);
+    
+    // Range: -100 (all sell) to +100 (all buy)
+    return buy - sell;
+}
+
+/**
+ * Determine sentiment category.
+ * @param {Object} data - insights_data object
+ * @returns {string} 'very_bullish' | 'bullish' | 'neutral' | 'bearish' | 'very_bearish'
+ */
+function getSentimentCategory(data) {
+    const score = calculateSentimentScore(data);
+    
+    if (score >= 40) return 'very_bullish';
+    if (score >= 10) return 'bullish';
+    if (score > -10) return 'neutral';
+    if (score > -40) return 'bearish';
+    return 'very_bearish';
+}
+
+/**
+ * Calculate sentiment change from previous day.
+ * @param {Object} data - insights_data object
+ * @returns {number}
+ */
+function getSentimentChange(data) {
+    const currentScore = getBuyPercent(data) - getSellPercent(data);
+    const prevScore = getPrevBuy(data) - getPrevSell(data);
+    
+    return currentScore - prevScore;
+}
+
+/**
+ * Check if sentiment is trending up.
+ * @param {Object} data - insights_data object
+ * @returns {boolean}
+ */
+function isSentimentTrendingUp(data) {
+    return getSentimentChange(data) > 0;
+}
+
+// =============================================================================
+// ASSET PRICES
+// =============================================================================
+
+/**
+ * Get price from asset_prices row.
+ * @param {Object} row - asset_prices row
+ * @returns {number}
+ */
+function getPrice(row) {
+    return row?.price ?? row?.close ?? 0;
+}
+
+/**
+ * Get close price.
+ * @param {Object} row - asset_prices row
+ * @returns {number}
+ */
+function getClosePrice(row) {
+    return row?.close ?? row?.price ?? 0;
+}
+
+/**
+ * Get open price.
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getOpenPrice(row) {
+    return row?.open || null;
+}
+
+/**
+ * Get high price.
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getHighPrice(row) {
+    return row?.high || null;
+}
+
+/**
+ * Get low price.
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getLowPrice(row) {
+    return row?.low || null;
+}
+
+/**
+ * Get volume.
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getVolume(row) {
+    return row?.volume || null;
+}
+
+/**
+ * Get instrument ID from price row.
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getPriceInstrumentId(row) {
+    return row?.instrument_id || null;
+}
+
+/**
+ * Get ticker from price row.
+ * @param {Object} row - asset_prices row
+ * @returns {string|null}
+ */
+function getPriceTicker(row) {
+    const ticker = row?.ticker;
+    if (!ticker || ticker.startsWith('unknown_')) return null;
+    return ticker;
+}
+
+/**
+ * Calculate price change from open (if available).
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getDailyChange(row) {
+    const open = getOpenPrice(row);
+    const close = getClosePrice(row);
+    
+    if (!open || !close || open === 0) return null;
+    
+    return ((close - open) / open) * 100;
+}
+
+/**
+ * Calculate intraday range percentage (if available).
+ * @param {Object} row - asset_prices row
+ * @returns {number|null}
+ */
+function getIntradayRange(row) {
+    const high = getHighPrice(row);
+    const low = getLowPrice(row);
+    
+    if (!high || !low || low === 0) return null;
+    
+    return ((high - low) / low) * 100;
+}
+
+// =============================================================================
+// TICKER MAPPINGS
+// =============================================================================
+
+/**
+ * Build a ticker lookup map from ticker_mappings rows.
+ * @param {Array} rows - Array of ticker_mappings rows
+ * @returns {Object} { byId: Map<id, ticker>, byTicker: Map<ticker, id> }
+ */
+function buildTickerMaps(rows) {
+    const byId = new Map();
+    const byTicker = new Map();
+    
+    for (const row of (rows || [])) {
+        const id = row.instrument_id;
+        const ticker = row.ticker;
+        
+        if (id && ticker) {
+            byId.set(id, ticker);
+            byTicker.set(ticker.toUpperCase(), id);
+        }
+    }
+    
+    return { byId, byTicker };
+}
+
+/**
+ * Get ticker by instrument ID.
+ * @param {Map|Object} tickerMap - Map of id -> ticker (or byId map)
+ * @param {number|string} instrumentId - Instrument ID
+ * @returns {string|null}
+ */
+function getTickerById(tickerMap, instrumentId) {
+    if (tickerMap instanceof Map) {
+        return tickerMap.get(Number(instrumentId)) || null;
+    }
+    return tickerMap?.[instrumentId] || null;
+}
+
+/**
+ * Get instrument ID by ticker.
+ * @param {Map|Object} tickerMap - Map of ticker -> id (or byTicker map)
+ * @param {string} ticker - Ticker symbol
+ * @returns {number|null}
+ */
+function getIdByTicker(tickerMap, ticker) {
+    if (!ticker) return null;
+    
+    if (tickerMap instanceof Map) {
+        return tickerMap.get(ticker.toUpperCase()) || null;
+    }
+    return tickerMap?.[ticker.toUpperCase()] || null;
+}
+
+// =============================================================================
+// PRICE UTILITIES
+// =============================================================================
+
+/**
+ * Build a price lookup map from asset_prices rows.
+ * @param {Array} rows - Array of asset_prices rows
+ * @returns {Map} Map of instrumentId -> price
+ */
+function buildPriceMap(rows) {
+    const priceMap = new Map();
+    
+    for (const row of (rows || [])) {
+        const id = getPriceInstrumentId(row);
+        const price = getPrice(row);
+        
+        if (id && price > 0) {
+            priceMap.set(id, price);
+        }
+    }
+    
+    return priceMap;
+}
+
+/**
+ * Get price for an instrument from price map.
+ * @param {Map|Object} priceMap - Price lookup map
+ * @param {number|string} instrumentId - Instrument ID
+ * @returns {number}
+ */
+function getPriceForInstrument(priceMap, instrumentId) {
+    if (priceMap instanceof Map) {
+        return priceMap.get(Number(instrumentId)) || 0;
+    }
+    return priceMap?.[instrumentId] || 0;
+}
+
+/**
+ * Calculate price change between two price rows.
+ * @param {Object} currentRow - Current price row
+ * @param {Object} previousRow - Previous price row
+ * @returns {Object} { absolute, percentage }
+ */
+function calculatePriceChange(currentRow, previousRow) {
+    const current = getPrice(currentRow);
+    const previous = getPrice(previousRow);
+    
+    if (!previous || previous === 0) {
+        return { absolute: 0, percentage: 0 };
+    }
+    
+    return {
+        absolute: current - previous,
+        percentage: ((current - previous) / previous) * 100
+    };
+}
+
+// =============================================================================
+// COMBINED INSTRUMENT INFO
+// =============================================================================
+
+/**
+ * Build comprehensive instrument info.
+ * @param {Object} options
+ * @param {Object} [options.insightsRow] - instrument_insights row
+ * @param {Object} [options.priceRow] - asset_prices row
+ * @param {Object} [options.tickerMaps] - Ticker maps
+ * @returns {Object}
+ */
+function buildInstrumentInfo(options = {}) {
+    const { insightsRow, priceRow, tickerMaps } = options;
+    
+    const insightsData = insightsRow ? extractInsightsData(insightsRow) : null;
+    const instrumentId = insightsRow 
+        ? getInsightsInstrumentId(insightsRow) 
+        : (priceRow ? getPriceInstrumentId(priceRow) : null);
+    
+    const ticker = priceRow 
+        ? getPriceTicker(priceRow) 
+        : (tickerMaps?.byId ? getTickerById(tickerMaps.byId, instrumentId) : null);
+    
+    return {
+        instrumentId,
+        ticker,
+        
+        // Price data
+        price: priceRow ? getPrice(priceRow) : null,
+        
+        // Sentiment data
+        sentiment: insightsData ? {
+            buyPercent: getBuyPercent(insightsData),
+            sellPercent: getSellPercent(insightsData),
+            score: calculateSentimentScore(insightsData),
+            category: getSentimentCategory(insightsData),
+            growth: getGrowth(insightsData),
+            platformPct: getPlatformPercentage(insightsData),
+            totalOwners: getTotalOwners(insightsData)
+        } : null
+    };
+}
+
+module.exports = {
+    // Insights
+    extractInsightsData,
+    getInsightsInstrumentId,
+    getBuyPercent,
+    getSellPercent,
+    getGrowth,
+    getPlatformPercentage,
+    getTotalOwners,
+    getPrevBuy,
+    getPrevSell,
+    calculateSentimentScore,
+    getSentimentCategory,
+    getSentimentChange,
+    isSentimentTrendingUp,
+    
+    // Prices
+    getPrice,
+    getClosePrice,
+    getOpenPrice,
+    getHighPrice,
+    getLowPrice,
+    getVolume,
+    getPriceInstrumentId,
+    getPriceTicker,
+    getDailyChange,
+    getIntradayRange,
+    
+    // Ticker mappings
+    buildTickerMaps,
+    getTickerById,
+    getIdByTicker,
+    
+    // Price utilities
+    buildPriceMap,
+    getPriceForInstrument,
+    calculatePriceChange,
+    
+    // Combined
+    buildInstrumentInfo
+};