feat(analytics): add content performance metrics

app.js

@@ -64,6 +64,7 @@ import courseBundleRoutes from "./src/routes/course-bundle.routes.js";
 import certificateRoutes from "./src/routes/certificate.routes.js";
 import badgeRoutes from "./src/routes/badge.routes.js";
 import achievementRoutes from "./src/routes/api/achievements.js";
+import contentPerformanceRoutes from "./src/routes/analytics/contentPerformanceRoutes.js";
 import { healthCheck, ping } from "./src/controllers/healthController.js";
 import databaseHealthRoutes from "./src/routes/health/database.js";
 import databaseMetricsRoutes from "./src/routes/metrics/database.js";
@@ -287,6 +288,9 @@ app.use(versionMiddleware);
 app.use("/api/v1", generousLimiter, v1Router);
 app.use("/api/v2", generousLimiter, v2Router);
 
+// Issue #244 — Content performance analytics (views, engagement, completion).
+app.use("/api/analytics", generousLimiter, contentPerformanceRoutes);
+
 // Issue #212 — Hashtag trending endpoints.
 app.use("/api/hashtags", generousLimiter, hashtagRoutes);
 

src/controllers/analytics/contentPerformanceController.js

@@ -0,0 +1,62 @@
+// controllers/analytics/contentPerformanceController.js
+import mongoose from "mongoose";
+import logger from "../../config/logger.js";
+import contentMetricsService from "../../services/analytics/contentMetricsService.js";
+
+/**
+ * GET /api/analytics/content-performance
+ * Comparative analytics across all courses and books: views, engagement,
+ * completion rates, and a platform-level roll-up.
+ */
+export const getContentPerformance = async (req, res) => {
+  try {
+    const performance = await contentMetricsService.getContentPerformance();
+    res.status(200).json({ success: true, ...performance });
+  } catch (error) {
+    logger.error("Failed to compute content performance:", error);
+    res.status(500).json({
+      success: false,
+      message: "Failed to compute content performance",
+    });
+  }
+};
+
+/**
+ * GET /api/analytics/content-performance/:type/:id
+ * Metrics for a single course or book.
+ */
+export const getContentMetrics = async (req, res) => {
+  try {
+    const { type, id } = req.params;
+
+    if (!["course", "book"].includes(type)) {
+      return res.status(400).json({
+        success: false,
+        message: "type must be either 'course' or 'book'",
+      });
+    }
+
+    if (!mongoose.Types.ObjectId.isValid(id)) {
+      return res.status(400).json({
+        success: false,
+        message: "A valid content id is required",
+      });
+    }
+
+    const metrics = await contentMetricsService.getContentMetrics({ type, id });
+    if (!metrics) {
+      return res.status(404).json({
+        success: false,
+        message: "Content not found",
+      });
+    }
+
+    res.status(200).json({ success: true, metrics });
+  } catch (error) {
+    logger.error("Failed to compute content metrics:", error);
+    res.status(500).json({
+      success: false,
+      message: "Failed to compute content metrics",
+    });
+  }
+};

src/controllers/books/bookController.js

@@ -5,6 +5,7 @@ import User from "../../models/User.js";
 import cloudinary from "../../utils/cloudinary.js";
 import logger from "../../config/logger.js";
 import { validateMagicBytes } from "../../utils/fileValidation.js";
+import contentMetricsService from "../../services/analytics/contentMetricsService.js";
 import { bookService } from "../../services/book.service.js";
 import { createNewBookNotification } from "../notificationController.js";
 import { APIError, catchAsync } from "../../middlewares/errorHandler.js";
@@ -183,6 +184,13 @@ export const getBook = async (req, res) => {
     .populate("reviews.user", "name avatar")
     .lean();
   if (!book) return res.status(404).json({ success: false, message: "Book not found" });
+
+  // Track a book view for content-performance analytics (issue #244),
+  // fire-and-forget so a failed metric write never blocks the response.
+  contentMetricsService
+    .recordBookView(book._id)
+    .catch((err) => logger.error("Failed to increment book read count:", err));
+
   res.status(200).json({ success: true, data: book });
 };
 

src/controllers/courses/courseController.js

@@ -5,6 +5,7 @@ import logger from "../../config/logger.js";
 import { catchAsync, APIError } from "../../middlewares/errorHandler.js";
 import { getCacheOrSet, CACHE_TTL, CACHE_KEYS } from "../../utils/cache.js";
 import { createNewCourseNotification } from "../notificationController.js";
+import contentMetricsService from "../../services/analytics/contentMetricsService.js";
 import { emitEvent, EVENT_TYPES } from "../../services/webhooks/webhookService.js";
 import {
   categoryTaxonomyExists,
@@ -162,11 +163,12 @@ export const getCourseById = async (req, res) => {
         .status(404)
         .json({ success: false, message: "Course not found" });
 
-    // Track a course view for creator analytics (fire-and-forget so a failed
-    // metric write never blocks or fails the detail response).
-    Course.updateOne({ _id: course._id }, { $inc: { views: 1 } }).catch((err) =>
-      logger.error("Failed to increment course view count:", err)
-    );
+    // Track a course view for content-performance analytics (issue #244),
+    // fire-and-forget so a failed metric write never blocks or fails the
+    // detail response.
+    contentMetricsService
+      .recordCourseView(course._id)
+      .catch((err) => logger.error("Failed to increment course view count:", err));
 
     res.status(200).json({ success: true, data: course });
   } catch (error) {

src/routes/analytics/contentPerformanceRoutes.js

@@ -0,0 +1,20 @@
+// routes/analytics/contentPerformanceRoutes.js
+//
+// Content performance analytics endpoints. Mounted at /api/analytics in
+// app.js. All endpoints require authentication (protect).
+import express from "express";
+import { protect } from "../../middlewares/authMiddleware.js";
+import {
+  getContentPerformance,
+  getContentMetrics,
+} from "../../controllers/analytics/contentPerformanceController.js";
+
+const router = express.Router();
+
+// Comparative analytics across all courses and books.
+router.get("/content-performance", protect, getContentPerformance);
+
+// Metrics for a single item: /content-performance/course/:id | /book/:id
+router.get("/content-performance/:type/:id", protect, getContentMetrics);
+
+export default router;

src/services/analytics/contentMetricsService.js

@@ -0,0 +1,223 @@
+// services/analytics/contentMetricsService.js
+//
+// Content performance analytics (issue #244): tracks view counts for courses
+// and books, and aggregates engagement, completion and interaction metrics
+// across all content so creators can see how their work is performing and
+// compare items against each other.
+
+import Course from "../../models/Course.js";
+import Book from "../../models/Book.js";
+import CourseProgress from "../../models/CourseProgress.js";
+import ReadingProgress from "../../models/ReadingProgress.js";
+import {
+  interactionRate,
+  completionRate,
+  avgTimeSpentSeconds,
+  avgPercentComplete,
+  engagementScore,
+} from "../../utils/analytics/engagementCalculator.js";
+
+export class ContentMetricsService {
+  /**
+   * Record a course view (fire-and-forget so a failed metric write never
+   * blocks or fails the detail response).
+   *
+   * @param {string} courseId - Course ObjectId.
+   */
+  async recordCourseView(courseId) {
+    try {
+      await Course.updateOne({ _id: courseId }, { $inc: { views: 1 } });
+    } catch {
+      // View tracking is best-effort; ignore write failures.
+    }
+  }
+
+  /**
+   * Record a book view (read) — same best-effort semantics as course views.
+   *
+   * @param {string} bookId - Book ObjectId.
+   */
+  async recordBookView(bookId) {
+    try {
+      await Book.updateOne({ _id: bookId }, { $inc: { readCount: 1 } });
+    } catch {
+      // View tracking is best-effort; ignore write failures.
+    }
+  }
+
+  /**
+   * Build the metrics row for a single course.
+   *
+   * @param {object} course - Lean Course document.
+   * @param {Array<object>} progressDocs - CourseProgress records for the course.
+   * @returns {object} The metrics row.
+   */
+  _courseRow(course, progressDocs) {
+    const views = course.views || 0;
+    const reviews = course.numReviews || 0;
+    const enrollments = Array.isArray(course.enrolledUsers)
+      ? course.enrolledUsers.length
+      : 0;
+    const completions = progressDocs.filter(
+      (p) => p.completedAt || Number(p.percentComplete || 0) >= 100
+    ).length;
+    const cr = completionRate(completions, enrollments);
+
+    return {
+      id: String(course._id),
+      type: "course",
+      title: course.title,
+      category: course.category || "",
+      views,
+      reviews,
+      enrollments,
+      completions,
+      completionRate: cr,
+      interactionRate: interactionRate(reviews, views),
+      avgTimeSpentSeconds: avgTimeSpentSeconds(progressDocs),
+      avgPercentComplete: avgPercentComplete(progressDocs),
+      engagementScore: engagementScore({
+        completionRate: cr,
+        interactionRate: interactionRate(reviews, views),
+        avgPercentComplete: avgPercentComplete(progressDocs),
+      }),
+    };
+  }
+
+  /**
+   * Build the metrics row for a single book.
+   *
+   * @param {object} book - Lean Book document.
+   * @param {Array<object>} progressDocs - ReadingProgress records for the book.
+   * @returns {object} The metrics row.
+   */
+  _bookRow(book, progressDocs) {
+    const views = book.readCount || 0;
+    const reviews = book.numReviews || 0;
+    // Books have no enrollments; learner depth is the average reading progress
+    // (ReadingProgress stores the field as `percentage`, not `percentComplete`).
+    const apc = avgPercentComplete(
+      progressDocs.map((p) => ({ percentComplete: p.percentage }))
+    );
+
+    return {
+      id: String(book._id),
+      type: "book",
+      title: book.title,
+      category: book.category || "",
+      views,
+      reviews,
+      enrollments: 0,
+      completions: 0,
+      completionRate: apc, // proxy: avg reading progress percentage
+      interactionRate: interactionRate(reviews, views),
+      avgTimeSpentSeconds: 0,
+      avgPercentComplete: apc,
+      engagementScore: engagementScore({
+        completionRate: apc,
+        interactionRate: interactionRate(reviews, views),
+        avgPercentComplete: apc,
+      }),
+    };
+  }
+
+  /**
+   * Comparative analytics across ALL content (courses + books), sorted by
+   * views, with a platform-level roll-up.
+   *
+   * @returns {Promise<{summary: object, content: object[]}>}
+   */
+  async getContentPerformance() {
+    const [courses, books] = await Promise.all([
+      Course.find().lean(),
+      Book.find().lean(),
+    ]);
+
+    const [courseProgress, bookProgress] = await Promise.all([
+      CourseProgress.find({ course: { $in: courses.map((c) => c._id) } }).lean(),
+      ReadingProgress.find({ book: { $in: books.map((b) => b._id) } }).lean(),
+    ]);
+
+    const progressByCourse = this._groupBy(courseProgress, "course");
+    const progressByBook = this._groupBy(bookProgress, "book");
+
+    const content = [
+      ...courses.map((course) =>
+        this._courseRow(course, progressByCourse.get(String(course._id)) || [])
+      ),
+      ...books.map((book) =>
+        this._bookRow(book, progressByBook.get(String(book._id)) || [])
+      ),
+    ].sort((a, b) => b.views - a.views);
+
+    // Course-only completion average for the roll-up (books have no enrollments).
+    const courseRows = content.filter((row) => row.type === "course");
+    const avgCourseCompletion = courseRows.length
+      ? Math.round(
+          (courseRows.reduce((sum, r) => sum + r.completionRate, 0) /
+            courseRows.length) *
+            100
+        ) / 100
+      : 0;
+
+    return {
+      summary: {
+        totalContent: content.length,
+        totalCourses: courseRows.length,
+        totalBooks: content.length - courseRows.length,
+        totalViews: content.reduce((sum, r) => sum + r.views, 0),
+        totalReviews: content.reduce((sum, r) => sum + r.reviews, 0),
+        avgCompletionRate: avgCourseCompletion,
+        topByViews: [...content].sort((a, b) => b.views - a.views).slice(0, 3),
+        topByEngagement: [...content]
+          .sort((a, b) => b.engagementScore - a.engagementScore)
+          .slice(0, 3),
+      },
+      content,
+    };
+  }
+
+  /**
+   * Metrics for a single course or book.
+   *
+   * @param {object} params
+   * @param {"course"|"book"} params.type - Content type.
+   * @param {string} params.id - Content ObjectId.
+   * @returns {Promise<object|null>} The metrics row, or null when not found.
+   */
+  async getContentMetrics({ type, id }) {
+    if (type === "course") {
+      const course = await Course.findById(id).lean();
+      if (!course) return null;
+      const progressDocs = await CourseProgress.find({ course: id }).lean();
+      return this._courseRow(course, progressDocs);
+    }
+    if (type === "book") {
+      const book = await Book.findById(id).lean();
+      if (!book) return null;
+      const progressDocs = await ReadingProgress.find({ book: id }).lean();
+      return this._bookRow(book, progressDocs);
+    }
+    return null;
+  }
+
+  /**
+   * Group a list of documents by a field, keyed by its string value.
+   *
+   * @param {Array<object>} docs - Documents to group.
+   * @param {string} field - Field name to group by.
+   * @returns {Map<string, object[]>}
+   */
+  _groupBy(docs, field) {
+    const groups = new Map();
+    for (const doc of docs) {
+      const key = String(doc[field]);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(doc);
+    }
+    return groups;
+  }
+}
+
+export const contentMetricsService = new ContentMetricsService();
+export default contentMetricsService;