bulltrackers-module 1.0.992 → 1.0.993

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

@@ -24,6 +24,7 @@ const logsRoutes = require('./logs');
 const dashboardRoutes = require('./dashboard');
 const devRoutes = require('./dev');
 const accountRoutes = require('./account');
+const tutorialRoutes = require('./tutorial');
 
 /**
  * Create and configure all API routes.
@@ -51,6 +52,7 @@ function createRoutes() {
     router.use('/logs', logsRoutes);
     router.use('/dev', devRoutes);
     router.use('/account', accountRoutes);
+    router.use('/tutorial', tutorialRoutes);
 
     // Legacy route compatibility: /user/:userId/sync
     router.post('/user/:userId/sync', async (req, res, next) => {

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

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Tutorial Progress Routes
+ * Tracks per-user completion of onboarding/tutorial tasks in Firestore.
+ */
+
+const express = require('express');
+const { z } = require('zod');
+const { requireVerifiedUser } = require('../middleware/identity');
+
+const router = express.Router();
+
+const completeSchema = z.object({
+  taskId: z.string().min(1).max(200),
+});
+
+const restartSchema = z.object({
+  taskId: z.string().min(1).max(200),
+  /** Optional hint about restart strategy from frontend; backend still validates. */
+  restartStrategy: z.enum(['tutorialStateOnly', 'fullReset']).optional(),
+});
+
+function getTutorialProgressRef(db, cid) {
+  return db
+    .collection('SignedInUsers')
+    .doc(String(cid))
+    .collection('tutorial')
+    .doc('progress');
+}
+
+async function getTutorialConfig(req) {
+  const config = (req.config && req.config.tutorial) || {};
+  return {
+    nonRestartable: new Set(config.nonRestartableTaskIds || []),
+    fullReset: new Set(config.fullResetTaskIds || []),
+  };
+}
+
+router.get('/progress', requireVerifiedUser, async (req, res, next) => {
+  try {
+    const { db } = req.services;
+    const cid = req.targetUserId;
+
+    const doc = await getTutorialProgressRef(db, cid).get();
+    const data = doc.exists ? doc.data() : {};
+
+    res.json({
+      success: true,
+      data: {
+        completedTaskIds: Array.isArray(data.completedTaskIds)
+          ? data.completedTaskIds
+          : [],
+        explicitlyDismissedTaskIds: Array.isArray(
+          data.explicitlyDismissedTaskIds
+        )
+          ? data.explicitlyDismissedTaskIds
+          : [],
+        taskMetadata: data.taskMetadata || {},
+      },
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post('/progress/complete', requireVerifiedUser, async (req, res, next) => {
+  try {
+    const parsed = completeSchema.parse(req.body || {});
+    const { db } = req.services;
+    const cid = req.targetUserId;
+
+    const ref = getTutorialProgressRef(db, cid);
+    await db.runTransaction(async (tx) => {
+      const snap = await tx.get(ref);
+      const existing = snap.exists ? snap.data() || {} : {};
+
+      const completed = new Set(
+        Array.isArray(existing.completedTaskIds)
+          ? existing.completedTaskIds
+          : []
+      );
+      completed.add(parsed.taskId);
+
+      const meta = existing.taskMetadata || {};
+      const now = new Date();
+      const current = meta[parsed.taskId] || {};
+
+      tx.set(
+        ref,
+        {
+          completedTaskIds: Array.from(completed),
+          taskMetadata: {
+            ...meta,
+            [parsed.taskId]: {
+              ...current,
+              lastCompletedAt: now,
+              runCount: (current.runCount || 0) + 1,
+            },
+          },
+        },
+        { merge: true }
+      );
+    });
+
+    res.json({ success: true });
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post('/progress/restart', requireVerifiedUser, async (req, res, next) => {
+  try {
+    const parsed = restartSchema.parse(req.body || {});
+    const { db } = req.services;
+    const cid = req.targetUserId;
+    const { nonRestartable, fullReset } = await getTutorialConfig(req);
+
+    if (nonRestartable.has(parsed.taskId)) {
+      return res.status(400).json({
+        success: false,
+        error: 'NonRestartable',
+        message: 'This tutorial task cannot be restarted once completed.',
+      });
+    }
+
+    const shouldFullReset =
+      parsed.restartStrategy === 'fullReset' || fullReset.has(parsed.taskId);
+
+    if (shouldFullReset) {
+      const collectionPath = `SignedInUsers/${cid}`;
+      if (parsed.taskId === 'alerts_create_threshold') {
+        const alertsRef = db
+          .collection(collectionPath)
+          .doc(String(cid))
+          .collection('alert_subscriptions');
+        const snap = await alertsRef.limit(50).get();
+        const batch = db.batch();
+        snap.docs.forEach((doc) => {
+          const data = doc.data() || {};
+          if (data.source === 'tutorial') {
+            batch.delete(doc.ref);
+          }
+        });
+        await batch.commit();
+      }
+    }
+
+    const ref = getTutorialProgressRef(db, cid);
+    await db.runTransaction(async (tx) => {
+      const snap = await tx.get(ref);
+      const existing = snap.exists ? snap.data() || {} : {};
+
+      const completed = new Set(
+        Array.isArray(existing.completedTaskIds)
+          ? existing.completedTaskIds
+          : []
+      );
+      completed.delete(parsed.taskId);
+
+      const meta = existing.taskMetadata || {};
+      const now = new Date();
+      const current = meta[parsed.taskId] || {};
+
+      tx.set(
+        ref,
+        {
+          completedTaskIds: Array.from(completed),
+          taskMetadata: {
+            ...meta,
+            [parsed.taskId]: {
+              ...current,
+              lastRestartedAt: now,
+              restartedCount: (current.restartedCount || 0) + 1,
+            },
+          },
+        },
+        { merge: true }
+      );
+    });
+
+    res.json({ success: true, fullResetApplied: shouldFullReset });
+  } catch (error) {
+    next(error);
+  }
+});
+
+module.exports = router;
+

package/package.json

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