bulltrackers-module 1.0.61 → 1.0.63

package/functions/user-activity-sampler/helpers/sampler_helpers.js

@@ -1,217 +1,291 @@
 /**
  * @fileoverview Main pipe: pipe.maintenance.runUserActivitySampler
- * Samples user activity levels based on the Rankings API.
- * REVISED: Removed exclusion list logic for simplification.
+ * REFACTORED: Now split into an orchestrator and a task handler.
+ * - runUserActivitySamplerOrchestrator: Publishes one task per block.
+ * - handleSampleBlockTask: Processes a single block with parallel fetching.
  */
 const { FieldValue } = require('@google-cloud/firestore');
 
 /**
- * Main pipe: pipe.maintenance.runUserActivitySampler
+ * Main pipe (Orchestrator): pipe.maintenance.runUserActivitySamplerOrchestrator
+ * This function is triggered by a schedule. It fans out the work by
+ * publishing one Pub/Sub message for each block to be sampled.
+ *
  * @param {object} config - Configuration object.
- * @param {object} dependencies - Contains db, logger, headerManager, proxyManager, firestoreUtils.
- * @returns {Promise<object>} Summary of the sampling process.
+ * @param {object} dependencies - Contains db, logger, firestoreUtils, pubsubUtils.
+ * @returns {Promise<object>} Summary of the orchestration.
  */
-exports.runUserActivitySampler = async (config, dependencies) => {
-    // NOTE: firestoreUtils is still in dependencies but getExclusionIds is no longer called from here.
-    const { db, logger, headerManager, proxyManager, firestoreUtils } = dependencies;
-    const today = new Date().toISOString().slice(0, 10);
-    logger.log('INFO', '[UserActivitySampler] Starting user activity sampling (simplified)...');
-
-    // Validate configuration (Removed exclusionConfig validation)
-    if (!config.rankingsApiUrl || !config.targetPublicUsersPerBlock || !config.apiBatchSize || !config.outputCollectionName || !config.allHighValueBlocks ) {
-        logger.log('ERROR', '[UserActivitySampler] Missing required configuration.');
-        throw new Error('Missing required configuration for User Activity Sampler.');
+exports.runUserActivitySamplerOrchestrator = async (config, dependencies) => {
+    const { logger, firestoreUtils, pubsubUtils } = dependencies;
+    logger.log('INFO', '[SamplerOrchestrator] Starting user activity sampling orchestration...');
+
+    // Validate configuration
+    if (!config.allHighValueBlocks || !Array.isArray(config.allHighValueBlocks) || !config.samplerTaskTopicName) {
+        logger.log('ERROR', '[SamplerOrchestrator] Missing required configuration: allHighValueBlocks (array) or samplerTaskTopicName.');
+        throw new Error('Missing required configuration for Sampler Orchestrator.');
     }
 
     try {
-        await firestoreUtils.resetProxyLocks(dependencies, config); // Use shared config for proxy path
+        // Reset locks once for all tasks
+        await firestoreUtils.resetProxyLocks(dependencies, config);
 
-        // --- REMOVED Exclusion ID fetching ---
-        // const exclusionIds = await firestoreUtils.getExclusionIds(dependencies, config.exclusionConfig, 'sampler');
-        // logger.log('INFO', `[UserActivitySampler] Fetched ${exclusionIds.size} exclusion IDs.`);
-        const processedInThisRun = new Set(); // Keep track of IDs processed in this run to avoid duplicates within batches
+        const tasks = [];
+        for (const block of config.allHighValueBlocks) {
+            // Ensure block and block.startId exist
+            if (!block || typeof block.startId === 'undefined') {
+                logger.log('WARN', '[SamplerOrchestrator] Skipping invalid block configuration:', block);
+                continue;
+            }
+            tasks.push({
+                type: 'sample-block',
+                blockId: block.startId
+            });
+        }
 
-        const blockResults = [];
-        let totalPublicSampled = 0;
-        let totalPrivateEstimate = 0;
+        if (tasks.length === 0) {
+            logger.log('WARN', '[SamplerOrchestrator] No valid blocks found to sample.');
+            return { success: true, message: "No valid blocks configured." };
+        }
 
-        // Ensure allHighValueBlocks is defined and is an array
-        if (!config.allHighValueBlocks || !Array.isArray(config.allHighValueBlocks)) {
-             logger.log('ERROR', '[UserActivitySampler] Configuration error: allHighValueBlocks is missing or not an array.');
-             throw new Error('Configuration error: allHighValueBlocks must be an array.');
+        // Use pubsubUtils to batch publish all block tasks
+        await pubsubUtils.batchPublishTasks(dependencies, {
+            topicName: config.samplerTaskTopicName,
+            tasks: tasks,
+            taskType: 'sampler-block-task'
+        });
+
+        logger.log('SUCCESS', `[SamplerOrchestrator] Successfully published ${tasks.length} block sampling tasks.`);
+        return { success: true, blocksQueued: tasks.length };
+
+    } catch (error) {
+        logger.log('ERROR', '[SamplerOrchestrator] Fatal error during orchestration.', { errorMessage: error.message, errorStack: error.stack });
+        throw error;
+    }
+};
+
+/**
+ * Internal Helper: Fetches a single batch of CIDs for the sampler.
+ * This is designed to be called in parallel.
+ */
+async function fetchSampleBatch(blockId, config, dependencies, processedInThisRun) {
+    const { logger, headerManager, proxyManager } = dependencies;
+    const cidsToSample = [];
+
+    // 1. Generate CIDs for this batch
+    while (cidsToSample.length < config.apiBatchSize) {
+        const randomId = String(Math.floor(Math.random() * 1000000) + blockId);
+        // Use a Set to prevent processing the same ID twice *within this run*
+        if (!processedInThisRun.has(randomId)) {
+            cidsToSample.push(parseInt(randomId, 10));
+            processedInThisRun.add(randomId);
         }
+        // Note: If this loops too long, it could be inefficient, but it's
+        // unlikely with a large ID space and a reasonable sample size.
+    }
 
+    let selectedHeader = null;
+    let wasSuccess = false;
+    try {
+        selectedHeader = await headerManager.selectHeader();
+        if (!selectedHeader) throw new Error("Could not select header.");
+        
+        const urlWithParam = `${config.rankingsApiUrl}?Period=LastTwoYears`;
+        const response = await proxyManager.fetch(urlWithParam, {
+            method: 'POST',
+            headers: { ...selectedHeader.header, 'Content-Type': 'application/json' },
+            body: JSON.stringify(cidsToSample),
+        });
+
+        if (!response || typeof response.json !== 'function') {
+            logger.log('WARN', `[SamplerTask] Invalid response structure from proxy for block ${blockId}.`);
+            logger.log('DEBUG', `[SamplerTask] Response details: ${JSON.stringify(response)}`);
+            return { success: false, cidsSent: cidsToSample.length, publicUsers: [] };
+        }
 
-        for (const block of config.allHighValueBlocks) {
-             // Ensure block and block.startId exist
-             if (!block || typeof block.startId === 'undefined') {
-                logger.log('WARN', '[UserActivitySampler] Skipping invalid block configuration:', block);
-                continue;
-            }
-            const blockId = block.startId;
-            logger.log('INFO', `[UserActivitySampler] Processing block ${blockId}...`);
-
-            let N_public_sampled_block = 0;
-            let N_sampled_total_block = 0;
-            const public_users_data = []; // Store { CID, LastActivity }
-
-            const MAX_ATTEMPTS = config.maxSamplingAttemptsPerBlock || 1000; // Prevent infinite loops
-            let attempts = 0;
-
-            while (N_public_sampled_block < config.targetPublicUsersPerBlock && attempts < MAX_ATTEMPTS) {
-                attempts++;
-                const cidsToSample = [];
-                // Generate CIDs, ensuring they are not already processed in this run
-                while (cidsToSample.length < config.apiBatchSize) {
-                    const randomId = String(Math.floor(Math.random() * 1000000) + blockId);
-                    // --- REMOVED exclusionIds check, added check for processedInThisRun ---
-                    if (!processedInThisRun.has(randomId)) {
-                        cidsToSample.push(parseInt(randomId, 10));
-                        // Add temporarily to processed set for this run to avoid duplicates within batches
-                        processedInThisRun.add(randomId);
-                    }
-                }
-                N_sampled_total_block += cidsToSample.length;
-
-                let selectedHeader = null;
-                let wasSuccess = false;
-                try {
-                    selectedHeader = await headerManager.selectHeader();
-                    if (!selectedHeader) throw new Error("Could not select header.");
-                    const urlWithParam = `${config.rankingsApiUrl}?Period=LastTwoYears`;
-                    const response = await proxyManager.fetch(urlWithParam, {
-                        method: 'POST',
-                        headers: { ...selectedHeader.header, 'Content-Type': 'application/json' },
-                        body: JSON.stringify(cidsToSample),
-                    });
-
-                    if (!response || typeof response.json !== 'function') {
-                         logger.log('WARN', `[UserActivitySampler] Invalid response structure from proxy for block ${blockId}, batch attempt ${attempts}. Skipping batch.`);
-                         continue; // Skip to next attempt
-                    }
-
-
-                    if (!response.ok) {
-                        const errorText = await response.text();
-                        logger.log('WARN', `[UserActivitySampler] API error ${response.status} for block ${blockId}, batch attempt ${attempts}. Skipping batch. Error: ${errorText}`);
-                        wasSuccess = false;
-                        continue; // Skip to next attempt
-                    }
-
-                    wasSuccess = true;
-                    const publicUsersBatch = await response.json();
-
-                    if (Array.isArray(publicUsersBatch)) {
-                        const N_public_returned_batch = publicUsersBatch.length;
-                        N_public_sampled_block += N_public_returned_batch;
-                        public_users_data.push(...publicUsersBatch.map(u => ({
-                            CID: u.CID,
-                            LastActivity: u.Value?.LastActivity // Handle potential missing Value
-                        })));
-                    } else {
-                         logger.log('WARN', `[UserActivitySampler] API response was not an array for block ${blockId}, batch attempt ${attempts}. Skipping batch.`);
-                         continue;
-                    }
-
-
-                } catch (fetchError) {
-                    logger.log('ERROR', `[UserActivitySampler] Fetch failed for block ${blockId}, batch attempt ${attempts}. Skipping batch.`, { errorMessage: fetchError.message });
-                    wasSuccess = false; // Mark as failure for header performance
-                } finally {
-                    if (selectedHeader) {
-                        headerManager.updatePerformance(selectedHeader.id, wasSuccess);
-                    }
-                }
-                 await new Promise(resolve => setTimeout(resolve, config.delayBetweenBatchesMs || 200));
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.log('WARN', `[SamplerTask] API error ${response.status} for block ${blockId}. Error: ${errorText}`);
+            wasSuccess = false;
+            return { success: false, cidsSent: cidsToSample.length, publicUsers: [] };
+        }
 
-            } // End while loop for block sampling
+        wasSuccess = true;
+        const publicUsersBatch = await response.json();
 
-            if (attempts >= MAX_ATTEMPTS) {
-                 logger.log('WARN', `[UserActivitySampler] Reached max sampling attempts (${MAX_ATTEMPTS}) for block ${blockId}. Proceeding with ${N_public_sampled_block} users.`);
-            }
+        if (!Array.isArray(publicUsersBatch)) {
+            logger.log('WARN', `[SamplerTask] API response was not an array for block ${blockId}.`);
+            return { success: false, cidsSent: cidsToSample.length, publicUsers: [] };
+        }
+        
+        // Return a successful result
+        return {
+            success: true,
+            cidsSent: cidsToSample.length,
+            publicUsers: publicUsersBatch.map(u => ({
+                CID: u.CID,
+                LastActivity: u.Value?.LastActivity
+            }))
+        };
+
+    } catch (fetchError) {
+        logger.log('ERROR', `[SamplerTask] Fetch failed for block ${blockId}.`, { errorMessage: fetchError.message });
+        wasSuccess = false;
+        return { success: false, cidsSent: cidsToSample.length, publicUsers: [] };
+    } finally {
+        if (selectedHeader) {
+            headerManager.updatePerformance(selectedHeader.id, wasSuccess);
+        }
+    }
+}
 
+/**
+ * Main pipe (Task Handler): pipe.maintenance.handleSampleBlockTask
+ * This function is triggered by Pub/Sub for a single block.
+ * It runs the sampling in parallel to finish within timeout.
+ *
+ * @param {object} message - The Pub/Sub message.
+ * @param {object} context - The message context.
+ * @param {object} config - Configuration object.
+ * @param {object} dependencies - Contains db, logger, headerManager, proxyManager.
+ * @returns {Promise<void>}
+ */
+exports.handleSampleBlockTask = async (message, context, config, dependencies) => {
+    const { db, logger, headerManager } = dependencies;
+    
+    let task;
+    try {
+        task = JSON.parse(Buffer.from(message.data, 'base64').toString('utf-8'));
+    } catch (e) {
+        logger.log('ERROR', '[SamplerTask] Failed to parse Pub/Sub message data.', { error: e.message, data: message.data });
+        return; // Acknowledge the message to prevent retries
+    }
 
-            const f_private_block = N_sampled_total_block > 0 ? 1 - (N_public_sampled_block / N_sampled_total_block) : 0;
+    const { blockId } = task;
+    const taskId = `block-${blockId}-${context.eventId || Date.now()}`;
+    const today = new Date().toISOString().slice(0, 10);
+    logger.log('INFO', `[SamplerTask/${taskId}] Processing block ${blockId}...`);
 
-            // Categorize users
-            const counts = { A1: 0, A2: 0, A3: 0, A4: 0 };
-            const now = new Date();
-            const oneDayAgo = new Date(now.getTime() - (24 * 60 * 60 * 1000));
-            const oneWeekAgo = new Date(now.getTime() - (7 * 24 * 60 * 60 * 1000));
-             const threeMonthsAgo = new Date(now.getTime() - (90 * 24 * 60 * 60 * 1000)); // Approx
+    // --- Config validation for this task ---
+    if (!config.rankingsApiUrl || !config.targetPublicUsersPerBlock || !config.apiBatchSize || !config.outputCollectionName || !config.parallelRequests) {
+        logger.log('ERROR', `[SamplerTask/${taskId}] Missing required configuration for task execution.`);
+        throw new Error('Missing required configuration for Sampler Task.');
+    }
 
+    const processedInThisRun = new Set();
+    let N_public_sampled_block = 0;
+    let N_sampled_total_block = 0;
+    const public_users_data = []; // Store { CID, LastActivity }
 
-            public_users_data.forEach(user => {
-                if (!user.LastActivity) {
-                    counts.A4++; // Assume inactive if LastActivity is missing
-                    return;
-                }
-                try {
-                    const lastActivityDate = new Date(user.LastActivity);
-                     if (isNaN(lastActivityDate)) {
-                         counts.A4++; // Treat invalid dates as inactive
-                         return;
-                     }
-
-                    if (lastActivityDate >= oneDayAgo) counts.A1++;
-                    else if (lastActivityDate >= oneWeekAgo) counts.A2++;
-                    else if (lastActivityDate >= threeMonthsAgo) counts.A3++;
-                    else counts.A4++;
-                } catch(e) {
-                     logger.log('WARN', `[UserActivitySampler] Error parsing LastActivity date '${user.LastActivity}' for user ${user.CID}. Counting as A4.`);
-                     counts.A4++;
-                }
+    const MAX_ATTEMPTS = config.maxSamplingAttemptsPerBlock || 1000;
+    let totalBatchesAttempted = 0;
+    const CONCURRENT_REQUESTS = config.parallelRequests;
 
-            });
+    try {
+        // --- Start Parallel Loop ---
+        while (N_public_sampled_block < config.targetPublicUsersPerBlock && totalBatchesAttempted < MAX_ATTEMPTS) {
+            const promises = [];
+            const numRequests = Math.min(CONCURRENT_REQUESTS, MAX_ATTEMPTS - totalBatchesAttempted);
+
+            logger.log('TRACE', `[SamplerTask/${taskId}] Starting parallel batch of ${numRequests} requests...`);
+            for (let i = 0; i < numRequests; i++) {
+                promises.push(fetchSampleBatch(blockId, config, dependencies, processedInThisRun));
+            }
 
-            const fractions = {};
-            for (const category in counts) {
-                fractions[category] = N_public_sampled_block > 0 ? (counts[category] / N_public_sampled_block) : 0;
+            const results = await Promise.allSettled(promises);
+            totalBatchesAttempted += numRequests;
+
+            // Process results from the parallel batch
+            for (const result of results) {
+                if (result.status === 'fulfilled' && result.value.success) {
+                    const batchResult = result.value;
+                    N_sampled_total_block += batchResult.cidsSent;
+                    N_public_sampled_block += batchResult.publicUsers.length;
+                    public_users_data.push(...batchResult.publicUsers);
+                } else if (result.status === 'fulfilled' && !result.value.success) {
+                    // Failed API call, but we still count the CIDs we tried to sample
+                    N_sampled_total_block += result.value.cidsSent;
+                } else {
+                    // Promise rejected (unexpected error)
+                    logger.log('WARN', `[SamplerTask/${taskId}] A sample fetch promise was rejected.`, { reason: result.reason });
+                }
             }
+            
+            logger.log('INFO', `[SamplerTask/${taskId}] Batch complete. Total public sampled: ${N_public_sampled_block}/${config.targetPublicUsersPerBlock}`);
 
-            const N_block = 1000000; // Total users assumed per block
+            // --- REMOVED artificial delay ---
+        }
+        // --- End Parallel Loop ---
 
-            const estimatedCounts = {};
-            for (const category in fractions) {
-                estimatedCounts[category] = Math.round(fractions[category] * N_block);
-            }
+        if (totalBatchesAttempted >= MAX_ATTEMPTS) {
+            logger.log('WARN', `[SamplerTask/${taskId}] Reached max sampling attempts (${MAX_ATTEMPTS}). Proceeding with ${N_public_sampled_block} users.`);
+        }
 
-            const result = {
-                blockId: blockId,
-                sampledDate: today,
-                f_private: f_private_block,
-                publicSampleSize: N_public_sampled_block,
-                totalUsersInBlock: N_block,
-                activityCounts_Sample: counts,
-                activityFractions_Sample: fractions,
-                estimatedCounts_TotalBlock: estimatedCounts,
-                lastUpdated: FieldValue.serverTimestamp()
-            };
+        // --- Calculate and Store Results (same as before) ---
+        const f_private_block = N_sampled_total_block > 0 ? 1 - (N_public_sampled_block / N_sampled_total_block) : 0;
 
-            blockResults.push(result);
-            totalPublicSampled += N_public_sampled_block;
-            totalPrivateEstimate += f_private_block * N_block;
+        const counts = { A1: 0, A2: 0, A3: 0, A4: 0 };
+        const now = new Date();
+        const oneDayAgo = new Date(now.getTime() - (24 * 60 * 60 * 1000));
+        const oneWeekAgo = new Date(now.getTime() - (7 * 24 * 60 * 60 * 1000));
+        const threeMonthsAgo = new Date(now.getTime() - (90 * 24 * 60 * 60 * 1000));
 
-            // Store result for this block
-            const docRef = db.collection(config.outputCollectionName).doc(`${blockId}_${today}`);
-            await docRef.set(result);
-            logger.log('INFO', `[UserActivitySampler] Stored results for block ${blockId}. Sampled: ${N_public_sampled_block}. Private fraction: ${f_private_block.toFixed(3)}.`);
+        public_users_data.forEach(user => {
+            if (!user.LastActivity) {
+                counts.A4++; return;
+            }
+            try {
+                const lastActivityDate = new Date(user.LastActivity);
+                if (isNaN(lastActivityDate)) { counts.A4++; return; }
+                if (lastActivityDate >= oneDayAgo) counts.A1++;
+                else if (lastActivityDate >= oneWeekAgo) counts.A2++;
+                else if (lastActivityDate >= threeMonthsAgo) counts.A3++;
+                else counts.A4++;
+            } catch (e) {
+                logger.log('WARN', `[SamplerTask/${taskId}] Error parsing LastActivity date '${user.LastActivity}' for user ${user.CID}. Counting as A4.`);
+                counts.A4++;
+            }
+        });
 
-        } // End for loop through blocks
+        const fractions = {};
+        for (const category in counts) {
+            fractions[category] = N_public_sampled_block > 0 ? (counts[category] / N_public_sampled_block) : 0;
+        }
 
-        await headerManager.flushPerformanceUpdates();
-        logger.log('SUCCESS', `[UserActivitySampler] Sampling complete. Processed ${blockResults.length} blocks. Total public sampled: ${totalPublicSampled}.`);
+        const N_block = 1000000;
+        const estimatedCounts = {};
+        for (const category in fractions) {
+            estimatedCounts[category] = Math.round(fractions[category] * N_block);
+        }
 
-        return {
-            success: true,
-            processedBlocks: blockResults.length,
-            totalPublicSampled: totalPublicSampled,
-            estimatedTotalPrivate: Math.round(totalPrivateEstimate)
+        const result = {
+            blockId: blockId,
+            sampledDate: today,
+            f_private: f_private_block,
+            publicSampleSize: N_public_sampled_block,
+            totalSampleSize: N_sampled_total_block,
+            totalUsersInBlock: N_block,
+            activityCounts_Sample: counts,
+            activityFractions_Sample: fractions,
+            estimatedCounts_TotalBlock: estimatedCounts,
+            lastUpdated: FieldValue.serverTimestamp()
         };
 
+        const docRef = db.collection(config.outputCollectionName).doc(`${blockId}_${today}`);
+        await docRef.set(result);
+        
+        logger.log('SUCCESS', `[SamplerTask/${taskId}] Stored results for block ${blockId}. Sampled: ${N_public_sampled_block}. Private fraction: ${f_private_block.toFixed(3)}.`);
+
     } catch (error) {
-        logger.log('ERROR', '[UserActivitySampler] Fatal error during sampling process.', { errorMessage: error.message, errorStack: error.stack });
-        try { await headerManager.flushPerformanceUpdates(); } catch (e) { /* ignore flush error */ }
+        logger.log('ERROR', `[SamplerTask/${taskId}] Fatal error during task execution.`, { errorMessage: error.message, errorStack: error.stack });
+        // Re-throw the error to signal failure to Cloud Functions, which will trigger a retry.
         throw error;
+    } finally {
+        // Always flush header performance at the end of the task, even on failure.
+        try {
+            await headerManager.flushPerformanceUpdates();
+            logger.log('INFO', `[SamplerTask/${taskId}] Header performance flushed.`);
+        } catch (flushError) {
+            logger.log('ERROR', `[SamplerTask/${taskId}] Failed to flush header performance.`, { errorMessage: flushError.message });
+        }
     }
 };

package/index.js

@@ -5,7 +5,7 @@
  */
 
 // --- Core Utilities (Classes and Stateless Helpers) ---
-// These are imported directly as they form the 'core' dependency set
+// ... (no changes here) ...
 const core = {
     IntelligentHeaderManager: require('./functions/core/utils/intelligent_header_manager').IntelligentHeaderManager,
     IntelligentProxyManager: require('./functions/core/utils/intelligent_proxy_manager').IntelligentProxyManager,
@@ -15,7 +15,7 @@ const core = {
 };
 
 // --- Pipe 1: Orchestrator ---
-// The 'brain' that decides what work to do
+// ... (no changes here) ...
 const orchestrator = {
     // Main Pipes (Entry points for Cloud Functions)
     runDiscoveryOrchestrator: require('./functions/orchestrator/index').runDiscoveryOrchestrator,
@@ -32,7 +32,7 @@ const orchestrator = {
 };
 
 // --- Pipe 2: Dispatcher ---
-// The 'throttle' that rate-limits tasks
+// ... (no changes here) ...
 const dispatcher = {
     // Main Pipe
     handleRequest: require('./functions/dispatcher/index').handleRequest,
@@ -42,7 +42,7 @@ const dispatcher = {
 };
 
 // --- Pipe 3: Task Engine ---
-// The 'factory' that executes individual tasks
+// ... (no changes here) ...
 const taskEngine = {
     // Main Pipe
     handleRequest: require('./functions/task-engine/handler_creator').handleRequest,
@@ -54,7 +54,7 @@ const taskEngine = {
 };
 
 // --- Pipe 4: Computation System ---
-// The 'refinery' that processes raw data
+// ... (no changes here) ...
 const computationSystem = {
     // Main Pipe
     runOrchestration: require('./functions/computation-system/helpers/orchestration_helpers').runComputationOrchestrator,
@@ -65,7 +65,7 @@ const computationSystem = {
 };
 
 // --- Pipe 5: API ---
-// The 'tap' that serves processed data
+// ... (no changes here) ...
 const api = {
     // Main Pipe
     createApiApp: require('./functions/generic-api/index').createApiApp,
@@ -81,11 +81,15 @@ const maintenance = {
     handleInvalidSpeculator: require('./functions/invalid-speculator-handler/helpers/handler_helpers').handleInvalidSpeculator,
     runFetchInsights: require('./functions/fetch-insights/helpers/handler_helpers').fetchAndStoreInsights,
     runFetchPrices: require('./functions/etoro-price-fetcher/helpers/handler_helpers').fetchAndStorePrices,
-    runUserActivitySampler: require('./functions/user-activity-sampler/helpers/sampler_helpers').runUserActivitySampler, 
+    
+    // --- UPDATED ---
+    runUserActivitySamplerOrchestrator: require('./functions/user-activity-sampler/helpers/sampler_helpers').runUserActivitySamplerOrchestrator, 
+    handleSampleBlockTask: require('./functions/user-activity-sampler/helpers/sampler_helpers').handleSampleBlockTask, 
+    // --- END UPDATE ---
 };
 
 // --- Pipe 7: Proxy ---
-// The Google Apps Script proxy endpoint logic
+// ... (no changes here) ...
 const proxy = {
     handlePost: require('./functions/appscript-api/index').handlePost,
 };
@@ -102,4 +106,4 @@ module.exports = {
         maintenance,
         proxy,
     }
-};
+};

package/package.json

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