bulltrackers-module 1.0.592 → 1.0.593

package/functions/old-generic-api/user-api/helpers/core/path_resolution_helpers.js

@@ -0,0 +1,640 @@
+/**
+ * @fileoverview Path Resolution with Migration Support
+ * Enhanced path resolution using collection registry with auto-migration
+ * Supports both new CID-based paths and legacy paths with automatic migration
+ */
+
+const { FieldValue } = require('@google-cloud/firestore');
+
+// Try to require registry functions, but they may be injected instead
+let getCollectionPath, resolvePath, getCollectionMetadata;
+try {
+    const registry = require('../../../../../../config/collection_registry');
+    getCollectionPath = registry.getCollectionPath;
+    resolvePath = registry.resolvePath;
+    getCollectionMetadata = registry.getCollectionMetadata;
+} catch (error) {
+    // Registry will be injected via dependencies
+    getCollectionPath = null;
+    resolvePath = null;
+    getCollectionMetadata = null;
+}
+
+/**
+ * Get registry functions from options or fallback to module-level
+ * @param {object} options - Options object that may contain collectionRegistry
+ * @returns {object} - Object with getCollectionPath, resolvePath, getCollectionMetadata
+ */
+function getRegistryFunctions(options = {}) {
+    // Try to get from options first (injected)
+    if (options.collectionRegistry) {
+        // Try to get getCollectionMetadata from injected registry, fallback to module-level if not available
+        let getMetadata = options.collectionRegistry.getCollectionMetadata;
+        if (!getMetadata && getCollectionMetadata) {
+            getMetadata = getCollectionMetadata;
+        }
+        // If still not available, try requiring the registry
+        if (!getMetadata) {
+            try {
+                const registryFallback = require('../../../../../../config/collection_registry');
+                getMetadata = registryFallback.getCollectionMetadata;
+            } catch (e) {
+                // getMetadata will be undefined, which is fine - we'll handle it gracefully
+            }
+        }
+        
+        return {
+            getCollectionPath: options.collectionRegistry.getCollectionPath,
+            resolvePath: options.collectionRegistry.resolvePath || resolvePath,
+            getCollectionMetadata: getMetadata
+        };
+    }
+    
+    // Fallback to module-level (if required successfully)
+    if (getCollectionPath && resolvePath && getCollectionMetadata) {
+        return { getCollectionPath, resolvePath, getCollectionMetadata };
+    }
+    
+    // Last resort: try to require again (in case it's available now)
+    try {
+        const registryLastResort = require('../../../../../../config/collection_registry');
+        return {
+            getCollectionPath: registryLastResort.getCollectionPath,
+            resolvePath: registryLastResort.resolvePath,
+            getCollectionMetadata: registryLastResort.getCollectionMetadata
+        };
+    } catch (error) {
+        // Return functions that might be available, with getCollectionMetadata as undefined
+        return {
+            getCollectionPath: getCollectionPath || null,
+            resolvePath: resolvePath || null,
+            getCollectionMetadata: getCollectionMetadata || null
+        };
+    }
+}
+
+/**
+ * Get eToro CID from Firebase UID
+ * @param {object} db - Firestore instance
+ * @param {string} firebaseUid - Firebase authentication UID
+ * @returns {Promise<number|null>} - eToro CID or null if not found
+ */
+async function getCidFromFirebaseUid(db, firebaseUid) {
+    try {
+        const userDoc = await db.collection('signedInUsers').doc(firebaseUid).get();
+        if (!userDoc.exists) return null;
+        const data = userDoc.data();
+        return data.etoroCID || data.cid || null;
+    } catch (error) {
+        console.error('[getCidFromFirebaseUid] Error fetching CID:', error);
+        return null;
+    }
+}
+
+/**
+ * Get new path from collection registry
+ * @param {string} category - Registry category (e.g., 'signedInUsers')
+ * @param {string} subcategory - Subcategory name (e.g., 'notifications')
+ * @param {object} params - Dynamic segment values (e.g., { cid: '123' })
+ * @param {object} options - Options object that may contain collectionRegistry
+ * @returns {string} - Resolved path
+ */
+function getNewPath(category, subcategory, params = {}, options = {}) {
+    try {
+        const { getCollectionPath: getPath } = getRegistryFunctions(options);
+        return getPath(category, subcategory, params);
+    } catch (error) {
+        console.error(`[getNewPath] Error resolving path for ${category}/${subcategory}:`, error.message);
+        throw error;
+    }
+}
+
+/**
+ * Get legacy path mapping for a collection type
+ * Maps new collection types to their legacy paths
+ * @param {string} dataType - Data type (e.g., 'notifications', 'alerts', 'watchlists')
+ * @param {string|number} userCid - User CID
+ * @param {object} config - Configuration object
+ * @returns {string|null} - Legacy path or null if no legacy path exists
+ */
+/**
+ * Get legacy path mapping for a collection type
+ * Maps new collection types to their legacy paths based on user requirements
+ * 
+ * This function first tries to get legacy paths from the collection registry,
+ * then falls back to the hardcoded legacyPathMap for backward compatibility.
+ * 
+ * @param {string} dataType - Data type (e.g., 'notifications', 'alerts', 'watchlists')
+ * @param {string|number} userCid - User CID (or piCid for PI-specific data)
+ * @param {object} config - Configuration object
+ * @param {object} params - Additional parameters (e.g., { firebaseUid, username, date, requestId, etc. })
+ * @param {string} category - Registry category (e.g., 'signedInUsers', 'popularInvestors') - optional
+ * @param {string} subcategory - Registry subcategory (e.g., 'notifications', 'alerts') - optional
+ * @returns {string|null} - Legacy path template or null if no legacy path exists
+ */
+function getLegacyPath(dataType, userCid, config = {}, params = {}, category = null, subcategory = null, options = {}) {
+    // Try to get legacy paths from collection registry first
+    if (category && subcategory) {
+        try {
+            const registryFuncs = getRegistryFunctions(options);
+            const getMetadata = registryFuncs.getCollectionMetadata;
+            const resolve = registryFuncs.resolvePath;
+            
+            // Check if getCollectionMetadata is available - if not, fall through to hardcoded map
+            if (getMetadata && typeof getMetadata === 'function') {
+                const metadata = getMetadata(category, subcategory);
+                if (metadata && metadata.legacyPaths && metadata.legacyPaths.length > 0) {
+                    // Use first legacy path from registry (can be enhanced to try multiple)
+                    let legacyPathTemplate = metadata.legacyPaths[0];
+                    
+                    // Resolve dynamic segments in the legacy path
+                    const cid = String(userCid);
+                    const resolvedParams = {
+                        cid: cid,
+                        userCid: cid,
+                        firebaseUid: params.firebaseUid || '',
+                        username: params.username || '',
+                        date: params.date || '{date}',
+                        requestId: params.requestId || '{requestId}',
+                        piCid: params.piCid || cid,
+                        reviewId: params.reviewId || `{piCid}_{userCid}`,
+                        postId: params.postId || '{postId}',
+                        viewId: params.viewId || `{piCid}_{viewerCid}_{timestamp}`,
+                        watchlistId: params.watchlistId || '{watchlistId}',
+                        version: params.version || '{version}',
+                        ...params // Allow params to override defaults
+                    };
+                    
+                    // Resolve path template
+                    legacyPathTemplate = resolve(legacyPathTemplate, resolvedParams);
+                    
+                    // Replace any remaining placeholders
+                    for (const [key, value] of Object.entries(resolvedParams)) {
+                        legacyPathTemplate = legacyPathTemplate.replace(`{${key}}`, String(value));
+                    }
+                    
+                    return legacyPathTemplate;
+                }
+                // If metadata exists but no legacyPaths, fall through to hardcoded map
+            }
+        } catch (error) {
+            // Fall through to hardcoded map if registry lookup fails
+            // Only log if it's not the expected "not available" error
+            if (error.message !== 'getCollectionMetadata is not available') {
+                console.warn(`[getLegacyPath] Could not get legacy path from registry for ${category}/${subcategory}:`, error.message);
+            }
+        }
+    }
+    
+    // Fallback to hardcoded legacy path map (for backward compatibility)
+    const cid = String(userCid);
+    const firebaseUid = params.firebaseUid || '';
+    const username = params.username || '';
+    const date = params.date || '{date}';
+    const requestId = params.requestId || '{requestId}';
+    const piCid = params.piCid || cid;
+    const reviewId = params.reviewId || `{piCid}_{userCid}`;
+    const postId = params.postId || '{postId}';
+    const viewId = params.viewId || `{piCid}_{viewerCid}_{timestamp}`;
+    const watchlistId = params.watchlistId || '{watchlistId}';
+    const version = params.version || '{version}';
+    
+    const legacyPathMap = {
+        // Signed-in user data (CID-based)
+        notifications: firebaseUid ? `user_notifications/${firebaseUid}/notifications` : `user_notifications/${cid}/notifications`,
+        notificationsCounters: firebaseUid ? `user_notifications/${firebaseUid}/counters` : `user_notifications/${cid}/counters`,
+        alerts: `user_alerts/${cid}/alerts`,
+        alertsCounters: `user_alerts/${cid}/counters`,
+        watchlists: `user_watchlists/${cid}/lists`,
+        subscriptions: `watchlist_subscriptions/${cid}/alerts`,
+        verification: config.verificationsCollection ? `${config.verificationsCollection}/${username}` : `user_verifications/${username}`,
+        syncRequests: `user_sync_requests/${cid}/requests`,
+        syncStatus: `user_sync_requests/${cid}/global/latest`,
+        portfolio: config.signedInUsersCollection ? `${config.signedInUsersCollection}/19M/snapshots/${date}/parts` : `signed_in_users/19M/snapshots/${date}/parts`,
+        tradeHistory: config.signedInHistoryCollection ? `${config.signedInHistoryCollection}/19M/snapshots/${date}/parts` : `signed_in_user_history/19M/snapshots/${date}/parts`,
+        socialPosts: `signed_in_users_social/${cid}/posts`,
+        
+        // Popular Investor data (PI CID-based)
+        piFetchRequests: `pi_fetch_requests/${piCid}/requests/${requestId}`,
+        piFetchStatus: `pi_fetch_requests/${piCid}/global/latest`,
+        piUserFetchRequests: `PopularInvestors/${piCid}/userFetchRequests/${cid}`,
+        piReviews: `pi_reviews/${reviewId}`,
+        piSocialPosts: `pi_social_posts/${piCid}/posts/${postId}`,
+        piProfileViews: `profile_views/${piCid}_${date}`,
+        piIndividualViews: `profile_views/individual_views/views/${viewId}`,
+        
+        // Public/system data (no migration needed, but documented)
+        publicWatchlists: `public_watchlists/${watchlistId}/versions/${version}`,
+        userGcidMappings: `user_gcid_mappings/${cid}`,
+        
+        // Root data collections (no migration - these are date-based and stay as-is)
+        // These are populated by task engines and should remain in their current format
+        signedInUserPortfolioRoot: `SignedInUserPortfolioData/${date}/${cid}`,
+        signedInUserTradeHistoryRoot: `SignedInUserTradeHistoryData/${date}/${cid}`,
+        signedInUserSocialRoot: `SignedInUserSocialPostData/${date}/${cid}`,
+        popularInvestorPortfolioRoot: `PopularInvestorPortfolioData/${date}/${piCid}`,
+        popularInvestorTradeHistoryRoot: `PopularInvestorTradeHistoryData/${date}/${piCid}`,
+        popularInvestorSocialRoot: `PopularInvestorSocialPostData/${date}/${piCid}`,
+        piPortfoliosDeep: `pi_portfolios_deep/19M/snapshots/${date}/parts`,
+        piPortfoliosOverall: `pi_portfolios_overall/19M/snapshots/${date}/parts`
+    };
+    
+    return legacyPathMap[dataType] || null;
+}
+
+/**
+ * Read with migration - tries new path first, falls back to legacy, auto-migrates if found
+ * @param {object} db - Firestore instance
+ * @param {string} category - Registry category
+ * @param {string} subcategory - Subcategory name
+ * @param {object} params - Path parameters
+ * @param {object} options - Read options
+ * @param {boolean} options.isCollection - If true, reads as collection; if false, reads as document
+ * @param {string} options.dataType - Data type for legacy path lookup
+ * @param {object} options.config - Configuration object
+ * @param {object} options.logger - Logger instance
+ * @param {string} options.documentId - Document ID (for collections)
+ * @returns {Promise<object|null>} - Document data or snapshot, with migration info
+ */
+async function readWithMigration(db, category, subcategory, params, options = {}) {
+    const { 
+        isCollection = false, 
+        dataType = null, 
+        config = {}, 
+        logger = null,
+        documentId = null,
+        collectionRegistry = null
+    } = options;
+    
+    // Add collectionRegistry to options for registry function access
+    const registryOptions = { collectionRegistry };
+    
+    const userCid = params.cid || params.userCid;
+    
+    // Get new path from registry
+    let newPath;
+    try {
+        newPath = getNewPath(category, subcategory, params, registryOptions);
+    } catch (error) {
+        if (logger) logger.log('WARN', `[readWithMigration] Could not resolve new path for ${category}/${subcategory}: ${error.message}`);
+        newPath = null;
+    }
+    
+        // Try new path first
+    if (newPath) {
+        try {
+            if (isCollection) {
+                // Collection path must have odd number of segments
+                if (documentId) {
+                    // Read specific document from collection
+                    const docRef = db.collection(newPath).doc(documentId);
+                    const doc = await docRef.get();
+                    if (doc.exists) {
+                        if (logger) logger.log('INFO', `[readWithMigration] Found document in new path: ${docRef.path}`);
+                        return { data: doc.data(), exists: true, source: 'new', path: docRef.path };
+                    }
+                } else {
+                    // Read entire collection
+                    const collectionRef = db.collection(newPath);
+                    const snapshot = await collectionRef.get();
+                    if (!snapshot.empty) {
+                        if (logger) logger.log('INFO', `[readWithMigration] Found data in new path: ${newPath}`);
+                        return { snapshot, source: 'new', path: newPath };
+                    }
+                }
+            } else {
+                // Document path: if newPath has even segments, it's already a document path
+                // If documentId is provided, newPath should be collection path (odd segments)
+                let docRef;
+                if (documentId) {
+                    // newPath should be collection (odd segments), add documentId
+                    const pathSegments = newPath.split('/');
+                    if (pathSegments.length % 2 === 0) {
+                        // Even segments = document path, can't add documentId
+                        throw new Error(`Path ${newPath} is a document path but documentId was provided`);
+                    }
+                    docRef = db.collection(newPath).doc(documentId);
+                } else {
+                    // No documentId, newPath should be full document path (even segments)
+                    docRef = db.doc(newPath);
+                }
+                const doc = await docRef.get();
+                if (doc.exists) {
+                    if (logger) logger.log('INFO', `[readWithMigration] Found data in new path: ${docRef.path}`);
+                    return { data: doc.data(), source: 'new', path: docRef.path };
+                }
+            }
+        } catch (newError) {
+            if (logger) logger.log('WARN', `[readWithMigration] Error reading from new path ${newPath}: ${newError.message}`);
+        }
+    }
+    
+    // Fallback to legacy path
+    if (dataType && userCid) {
+        const legacyPathTemplate = getLegacyPath(dataType, userCid, config, params, category, subcategory, registryOptions);
+        if (legacyPathTemplate) {
+            try {
+                // Resolve legacy path (may have additional params like date, username)
+                // Replace placeholders in legacy path template
+                let legacyPath = legacyPathTemplate;
+                for (const [key, value] of Object.entries(params)) {
+                    legacyPath = legacyPath.replace(`{${key}}`, String(value));
+                }
+                // Also replace common placeholders
+                legacyPath = legacyPath.replace(/{date}/g, params.date || '{date}');
+                legacyPath = legacyPath.replace(/{requestId}/g, params.requestId || documentId || '{requestId}');
+                legacyPath = legacyPath.replace(/{username}/g, params.username || '{username}');
+                legacyPath = legacyPath.replace(/{piCid}/g, params.piCid || userCid);
+                legacyPath = legacyPath.replace(/{userCid}/g, String(userCid));
+                legacyPath = legacyPath.replace(/{cid}/g, String(userCid));
+                legacyPath = legacyPath.replace(/{viewerCid}/g, params.viewerCid || '{viewerCid}');
+                legacyPath = legacyPath.replace(/{timestamp}/g, params.timestamp || Date.now().toString());
+                legacyPath = legacyPath.replace(/{viewId}/g, params.viewId || documentId || '{viewId}');
+                legacyPath = legacyPath.replace(/{reviewId}/g, params.reviewId || documentId || `{piCid}_{userCid}`);
+                legacyPath = legacyPath.replace(/{postId}/g, params.postId || documentId || '{postId}');
+                legacyPath = legacyPath.replace(/{watchlistId}/g, params.watchlistId || '{watchlistId}');
+                legacyPath = legacyPath.replace(/{version}/g, params.version || '{version}');
+                
+                if (isCollection) {
+                    if (documentId) {
+                        // Read specific document from legacy collection
+                        const legacyDocRef = db.collection(legacyPath).doc(documentId);
+                        const legacyDoc = await legacyDocRef.get();
+                        if (legacyDoc.exists) {
+                            if (logger) logger.log('INFO', `[readWithMigration] Found document in legacy path: ${legacyDocRef.path}, will migrate`);
+                            
+                            // Auto-migrate if new path is available
+                            if (newPath) {
+                                await migrateDocumentData(db, legacyDoc, newPath, documentId, logger);
+                            }
+                            
+                            return { data: legacyDoc.data(), exists: true, source: 'legacy', path: legacyDocRef.path, migrated: !!newPath };
+                        }
+                    } else {
+                        // Read entire legacy collection
+                        const legacyCollectionRef = db.collection(legacyPath);
+                        const legacySnapshot = await legacyCollectionRef.get();
+                        if (!legacySnapshot.empty) {
+                            if (logger) logger.log('INFO', `[readWithMigration] Found data in legacy path: ${legacyPath}, will migrate`);
+                            
+                            // Auto-migrate if new path is available
+                            if (newPath) {
+                                await migrateCollectionData(db, legacySnapshot, newPath, dataType, logger);
+                            }
+                            
+                            return { snapshot: legacySnapshot, source: 'legacy', path: legacyPath, migrated: !!newPath };
+                        }
+                    }
+                } else {
+                    const legacyDocRef = documentId
+                        ? db.collection(legacyPath).doc(documentId)
+                        : db.doc(legacyPath);
+                    const legacyDoc = await legacyDocRef.get();
+                    if (legacyDoc.exists) {
+                        if (logger) logger.log('INFO', `[readWithMigration] Found data in legacy path: ${legacyDocRef.path}, will migrate`);
+                        
+                        // Auto-migrate if new path is available
+                        if (newPath) {
+                            await migrateDocumentData(db, legacyDoc, newPath, documentId, logger);
+                        }
+                        
+                        return { data: legacyDoc.data(), source: 'legacy', path: legacyDocRef.path, migrated: !!newPath };
+                    }
+                }
+            } catch (legacyError) {
+                if (logger) logger.log('WARN', `[readWithMigration] Error reading from legacy path: ${legacyError.message}`);
+            }
+        }
+    }
+    
+    return null;
+}
+
+/**
+ * Migrate document data from legacy to new path
+ * @param {object} db - Firestore instance
+ * @param {object} legacyDoc - Legacy document snapshot
+ * @param {string} newPath - New path (collection path, not full document path)
+ * @param {string} documentId - Document ID
+ * @param {object} logger - Logger instance
+ * @returns {Promise<void>}
+ */
+async function migrateDocumentData(db, legacyDoc, newPath, documentId, logger) {
+    try {
+        const data = legacyDoc.data();
+        const newDocRef = documentId 
+            ? db.collection(newPath).doc(documentId)
+            : db.doc(newPath);
+        
+        // Check if already migrated
+        const existingDoc = await newDocRef.get();
+        if (existingDoc.exists) {
+            if (logger) logger.log('INFO', `[migrateDocumentData] Data already exists in new path: ${newDocRef.path}`);
+            return;
+        }
+        
+        // Migrate data
+        await newDocRef.set({
+            ...data,
+            _migratedAt: FieldValue.serverTimestamp(),
+            _migratedFrom: legacyDoc.ref.path
+        });
+        
+        if (logger) logger.log('SUCCESS', `[migrateDocumentData] Migrated document from ${legacyDoc.ref.path} to ${newDocRef.path}`);
+    } catch (error) {
+        if (logger) logger.log('ERROR', `[migrateDocumentData] Migration failed: ${error.message}`);
+        // Don't throw - migration failures shouldn't break reads
+    }
+}
+
+/**
+ * Migrate collection data from legacy to new path
+ * @param {object} db - Firestore instance
+ * @param {object} legacySnapshot - Legacy collection snapshot
+ * @param {string} newPath - New collection path
+ * @param {string} dataType - Data type
+ * @param {object} logger - Logger instance
+ * @returns {Promise<void>}
+ */
+async function migrateCollectionData(db, legacySnapshot, newPath, dataType, logger) {
+    try {
+        const batch = db.batch();
+        let migratedCount = 0;
+        
+        for (const doc of legacySnapshot.docs) {
+            const newDocRef = db.collection(newPath).doc(doc.id);
+            
+            // Check if already migrated
+            const existingDoc = await newDocRef.get();
+            if (existingDoc.exists) {
+                continue; // Skip if already migrated
+            }
+            
+            // Add to batch
+            batch.set(newDocRef, {
+                ...doc.data(),
+                _migratedAt: FieldValue.serverTimestamp(),
+                _migratedFrom: doc.ref.path
+            });
+            migratedCount++;
+        }
+        
+        if (migratedCount > 0) {
+            await batch.commit();
+            if (logger) logger.log('SUCCESS', `[migrateCollectionData] Migrated ${migratedCount} documents from legacy to ${newPath}`);
+        }
+    } catch (error) {
+        if (logger) logger.log('ERROR', `[migrateCollectionData] Migration failed: ${error.message}`);
+        // Don't throw - migration failures shouldn't break reads
+    }
+}
+
+/**
+ * Write with dual write support (writes to both new and legacy during migration)
+ * @param {object} db - Firestore instance
+ * @param {string} category - Registry category
+ * @param {string} subcategory - Subcategory name
+ * @param {object} params - Path parameters
+ * @param {object} data - Data to write
+ * @param {object} options - Write options
+ * @param {boolean} options.isCollection - If true, writes as collection; if false, writes as document
+ * @param {boolean} options.merge - If true, merges data instead of overwriting
+ * @param {string} options.dataType - Data type for legacy path lookup
+ * @param {object} options.config - Configuration object
+ * @param {string} options.documentId - Document ID (required for collections)
+ * @param {boolean} options.dualWrite - If true, writes to both paths (default: true during migration)
+ * @returns {Promise<void>}
+ */
+async function writeWithMigration(db, category, subcategory, params, data, options = {}) {
+    const {
+        isCollection = false,
+        merge = false,
+        dataType = null,
+        config = {},
+        documentId = null,
+        dualWrite = true, // Default to dual write during migration period
+        collectionRegistry = null
+    } = options;
+    
+    // Add collectionRegistry to options for registry function access
+    const registryOptions = { collectionRegistry };
+    
+    const userCid = params.cid || params.userCid;
+    
+    // Get new path
+    const newPath = getNewPath(category, subcategory, params, registryOptions);
+    
+    // Get legacy path if dual write is enabled
+    let legacyPath = null;
+    if (dualWrite && dataType && userCid) {
+        try {
+            const registryFuncs = getRegistryFunctions(registryOptions);
+            const resolve = registryFuncs?.resolvePath;
+            legacyPath = getLegacyPath(dataType, userCid, config, params, null, null, registryOptions);
+            if (legacyPath && resolve && typeof resolve === 'function') {
+                legacyPath = resolve(legacyPath, params);
+            } else if (legacyPath) {
+                // If resolve is not available, manually replace placeholders
+                for (const [key, value] of Object.entries(params)) {
+                    legacyPath = legacyPath.replace(`{${key}}`, String(value));
+                }
+            }
+        } catch (error) {
+            console.warn('[writeWithMigration] Could not resolve legacy path, skipping dual write:', error.message);
+            legacyPath = null; // Skip dual write if we can't resolve legacy path
+        }
+    }
+    
+    const batch = db.batch();
+    
+    try {
+        // Write to new path
+        if (isCollection) {
+            if (!documentId) {
+                throw new Error('Collection writes require documentId');
+            }
+            // Collection path must have odd number of segments
+            const pathSegments = newPath.split('/');
+            if (pathSegments.length % 2 === 0) {
+                throw new Error(`Path ${newPath} is a document path but isCollection=true was specified`);
+            }
+            const newRef = db.collection(newPath).doc(documentId);
+            if (merge) {
+                batch.set(newRef, data, { merge: true });
+            } else {
+                batch.set(newRef, data);
+            }
+        } else {
+            // Document path: if documentId provided, newPath should be collection (odd segments)
+            // If no documentId, newPath should be full document path (even segments)
+            let newRef;
+            if (documentId) {
+                const pathSegments = newPath.split('/');
+                if (pathSegments.length % 2 === 0) {
+                    throw new Error(`Path ${newPath} is a document path but documentId was provided`);
+                }
+                newRef = db.collection(newPath).doc(documentId);
+            } else {
+                newRef = db.doc(newPath);
+            }
+            if (merge) {
+                batch.set(newRef, data, { merge: true });
+            } else {
+                batch.set(newRef, data);
+            }
+        }
+        
+        // Write to legacy path if dual write is enabled
+        if (legacyPath) {
+            if (isCollection) {
+                if (!documentId) {
+                    throw new Error('Collection writes require documentId');
+                }
+                const legacyRef = db.collection(legacyPath).doc(documentId);
+                if (merge) {
+                    batch.set(legacyRef, data, { merge: true });
+                } else {
+                    batch.set(legacyRef, data);
+                }
+            } else {
+                const legacyRef = documentId
+                    ? db.collection(legacyPath).doc(documentId)
+                    : db.doc(legacyPath);
+                if (merge) {
+                    batch.set(legacyRef, data, { merge: true });
+                } else {
+                    batch.set(legacyRef, data);
+                }
+            }
+        }
+        
+        await batch.commit();
+    } catch (error) {
+        console.error('[writeWithMigration] Error writing data:', error);
+        throw error;
+    }
+}
+
+/**
+ * Get collection path helper (for backward compatibility)
+ * @param {object} collectionRegistry - Collection registry (injected)
+ * @param {string} category - Registry category
+ * @param {string} subcategory - Subcategory name
+ * @param {object} params - Path parameters
+ * @returns {string} - Resolved path
+ */
+function getCollectionPathHelper(collectionRegistry, category, subcategory, params = {}) {
+    return getNewPath(category, subcategory, params, { collectionRegistry });
+}
+
+module.exports = {
+    getCidFromFirebaseUid,
+    getNewPath,
+    getLegacyPath,
+    readWithMigration,
+    writeWithMigration,
+    migrateDocumentData,
+    migrateCollectionData,
+    getCollectionPath: getCollectionPathHelper // For backward compatibility
+};
+