bulltrackers-module 1.0.994 → 1.0.996

package/functions/api-v3/routes/popular-investors.js

@@ -9,6 +9,7 @@ const { requireFirebaseAuth } = require('../middleware/auth');
 const { requireVerifiedUser, sanitizeCid } = require('../middleware/identity');
 
 const { EtoroApiService } = require('../services/EtoroApiService');
+const { recordAnalyticsWrite } = require('../../core/utils/analytics_registry');
 
 const router = express.Router();
 
@@ -137,7 +138,7 @@ router.get('/search', async (req, res, next) => {
                 query: validated.query,
                 resultCount: results.length,
                 createdAt: new Date()
-            }).catch(() => {});
+            }).then(() => recordAnalyticsWrite(db, 'analytics_events_search_query').catch(() => {})).catch(() => {});
         }
 
         res.json({ success: true, count: results.length, data: results });
@@ -295,7 +296,7 @@ router.post('/request-addition', async (req, res, next) => {
                     requestedAt: new Date(),
                     status: 'rejected_not_pi',
                     etoroCid: info.realCID || info.gcid || null
-                }).catch(() => {});
+                }).then(() => recordAnalyticsWrite(db, 'pi_addition_requests').catch(() => {})).catch(() => {});
             }
 
             return res.status(400).json({
@@ -355,7 +356,7 @@ router.post('/request-addition', async (req, res, next) => {
                 requestedAt: new Date(),
                 status: 'accepted',
                 isPi: true
-            }).catch(() => {});
+            }).then(() => recordAnalyticsWrite(db, 'pi_addition_requests').catch(() => {})).catch(() => {});
         }
 
         return res.json({

package/functions/api-v3/routes/workspace.js

@@ -4,11 +4,32 @@
  */
 
 const express = require('express');
+const fs = require('fs');
+const path = require('path');
 const config = require('../config');
 const { requireVerifiedUser } = require('../middleware/identity');
 const { requireFirebaseAuth } = require('../middleware/auth');
 const { generateDynamicPaths } = require('./workspace-generator');
 
+const FRAMEWORK_ROOT = path.join(__dirname, '../../computation-system-v3/framework');
+
+// Read-only sample computation templates that we copy into each user's
+// editable `computations/` directory on first bootstrap.
+const SAMPLE_COMPUTATION_TEMPLATES = [
+    {
+        source: 'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+        target: 'computations/Sample_PortfolioDailySummary_Grade1.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+        target: 'computations/Sample_EntityRiskChange_Grade2.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+        target: 'computations/Sample_RiskSpikeAlerts_Grade3.js'
+    }
+];
+
 const MAX_PATHS_PER_USER = 500;
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_TOTAL_BYTES = 5 * 1024 * 1024;
@@ -147,21 +168,48 @@ function createWorkspaceRouter() {
         }
     });
 
-    // POST /workspace/bootstrap — Only initializes user directories now!
+    // POST /workspace/bootstrap — Initializes user directories and sample computations.
     router.post('/bootstrap', requireVerifiedUser, async (req, res, next) => {
         try {
             const userId = (req.identity && req.identity.cid) || req.targetUserId;
             const ref = req.services.db.collection('users').doc(userId).collection('workspace_files');
             const snap = await ref.get();
 
-            // We only need to bootstrap user-editable files now. 
+            // We only need to bootstrap user-editable files now.
             // The read-only registry is automatically served in /tree and /file.
-            const userPaths = [
-                { path: 'computations', kind: 'directory', content: null }
-            ];
+            const userPaths = [{ path: 'computations', kind: 'directory', content: null }];
+
+            // Pre-populate the computations/ directory with three fully documented,
+            // valid sample computations. The source of truth lives under
+            // computation-system-v3/framework/docs/authoring/sample-computations/*.
+            const sampleFiles = [];
+            for (const template of SAMPLE_COMPUTATION_TEMPLATES) {
+                const absolute = path.join(FRAMEWORK_ROOT, template.source);
+                try {
+                    if (fs.existsSync(absolute)) {
+                        const content = fs.readFileSync(absolute, 'utf8');
+                        sampleFiles.push({
+                            path: template.target,
+                            kind: 'file',
+                            content
+                        });
+                    }
+                } catch (e) {
+                    // If a template cannot be read, skip it; bootstrap should still succeed.
+                    // The admin can fix the underlying file and re-bootstrap later.
+                    // eslint-disable-next-line no-console
+                    console.error(
+                        '[workspace.bootstrap] Failed to read sample computation template',
+                        template.source,
+                        e && e.message
+                    );
+                }
+            }
 
             const now = new Date().toISOString();
-            for (const item of userPaths) {
+            const bootstrapItems = [...userPaths, ...sampleFiles];
+
+            for (const item of bootstrapItems) {
                 const existing = snap.docs.find((d) => (d.data().path || d.id.replace(/__/g, '/')) === item.path);
                 if (existing) continue;
 

package/functions/api-v3/services/WriteService.js

@@ -11,6 +11,7 @@ const {
 } = require('../../shared/upstashRedis');
 
 const { VALID_WATCHLIST_TAGS } = require('../constants');
+const { recordAnalyticsWrite } = require('../../core/utils/analytics_registry');
 
 const LIMITS = {
     WATCHLIST_NAME_MAX: 200,
@@ -349,6 +350,7 @@ class WriteService {
 
             await this._updateWatchlistMembership(validUserId, watchlistId, oldItems, firestoreData.items || []);
 
+            recordAnalyticsWrite(this.db, 'watchlists').catch(() => {});
             firestoreSuccess = true;
         } catch (error) {
             console.error('[WriteService] Firestore write failed for watchlist:', error.message);
@@ -381,6 +383,7 @@ class WriteService {
         // Delete from Firestore only. Hourly analytics-load job syncs watchlist state to BigQuery.
         await docRef.delete();
 
+        recordAnalyticsWrite(this.db, 'watchlists').catch(() => {});
         await this._updateWatchlistMembership(validUserId, validWatchlistId, oldItems, []);
     }
 
@@ -438,6 +441,7 @@ class WriteService {
                     .doc(validUserId);
                 transaction.set(piReviewRef, review);
             });
+            recordAnalyticsWrite(this.db, 'reviews').catch(() => {});
         } catch (error) {
             // Rethrow explicit errors, log others
             if (error.message === 'Already reviewed') {
@@ -520,6 +524,7 @@ class WriteService {
                 viewedAt: now,
                 createdAt: now
             });
+            recordAnalyticsWrite(this.db, 'analytics_events_pi_page_view').catch(() => {});
         } catch (error) {
             console.error('[WriteService] analytics_events pi_page_view write failed:', error.message);
         }
@@ -544,6 +549,7 @@ class WriteService {
                 new_watchlist_id: this._validateId(newWatchlistId, 'New watchlist ID'),
                 createdAt: now
             });
+            recordAnalyticsWrite(this.db, 'analytics_events_watchlist_copied').catch(() => {});
         } catch (error) {
             console.error('[WriteService] analytics_events watchlist_copied write failed:', error.message);
         }
@@ -689,6 +695,7 @@ class WriteService {
                 ...settings,
                 updatedAt: new Date()
             }, { merge: true });
+        recordAnalyticsWrite(this.db, 'alert_subscriptions').catch(() => {});
     }
 
     /**
@@ -707,6 +714,7 @@ class WriteService {
             .collection('alert_subscriptions')
             .doc(validPiCid)
             .delete();
+        recordAnalyticsWrite(this.db, 'alert_subscriptions').catch(() => {});
     }
 
     // =========================================================================
@@ -743,6 +751,8 @@ class WriteService {
 
         await firestoreRef.set({ investors }, { merge: true });
 
+        recordAnalyticsWrite(this.db, 'pi_master_list').catch(() => {});
+
         // Invalidate API cache for PI master list so new PI appears quickly.
         if (this.redisEnabled) {
             const cacheKey = `api:pi-master-list:${coll}:${docId}`;

package/functions/computation-system-v3/framework/doc-registry.js

@@ -49,6 +49,13 @@ const REGISTERED_FILES = [
     'docs/modules/trades.md',
     'docs/modules/userMetrics.md',
 
+    // ── Authoring Samples ──────────────────────────────────────────────────────────
+    // These are read-only, fully documented example computations that are also used
+    // as templates for pre-populating the user's `computations/` directory.
+    'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+    'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+    'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+
     // ── SQL Reference ─────────────────────────────────────────────────────────────
     'docs/sql/annotated-sql.md',
 

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade1-portfolio-summary.js

@@ -0,0 +1,93 @@
+/**
+ * Grade 1 sample computation — Daily portfolio value summary.
+ *
+ * This is a deliberately small, linear example that shows:
+ *   - How to declare a minimal `config` for a user computation.
+ *   - How to read from `ctx.data` using the keys defined in `config.requires`.
+ *   - How to log a short, human-readable trace line via `ctx.log`.
+ *   - How to return a safe, envelope-compatible result object (no reserved keys).
+ *
+ * The goal is to be a "perfect role model" for new authors, not to be clever.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` is globally unique per tenant and used in scheduling / storage paths.
+ * - `skills: ['lib']` enables read-only helper libraries on `ctx.lib` (not used here,
+ *   but included so users see the recommended default).
+ * - `requires.portfolio_snapshots` declares the data this computation expects:
+ *   a recent window of portfolio snapshots with `date` + `total_value` fields.
+ * - `storage.bigquery: true` means the framework will persist results to BigQuery
+ *   under the standard `computations` dataset for this tenant.
+ */
+exports.config = {
+    name: 'Sample_PortfolioDailySummary_Grade1',
+    skills: ['lib'],
+    lib: [],
+    requires: {
+        portfolio_snapshots: {
+            // The runtime will fetch up to 7 days of snapshots ending at ctx.date.
+            lookback: 7,
+            mandatory: true,
+            fields: ['date', 'total_value']
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — called by the runtime for a single execution target.
+ *
+ * Signature:
+ *   - ctx.computation: string  → the value of config.name.
+ *   - ctx.date: string         → ISO date (YYYY-MM-DD) the run is targeting.
+ *   - ctx.data: object         → data fetched according to `config.requires`.
+ *   - ctx.log: (message) => void → structured log helper scoped to this computation.
+ *
+ * Behaviour:
+ *   1. Read the `portfolio_snapshots` array from ctx.data.
+ *   2. Filter out rows that do not have a finite numeric `total_value`.
+ *   3. Compute a simple count and average total value over the window.
+ *   4. Log a short summary line with the number of snapshots analysed.
+ *   5. Return a result object with:
+ *        - outcome: high-level status code for domain logic ("OK" or "NO_DATA").
+ *        - asOfDate: the target date for the run.
+ *        - snapshotCount: how many rows were actually used.
+ *        - averagePortfolioValue: null if there was no valid data.
+ */
+exports.process = function process(ctx) {
+    const snapshots = Array.isArray(ctx.data && ctx.data.portfolio_snapshots)
+        ? ctx.data.portfolio_snapshots
+        : [];
+
+    const numericValues = [];
+    for (const row of snapshots) {
+        const raw = row && row.total_value;
+        const value = typeof raw === 'number' ? raw : Number(raw);
+        if (Number.isFinite(value)) {
+            numericValues.push(value);
+        }
+    }
+
+    const snapshotCount = numericValues.length;
+    const averagePortfolioValue =
+        snapshotCount === 0
+            ? null
+            : numericValues.reduce((sum, value) => sum + value, 0) / snapshotCount;
+
+    ctx.log(
+        `[Sample_PortfolioDailySummary_Grade1] analysed ${snapshotCount} snapshot(s) for ${ctx.date}`
+    );
+
+    return {
+        // Use a domain-level outcome key; never use reserved keys like `status` or `error`.
+        outcome: snapshotCount === 0 ? 'NO_DATA' : 'OK',
+        asOfDate: ctx.date,
+        snapshotCount,
+        averagePortfolioValue
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade2-entity-risk-change.js

@@ -0,0 +1,145 @@
+/**
+ * Grade 2 sample computation — Per-entity risk change over a rolling window.
+ *
+ * This example builds on the Grade 1 sample by:
+ *   - Operating in a clearly per-entity way (each entity is evaluated independently).
+ *   - Working with two logical inputs (`risk_snapshots` and `portfolio_snapshots`).
+ *   - Computing a small derived metric (risk delta) per entity.
+ *   - Demonstrating safe handling of missing / partial data.
+ *
+ * It is still intentionally linear and readable; the comments explain each step so that
+ * new authors can copy this pattern when adding their own logic.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` uniquely identifies this computation.
+ * - `type: 'per-entity'` tells the runtime to run once per entity (e.g. per portfolio).
+ * - `requires.risk_snapshots` and `requires.portfolio_snapshots` declare the inputs.
+ * - `storage.bigquery: true` persists the result into tenant-scoped BigQuery tables.
+ */
+exports.config = {
+    name: 'Sample_EntityRiskChange_Grade2',
+    type: 'per-entity',
+    skills: ['lib'],
+    lib: [],
+    requires: {
+        risk_snapshots: {
+            // 30-day lookback window of per-entity risk scores.
+            lookback: 30,
+            mandatory: true,
+            fields: ['date', 'entity_id', 'risk_score']
+        },
+        portfolio_snapshots: {
+            // Optional: we only need a name/label for display purposes.
+            lookback: 1,
+            mandatory: false,
+            fields: ['entity_id', 'display_name']
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — computes the change in risk score for a single entity.
+ *
+ * For each entity on a given date:
+ *   1. Filter the `risk_snapshots` array down to the current entityId (if provided).
+ *   2. Sort snapshots by date to find the "previous" and "current" entries.
+ *   3. Compute a simple delta: current_risk - previous_risk.
+ *   4. Look up a human-readable portfolio name from `portfolio_snapshots` if present.
+ *   5. Return a single object that describes today's risk position for this entity.
+ */
+exports.process = function process(ctx) {
+    const entityId = ctx.entityId;
+
+    const allRiskSnapshots = Array.isArray(ctx.data && ctx.data.risk_snapshots)
+        ? ctx.data.risk_snapshots
+        : [];
+
+    // Step 1: isolate this entity's rows (or all rows if entityId is not provided).
+    const entityRiskRows = allRiskSnapshots.filter((row) => {
+        if (!row) return false;
+        if (entityId == null) return true;
+        return String(row.entity_id) === String(entityId);
+    });
+
+    // Step 2: sort by date ascending so the last element is the most recent snapshot.
+    entityRiskRows.sort((a, b) => {
+        const ad = a && a.date ? String(a.date) : '';
+        const bd = b && b.date ? String(b.date) : '';
+        return ad.localeCompare(bd);
+    });
+
+    const rowCount = entityRiskRows.length;
+    if (rowCount === 0) {
+        ctx.log(
+            `[Sample_EntityRiskChange_Grade2] no risk_snapshots found for entity ${String(
+                entityId || 'GLOBAL'
+            )} on ${ctx.date}`
+        );
+
+        return {
+            outcome: 'NO_DATA',
+            asOfDate: ctx.date,
+            entityId: entityId || null,
+            currentRisk: null,
+            previousRisk: null,
+            riskDelta: null
+        };
+    }
+
+    const latest = entityRiskRows[rowCount - 1];
+    const previous = rowCount > 1 ? entityRiskRows[rowCount - 2] : null;
+
+    const currentRisk =
+        latest && typeof latest.risk_score === 'number'
+            ? latest.risk_score
+            : Number(latest && latest.risk_score);
+    const previousRisk =
+        previous && typeof previous.risk_score === 'number'
+            ? previous.risk_score
+            : Number(previous && previous.risk_score);
+
+    const safeCurrent = Number.isFinite(currentRisk) ? currentRisk : null;
+    const safePrevious = Number.isFinite(previousRisk) ? previousRisk : null;
+
+    let riskDelta = null;
+    if (safeCurrent != null && safePrevious != null) {
+        riskDelta = safeCurrent - safePrevious;
+    }
+
+    // Optional: look up a display name from portfolio_snapshots for nicer reporting.
+    let portfolioName = null;
+    const portfolioRows = Array.isArray(ctx.data && ctx.data.portfolio_snapshots)
+        ? ctx.data.portfolio_snapshots
+        : [];
+    const matchingPortfolio = portfolioRows.find((row) => {
+        if (!row) return false;
+        if (entityId == null) return false;
+        return String(row.entity_id) === String(entityId);
+    });
+    if (matchingPortfolio && typeof matchingPortfolio.display_name === 'string') {
+        portfolioName = matchingPortfolio.display_name;
+    }
+
+    ctx.log(
+        `[Sample_EntityRiskChange_Grade2] entity ${String(
+            entityId || 'GLOBAL'
+        )} risk=${safeCurrent} (delta=${riskDelta}) on ${ctx.date}`
+    );
+
+    return {
+        outcome: 'OK',
+        asOfDate: ctx.date,
+        entityId: entityId || null,
+        portfolioName,
+        currentRisk: safeCurrent,
+        previousRisk: safePrevious,
+        riskDelta
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade3-alert-on-risk-spike.js

@@ -0,0 +1,102 @@
+/**
+ * Grade 3 sample computation — Simple alert surface for risk spikes.
+ *
+ * This example is intentionally still single-file and easy to read, but it
+ * shows a slightly more "production-like" pattern:
+ *   - It depends on the Grade 2 computation's result by name via `dependencies`.
+ *   - It treats the upstream result as an input table in `requires`.
+ *   - It emits a compact list of "alerts" that could be consumed by downstream
+ *     dashboards or notification systems.
+ *
+ * This is not wired into any real alerting system; it is a didactic example
+ * that demonstrates how to compose computations safely.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `dependencies` lists another computation by name. The planner ensures that
+ *   the dependency runs first for the target date / entity set before this one.
+ * - `requires.entity_risk_change` models the dependency's output as a table-like
+ *   input; in a real deployment this would be backed by storage (e.g. BigQuery).
+ */
+exports.config = {
+    name: 'Sample_RiskSpikeAlerts_Grade3',
+    skills: ['lib'],
+    lib: [],
+    dependencies: ['Sample_EntityRiskChange_Grade2'],
+    requires: {
+        entity_risk_change: {
+            // The runtime will typically resolve this from the dependency's output.
+            lookback: 1,
+            mandatory: true,
+            fields: [
+                'asOfDate',
+                'entityId',
+                'portfolioName',
+                'currentRisk',
+                'previousRisk',
+                'riskDelta'
+            ]
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — builds a list of simple alert objects when risk jumps.
+ *
+ * Behaviour:
+ *   1. Read the `entity_risk_change` rows for the current date.
+ *   2. Filter to entities whose absolute riskDelta is above a fixed threshold.
+ *   3. Map each row to a small, explicit alert object.
+ *   4. Return a payload containing:
+ *        - outcome: "OK" or "NO_ALERTS".
+ *        - asOfDate: the date we evaluated.
+ *        - alerts: array of alert objects (possibly empty).
+ *
+ * NOTE: This computation does not send notifications itself; it produces clean,
+ * queryable data that other systems can use as a source of truth.
+ */
+exports.process = function process(ctx) {
+    const rows = Array.isArray(ctx.data && ctx.data.entity_risk_change)
+        ? ctx.data.entity_risk_change
+        : [];
+
+    const THRESHOLD = 5; // Example threshold for a "meaningful" risk move.
+
+    const alerts = [];
+    for (const row of rows) {
+        if (!row) continue;
+
+        const delta = row.riskDelta;
+        if (!Number.isFinite(delta)) continue;
+
+        if (Math.abs(delta) < THRESHOLD) {
+            continue;
+        }
+
+        alerts.push({
+            entityId: row.entityId || null,
+            portfolioName: typeof row.portfolioName === 'string' ? row.portfolioName : null,
+            asOfDate: row.asOfDate || ctx.date,
+            currentRisk: Number.isFinite(row.currentRisk) ? row.currentRisk : null,
+            previousRisk: Number.isFinite(row.previousRisk) ? row.previousRisk : null,
+            riskDelta: delta,
+            direction: delta > 0 ? 'INCREASE' : 'DECREASE'
+        });
+    }
+
+    ctx.log(
+        `[Sample_RiskSpikeAlerts_Grade3] generated ${alerts.length} alert(s) for ${ctx.date} with threshold ${THRESHOLD}`
+    );
+
+    return {
+        outcome: alerts.length === 0 ? 'NO_ALERTS' : 'OK',
+        asOfDate: ctx.date,
+        alerts
+    };
+};
+

package/functions/core/utils/analytics_registry.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Analytics load registry: time-bucketed Firestore docs for "what to sync".
+ * API calls recordAnalyticsWrite(db, sourceKey) after writing analytics data; the loader
+ * reads period docs to discover which sources had writes in the run window.
+ * Documents are named by time period (e.g. YYYY-MM-DD-HH for 2h buckets) to avoid 1MB limit;
+ * each doc has sources: { [sourceKey]: lastWrittenAt } and expire_at for TTL (30 days).
+ */
+
+const BUCKET_HOURS = parseInt(process.env.REGISTRY_BUCKET_HOURS || '2', 10) || 2;
+const TTL_DAYS = parseInt(process.env.REGISTRY_TTL_DAYS || '30', 10) || 30;
+const REGISTRY_COLLECTION = process.env.FIRESTORE_ANALYTICS_REGISTRY_COLLECTION || 'analytics_load_registry';
+
+/**
+ * Get the period document ID for a given date (e.g. "2025-03-13-00" for 2h buckets).
+ * @param {Date} date - Reference time
+ * @returns {string} Period doc ID (YYYY-MM-DD-HH)
+ */
+function getPeriodDocId(date = new Date()) {
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const d = String(date.getUTCDate()).padStart(2, '0');
+    const hour = date.getUTCHours();
+    const bucketHour = Math.floor(hour / BUCKET_HOURS) * BUCKET_HOURS;
+    const h = String(bucketHour).padStart(2, '0');
+    return `${y}-${m}-${d}-${h}`;
+}
+
+/**
+ * Get period start date (UTC) for expire_at calculation.
+ * @param {string} periodDocId - e.g. "2025-03-13-00"
+ * @returns {Date} Start of that period (UTC)
+ */
+function getPeriodStartFromDocId(periodDocId) {
+    const [y, m, d, h] = periodDocId.split('-').map(Number);
+    return new Date(Date.UTC(y, m - 1, d, h, 0, 0, 0));
+}
+
+/**
+ * Record that a source was written to (for the analytics loader). Fire-and-forget; logs errors only.
+ * Updates the current period's registry doc: merge source key + writtenAt into sources, set expire_at.
+ * @param {object} db - Firestore instance
+ * @param {string} sourceKey - e.g. 'watchlists', 'analytics_events_pi_page_view'
+ */
+async function recordAnalyticsWrite(db, sourceKey) {
+    const now = new Date();
+    const periodDocId = getPeriodDocId(now);
+    const periodStart = getPeriodStartFromDocId(periodDocId);
+    const expireAt = new Date(periodStart);
+    expireAt.setUTCDate(expireAt.getUTCDate() + TTL_DAYS);
+
+    try {
+        const col = db.collection(REGISTRY_COLLECTION);
+        const ref = col.doc(periodDocId);
+        await ref.set(
+            {
+                [`sources.${sourceKey}`]: now,
+                expire_at: expireAt
+            },
+            { merge: true }
+        );
+    } catch (error) {
+        console.error('[analytics_registry] recordAnalyticsWrite failed:', error.message);
+    }
+}
+
+/**
+ * List period doc IDs that overlap the given time window [since, now].
+ * @param {Date} since - Start of window
+ * @param {Date} end - End of window (default now)
+ * @returns {string[]} Period doc IDs in range
+ */
+function getPeriodDocIdsInWindow(since, end = new Date()) {
+    const ids = [];
+    const cursor = new Date(since);
+    cursor.setUTCMinutes(0, 0, 0);
+    const hour = cursor.getUTCHours();
+    const bucketHour = Math.floor(hour / BUCKET_HOURS) * BUCKET_HOURS;
+    cursor.setUTCHours(bucketHour, 0, 0, 0);
+
+    while (cursor <= end) {
+        ids.push(getPeriodDocId(cursor));
+        cursor.setUTCHours(cursor.getUTCHours() + BUCKET_HOURS);
+    }
+    return [...new Set(ids)];
+}
+
+/**
+ * Read registry docs for the given period IDs and return the union of source keys that had writes.
+ * @param {object} db - Firestore instance
+ * @param {string[]} periodDocIds - Period document IDs to read
+ * @returns {Promise<Set<string>>} Set of source keys
+ */
+async function getSourceKeysFromRegistry(db, periodDocIds) {
+    const keys = new Set();
+    const col = db.collection(REGISTRY_COLLECTION);
+    await Promise.all(
+        periodDocIds.map(async (id) => {
+            const snap = await col.doc(id).get();
+            if (!snap.exists) return;
+            const data = snap.data();
+            const sources = data && data.sources && typeof data.sources === 'object' ? data.sources : {};
+            Object.keys(sources).forEach((k) => keys.add(k));
+        })
+    );
+    return keys;
+}
+
+module.exports = {
+    recordAnalyticsWrite,
+    getPeriodDocId,
+    getPeriodDocIdsInWindow,
+    getSourceKeysFromRegistry,
+    REGISTRY_COLLECTION,
+    BUCKET_HOURS,
+    TTL_DAYS
+};