bulltrackers-module 1.0.428 → 1.0.429

package/functions/computation-system/persistence/ResultCommitter.js

@@ -2,12 +2,14 @@
  * @fileoverview Handles saving computation results with observability and Smart Cleanup.
  * UPDATED: Tracks specific Firestore Ops (Writes/Deletes) for cost analysis.
  * UPDATED: Added Dynamic Circuit Breaker Bypass for Price-Only calculations.
+ * UPDATED: Integrated Alert System Pub/Sub triggers for marked computations.
  */
 const { commitBatchInChunks, generateDataHash } = require('../utils/utils');
 const { updateComputationStatus }          = require('./StatusRepository');
 const { batchStoreSchemas }                = require('../utils/schema_capture');
 const { generateProcessId, PROCESS_TYPES } = require('../logger/logger');
 const { HeuristicValidator }               = require('./ResultsValidator');
+const { PubSubUtils }                      = require('../../core/utils/pubsub_utils');
 const ContractValidator                    = require('./ContractValidator');
 const validationOverrides                  = require('../config/validation_overrides'); 
 const pLimit                               = require('p-limit'); 
@@ -22,6 +24,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     const failureReport  = [];
     const schemas        = [];
     const cleanupTasks   = []; 
+    const alertTriggers  = []; // [NEW] Collect alert triggers
     const { logger, db } = deps;
     const pid            = generateProcessId(PROCESS_TYPES.STORAGE, passName, dStr);
     
@@ -30,6 +33,7 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     const shardIndexes     = options.shardIndexes || {};
     const nextShardIndexes = {};
     const fanOutLimit      = pLimit(10); 
+    const pubSubUtils      = new PubSubUtils(deps);
 
     // 1. [BATCH OPTIMIZATION] Fetch all SimHashes and Contracts upfront
     const calcNames = Object.keys(stateObj);
@@ -61,14 +65,11 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             const isPriceOnly = (dataDeps.length === 1 && dataDeps[0] === 'price');
             let effectiveOverrides = { ...configOverrides };
 
-            // If a calculation relies solely on price, we strictly bypass the circuit breaker.
-            // This handles Holidays (Weekday 0s), Weekends (Scheduler Gaps), and Crypto/Stock mix.
             if (isPriceOnly) {
                 effectiveOverrides.maxZeroPct = 100;
                 effectiveOverrides.maxFlatlinePct = 100;
                 effectiveOverrides.maxNullPct = 100;
                 effectiveOverrides.maxNanPct = 100;
-                // Remove specific weekend config to ensure these permissive global limits apply 7 days/week
                 delete effectiveOverrides.weekend; 
             }
             // --- [DYNAMIC OVERRIDE LOGIC END] ---
@@ -99,7 +100,6 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             const isEmpty = !result || (typeof result === 'object' && Object.keys(result).length === 0);
             const resultHash = isEmpty ? 'empty' : generateDataHash(result);
             
-            // [NEW] Use pre-fetched SimHash
             const simHash = (flushMode !== 'INTERMEDIATE') ? (simHashMap[calc.manifest.hash] || null) : null;
 
             if (isEmpty) { 
@@ -119,6 +119,9 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
             const resultKeys = Object.keys(result || {});
             const isMultiDate = resultKeys.length > 0 && resultKeys.every(k => /^\d{4}-\d{2}-\d{2}$/.test(k));
 
+            // [NEW] Check metadata for alert flag (defaults to false)
+            const isAlertComputation = calc.manifest.isAlertComputation === true;
+
             if (isMultiDate) {
                 const datePromises  = resultKeys.map((historicalDate) => fanOutLimit(async () => {
                     const dailyData = result[historicalDate];
@@ -127,6 +130,15 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                     const stats = await writeSingleResult(dailyData, historicalDocRef, name, historicalDate, logger, config, deps, 0, 'STANDARD', false);
                     runMetrics.io.writes += stats.opCounts.writes;
                     runMetrics.io.deletes += stats.opCounts.deletes;
+
+                    // [NEW] Queue alert for historical date if applicable
+                    if (isAlertComputation && flushMode !== 'INTERMEDIATE') {
+                        alertTriggers.push({
+                            date: historicalDate,
+                            computationName: name,
+                            documentPath: historicalDocRef.path
+                        });
+                    }
                 }));
                 await Promise.all(datePromises);
                 
@@ -143,11 +155,19 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
                 
                 nextShardIndexes[name] = writeStats.nextShardIndex;
                 if (calc.manifest.hash) { successUpdates[name] = { hash: calc.manifest.hash, simHash, resultHash, dependencyResultHashes: calc.manifest.dependencyResultHashes || {}, category: calc.manifest.category, composition: calc.manifest.composition, metrics: runMetrics }; }
+
+                // [NEW] Queue alert for standard write
+                if (isAlertComputation && flushMode !== 'INTERMEDIATE') {
+                    alertTriggers.push({
+                        date: dStr,
+                        computationName: name,
+                        documentPath: mainDocRef.path
+                    });
+                }
             }
 
             if (calc.manifest.class.getSchema && flushMode !== 'INTERMEDIATE') {
                 const { class: _cls, ...safeMetadata } = calc.manifest;
-                // Remove undefined values to prevent Firestore errors
                 const cleanedMetadata = {};
                 for (const [key, value] of Object.entries(safeMetadata)) {
                     if (value !== undefined) {
@@ -172,6 +192,18 @@ async function commitResults(stateObj, dStr, passName, config, deps, skipStatusW
     if (!skipStatusWrite && Object.keys(successUpdates).length > 0 && flushMode !== 'INTERMEDIATE') { 
         await updateComputationStatus(dStr, successUpdates, config, deps); 
     }
+
+    // [NEW] Flush Alert Triggers to Pub/Sub
+    if (alertTriggers.length > 0) {
+        const topicName = config.alertTopicName || 'alert-trigger';
+        try {
+            await pubSubUtils.publishMessageBatch(topicName, alertTriggers);
+            logger.log('INFO', `[Alert System] Triggered ${alertTriggers.length} alerts to ${topicName}`);
+        } catch (alertErr) {
+            logger.log('ERROR', `[Alert System] Failed to publish alerts: ${alertErr.message}`);
+            // Non-blocking: We don't fail the computation if alerts fail to publish, but we log strictly.
+        }
+    }
     
     return { successUpdates, failureReport, shardIndexes: nextShardIndexes };
 }
@@ -207,8 +239,6 @@ async function writeSingleResult(result, docRef, name, dateContext, logger, conf
     if (isInitialWrite) {
         try {
             const currentSnap = await docRef.get();
-            // Note: Reads tracked implicitly by calling code or approximated here if needed.
-            // We focus on writes/deletes here.
             if (currentSnap.exists) {
                 const d = currentSnap.data();
                 wasSharded = (d._sharded === true);

package/functions/generic-api/user-api/helpers/alert_helpers.js

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview Alert Management API Helpers
+ * Handles fetching and managing user alerts
+ */
+
+const { FieldValue } = require('@google-cloud/firestore');
+const { getAllAlertTypes, getAlertType } = require('../../../alert-system/helpers/alert_type_registry');
+
+/**
+ * GET /user/me/alert-types
+ * Get all available alert types
+ */
+async function getAlertTypes(req, res, dependencies, config) {
+  try {
+    const alertTypes = getAllAlertTypes();
+    
+    return res.status(200).json({
+      success: true,
+      alertTypes: alertTypes.map(type => ({
+        id: type.id,
+        name: type.name,
+        description: type.description,
+        severity: type.severity
+      }))
+    });
+  } catch (error) {
+    const { logger } = dependencies;
+    logger.log('ERROR', '[getAlertTypes] Error fetching alert types', error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * GET /user/me/alerts
+ * Get user's alerts (paginated)
+ */
+async function getUserAlerts(req, res, dependencies, config) {
+  const { db, logger } = dependencies;
+  const { userCid } = req.query;
+  const { unreadOnly, limit = 50, offset = 0, alertType } = req.query;
+  
+  if (!userCid) {
+    return res.status(400).json({ error: "Missing userCid" });
+  }
+  
+  try {
+    const alertsRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('alerts');
+    
+    let query = alertsRef.orderBy('createdAt', 'desc');
+    
+    // Filter by read status
+    if (unreadOnly === 'true') {
+      query = query.where('read', '==', false);
+    }
+    
+    // Filter by alert type
+    if (alertType) {
+      query = query.where('alertType', '==', alertType);
+    }
+    
+    // Apply pagination
+    query = query.limit(Number(limit)).offset(Number(offset));
+    
+    const snapshot = await query.get();
+    const alerts = [];
+    
+    snapshot.forEach(doc => {
+      const data = doc.data();
+      alerts.push({
+        id: doc.id,
+        ...data,
+        createdAt: data.createdAt?.toDate?.() || data.createdAt,
+        readAt: data.readAt?.toDate?.() || data.readAt
+      });
+    });
+    
+    return res.status(200).json({
+      success: true,
+      alerts: alerts,
+      count: alerts.length,
+      limit: Number(limit),
+      offset: Number(offset)
+    });
+  } catch (error) {
+    logger.log('ERROR', `[getUserAlerts] Error fetching alerts for user ${userCid}`, error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * GET /user/me/alerts/count
+ * Get unread alert count
+ */
+async function getAlertCount(req, res, dependencies, config) {
+  const { db, logger } = dependencies;
+  const { userCid } = req.query;
+  
+  if (!userCid) {
+    return res.status(400).json({ error: "Missing userCid" });
+  }
+  
+  try {
+    // Get today's counter
+    const today = new Date().toISOString().split('T')[0];
+    const counterRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('counters')
+      .doc(today);
+    
+    const counterDoc = await counterRef.get();
+    
+    if (counterDoc.exists) {
+      const data = counterDoc.data();
+      return res.status(200).json({
+        success: true,
+        unreadCount: data.unreadCount || 0,
+        totalCount: data.totalCount || 0,
+        byType: data.byType || {}
+      });
+    }
+    
+    // If no counter exists, count unread alerts directly
+    const unreadSnapshot = await db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('alerts')
+      .where('read', '==', false)
+      .get();
+    
+    return res.status(200).json({
+      success: true,
+      unreadCount: unreadSnapshot.size,
+      totalCount: unreadSnapshot.size,
+      byType: {}
+    });
+  } catch (error) {
+    logger.log('ERROR', `[getAlertCount] Error fetching alert count for user ${userCid}`, error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * PUT /user/me/alerts/:alertId/read
+ * Mark alert as read
+ */
+async function markAlertRead(req, res, dependencies, config) {
+  const { db, logger } = dependencies;
+  const { userCid } = req.query;
+  const { alertId } = req.params;
+  
+  if (!userCid || !alertId) {
+    return res.status(400).json({ error: "Missing userCid or alertId" });
+  }
+  
+  try {
+    const alertRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('alerts')
+      .doc(alertId);
+    
+    const alertDoc = await alertRef.get();
+    
+    if (!alertDoc.exists) {
+      return res.status(404).json({ error: "Alert not found" });
+    }
+    
+    const alertData = alertDoc.data();
+    
+    // Only update if not already read
+    if (!alertData.read) {
+      await alertRef.update({
+        read: true,
+        readAt: FieldValue.serverTimestamp()
+      });
+      
+      // Update counter
+      const today = new Date().toISOString().split('T')[0];
+      const counterRef = db.collection('user_alerts')
+        .doc(String(userCid))
+        .collection('counters')
+        .doc(today);
+      
+      await counterRef.set({
+        unreadCount: FieldValue.increment(-1),
+        lastUpdated: FieldValue.serverTimestamp()
+      }, { merge: true });
+    }
+    
+    return res.status(200).json({
+      success: true,
+      message: "Alert marked as read"
+    });
+  } catch (error) {
+    logger.log('ERROR', `[markAlertRead] Error marking alert ${alertId} as read`, error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * PUT /user/me/alerts/read-all
+ * Mark all alerts as read
+ */
+async function markAllAlertsRead(req, res, dependencies, config) {
+  const { db, logger } = dependencies;
+  const { userCid } = req.query;
+  
+  if (!userCid) {
+    return res.status(400).json({ error: "Missing userCid" });
+  }
+  
+  try {
+    const alertsRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('alerts');
+    
+    const unreadSnapshot = await alertsRef
+      .where('read', '==', false)
+      .get();
+    
+    if (unreadSnapshot.empty) {
+      return res.status(200).json({
+        success: true,
+        message: "No unread alerts",
+        updated: 0
+      });
+    }
+    
+    const batch = db.batch();
+    let count = 0;
+    
+    unreadSnapshot.forEach(doc => {
+      batch.update(doc.ref, {
+        read: true,
+        readAt: FieldValue.serverTimestamp()
+      });
+      count++;
+    });
+    
+    await batch.commit();
+    
+    // Reset counter
+    const today = new Date().toISOString().split('T')[0];
+    const counterRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('counters')
+      .doc(today);
+    
+    await counterRef.set({
+      unreadCount: 0,
+      lastUpdated: FieldValue.serverTimestamp()
+    }, { merge: true });
+    
+    return res.status(200).json({
+      success: true,
+      message: "All alerts marked as read",
+      updated: count
+    });
+  } catch (error) {
+    logger.log('ERROR', `[markAllAlertsRead] Error marking all alerts as read for user ${userCid}`, error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+/**
+ * DELETE /user/me/alerts/:alertId
+ * Delete specific alert
+ */
+async function deleteAlert(req, res, dependencies, config) {
+  const { db, logger } = dependencies;
+  const { userCid } = req.query;
+  const { alertId } = req.params;
+  
+  if (!userCid || !alertId) {
+    return res.status(400).json({ error: "Missing userCid or alertId" });
+  }
+  
+  try {
+    const alertRef = db.collection('user_alerts')
+      .doc(String(userCid))
+      .collection('alerts')
+      .doc(alertId);
+    
+    const alertDoc = await alertRef.get();
+    
+    if (!alertDoc.exists) {
+      return res.status(404).json({ error: "Alert not found" });
+    }
+    
+    await alertRef.delete();
+    
+    // Update counter if alert was unread
+    const alertData = alertDoc.data();
+    if (!alertData.read) {
+      const today = new Date().toISOString().split('T')[0];
+      const counterRef = db.collection('user_alerts')
+        .doc(String(userCid))
+        .collection('counters')
+        .doc(today);
+      
+      await counterRef.set({
+        unreadCount: FieldValue.increment(-1),
+        totalCount: FieldValue.increment(-1),
+        lastUpdated: FieldValue.serverTimestamp()
+      }, { merge: true });
+    }
+    
+    return res.status(200).json({
+      success: true,
+      message: "Alert deleted"
+    });
+  } catch (error) {
+    logger.log('ERROR', `[deleteAlert] Error deleting alert ${alertId}`, error);
+    return res.status(500).json({ error: error.message });
+  }
+}
+
+module.exports = {
+  getAlertTypes,
+  getUserAlerts,
+  getAlertCount,
+  markAlertRead,
+  markAllAlertsRead,
+  deleteAlert
+};
+

package/functions/generic-api/user-api/index.js

@@ -9,6 +9,7 @@ const { initiateVerification, finalizeVerification } = require('./helpers/verifi
 const { getUserWatchlists, getWatchlist: getWatchlistById, createWatchlist, updateWatchlist: updateWatchlistById, deleteWatchlist, copyWatchlist, getPublicWatchlists } = require('./helpers/watchlist_helpers');
 const { subscribeToAlerts, updateSubscription, unsubscribeFromAlerts, getUserSubscriptions, subscribeToWatchlist } = require('./helpers/subscription_helpers');
 const { setDevOverride, getDevOverrideStatus } = require('./helpers/dev_helpers');
+const { getAlertTypes, getUserAlerts, getAlertCount, markAlertRead, markAllAlertsRead, deleteAlert } = require('./helpers/alert_helpers');
 
 module.exports = (dependencies, config) => {
     const router = express.Router();
@@ -75,5 +76,13 @@ module.exports = (dependencies, config) => {
     router.post('/dev/override', (req, res) => setDevOverride(req, res, dependencies, config));
     router.get('/dev/override', (req, res) => getDevOverrideStatus(req, res, dependencies, config));
     
+    // --- Alert Management ---
+    router.get('/me/alert-types', (req, res) => getAlertTypes(req, res, dependencies, config));
+    router.get('/me/alerts', (req, res) => getUserAlerts(req, res, dependencies, config));
+    router.get('/me/alerts/count', (req, res) => getAlertCount(req, res, dependencies, config));
+    router.put('/me/alerts/:alertId/read', (req, res) => markAlertRead(req, res, dependencies, config));
+    router.put('/me/alerts/read-all', (req, res) => markAllAlertsRead(req, res, dependencies, config));
+    router.delete('/me/alerts/:alertId', (req, res) => deleteAlert(req, res, dependencies, config));
+    
     return router;
 };

package/index.js

@@ -56,6 +56,9 @@ const { runRootDataIndexer }                              = require('./functions
 // [NEW] Popular Investor Fetcher
 const { runPopularInvestorFetch }                         = require('./functions/fetch-popular-investors/index');
 
+// Alert System
+const { handleAlertTrigger, handleComputationResultWrite } = require('./functions/alert-system/index');
+
 // Proxy
 const { handlePost }                                      = require('./functions/appscript-api/index');
 
@@ -122,6 +125,11 @@ const maintenance = {
 
 const proxy = { handlePost };
 
+const alertSystem = {
+  handleAlertTrigger,
+  handleComputationResultWrite
+};
+
 module.exports = {
-  pipe: { core, orchestrator, dispatcher, taskEngine, computationSystem, api, maintenance, proxy },
+  pipe: { core, orchestrator, dispatcher, taskEngine, computationSystem, api, maintenance, proxy, alertSystem },
 };

package/package.json

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