@momentumcms/plugins-analytics 0.3.0 → 0.4.1

package/index.cjs

@@ -36,6 +36,10 @@ __export(block_tracker_exports, {
   attachBlockTracking: () => attachBlockTracking
 });
 function attachBlockTracking(tracker, container) {
+  if (typeof document === "undefined" || !document.body) {
+    return () => {
+    };
+  }
   const root = container ?? document.body;
   const impressionsSeen = /* @__PURE__ */ new Set();
   const hoverCooldowns = /* @__PURE__ */ new Map();
@@ -405,16 +409,20 @@ __export(src_exports, {
   TrackingRules: () => TrackingRules,
   analyticsPlugin: () => analyticsPlugin,
   attachBlockTracking: () => attachBlockTracking,
+  compileContentRoutes: () => compileContentRoutes,
   createAnalyticsMiddleware: () => createAnalyticsMiddleware,
   createAnalyticsQueryRouter: () => createAnalyticsQueryRouter,
   createApiCollectorMiddleware: () => createApiCollectorMiddleware,
   createContentPerformanceRouter: () => createContentPerformanceRouter,
   createIngestRouter: () => createIngestRouter,
+  createPageViewCollectorMiddleware: () => createPageViewCollectorMiddleware,
   createRuleEngine: () => createRuleEngine,
   createTracker: () => createTracker,
   createTrackingRulesRouter: () => createTrackingRulesRouter,
   injectBlockAnalyticsFields: () => injectBlockAnalyticsFields,
   injectCollectionCollector: () => injectCollectionCollector,
+  isBot: () => isBot,
+  matchContentRoute: () => matchContentRoute,
   parseUserAgent: () => parseUserAgent,
   postgresAnalyticsAdapter: () => postgresAnalyticsAdapter
 });
@@ -872,8 +880,210 @@ function createApiCollectorMiddleware(emitter) {
   };
 }
 
-// libs/plugins/analytics/src/lib/ingest-handler.ts
+// libs/plugins/analytics/src/lib/collectors/page-view-collector.ts
 var import_node_crypto3 = require("node:crypto");
+
+// libs/plugins/analytics/src/lib/utils/content-route-matcher.ts
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function compileContentRoute(collection, pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  const paramNames = [];
+  let staticCount = 0;
+  const regexParts = segments.map((seg) => {
+    if (seg.startsWith(":")) {
+      paramNames.push(seg.slice(1));
+      return "([^/]+)";
+    }
+    staticCount++;
+    return escapeRegex(seg);
+  });
+  const regexStr = "^/" + regexParts.join("/") + "/?$";
+  return {
+    collection,
+    pattern,
+    regex: new RegExp(regexStr),
+    paramNames,
+    staticSegments: staticCount
+  };
+}
+function compileContentRoutes(routes) {
+  const compiled = Object.entries(routes).map(
+    ([collection, pattern]) => compileContentRoute(collection, pattern)
+  );
+  compiled.sort((a, b) => b.staticSegments - a.staticSegments);
+  return compiled;
+}
+function matchContentRoute(path, routes) {
+  for (const route of routes) {
+    const match = route.regex.exec(path);
+    if (match) {
+      const params = {};
+      for (let i = 0; i < route.paramNames.length; i++) {
+        params[route.paramNames[i]] = match[i + 1];
+      }
+      return { collection: route.collection, params };
+    }
+  }
+  return void 0;
+}
+
+// libs/plugins/analytics/src/lib/collectors/page-view-collector.ts
+var DEFAULT_EXCLUDE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".js",
+  ".css",
+  ".ico",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".svg",
+  ".webp",
+  ".avif",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".map",
+  ".json",
+  ".xml",
+  ".txt",
+  ".mp4",
+  ".webm",
+  ".ogg",
+  ".mp3"
+]);
+var ALWAYS_EXCLUDED_PREFIXES = [
+  "/api/",
+  "/admin",
+  "/__vite",
+  "/@fs/",
+  "/@id/",
+  "/.analog/",
+  "/node_modules/"
+];
+var ALWAYS_EXCLUDED_EXACT = /* @__PURE__ */ new Set([
+  "/api",
+  "/favicon.ico",
+  "/robots.txt",
+  "/sitemap.xml",
+  "/sitemap-index.xml",
+  "/health",
+  "/healthz",
+  "/ready",
+  "/.well-known/security.txt"
+]);
+var BOT_PATTERN = /bot|crawl|spider|slurp|bingpreview|mediapartners|facebookexternalhit|linkedinbot|twitterbot|whatsapp|telegrambot|discordbot|applebot|duckduckbot|yandex|baidu|sogou|ia_archiver|semrush|ahref|mj12bot|dotbot|petalbot|bytespider/i;
+function isBot(ua) {
+  if (!ua)
+    return false;
+  return BOT_PATTERN.test(ua);
+}
+function shouldExcludePath(path, excludeExtensions, excludePaths) {
+  if (ALWAYS_EXCLUDED_EXACT.has(path))
+    return true;
+  for (const prefix of ALWAYS_EXCLUDED_PREFIXES) {
+    if (path.startsWith(prefix))
+      return true;
+  }
+  for (const pattern of excludePaths) {
+    if (path.startsWith(pattern))
+      return true;
+  }
+  const dotIndex = path.lastIndexOf(".");
+  if (dotIndex !== -1) {
+    const ext = path.slice(dotIndex).toLowerCase();
+    if (excludeExtensions.has(ext))
+      return true;
+  }
+  return false;
+}
+function extractUserId(req) {
+  if (!("user" in req))
+    return void 0;
+  const user = req["user"];
+  if (user == null || typeof user !== "object")
+    return void 0;
+  if (!("id" in user))
+    return void 0;
+  const id = user.id;
+  return typeof id === "string" ? id : void 0;
+}
+function createPageViewCollectorMiddleware(emitter, options = {}) {
+  const excludeExtensions = options.excludeExtensions ? new Set(options.excludeExtensions) : DEFAULT_EXCLUDE_EXTENSIONS;
+  const excludePaths = options.excludePaths ?? [];
+  const onlySuccessful = options.onlySuccessful !== false;
+  const trackBots = options.trackBots === true;
+  const compiledRoutes = options.contentRoutes ? compileContentRoutes(options.contentRoutes) : void 0;
+  return (req, res, next) => {
+    if (req.method !== "GET") {
+      next();
+      return;
+    }
+    const path = req.path;
+    if (shouldExcludePath(path, excludeExtensions, excludePaths)) {
+      next();
+      return;
+    }
+    const ua = req.headers["user-agent"];
+    if (!trackBots && isBot(ua)) {
+      next();
+      return;
+    }
+    const start = Date.now();
+    res.once("finish", () => {
+      if (onlySuccessful && (res.statusCode < 200 || res.statusCode >= 300)) {
+        return;
+      }
+      const duration = Date.now() - start;
+      const parsed = parseUserAgent(ua);
+      const refHeader = req.headers["referer"] ?? req.headers["referrer"];
+      const referrer = Array.isArray(refHeader) ? refHeader[0] : refHeader;
+      let contentCollection;
+      let contentSlug;
+      if (compiledRoutes) {
+        const routeMatch = matchContentRoute(path, compiledRoutes);
+        if (routeMatch) {
+          contentCollection = routeMatch.collection;
+          contentSlug = routeMatch.params["slug"];
+        }
+      }
+      const event = {
+        id: (0, import_node_crypto3.randomUUID)(),
+        category: "page",
+        name: "page_view",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        userId: extractUserId(req),
+        properties: {
+          method: req.method,
+          path,
+          statusCode: res.statusCode,
+          ...contentCollection != null ? { collection: contentCollection } : {},
+          ...contentSlug != null ? { slug: contentSlug } : {}
+        },
+        context: {
+          source: "server",
+          url: req.originalUrl,
+          referrer,
+          userAgent: ua,
+          ip: req.ip ?? req.socket.remoteAddress,
+          device: parsed.device,
+          browser: parsed.browser,
+          os: parsed.os,
+          duration,
+          statusCode: res.statusCode,
+          ...contentCollection != null ? { collection: contentCollection } : {}
+        }
+      };
+      emitter(event);
+    });
+    next();
+  };
+}
+
+// libs/plugins/analytics/src/lib/ingest-handler.ts
+var import_node_crypto4 = require("node:crypto");
 var import_express = require("express");
 
 // libs/core/src/lib/collections/define-collection.ts
@@ -1154,7 +1364,7 @@ function createIngestRouter(options) {
       }
       const partial = raw;
       const event = {
-        id: (0, import_node_crypto3.randomUUID)(),
+        id: (0, import_node_crypto4.randomUUID)(),
         category: partial.category ?? "custom",
         name: partial.name ?? "unknown",
         // Server-side timestamp (prevents client clock skew)
@@ -1760,6 +1970,42 @@ function matchesDocumentUrl(eventUrl, documentPath) {
   }
   return pathname === documentPath || pathname === `${documentPath}/`;
 }
+async function queryEventsByDocument(queryFn, eventName, collection, documentId, documentPath, options) {
+  const queryBase = {
+    ...options.category ? { category: options.category } : {},
+    name: eventName,
+    from: options.from,
+    to: options.to,
+    limit: 1e3
+  };
+  const [serverResult, allResult] = await Promise.all([
+    queryFn({ ...queryBase, collection }),
+    queryFn(queryBase)
+  ]);
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const e of [...serverResult.events, ...allResult.events]) {
+    if (seen.has(e.id))
+      continue;
+    seen.add(e.id);
+    const matchesCollection = e.context.collection === collection || e.properties["collection"] === collection;
+    const matchesSlug = typeof e.properties["slug"] === "string" && e.properties["slug"] === documentId;
+    if (matchesCollection && matchesSlug)
+      results.push(e);
+  }
+  if (results.length > 0)
+    return results;
+  const urlResult = await queryFn({ ...queryBase, search: documentPath });
+  return urlResult.events.filter((e) => matchesDocumentUrl(e.context.url, documentPath));
+}
+function countByBlockType(events) {
+  const map = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const bt = String(event.properties["blockType"] ?? "unknown");
+    map.set(bt, (map.get(bt) ?? 0) + 1);
+  }
+  return map;
+}
 function createContentPerformanceRouter(adapter) {
   const router = (0, import_express3.Router)();
   router.get("/content-performance", requireAdmin, async (req, res) => {
@@ -1778,16 +2024,15 @@ function createContentPerformanceRouter(adapter) {
         return;
       }
       const documentPath = `/${collection}/${documentId}`;
-      const pageViewResult = await adapter.query({
-        category: "page",
-        name: "page_view",
-        search: documentPath,
-        from,
-        to,
-        limit: 1e3
-      });
-      const pageViewEvents = pageViewResult.events.filter(
-        (e) => matchesDocumentUrl(e.context.url, documentPath)
+      const queryFn = adapter.query.bind(adapter);
+      const dateRange = { from, to };
+      const pageViewEvents = await queryEventsByDocument(
+        queryFn,
+        "page_view",
+        collection,
+        documentId,
+        documentPath,
+        { category: "page", ...dateRange }
       );
       const visitorSet = /* @__PURE__ */ new Set();
       const referrerMap = /* @__PURE__ */ new Map();
@@ -1802,38 +2047,26 @@ function createContentPerformanceRouter(adapter) {
       }
       let blockEngagement;
       try {
-        const [impressionResult, hoverResult] = await Promise.all([
-          adapter.query({
-            name: "block_impression",
-            search: documentPath,
-            from,
-            to,
-            limit: 1e3
-          }),
-          adapter.query({
-            name: "block_hover",
-            search: documentPath,
-            from,
-            to,
-            limit: 1e3
-          })
+        const [impressionEvents, hoverEvents] = await Promise.all([
+          queryEventsByDocument(
+            queryFn,
+            "block_impression",
+            collection,
+            documentId,
+            documentPath,
+            dateRange
+          ),
+          queryEventsByDocument(
+            queryFn,
+            "block_hover",
+            collection,
+            documentId,
+            documentPath,
+            dateRange
+          )
         ]);
-        const impressionEvents = impressionResult.events.filter(
-          (e) => matchesDocumentUrl(e.context.url, documentPath)
-        );
-        const hoverEvents = hoverResult.events.filter(
-          (e) => matchesDocumentUrl(e.context.url, documentPath)
-        );
-        const impressionMap = /* @__PURE__ */ new Map();
-        for (const event of impressionEvents) {
-          const bt = String(event.properties["blockType"] ?? "unknown");
-          impressionMap.set(bt, (impressionMap.get(bt) ?? 0) + 1);
-        }
-        const hoverMap = /* @__PURE__ */ new Map();
-        for (const event of hoverEvents) {
-          const bt = String(event.properties["blockType"] ?? "unknown");
-          hoverMap.set(bt, (hoverMap.get(bt) ?? 0) + 1);
-        }
+        const impressionMap = countByBlockType(impressionEvents);
+        const hoverMap = countByBlockType(hoverEvents);
         const allTypes = /* @__PURE__ */ new Set([...impressionMap.keys(), ...hoverMap.keys()]);
         if (allTypes.size > 0) {
           blockEngagement = [];
@@ -2086,11 +2319,11 @@ function analyticsPlugin(config) {
     // Browser-safe import paths for the admin config generator
     browserImports: {
       adminRoutes: {
-        path: "@momentumcms/plugins/analytics/admin-routes",
+        path: "@momentumcms/plugins-analytics/admin-routes",
         exportName: "analyticsAdminRoutes"
       },
       modifyCollections: {
-        path: "@momentumcms/plugins/analytics/block-fields",
+        path: "@momentumcms/plugins-analytics/block-fields",
         exportName: "injectBlockAnalyticsFields"
       }
     },
@@ -2141,6 +2374,19 @@ function analyticsPlugin(config) {
           position: "before-api"
         });
       }
+      if (config.trackPageViews !== false) {
+        const pageViewOptions = typeof config.trackPageViews === "object" ? config.trackPageViews : {};
+        const pageViewCollector = createPageViewCollectorMiddleware(
+          (event) => eventStore.add(event),
+          pageViewOptions
+        );
+        registerMiddleware({
+          path: "/",
+          handler: pageViewCollector,
+          position: "root"
+        });
+        logger.info("Page view tracking enabled");
+      }
       if (config.contentPerformance !== false) {
         const contentPerfRouter = createContentPerformanceRouter(config.adapter);
         registerMiddleware({
@@ -2226,16 +2472,20 @@ init_rule_engine();
   TrackingRules,
   analyticsPlugin,
   attachBlockTracking,
+  compileContentRoutes,
   createAnalyticsMiddleware,
   createAnalyticsQueryRouter,
   createApiCollectorMiddleware,
   createContentPerformanceRouter,
   createIngestRouter,
+  createPageViewCollectorMiddleware,
   createRuleEngine,
   createTracker,
   createTrackingRulesRouter,
   injectBlockAnalyticsFields,
   injectCollectionCollector,
+  isBot,
+  matchContentRoute,
   parseUserAgent,
   postgresAnalyticsAdapter
 });