bulltrackers-module 1.0.725 → 1.0.726

package/functions/alert-system/helpers/alert_helpers.js

@@ -1,6 +1,9 @@
 /**
  * @fileoverview Alert Generation Helpers
  * Handles creating alerts from computation results
+ * 
+ * UPDATED: Now sends FCM push notifications in addition to Firestore writes.
+ * This enables background notifications even when the user is offline.
  */
 
 const { FieldValue } = require('@google-cloud/firestore');
@@ -8,7 +11,7 @@ const zlib = require('zlib');
 const { Storage } = require('@google-cloud/storage');
 const { generateAlertMessage } = require('./alert_manifest_loader');
 const { evaluateDynamicConditions } = require('./dynamic_evaluator');
-// [UPDATED] Now uses dynamic manifest loading and condition evaluation
+const { sendAlertPushNotification } = require('../../core/utils/fcm_utils');
 
 const storage = new Storage(); // Singleton GCS Client
 
@@ -174,20 +177,34 @@ async function processAlertForPI(db, logger, piCid, alertType, computationMetada
         ...(computationMetadata || {})
       };
       
-      const writePromise = db.collection('SignedInUsers')
-        .doc(String(userCid))
-        .collection('alerts')
-        .doc(notificationId)
-        .set(alertData)
-        .catch(err => {
+      // Combined promise: write to Firestore AND send FCM push notification
+      const writeAndPushPromise = (async () => {
+        // 1. Write to Firestore first (this is the source of truth)
+        await db.collection('SignedInUsers')
+          .doc(String(userCid))
+          .collection('alerts')
+          .doc(notificationId)
+          .set(alertData);
+        
+        // 2. Send FCM push notification (non-blocking, don't fail if push fails)
+        // This enables notifications even when user is offline
+        try {
+          await sendAlertPushNotification(db, userCid, alertData, logger);
+        } catch (fcmError) {
+          // Log but don't throw - FCM failure shouldn't fail the alert
+          logger.log('WARN', `[processAlertForPI] FCM push failed for CID ${userCid}: ${fcmError.message}`);
+        }
+        
+        return { userCid, success: true };
+      })().catch(err => {
         logger.log('ERROR', `[processAlertForPI] Failed to write alert for CID ${userCid}: ${err.message}`, err);
         throw err; // Re-throw so we know if writes are failing
       });
       
-      notificationPromises.push(writePromise);
+      notificationPromises.push(writeAndPushPromise);
     }
     
-    // Wait for all notifications to be written
+    // Wait for all notifications to be written and push notifications sent
     await Promise.all(notificationPromises);
     
     // 5. Notify the PI themselves if they are a signed-in user (Optional feature)

package/functions/alert-system/index.js

@@ -2,10 +2,12 @@
  * @fileoverview Alert System Trigger Handler
  * Can be triggered via Pub/Sub when computation results are written
  * [UPDATED] Now uses dynamic manifest loading instead of hardcoded registry
+ * [UPDATED] Now sends FCM push notifications for all alert types
  */
 
 const { loadAlertTypesFromManifest, getAlertTypeByComputation, isAlertComputation } = require('./helpers/alert_manifest_loader');
 const { processAlertForPI, readComputationResults, readComputationResultsWithShards } = require('./helpers/alert_helpers');
+const { sendAlertPushNotification } = require('../core/utils/fcm_utils');
 
 // Cache for loaded alert types (loaded once per function instance)
 let cachedAlertTypes = null;
@@ -463,12 +465,21 @@ async function sendAllClearNotification(db, logger, userCid, piCid, piUsername,
       computationDate: date
     };
     
+    // 1. Write to Firestore (source of truth)
     await db.collection('SignedInUsers')
       .doc(String(userCid))
       .collection('alerts')
       .doc(notificationId)
       .set(alertData);
     
+    // 2. Send FCM push notification (non-blocking)
+    try {
+      await sendAlertPushNotification(db, userCid, alertData, logger);
+    } catch (fcmError) {
+      // Log but don't throw - FCM failure shouldn't fail the alert
+      logger.log('WARN', `[sendAllClearNotification] FCM push failed for user ${userCid}: ${fcmError.message}`);
+    }
+    
     logger.log('INFO', `[sendAllClearNotification] Sent all-clear notification to user ${userCid} for PI ${piCid}`);
     
   } catch (error) {

package/functions/api-v2/routes/fcm.js

@@ -0,0 +1,261 @@
+/**
+ * @fileoverview FCM (Firebase Cloud Messaging) Token Management Routes
+ * 
+ * Handles registration and unregistration of FCM tokens for push notifications.
+ * Tokens are associated with user CIDs and stored in Firestore.
+ * 
+ * Storage: SignedInUsers/{cid}/fcm_tokens/{tokenId}
+ */
+
+const express = require('express');
+const { z } = require('zod');
+const { 
+    registerFCMToken, 
+    unregisterFCMToken, 
+    getUserFCMTokens,
+    touchToken 
+} = require('../../core/utils/fcm_utils');
+
+const router = express.Router();
+
+// Input validation schemas
+const registerTokenSchema = z.object({
+    token: z.string().min(100).max(500), // FCM tokens are typically 150-180 chars
+    platform: z.enum(['web', 'ios', 'android']).optional().default('web'),
+    userAgent: z.string().max(500).optional()
+});
+
+const unregisterTokenSchema = z.object({
+    token: z.string().min(100).max(500)
+});
+
+/**
+ * POST /fcm/register-token
+ * 
+ * Register an FCM token for the authenticated user.
+ * Called by the frontend after login when the user grants notification permissions.
+ * 
+ * Body:
+ *   - token: string (required) - The FCM token from getToken()
+ *   - platform: string (optional) - 'web', 'ios', or 'android' (default: 'web')
+ *   - userAgent: string (optional) - Browser/device user agent
+ * 
+ * Returns:
+ *   - success: boolean
+ *   - tokenId: string (hashed token ID)
+ */
+router.post('/register-token', async (req, res, next) => {
+    try {
+        // Validate input
+        const validated = registerTokenSchema.parse(req.body);
+        
+        // Get user CID from authenticated request
+        const userCid = req.targetUserId;
+        if (!userCid) {
+            return res.status(401).json({ 
+                success: false, 
+                error: 'Authentication required',
+                message: 'You must be logged in to register for push notifications'
+            });
+        }
+        
+        const { db, logger } = req.dependencies;
+        
+        // Register the token
+        const result = await registerFCMToken(
+            db, 
+            userCid, 
+            validated.token, 
+            {
+                platform: validated.platform,
+                userAgent: validated.userAgent || req.headers['user-agent']
+            },
+            logger
+        );
+        
+        logger.log('INFO', `[FCM API] Token registered for user ${userCid}`);
+        
+        res.json({ 
+            success: true, 
+            tokenId: result.tokenId,
+            message: 'Push notifications enabled'
+        });
+        
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            return res.status(400).json({ 
+                success: false,
+                error: 'Invalid input', 
+                details: error.errors 
+            });
+        }
+        next(error);
+    }
+});
+
+/**
+ * POST /fcm/unregister-token
+ * 
+ * Unregister an FCM token (e.g., on logout or when user disables notifications).
+ * 
+ * Body:
+ *   - token: string (required) - The FCM token to unregister
+ * 
+ * Returns:
+ *   - success: boolean
+ */
+router.post('/unregister-token', async (req, res, next) => {
+    try {
+        // Validate input
+        const validated = unregisterTokenSchema.parse(req.body);
+        
+        // Get user CID from authenticated request
+        const userCid = req.targetUserId;
+        if (!userCid) {
+            return res.status(401).json({ 
+                success: false, 
+                error: 'Authentication required' 
+            });
+        }
+        
+        const { db, logger } = req.dependencies;
+        
+        // Unregister the token
+        const result = await unregisterFCMToken(db, userCid, validated.token, logger);
+        
+        logger.log('INFO', `[FCM API] Token unregistered for user ${userCid}`);
+        
+        res.json({ 
+            success: true,
+            message: 'Push notifications disabled for this device'
+        });
+        
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            return res.status(400).json({ 
+                success: false,
+                error: 'Invalid input', 
+                details: error.errors 
+            });
+        }
+        next(error);
+    }
+});
+
+/**
+ * GET /fcm/tokens
+ * 
+ * Get the list of registered FCM tokens for the current user.
+ * Useful for debugging and showing which devices have notifications enabled.
+ * 
+ * Returns:
+ *   - success: boolean
+ *   - count: number
+ *   - tokens: Array<{tokenId, platform, createdAt}>
+ */
+router.get('/tokens', async (req, res, next) => {
+    try {
+        // Get user CID from authenticated request
+        const userCid = req.targetUserId;
+        if (!userCid) {
+            return res.status(401).json({ 
+                success: false, 
+                error: 'Authentication required' 
+            });
+        }
+        
+        const { db, logger } = req.dependencies;
+        
+        // Get tokens (without exposing the actual token values)
+        const tokens = await getUserFCMTokens(db, userCid, logger);
+        
+        // Return sanitized token info (don't expose actual tokens)
+        const sanitizedTokens = tokens.map(t => ({
+            tokenId: t.tokenId,
+            platform: t.platform
+        }));
+        
+        res.json({ 
+            success: true,
+            count: sanitizedTokens.length,
+            tokens: sanitizedTokens
+        });
+        
+    } catch (error) {
+        next(error);
+    }
+});
+
+/**
+ * POST /fcm/refresh-token
+ * 
+ * Called when an FCM token is refreshed by the client.
+ * Updates the lastUsedAt timestamp and optionally replaces old token with new one.
+ * 
+ * Body:
+ *   - oldToken: string (optional) - Previous token to replace
+ *   - newToken: string (required) - New FCM token
+ *   - platform: string (optional) - Platform identifier
+ * 
+ * Returns:
+ *   - success: boolean
+ *   - tokenId: string
+ */
+router.post('/refresh-token', async (req, res, next) => {
+    try {
+        const refreshSchema = z.object({
+            oldToken: z.string().min(100).max(500).optional(),
+            newToken: z.string().min(100).max(500),
+            platform: z.enum(['web', 'ios', 'android']).optional().default('web')
+        });
+        
+        const validated = refreshSchema.parse(req.body);
+        
+        const userCid = req.targetUserId;
+        if (!userCid) {
+            return res.status(401).json({ 
+                success: false, 
+                error: 'Authentication required' 
+            });
+        }
+        
+        const { db, logger } = req.dependencies;
+        
+        // If old token provided, unregister it first
+        if (validated.oldToken) {
+            await unregisterFCMToken(db, userCid, validated.oldToken, logger);
+        }
+        
+        // Register the new token
+        const result = await registerFCMToken(
+            db, 
+            userCid, 
+            validated.newToken, 
+            {
+                platform: validated.platform,
+                userAgent: req.headers['user-agent']
+            },
+            logger
+        );
+        
+        logger.log('INFO', `[FCM API] Token refreshed for user ${userCid}`);
+        
+        res.json({ 
+            success: true, 
+            tokenId: result.tokenId,
+            message: 'Token refreshed successfully'
+        });
+        
+    } catch (error) {
+        if (error instanceof z.ZodError) {
+            return res.status(400).json({ 
+                success: false,
+                error: 'Invalid input', 
+                details: error.errors 
+            });
+        }
+        next(error);
+    }
+});
+
+module.exports = router;

package/functions/api-v2/routes/index.js

@@ -4,7 +4,8 @@ const { verifyFirebaseToken } = require('../middleware/firebase_auth_middleware.
 const { handleSyncRequest } = require('./sync.js');
 
 const notificationRoutes = require('./notifications.js');
-const alertsRoutes = require('./alerts.js'); // <--- NEW
+const alertsRoutes = require('./alerts.js');
+const fcmRoutes = require('./fcm.js'); // FCM push notification token management
 const verificationRoutes = require('./verification.js');
 const profileRoutes = require('./profile.js');
 const piRoutes = require('./popular_investors.js');
@@ -29,7 +30,8 @@ module.exports = (dependencies) => {
     router.use(resolveUserIdentity);
 
     router.use('/notifications', notificationRoutes);
-    router.use('/alerts', alertsRoutes); // <--- NEW
+    router.use('/alerts', alertsRoutes);
+    router.use('/fcm', fcmRoutes); // FCM push notification token management
     router.use('/verification', verificationRoutes);
     router.use('/profile', profileRoutes);
     router.use('/popular-investors', piRoutes);

package/functions/core/utils/fcm_utils.js

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview Firebase Cloud Messaging (FCM) Utilities
+ * 
+ * Provides push notification functionality via FCM.
+ * Works in background even when user is offline.
+ * Supports web push notifications and future mobile app integration.
+ * 
+ * Token Storage: SignedInUsers/{cid}/fcm_tokens/{tokenId}
+ */
+
+const admin = require('firebase-admin');
+
+// FCM Token collection path
+const FCM_TOKENS_SUBCOLLECTION = 'fcm_tokens';
+
+/**
+ * Register an FCM token for a user
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {string} token - FCM token from client
+ * @param {object} metadata - Additional metadata (platform, userAgent, etc.)
+ * @param {object} logger - Logger instance
+ * @returns {Promise<{success: boolean, tokenId: string}>}
+ */
+async function registerFCMToken(db, userCid, token, metadata = {}, logger = console) {
+    if (!token || typeof token !== 'string') {
+        throw new Error('Invalid FCM token');
+    }
+    
+    const cid = String(userCid);
+    
+    // Use a hash of the token as the document ID to prevent duplicates
+    const tokenId = hashToken(token);
+    
+    const tokenDoc = {
+        token: token,
+        platform: metadata.platform || 'web',
+        userAgent: metadata.userAgent || null,
+        createdAt: admin.firestore.FieldValue.serverTimestamp(),
+        lastUsedAt: admin.firestore.FieldValue.serverTimestamp(),
+        active: true
+    };
+    
+    try {
+        await db.collection('SignedInUsers')
+            .doc(cid)
+            .collection(FCM_TOKENS_SUBCOLLECTION)
+            .doc(tokenId)
+            .set(tokenDoc, { merge: true });
+        
+        logger.log('INFO', `[FCM] Registered token for user ${cid} (tokenId: ${tokenId.substring(0, 8)}...)`);
+        
+        return { success: true, tokenId };
+    } catch (error) {
+        logger.log('ERROR', `[FCM] Failed to register token for user ${cid}: ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+ * Unregister an FCM token (e.g., on logout)
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {string} token - FCM token to remove
+ * @param {object} logger - Logger instance
+ * @returns {Promise<{success: boolean}>}
+ */
+async function unregisterFCMToken(db, userCid, token, logger = console) {
+    const cid = String(userCid);
+    const tokenId = hashToken(token);
+    
+    try {
+        await db.collection('SignedInUsers')
+            .doc(cid)
+            .collection(FCM_TOKENS_SUBCOLLECTION)
+            .doc(tokenId)
+            .delete();
+        
+        logger.log('INFO', `[FCM] Unregistered token for user ${cid}`);
+        
+        return { success: true };
+    } catch (error) {
+        logger.log('WARN', `[FCM] Failed to unregister token for user ${cid}: ${error.message}`);
+        // Don't throw - token removal failure is non-critical
+        return { success: false, error: error.message };
+    }
+}
+
+/**
+ * Get all active FCM tokens for a user
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {object} logger - Logger instance
+ * @returns {Promise<string[]>} Array of FCM tokens
+ */
+async function getUserFCMTokens(db, userCid, logger = console) {
+    const cid = String(userCid);
+    
+    try {
+        const snapshot = await db.collection('SignedInUsers')
+            .doc(cid)
+            .collection(FCM_TOKENS_SUBCOLLECTION)
+            .where('active', '==', true)
+            .get();
+        
+        if (snapshot.empty) {
+            return [];
+        }
+        
+        return snapshot.docs.map(doc => ({
+            tokenId: doc.id,
+            token: doc.data().token,
+            platform: doc.data().platform
+        }));
+    } catch (error) {
+        logger.log('WARN', `[FCM] Failed to get tokens for user ${cid}: ${error.message}`);
+        return [];
+    }
+}
+
+/**
+ * Send a push notification to a specific user
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {object} notification - Notification payload
+ * @param {string} notification.title - Notification title
+ * @param {string} notification.body - Notification body
+ * @param {string} [notification.icon] - Notification icon URL
+ * @param {string} [notification.clickAction] - URL to open on click
+ * @param {object} [data] - Additional data payload
+ * @param {object} logger - Logger instance
+ * @returns {Promise<{success: boolean, sent: number, failed: number}>}
+ */
+async function sendPushNotification(db, userCid, notification, data = {}, logger = console) {
+    const cid = String(userCid);
+    
+    // Get user's FCM tokens
+    const tokenData = await getUserFCMTokens(db, cid, logger);
+    
+    if (tokenData.length === 0) {
+        logger.log('DEBUG', `[FCM] No FCM tokens registered for user ${cid}, skipping push`);
+        return { success: true, sent: 0, failed: 0, reason: 'no_tokens' };
+    }
+    
+    const tokens = tokenData.map(t => t.token);
+    
+    // Build FCM message
+    const message = {
+        notification: {
+            title: notification.title,
+            body: notification.body,
+            ...(notification.icon && { imageUrl: notification.icon })
+        },
+        data: {
+            ...data,
+            clickAction: notification.clickAction || '/',
+            timestamp: new Date().toISOString()
+        },
+        webpush: {
+            notification: {
+                icon: notification.icon || '/icons/notification-icon.png',
+                badge: '/icons/badge-icon.png',
+                requireInteraction: notification.requireInteraction || false
+            },
+            fcmOptions: {
+                link: notification.clickAction || '/'
+            }
+        },
+        tokens: tokens
+    };
+    
+    try {
+        const response = await admin.messaging().sendEachForMulticast(message);
+        
+        let sent = response.successCount;
+        let failed = response.failureCount;
+        
+        // Handle stale tokens
+        if (response.failureCount > 0) {
+            const staleTokens = [];
+            
+            response.responses.forEach((resp, idx) => {
+                if (!resp.success) {
+                    const errorCode = resp.error?.code;
+                    
+                    // These error codes indicate the token is no longer valid
+                    if (errorCode === 'messaging/invalid-registration-token' ||
+                        errorCode === 'messaging/registration-token-not-registered') {
+                        staleTokens.push(tokenData[idx]);
+                    } else {
+                        logger.log('WARN', `[FCM] Send failed for user ${cid}: ${resp.error?.message}`);
+                    }
+                }
+            });
+            
+            // Clean up stale tokens (async, don't wait)
+            if (staleTokens.length > 0) {
+                cleanupStaleTokens(db, cid, staleTokens, logger).catch(() => {});
+            }
+        }
+        
+        logger.log('INFO', `[FCM] Sent push to user ${cid}: ${sent} sent, ${failed} failed`);
+        
+        return { success: true, sent, failed };
+    } catch (error) {
+        logger.log('ERROR', `[FCM] Failed to send push to user ${cid}: ${error.message}`);
+        return { success: false, sent: 0, failed: tokens.length, error: error.message };
+    }
+}
+
+/**
+ * Send a push notification to multiple users
+ * @param {Firestore} db - Firestore instance
+ * @param {Array<string|number>} userCids - Array of user CIDs
+ * @param {object} notification - Notification payload
+ * @param {object} [data] - Additional data payload
+ * @param {object} logger - Logger instance
+ * @returns {Promise<{success: boolean, results: object}>}
+ */
+async function sendPushNotificationToMany(db, userCids, notification, data = {}, logger = console) {
+    const results = {
+        total: userCids.length,
+        sent: 0,
+        failed: 0,
+        noTokens: 0
+    };
+    
+    // Process in batches to avoid overwhelming FCM
+    const BATCH_SIZE = 50;
+    
+    for (let i = 0; i < userCids.length; i += BATCH_SIZE) {
+        const batch = userCids.slice(i, i + BATCH_SIZE);
+        
+        const promises = batch.map(async (cid) => {
+            const result = await sendPushNotification(db, cid, notification, data, logger);
+            return { cid, ...result };
+        });
+        
+        const batchResults = await Promise.all(promises);
+        
+        for (const result of batchResults) {
+            if (result.reason === 'no_tokens') {
+                results.noTokens++;
+            } else {
+                results.sent += result.sent;
+                results.failed += result.failed;
+            }
+        }
+    }
+    
+    logger.log('INFO', `[FCM] Batch send complete: ${results.sent} sent, ${results.failed} failed, ${results.noTokens} users without tokens`);
+    
+    return { success: true, results };
+}
+
+/**
+ * Send an alert notification (convenience wrapper for alert system)
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {object} alertData - Alert data from alert system
+ * @param {object} logger - Logger instance
+ * @returns {Promise<{success: boolean}>}
+ */
+async function sendAlertPushNotification(db, userCid, alertData, logger = console) {
+    const notification = {
+        title: alertData.alertTypeName || 'BullTrackers Alert',
+        body: alertData.message || `New alert for ${alertData.piUsername}`,
+        icon: '/icons/alert-icon.png',
+        clickAction: `/alerts/${alertData.alertId}`,
+        requireInteraction: alertData.severity === 'high'
+    };
+    
+    const data = {
+        type: 'alert',
+        alertId: alertData.alertId || '',
+        alertType: alertData.alertType || '',
+        piCid: String(alertData.piCid || ''),
+        piUsername: alertData.piUsername || '',
+        severity: alertData.severity || 'medium',
+        watchlistId: alertData.watchlistId || ''
+    };
+    
+    return sendPushNotification(db, userCid, notification, data, logger);
+}
+
+/**
+ * Clean up stale/invalid FCM tokens
+ * @param {Firestore} db - Firestore instance
+ * @param {string} userCid - User CID
+ * @param {Array} staleTokens - Array of {tokenId, token} objects
+ * @param {object} logger - Logger instance
+ */
+async function cleanupStaleTokens(db, userCid, staleTokens, logger = console) {
+    const batch = db.batch();
+    
+    for (const tokenData of staleTokens) {
+        const tokenRef = db.collection('SignedInUsers')
+            .doc(userCid)
+            .collection(FCM_TOKENS_SUBCOLLECTION)
+            .doc(tokenData.tokenId);
+        
+        batch.delete(tokenRef);
+    }
+    
+    try {
+        await batch.commit();
+        logger.log('INFO', `[FCM] Cleaned up ${staleTokens.length} stale tokens for user ${userCid}`);
+    } catch (error) {
+        logger.log('WARN', `[FCM] Failed to cleanup stale tokens: ${error.message}`);
+    }
+}
+
+/**
+ * Update last used timestamp for a token
+ * @param {Firestore} db - Firestore instance
+ * @param {string|number} userCid - User CID
+ * @param {string} token - FCM token
+ */
+async function touchToken(db, userCid, token) {
+    const cid = String(userCid);
+    const tokenId = hashToken(token);
+    
+    await db.collection('SignedInUsers')
+        .doc(cid)
+        .collection(FCM_TOKENS_SUBCOLLECTION)
+        .doc(tokenId)
+        .update({
+            lastUsedAt: admin.firestore.FieldValue.serverTimestamp()
+        })
+        .catch(() => {}); // Ignore errors
+}
+
+/**
+ * Hash a token to create a stable document ID
+ * @param {string} token - FCM token
+ * @returns {string} Hashed token ID
+ */
+function hashToken(token) {
+    const crypto = require('crypto');
+    return crypto.createHash('sha256').update(token).digest('hex').substring(0, 32);
+}
+
+module.exports = {
+    registerFCMToken,
+    unregisterFCMToken,
+    getUserFCMTokens,
+    sendPushNotification,
+    sendPushNotificationToMany,
+    sendAlertPushNotification,
+    touchToken,
+    FCM_TOKENS_SUBCOLLECTION
+};

package/package.json

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