bulltrackers-module 1.0.591 → 1.0.593

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

@@ -7,7 +7,7 @@
 const crypto = require('crypto');
 const { shouldTryProxy, recordProxyOutcome, getFailureCount, getMaxFailures } = require('../utils/proxy_circuit_breaker');
 const { FieldValue } = require('@google-cloud/firestore');
-const { notifyTaskEngineComplete, notifyTaskEngineProgress, notifyPIDataRefreshed } = require('../../generic-api/user-api/helpers/notifications/notification_helpers');
+const { notifyTaskEngineComplete, notifyTaskEngineProgress, notifyPIDataRefreshed } = require('../../old-generic-api/user-api/helpers/notifications/notification_helpers');
 const { conditionallyRunRootDataIndexer } = require('./root_data_indexer_helpers');
 
 const { 
@@ -405,7 +405,7 @@ async function finalizeOnDemandRequest(deps, config, taskData, isPI, success, to
     // 2. Trigger Computations (only if root data indexer completed successfully)
     if (indexerCompleted && pubsub && config.computationSystem) {
         const { triggerComputationWithDependencies } = require('../../computation-system/helpers/on_demand_helpers');
-        const { checkIfUserIsPI } = require('../../generic-api/user-api/helpers/core/user_status_helpers');
+        const { checkIfUserIsPI } = require('../../old-generic-api/user-api/helpers/core/user_status_helpers');
         
         // Use userType from metadata if available, otherwise fall back to isPI
         const userType = metadata?.userType || (isPI ? 'POPULAR_INVESTOR' : 'SIGNED_IN_USER');

package/index.js

@@ -47,8 +47,11 @@ const dataLoader                                          = require('./functions
 const computationUtils                                    = require('./functions/computation-system/utils/utils');
 
 // API
-const { createApiApp }                                    = require('./functions/generic-api/index');
-const apiHelpers                                          = require('./functions/generic-api/helpers/api_helpers');
+const { createApiApp }                                    = require('./functions/old-generic-api/index');
+const apiHelpers                                          = require('./functions/old-generic-api/helpers/api_helpers');
+
+// API v2 (CommonJS)
+const { createApiV2App } = require('./functions/api-v2/index');
 
 // Maintenance & Data Acquisition
 const { runCleanup }                                      = require('./functions/speculator-cleanup-orchestrator/helpers/cleanup_helpers');
@@ -115,6 +118,7 @@ const computationSystem = {
 
 const api = {
   createApiApp,
+  createApiV2App, // New API v2 entry point
   helpers: apiHelpers,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.591",
+  "version": "1.0.593",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [
@@ -9,7 +9,8 @@
     "functions/task-engine/",
     "functions/core/",
     "functions/computation-system/",
-    "functions/generic-api/",
+    "functions/old-generic-api/",
+    "functions/api-v2/",
     "functions/dispatcher/",
     "functions/invalid-speculator-handler/",
     "functions/speculator-cleanup-orchestrator/",

package/functions/generic-api/user-api/ADDING_LEGACY_ROUTES_GUIDE.md

@@ -1,345 +0,0 @@
-# Adding New Legacy Routes for Auto-Migration
-
-## How Easy Is It?
-
-**Answer: Very Easy!** Adding a new legacy route requires updating **just 1 location** in most cases!
-
-**Even Easier:** The system now automatically reads legacy paths from the collection registry, so you typically only need to add one line to the registry!
-
----
-
-## Quick Overview
-
-The auto-migration system works by:
-1. **Trying new path first** - Reads from the new CID-based path
-2. **Falling back to legacy** - If not found, tries legacy path(s) from registry
-3. **Auto-migrating** - If found in legacy, automatically migrates to new path
-
-To add a new legacy route, you typically only need to:
-1. **`collection_registry.js`** - Add to `legacyPaths` array (that's it!)
-
-**Only if you need complex conditional logic:**
-2. **`path_resolution_helpers.js`** - Add to `legacyPathMap` object (fallback)
-
----
-
-## Step-by-Step Guide
-
-### ✅ EASIEST WAY: Just Add to Collection Registry (Recommended)
-
-**File:** `Backend/Entrypoints/BullTrackers/Backend/Core/config/collection_registry.js`
-
-**Location:** Find your collection definition and add to `legacyPaths` array
-
-**Example:**
-```javascript
-notifications: {
-    path: 'SignedInUsers/{cid}/notifications',
-    description: 'User notifications',
-    dynamicSegments: ['{cid}'],
-    status: 'active',
-    legacyPaths: [
-        'user_notifications/{firebaseUid}/notifications',  // Existing
-        'user_notifications/{userCid}/notifications',        // Existing
-        'old_notifications/{userId}/items'                   // NEW - Just add here!
-    ]
-}
-```
-
-**That's it!** The system automatically uses the first legacy path from the registry. No other changes needed!
-
-**How it works:**
-- `readWithMigration()` automatically passes `category` and `subcategory` to `getLegacyPath()`
-- `getLegacyPath()` first tries to get legacy paths from the registry
-- If found, it automatically resolves dynamic segments and returns the path
-- No need to update `path_resolution_helpers.js`!
-
----
-
-### Alternative: Add to Legacy Path Map (For Complex Logic)
-
-**Only needed if:** You need conditional logic or special handling that can't be expressed in a simple path template.
-
-**File:** `Backend/Entrypoints/BullTrackers/Backend/Core/bulltrackers-module/functions/generic-api/user-api/helpers/core/path_resolution_helpers.js`
-
-**Location:** Inside `getLegacyPath()` function, add to `legacyPathMap` object
-
-**Example:**
-```javascript
-function getLegacyPath(dataType, userCid, config = {}, params = {}) {
-    // ... registry lookup happens first ...
-    
-    // Fallback to hardcoded map (only if registry doesn't have it)
-    const legacyPathMap = {
-        // ... existing mappings ...
-        
-        // NEW - Add your new data type here (only if you need complex logic)
-        newDataType: params.someCondition 
-            ? `old_collection/${userId}/items/${params.someParam}`
-            : `old_collection/${userId}/items`
-    };
-    
-    return legacyPathMap[dataType] || null;
-}
-```
-
-**Note:** This is only needed for complex conditional logic. For simple paths, just use the registry!
-
----
-
-## Real-World Example
-
-Let's say you want to add support for a legacy "user preferences" collection:
-
-### Step 1: Update Collection Registry
-
-```javascript
-// In collection_registry.js
-signedInUsers: {
-    // ... other collections ...
-    
-    preferences: {
-        path: 'SignedInUsers/{cid}/preferences/data',
-        description: 'User preferences (single document)',
-        dynamicSegments: ['{cid}'],
-        status: 'active',
-        legacyPaths: [
-            'user_preferences/{userCid}',           // Add this
-            'old_prefs/{userId}/settings'           // And this if multiple legacy formats exist
-        ]
-    }
-}
-```
-
-### Step 2: (Optional) Update Path Resolution Helper
-
-**Only needed if:** You need conditional logic that can't be expressed in a simple path template.
-
-```javascript
-// In path_resolution_helpers.js
-// This is only needed for complex conditional logic
-// The registry lookup happens first, so this is just a fallback
-```
-
-### Step 3: Use It in Your API
-
-```javascript
-// In your API helper file
-const { readWithMigration } = require('./helpers/core/path_resolution_helpers');
-
-async function getUserPreferences(req, res, dependencies, config) {
-    const { db, logger } = dependencies;
-    const { userCid } = req.query;
-    
-    const result = await readWithMigration(
-        db,
-        'signedInUsers',      // category
-        'preferences',        // subcategory
-        { cid: userCid },     // params
-        {
-            isCollection: false,  // It's a document
-            dataType: 'preferences',  // This triggers legacy path lookup
-            config: config,
-            logger: logger
-        }
-    );
-    
-    if (!result) {
-        return res.status(404).json({ error: "Preferences not found" });
-    }
-    
-    // result.data contains the preferences
-    // result.source tells you if it came from 'new' or 'legacy'
-    // result.migrated tells you if it was auto-migrated
-    
-    return res.status(200).json({
-        preferences: result.data,
-        source: result.source,
-        migrated: result.migrated || false
-    });
-}
-```
-
-**That's it!** The auto-migration happens automatically.
-
----
-
-## Advanced: Multiple Legacy Formats
-
-If you have multiple legacy formats for the same data type:
-
-### Option 1: Try Multiple Legacy Paths (Recommended)
-
-Update `getLegacyPath()` to return an array or try multiple paths:
-
-```javascript
-function getLegacyPath(dataType, userCid, config = {}, params = {}) {
-    const cid = String(userCid);
-    
-    const legacyPathMap = {
-        // ... existing ...
-        
-        preferences: [
-            `user_preferences/${cid}`,           // Try first
-            `old_prefs/${cid}/settings`,        // Try second
-            `legacy_preferences/${cid}/data`     // Try third
-        ]
-    };
-    
-    const path = legacyPathMap[dataType];
-    return Array.isArray(path) ? path[0] : path;  // Return first for now
-}
-```
-
-Then update `readWithMigration()` to try all paths in the array (this would require a small code change).
-
-### Option 2: Use Conditional Logic
-
-```javascript
-const legacyPathMap = {
-    preferences: params.useOldFormat 
-        ? `old_prefs/${userId}/settings`
-        : `user_preferences/${cid}`
-};
-```
-
----
-
-## Dynamic Segment Resolution
-
-The system automatically resolves common dynamic segments:
-
-- `{cid}` → User CID
-- `{userCid}` → User CID
-- `{firebaseUid}` → Firebase UID (from params)
-- `{username}` → Username (from params)
-- `{date}` → Date (from params)
-- `{requestId}` → Request ID (from params or documentId)
-- `{piCid}` → PI CID (from params)
-- `{postId}` → Post ID (from params or documentId)
-- `{watchlistId}` → Watchlist ID (from params)
-- `{version}` → Version (from params)
-- `{viewId}` → View ID (from params or documentId)
-- `{reviewId}` → Review ID (from params or documentId)
-- `{timestamp}` → Timestamp (from params or auto-generated)
-
-**Just use these placeholders in your legacy path string!**
-
----
-
-## Testing Your New Legacy Route
-
-1. **Create test data in legacy path:**
-   ```javascript
-   await db.collection('user_preferences').doc('29312236').set({
-       theme: 'dark',
-       notifications: true
-   });
-   ```
-
-2. **Call your API:**
-   ```javascript
-   GET /user/me/preferences?userCid=29312236
-   ```
-
-3. **Check the response:**
-   ```json
-   {
-       "preferences": { "theme": "dark", "notifications": true },
-       "source": "legacy",
-       "migrated": true
-   }
-   ```
-
-4. **Verify migration:**
-   ```javascript
-   const newDoc = await db.collection('SignedInUsers/29312236/preferences/data').get();
-   // Should exist with _migratedAt and _migratedFrom fields
-   ```
-
----
-
-## Common Patterns
-
-### Pattern 1: Simple CID-based Legacy Path
-```javascript
-legacyPaths: ['old_collection/{userCid}']
-legacyPathMap: { newDataType: `old_collection/${cid}` }
-```
-
-### Pattern 2: Firebase UID-based Legacy Path
-```javascript
-legacyPaths: ['old_collection/{firebaseUid}']
-legacyPathMap: { 
-    newDataType: firebaseUid 
-        ? `old_collection/${firebaseUid}` 
-        : `old_collection/${cid}` 
-}
-```
-
-### Pattern 3: Nested Legacy Path
-```javascript
-legacyPaths: ['old_collection/{userCid}/subcollection/{itemId}']
-legacyPathMap: { 
-    newDataType: `old_collection/${cid}/subcollection/${params.itemId || '{itemId}'}` 
-}
-```
-
-### Pattern 4: Date-based Legacy Path
-```javascript
-legacyPaths: ['old_collection/{date}/{userCid}']
-legacyPathMap: { 
-    newDataType: `old_collection/${params.date || '{date}'}/${cid}` 
-}
-```
-
----
-
-## Troubleshooting
-
-### Legacy Path Not Found?
-
-1. **Check `dataType` parameter** - Must match key in `legacyPathMap`
-2. **Check `params`** - Ensure all required dynamic segments are provided
-3. **Check path resolution** - Use logger to see what path is being tried
-
-### Migration Not Happening?
-
-1. **Check if new path exists** - Migration only happens if new path is available
-2. **Check logger** - Look for migration success/error messages
-3. **Check permissions** - Ensure write permissions to new path
-
-### Multiple Legacy Formats?
-
-1. **Add all to `legacyPaths` array** in registry
-2. **Use conditional logic** in `getLegacyPath()` to choose which to try first
-3. **Or modify `readWithMigration()`** to try multiple legacy paths sequentially
-
----
-
-## Summary
-
-**Adding a new legacy route is as simple as:**
-
-### ✅ EASIEST (Recommended):
-1. ✅ Add one line to `legacyPaths` array in `collection_registry.js`
-2. ✅ Use `readWithMigration()` in your API code (pass `category` and `subcategory`)
-
-**Total time: ~30 seconds per legacy route!**
-
-### Alternative (For Complex Logic):
-1. ✅ Add one line to `legacyPaths` array in `collection_registry.js` (optional, for documentation)
-2. ✅ Add one line to `legacyPathMap` in `path_resolution_helpers.js` (if you need conditional logic)
-3. ✅ Use `readWithMigration()` in your API code
-
-**Total time: ~2 minutes per legacy route!**
-
-The system handles:
-- ✅ Path resolution
-- ✅ Fallback logic
-- ✅ Auto-migration
-- ✅ Error handling
-- ✅ Logging
-
-You just need to define the paths! 🎉
-