bulltrackers-module 1.0.104 → 1.0.106

package/functions/generic-api/helpers/api_helpers.js

@@ -1,380 +1,380 @@
-/**
- * @fileoverview API sub-pipes.
- * REFACTORED: Now stateless and receive dependencies.
- * NEW: Added getDynamicSchema to "test run" calculations
- * by mocking async dependencies.
- */
-
-const { FieldPath } = require('@google-cloud/firestore');
-// --- NEW: Import calculation utils for mocking ---
-// We import 'aiden-shared-calculations-unified' to access its 'utils'
-const { utils } = require('aiden-shared-calculations-unified');
-
-// --- NEW: Store original utils ---
-const originalLoadMappings = utils.loadInstrumentMappings;
-const originalLoadPrices = utils.loadAllPriceData;
-const originalGetSectorMap = utils.getInstrumentSectorMap;
-
-// --- NEW: Define Mocks ---
-// This mock data will be "injected" into the calculations during the test run
-const mockMappings = { instrumentToTicker: { 1: 'TEST_TICKER', 2: 'ANOTHER' }, instrumentToSector: { 1: 'Test Sector', 2: 'Other' } };
-const mockPrices = { 1: { '2025-01-01': 100, '2025-01-02': 102 } };
-
-const mockPos = { InstrumentID: 1, NetProfit: 0.05, InvestedAmount: 50, Amount: 1000, Value: 55, Direction: 'Buy', IsBuy: true, PositionID: 123, OpenRate: 100, StopLossRate: 90, TakeProfitRate: 120, Leverage: 1, IsTslEnabled: false, OpenDateTime: '2025-01-01T12:00:00Z', CurrentRate: 105 };
-const mockToday = { AggregatedPositions: [mockPos, { ...mockPos, InstrumentID: 2 }], PublicPositions: [mockPos, { ...mockPos, InstrumentID: 2 }], PortfolioValue: 110 };
-const mockYesterday = { AggregatedPositions: [mockPos], PublicPositions: [mockPos], PortfolioValue: 100 };
-const mockInsights = { insights: [{ instrumentId: 1, total: 100, buy: 50, sell: 50 }] };
-const mockSocial = { 'post1': { tickers: ['TEST_TICKER'], sentiment: { overallSentiment: 'Bullish', topics: ['AI'] }, likeCount: 5, commentCount: 2, fullText: 'TEST_TICKER AI' } };
-
-// A mock context that's passed to process()
-const mockContext = { 
-    instrumentMappings: mockMappings.instrumentToTicker, 
-    sectorMapping: mockMappings.instrumentToSector,
-    todayDateStr: '2025-01-02',
-    yesterdayDateStr: '2025-01-01',
-    dependencies: { // For meta-calcs that read other calc results
-        db: { // Mock the DB to return fake data
-            collection: function() { return this; },
-            doc: function() { return this; },
-            get: async () => ({ 
-                exists: true, 
-                data: () => ({ /* mock data for meta-calc deps */ 
-                    'asset-crowd-flow': { 'TEST_TICKER': { net_crowd_flow_pct: 1.5 } },
-                    'social_sentiment_aggregation': { 'tickerSentiment': { 'TEST_TICKER': { sentimentRatio: 80 } } },
-                    'daily_investor_scores': { 'user123': 8.5 }
-                }) 
-            }),
-            getAll: async (...refs) => refs.map(ref => ({ 
-                exists: true, 
-                data: () => ({ /* mock data for meta-calc deps */ 
-                    'asset-crowd-flow': { 'TEST_TICKER': { net_crowd_flow_pct: 1.5 } },
-                    'social_sentiment_aggregation': { 'tickerSentiment': { 'TEST_TICKER': { sentimentRatio: 80 } } }
-                }) 
-            }))
-        },
-        logger: { log: () => {} } // Suppress logs during test run
-    },
-    config: {} // For meta-calcs
-};
-// --- END NEW MOCKS ---
-
-
-/**
- * Sub-pipe: pipe.api.helpers.validateRequest
- */
-const validateRequest = (query, config) => {
-    if (!query.computations) return "Missing 'computations' parameter.";
-    if (!query.startDate || !/^\d{4}-\d{2}-\d{2}$/.test(query.startDate)) return "Missing or invalid 'startDate'.";
-    if (!query.endDate || !/^\d{4}-\d{2}-\d{2}$/.test(query.endDate)) return "Missing or invalid 'endDate'.";
-
-    const start = new Date(query.startDate);
-    const end = new Date(query.endDate);
-    if (end < start) return "'endDate' must be after 'startDate'.";
-
-    const maxDateRange = config.maxDateRange || 100;
-    const diffTime = Math.abs(end - start);
-    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24)) + 1;
-    if (diffDays > maxDateRange) return `Date range cannot exceed ${maxDateRange} days.`;
-
-    return null;
-};
-
-/**
- * Sub-pipe: pipe.api.helpers.buildCalculationMap
- */
-const buildCalculationMap = (unifiedCalculations) => {
-    const calcMap = {};
-    for (const category in unifiedCalculations) {
-        for (const subKey in unifiedCalculations[category]) {
-            const item = unifiedCalculations[category][subKey];
-
-            // Handle historical subdirectory
-            if (subKey === 'historical' && typeof item === 'object') {
-                for (const calcName in item) {
-                    calcMap[calcName] = { category: category };
-                }
-            } 
-            // Handle regular daily/meta/social calc
-            else if (typeof item === 'function') {
-                const calcName = subKey;
-                calcMap[calcName] = { category: category };
-            }
-        }
-    }
-    return calcMap;
-};
-
-/**
- * Internal helper for date strings.
- */
-const getDateStringsInRange = (startDate, endDate) => {
-    const dates = [];
-    const current = new Date(startDate + 'T00:00:00Z');
-    const end = new Date(endDate + 'T00:00:00Z');
-
-    while (current <= end) {
-        dates.push(current.toISOString().slice(0, 10));
-        current.setUTCDate(current.getUTCDate() + 1);
-    }
-    return dates;
-};
-
-/**
- * Sub-pipe: pipe.api.helpers.fetchData
- * @param {object} config - The Generic API V2 configuration object.
- * @param {object} dependencies - Contains db, logger.
- * @param {string[]} calcKeys - Array of computation keys to fetch.
- * @param {string[]} dateStrings - Array of dates to fetch for.
- * @param {Object} calcMap - The pre-built calculation lookup map.
- * @returns {Promise<Object>} A nested object of [date][computationKey] = data.
- */
-const fetchUnifiedData = async (config, dependencies, calcKeys, dateStrings, calcMap) => {
-    const { db, logger } = dependencies;
-    const response = {};
-    const insightsCollection = config.unifiedInsightsCollection || 'unified_insights';
-    const resultsSub = config.resultsSubcollection || 'results';
-    const compsSub = config.computationsSubcollection || 'computations';
-
-    try {
-        for (const date of dateStrings) {
-            response[date] = {};
-            const docRefs = [];
-            const keyPaths = [];
-
-            for (const key of calcKeys) {
-                const pathInfo = calcMap[key];
-                if (pathInfo) {
-                    // Use db from dependencies
-                    const docRef = db.collection(insightsCollection).doc(date)
-                        .collection(resultsSub).doc(pathInfo.category)
-                        .collection(compsSub).doc(key);
-
-                    docRefs.push(docRef);
-                    keyPaths.push(key);
-                } else {
-                    logger.log('WARN', `[${date}] No path info found for computation key: ${key}`);
-                }
-            }
-
-            if (docRefs.length === 0) continue;
-
-            // Use db from dependencies
-            const snapshots = await db.getAll(...docRefs);
-            snapshots.forEach((doc, i) => {
-                const key = keyPaths[i];
-                if (doc.exists) {
-                    response[date][key] = doc.data();
-                } else {
-                    response[date][key] = null;
-                }
-            });
-        }
-    } catch (error) {
-        logger.log('ERROR', 'API: Error fetching data from Firestore.', { errorMessage: error.message });
-        throw new Error('Failed to retrieve computation data.');
-    }
-    return response;
-};
-
-/**
- * Factory for the main API handler.
- * @param {object} config - The Generic API V2 configuration object.
- * @param {object} dependencies - Contains db, logger.
- * @param {Object} calcMap - The pre-built calculation lookup map.
- * @returns {Function} An async Express request handler.
- */
-const createApiHandler = (config, dependencies, calcMap) => {
-    const { logger } = dependencies; // db is in dependencies
-    
-    return async (req, res) => {
-        const validationError = validateRequest(req.query, config);
-        if (validationError) {
-            logger.log('WARN', 'API Bad Request', { error: validationError, query: req.query });
-            return res.status(400).send({ status: 'error', message: validationError });
-        }
-
-        try {
-            const computationKeys = req.query.computations.split(',');
-            const dateStrings = getDateStringsInRange(req.query.startDate, req.query.endDate);
-
-            // Pass dependencies to sub-pipe
-            const data = await fetchUnifiedData(config, dependencies, computationKeys, dateStrings, calcMap);
-
-            res.status(200).send({
-                status: 'success',
-                metadata: {
-                    computations: computationKeys,
-                    startDate: req.query.startDate,
-                    endDate: req.query.endDate,
-                },
-                data,
-            });
-        } catch (error) {
-            logger.log('ERROR', 'API processing failed.', { errorMessage: error.message, stack: error.stack });
-            res.status(500).send({ status: 'error', message: 'An internal error occurred.' });
-        }
-    };
-};
-
-/**
- * Internal helper for snippet generation.
- */
-function createStructureSnippet(data, maxKeys = 20) {
-    if (data === null || typeof data !== 'object') {
-        // Handle primitive types
-        if (typeof data === 'number') return 0;
-        if (typeof data === 'string') return "string";
-        if (typeof data === 'boolean') return true;
-        return data;
-    }
-    if (Array.isArray(data)) {
-        if (data.length === 0) {
-            return "<empty array>";
-        }
-        // Generalize array contents to just the first element's structure
-        return [ createStructureSnippet(data[0], maxKeys) ];
-    }
-    const newObj = {};
-    const keys = Object.keys(data);
-    
-    // Check if it's an "example" object (like { "AAPL": {...} })
-    // This heuristic identifies keys that are all-caps or look like example tickers
-    if (keys.length > 0 && keys.every(k => k.match(/^[A-Z.]+$/) || k.includes('_') || k.match(/^[0-9]+$/))) {
-        const exampleKey = keys[0];
-        newObj[exampleKey] = createStructureSnippet(data[exampleKey], maxKeys);
-        newObj["... (more items)"] = "...";
-        return newObj;
-    }
-
-    if (keys.length > maxKeys) {
-        const firstKey = keys[0] || "example_key";
-        newObj[firstKey] = createStructureSnippet(data[firstKey], maxKeys);
-        newObj[`... (${keys.length - 1} more keys)`] = "<object>";
-    } else {
-        for (const key of keys) {
-            newObj[key] = createStructureSnippet(data[key], maxKeys);
-        }
-    }
-    return newObj;
-}
-
-/**
- * Sub-pipe: pipe.api.helpers.getComputationStructure
- * (This is now a debug tool to check *live* data)
- */
-async function getComputationStructure(computationName, calcMap, config, dependencies) {
-    const { db, logger } = dependencies;
-    try {
-        const pathInfo = calcMap[computationName];
-        if (!pathInfo) {
-            return { status: 'error', computation: computationName, message: `Computation not found in calculation map.` };
-        }
-        const { category } = pathInfo;
-
-        const insightsCollection = config.unifiedInsightsCollection || 'unified_insights';
-        const resultsSub = config.resultsSubcollection || 'results';
-        const compsSub = config.computationsSubcollection || 'computations';
-
-        const computationQueryPath = `${category}.${computationName}`;
-        // Use db from dependencies
-        const dateQuery = db.collection(insightsCollection)
-            .where(computationQueryPath, '==', true)
-            .orderBy(FieldPath.documentId(), 'desc')
-            .limit(1);
-            
-        const dateSnapshot = await dateQuery.get();
-
-        if (dateSnapshot.empty) {
-            return { status: 'error', computation: computationName, message: `No computed data found. (Query path: ${computationQueryPath})` };
-        }
-        
-        const latestStoredDate = dateSnapshot.docs[0].id;
-
-        // Use db from dependencies
-        const docRef = db.collection(insightsCollection).doc(latestStoredDate)
-            .collection(resultsSub).doc(category)
-            .collection(compsSub).doc(computationName);
-
-        const doc = await docRef.get();
-
-        if (!doc.exists) {
-            return { status: 'error', computation: computationName, message: `Summary flag was present for ${latestStoredDate} but doc is missing.` };
-        }
-
-        const fullData = doc.data();
-        const structureSnippet = createStructureSnippet(fullData);
-
-        return {
-            status: 'success',
-            computation: computationName,
-            category: category,
-            latestStoredDate: latestStoredDate,
-            structureSnippet: structureSnippet,
-        };
-
-    } catch (error) {
-        logger.log('ERROR', `API /structure/${computationName} helper failed.`, { errorMessage: error.message });
-        return { status: 'error', computation: computationName, message: error.message };
-    }
-}
-
-
-/**
- * --- NEW: DYNAMIC SCHEMA GENERATION HARNESS ---
- * @param {class} CalcClass The calculation class to test.
- * @param {string} calcName The name of the calculation for logging.
- * @returns {Promise<object>} A snippet of the output structure.
- */
-async function getDynamicSchema(CalcClass, calcName) {
-    // 1. Apply Mocks (Monkey-Patching)
-    utils.loadInstrumentMappings = async () => mockMappings;
-    utils.loadAllPriceData = async () => mockPrices;
-    utils.getInstrumentSectorMap = async () => mockMappings.instrumentToSector;
-
-    let result = {};
-    const calc = new CalcClass();
-
-    try {
-        // 2. Check for Meta-Calculation signature: process(dateStr, dependencies, config)
-        const processStr = calc.process.toString();
-        if (processStr.includes('dateStr') && processStr.includes('dependencies')) {
-            // It's a meta-calc. Run its process() with mock dependencies
-            result = await calc.process('2025-01-02', mockContext.dependencies, mockContext.config);
-        } else {
-            // It's a standard calculation. Run process() + getResult()
-            await calc.process(
-                mockToday, 
-                mockYesterday, 
-                'test-user-123', 
-                mockContext, 
-                mockInsights, // todayInsights
-                mockInsights, // yesterdayInsights
-                mockSocial,   // todaySocial
-                mockSocial    // yesterdaySocial
-            );
-            result = await calc.getResult();
-        }
-    } catch (e) {
-        console.error(`Error running schema test for ${calcName}: ${e.message}`);
-        result = { "ERROR": `Failed to generate schema: ${e.message}` };
-    } finally {
-        // 3. Restore Original Functions
-        utils.loadInstrumentMappings = originalLoadMappings;
-        utils.loadAllPriceData = originalLoadPrices;
-        utils.getInstrumentSectorMap = originalGetSectorMap;
-    }
-
-    // 4. Sanitize the result to just a "structure"
-    return createStructureSnippet(result);
-}
-// --- END NEW HARNESS ---
-
-
-module.exports = {
-    validateRequest,
-    buildCalculationMap,
-    fetchUnifiedData,
-    createApiHandler,
-    getComputationStructure,
-    getDynamicSchema // <-- EXPORT NEW HELPER
+/**
+ * @fileoverview API sub-pipes.
+ * REFACTORED: Now stateless and receive dependencies.
+ * NEW: Added getDynamicSchema to "test run" calculations
+ * by mocking async dependencies.
+ */
+
+const { FieldPath } = require('@google-cloud/firestore');
+// --- NEW: Import calculation utils for mocking ---
+// We import 'aiden-shared-calculations-unified' to access its 'utils'
+const { utils } = require('aiden-shared-calculations-unified');
+
+// --- NEW: Store original utils ---
+const originalLoadMappings = utils.loadInstrumentMappings;
+const originalLoadPrices = utils.loadAllPriceData;
+const originalGetSectorMap = utils.getInstrumentSectorMap;
+
+// --- NEW: Define Mocks ---
+// This mock data will be "injected" into the calculations during the test run
+const mockMappings = { instrumentToTicker: { 1: 'TEST_TICKER', 2: 'ANOTHER' }, instrumentToSector: { 1: 'Test Sector', 2: 'Other' } };
+const mockPrices = { 1: { '2025-01-01': 100, '2025-01-02': 102 } };
+
+const mockPos = { InstrumentID: 1, NetProfit: 0.05, InvestedAmount: 50, Amount: 1000, Value: 55, Direction: 'Buy', IsBuy: true, PositionID: 123, OpenRate: 100, StopLossRate: 90, TakeProfitRate: 120, Leverage: 1, IsTslEnabled: false, OpenDateTime: '2025-01-01T12:00:00Z', CurrentRate: 105 };
+const mockToday = { AggregatedPositions: [mockPos, { ...mockPos, InstrumentID: 2 }], PublicPositions: [mockPos, { ...mockPos, InstrumentID: 2 }], PortfolioValue: 110 };
+const mockYesterday = { AggregatedPositions: [mockPos], PublicPositions: [mockPos], PortfolioValue: 100 };
+const mockInsights = { insights: [{ instrumentId: 1, total: 100, buy: 50, sell: 50 }] };
+const mockSocial = { 'post1': { tickers: ['TEST_TICKER'], sentiment: { overallSentiment: 'Bullish', topics: ['AI'] }, likeCount: 5, commentCount: 2, fullText: 'TEST_TICKER AI' } };
+
+// A mock context that's passed to process()
+const mockContext = { 
+    instrumentMappings: mockMappings.instrumentToTicker, 
+    sectorMapping: mockMappings.instrumentToSector,
+    todayDateStr: '2025-01-02',
+    yesterdayDateStr: '2025-01-01',
+    dependencies: { // For meta-calcs that read other calc results
+        db: { // Mock the DB to return fake data
+            collection: function() { return this; },
+            doc: function() { return this; },
+            get: async () => ({ 
+                exists: true, 
+                data: () => ({ /* mock data for meta-calc deps */ 
+                    'asset-crowd-flow': { 'TEST_TICKER': { net_crowd_flow_pct: 1.5 } },
+                    'social_sentiment_aggregation': { 'tickerSentiment': { 'TEST_TICKER': { sentimentRatio: 80 } } },
+                    'daily_investor_scores': { 'user123': 8.5 }
+                }) 
+            }),
+            getAll: async (...refs) => refs.map(ref => ({ 
+                exists: true, 
+                data: () => ({ /* mock data for meta-calc deps */ 
+                    'asset-crowd-flow': { 'TEST_TICKER': { net_crowd_flow_pct: 1.5 } },
+                    'social_sentiment_aggregation': { 'tickerSentiment': { 'TEST_TICKER': { sentimentRatio: 80 } } }
+                }) 
+            }))
+        },
+        logger: { log: () => {} } // Suppress logs during test run
+    },
+    config: {} // For meta-calcs
+};
+// --- END NEW MOCKS ---
+
+
+/**
+ * Sub-pipe: pipe.api.helpers.validateRequest
+ */
+const validateRequest = (query, config) => {
+    if (!query.computations) return "Missing 'computations' parameter.";
+    if (!query.startDate || !/^\d{4}-\d{2}-\d{2}$/.test(query.startDate)) return "Missing or invalid 'startDate'.";
+    if (!query.endDate || !/^\d{4}-\d{2}-\d{2}$/.test(query.endDate)) return "Missing or invalid 'endDate'.";
+
+    const start = new Date(query.startDate);
+    const end = new Date(query.endDate);
+    if (end < start) return "'endDate' must be after 'startDate'.";
+
+    const maxDateRange = config.maxDateRange || 100;
+    const diffTime = Math.abs(end - start);
+    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24)) + 1;
+    if (diffDays > maxDateRange) return `Date range cannot exceed ${maxDateRange} days.`;
+
+    return null;
+};
+
+/**
+ * Sub-pipe: pipe.api.helpers.buildCalculationMap
+ */
+const buildCalculationMap = (unifiedCalculations) => {
+    const calcMap = {};
+    for (const category in unifiedCalculations) {
+        for (const subKey in unifiedCalculations[category]) {
+            const item = unifiedCalculations[category][subKey];
+
+            // Handle historical subdirectory
+            if (subKey === 'historical' && typeof item === 'object') {
+                for (const calcName in item) {
+                    calcMap[calcName] = { category: category };
+                }
+            } 
+            // Handle regular daily/meta/social calc
+            else if (typeof item === 'function') {
+                const calcName = subKey;
+                calcMap[calcName] = { category: category };
+            }
+        }
+    }
+    return calcMap;
+};
+
+/**
+ * Internal helper for date strings.
+ */
+const getDateStringsInRange = (startDate, endDate) => {
+    const dates = [];
+    const current = new Date(startDate + 'T00:00:00Z');
+    const end = new Date(endDate + 'T00:00:00Z');
+
+    while (current <= end) {
+        dates.push(current.toISOString().slice(0, 10));
+        current.setUTCDate(current.getUTCDate() + 1);
+    }
+    return dates;
+};
+
+/**
+ * Sub-pipe: pipe.api.helpers.fetchData
+ * @param {object} config - The Generic API V2 configuration object.
+ * @param {object} dependencies - Contains db, logger.
+ * @param {string[]} calcKeys - Array of computation keys to fetch.
+ * @param {string[]} dateStrings - Array of dates to fetch for.
+ * @param {Object} calcMap - The pre-built calculation lookup map.
+ * @returns {Promise<Object>} A nested object of [date][computationKey] = data.
+ */
+const fetchUnifiedData = async (config, dependencies, calcKeys, dateStrings, calcMap) => {
+    const { db, logger } = dependencies;
+    const response = {};
+    const insightsCollection = config.unifiedInsightsCollection || 'unified_insights';
+    const resultsSub = config.resultsSubcollection || 'results';
+    const compsSub = config.computationsSubcollection || 'computations';
+
+    try {
+        for (const date of dateStrings) {
+            response[date] = {};
+            const docRefs = [];
+            const keyPaths = [];
+
+            for (const key of calcKeys) {
+                const pathInfo = calcMap[key];
+                if (pathInfo) {
+                    // Use db from dependencies
+                    const docRef = db.collection(insightsCollection).doc(date)
+                        .collection(resultsSub).doc(pathInfo.category)
+                        .collection(compsSub).doc(key);
+
+                    docRefs.push(docRef);
+                    keyPaths.push(key);
+                } else {
+                    logger.log('WARN', `[${date}] No path info found for computation key: ${key}`);
+                }
+            }
+
+            if (docRefs.length === 0) continue;
+
+            // Use db from dependencies
+            const snapshots = await db.getAll(...docRefs);
+            snapshots.forEach((doc, i) => {
+                const key = keyPaths[i];
+                if (doc.exists) {
+                    response[date][key] = doc.data();
+                } else {
+                    response[date][key] = null;
+                }
+            });
+        }
+    } catch (error) {
+        logger.log('ERROR', 'API: Error fetching data from Firestore.', { errorMessage: error.message });
+        throw new Error('Failed to retrieve computation data.');
+    }
+    return response;
+};
+
+/**
+ * Factory for the main API handler.
+ * @param {object} config - The Generic API V2 configuration object.
+ * @param {object} dependencies - Contains db, logger.
+ * @param {Object} calcMap - The pre-built calculation lookup map.
+ * @returns {Function} An async Express request handler.
+ */
+const createApiHandler = (config, dependencies, calcMap) => {
+    const { logger } = dependencies; // db is in dependencies
+    
+    return async (req, res) => {
+        const validationError = validateRequest(req.query, config);
+        if (validationError) {
+            logger.log('WARN', 'API Bad Request', { error: validationError, query: req.query });
+            return res.status(400).send({ status: 'error', message: validationError });
+        }
+
+        try {
+            const computationKeys = req.query.computations.split(',');
+            const dateStrings = getDateStringsInRange(req.query.startDate, req.query.endDate);
+
+            // Pass dependencies to sub-pipe
+            const data = await fetchUnifiedData(config, dependencies, computationKeys, dateStrings, calcMap);
+
+            res.status(200).send({
+                status: 'success',
+                metadata: {
+                    computations: computationKeys,
+                    startDate: req.query.startDate,
+                    endDate: req.query.endDate,
+                },
+                data,
+            });
+        } catch (error) {
+            logger.log('ERROR', 'API processing failed.', { errorMessage: error.message, stack: error.stack });
+            res.status(500).send({ status: 'error', message: 'An internal error occurred.' });
+        }
+    };
+};
+
+/**
+ * Internal helper for snippet generation.
+ */
+function createStructureSnippet(data, maxKeys = 20) {
+    if (data === null || typeof data !== 'object') {
+        // Handle primitive types
+        if (typeof data === 'number') return 0;
+        if (typeof data === 'string') return "string";
+        if (typeof data === 'boolean') return true;
+        return data;
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0) {
+            return "<empty array>";
+        }
+        // Generalize array contents to just the first element's structure
+        return [ createStructureSnippet(data[0], maxKeys) ];
+    }
+    const newObj = {};
+    const keys = Object.keys(data);
+    
+    // Check if it's an "example" object (like { "AAPL": {...} })
+    // This heuristic identifies keys that are all-caps or look like example tickers
+    if (keys.length > 0 && keys.every(k => k.match(/^[A-Z.]+$/) || k.includes('_') || k.match(/^[0-9]+$/))) {
+        const exampleKey = keys[0];
+        newObj[exampleKey] = createStructureSnippet(data[exampleKey], maxKeys);
+        newObj["... (more items)"] = "...";
+        return newObj;
+    }
+
+    if (keys.length > maxKeys) {
+        const firstKey = keys[0] || "example_key";
+        newObj[firstKey] = createStructureSnippet(data[firstKey], maxKeys);
+        newObj[`... (${keys.length - 1} more keys)`] = "<object>";
+    } else {
+        for (const key of keys) {
+            newObj[key] = createStructureSnippet(data[key], maxKeys);
+        }
+    }
+    return newObj;
+}
+
+/**
+ * Sub-pipe: pipe.api.helpers.getComputationStructure
+ * (This is now a debug tool to check *live* data)
+ */
+async function getComputationStructure(computationName, calcMap, config, dependencies) {
+    const { db, logger } = dependencies;
+    try {
+        const pathInfo = calcMap[computationName];
+        if (!pathInfo) {
+            return { status: 'error', computation: computationName, message: `Computation not found in calculation map.` };
+        }
+        const { category } = pathInfo;
+
+        const insightsCollection = config.unifiedInsightsCollection || 'unified_insights';
+        const resultsSub = config.resultsSubcollection || 'results';
+        const compsSub = config.computationsSubcollection || 'computations';
+
+        const computationQueryPath = `${category}.${computationName}`;
+        // Use db from dependencies
+        const dateQuery = db.collection(insightsCollection)
+            .where(computationQueryPath, '==', true)
+            .orderBy(FieldPath.documentId(), 'desc')
+            .limit(1);
+            
+        const dateSnapshot = await dateQuery.get();
+
+        if (dateSnapshot.empty) {
+            return { status: 'error', computation: computationName, message: `No computed data found. (Query path: ${computationQueryPath})` };
+        }
+        
+        const latestStoredDate = dateSnapshot.docs[0].id;
+
+        // Use db from dependencies
+        const docRef = db.collection(insightsCollection).doc(latestStoredDate)
+            .collection(resultsSub).doc(category)
+            .collection(compsSub).doc(computationName);
+
+        const doc = await docRef.get();
+
+        if (!doc.exists) {
+            return { status: 'error', computation: computationName, message: `Summary flag was present for ${latestStoredDate} but doc is missing.` };
+        }
+
+        const fullData = doc.data();
+        const structureSnippet = createStructureSnippet(fullData);
+
+        return {
+            status: 'success',
+            computation: computationName,
+            category: category,
+            latestStoredDate: latestStoredDate,
+            structureSnippet: structureSnippet,
+        };
+
+    } catch (error) {
+        logger.log('ERROR', `API /structure/${computationName} helper failed.`, { errorMessage: error.message });
+        return { status: 'error', computation: computationName, message: error.message };
+    }
+}
+
+
+/**
+ * --- NEW: DYNAMIC SCHEMA GENERATION HARNESS ---
+ * @param {class} CalcClass The calculation class to test.
+ * @param {string} calcName The name of the calculation for logging.
+ * @returns {Promise<object>} A snippet of the output structure.
+ */
+async function getDynamicSchema(CalcClass, calcName) {
+    // 1. Apply Mocks (Monkey-Patching)
+    utils.loadInstrumentMappings = async () => mockMappings;
+    utils.loadAllPriceData = async () => mockPrices;
+    utils.getInstrumentSectorMap = async () => mockMappings.instrumentToSector;
+
+    let result = {};
+    const calc = new CalcClass();
+
+    try {
+        // 2. Check for Meta-Calculation signature: process(dateStr, dependencies, config)
+        const processStr = calc.process.toString();
+        if (processStr.includes('dateStr') && processStr.includes('dependencies')) {
+            // It's a meta-calc. Run its process() with mock dependencies
+            result = await calc.process('2025-01-02', mockContext.dependencies, mockContext.config);
+        } else {
+            // It's a standard calculation. Run process() + getResult()
+            await calc.process(
+                mockToday, 
+                mockYesterday, 
+                'test-user-123', 
+                mockContext, 
+                mockInsights, // todayInsights
+                mockInsights, // yesterdayInsights
+                mockSocial,   // todaySocial
+                mockSocial    // yesterdaySocial
+            );
+            result = await calc.getResult();
+        }
+    } catch (e) {
+        console.error(`Error running schema test for ${calcName}: ${e.message}`);
+        result = { "ERROR": `Failed to generate schema: ${e.message}` };
+    } finally {
+        // 3. Restore Original Functions
+        utils.loadInstrumentMappings = originalLoadMappings;
+        utils.loadAllPriceData = originalLoadPrices;
+        utils.getInstrumentSectorMap = originalGetSectorMap;
+    }
+
+    // 4. Sanitize the result to just a "structure"
+    return createStructureSnippet(result);
+}
+// --- END NEW HARNESS ---
+
+
+module.exports = {
+    validateRequest,
+    buildCalculationMap,
+    fetchUnifiedData,
+    createApiHandler,
+    getComputationStructure,
+    getDynamicSchema // <-- EXPORT NEW HELPER
 };