webspresso 0.0.97 → 0.0.98

package/plugins/site-analytics/index.js

@@ -9,11 +9,14 @@ const { createAnalyticsApiHandlers } = require('./api-handlers');
 const { generateAnalyticsComponent } = require('./admin-component');
 const { generateErrorTrackerScript } = require('./client-error-tracker');
 const { createErrorReportHandler } = require('./client-error-handler');
+const { purgeAnalyticsData } = require('./purge');
 
 /**
  * Site Analytics Plugin Factory
  * @param {Object} options
  * @param {Object} options.db - Database instance (must expose .knex)
+ * @param {string} [options.title] - Admin page title
+ * @param {string} [options.adminTitle] - Admin page title alias
  * @param {string[]} [options.excludePaths=[]] - Extra paths to exclude from tracking
  * @param {boolean} [options.trackBots=true] - Record bot visits (still counted separately)
  * @param {string} [options.tableName='analytics_page_views'] - DB table name
@@ -21,11 +24,22 @@ const { createErrorReportHandler } = require('./client-error-handler');
  * @param {number} [options.flushIntervalMs=3000] - Flush interval for low traffic
  * @param {boolean} [options.trackClientErrors=true] - Capture and report client-side JS errors
  * @param {string} [options.errorsTableName='analytics_client_errors'] - Client errors table
+ * @param {Object|boolean} [options.retention] - Retention policy configuration (set false to disable)
+ * @param {number} [options.retention.days=90] - Days to retain page views
+ * @param {number} [options.retention.errorDays=30] - Days to retain client errors
+ * @param {number} [options.retention.intervalMs=86400000] - Auto-cleanup timer frequency (24h)
+ * @param {boolean} [options.retention.runOnStart=true] - Run initial purge shortly after startup
+ * @param {number} [options.retentionDays=90] - Shorthand for retention.days
+ * @param {number} [options.errorRetentionDays=30] - Shorthand for retention.errorDays
+ * @param {number} [options.cleanupIntervalMs=86400000] - Shorthand for retention.intervalMs
+ * @param {boolean} [options.autoCleanup=true] - Enable/disable background periodic cleanup
  * @returns {Object} Plugin definition
  */
 function siteAnalyticsPlugin(options = {}) {
   const {
     db,
+    title,
+    adminTitle,
     excludePaths = [],
     trackBots = true,
     tableName = 'analytics_page_views',
@@ -33,14 +47,103 @@ function siteAnalyticsPlugin(options = {}) {
     errorsTableName = 'analytics_client_errors',
   } = options;
 
+  const pageTitle = title || adminTitle || 'Analytics';
+
   if (!db) {
     throw new Error('site-analytics plugin requires a database instance. Pass `db` in options.');
   }
 
+  // Retention configuration
+  const retentionOption = options.retention;
+  const isRetentionDisabled =
+    retentionOption === false ||
+    (typeof retentionOption === 'object' && retentionOption.enabled === false) ||
+    options.retentionDays === null ||
+    options.retentionDays === 0;
+
+  const autoCleanupEnabled =
+    !isRetentionDisabled &&
+    options.autoCleanup !== false &&
+    (typeof retentionOption !== 'object' || retentionOption.autoCleanup !== false);
+
+  const retentionConfig = {
+    enabled: !isRetentionDisabled,
+    autoCleanup: autoCleanupEnabled,
+    days: (typeof options.retentionDays === 'number' && options.retentionDays > 0)
+      ? options.retentionDays
+      : (typeof retentionOption === 'object' && retentionOption?.days ? retentionOption.days : 90),
+    errorDays: (typeof options.errorRetentionDays === 'number' && options.errorRetentionDays > 0)
+      ? options.errorRetentionDays
+      : (typeof retentionOption === 'object' && retentionOption?.errorDays ? retentionOption.errorDays : 30),
+    intervalMs: (typeof options.cleanupIntervalMs === 'number' && options.cleanupIntervalMs > 0)
+      ? options.cleanupIntervalMs
+      : (typeof retentionOption === 'object' && retentionOption?.intervalMs ? retentionOption.intervalMs : 24 * 60 * 60 * 1000),
+    runOnStart: (typeof retentionOption === 'object' && retentionOption?.runOnStart !== undefined)
+      ? !!retentionOption.runOnStart
+      : (options.cleanupOnStart !== undefined ? !!options.cleanupOnStart : true),
+  };
+
+  let cleanupInterval = null;
+  let cleanupStartTimeout = null;
+
+  async function runCleanup() {
+    try {
+      const knex = db.knex || db;
+      return await purgeAnalyticsData(knex, {
+        tableName,
+        errorsTableName,
+        days: retentionConfig.days,
+        errorDays: retentionConfig.errorDays,
+      });
+    } catch (err) {
+      if (process.env.NODE_ENV !== 'test') {
+        console.warn('[site-analytics] Failed to run retention cleanup:', err.message);
+      }
+    }
+  }
+
+  function startCleanup(customIntervalMs) {
+    stopCleanup();
+    if (!retentionConfig.enabled) return;
+    if (typeof customIntervalMs === 'number' && customIntervalMs > 0) {
+      retentionConfig.intervalMs = customIntervalMs;
+    }
+
+    if (retentionConfig.runOnStart) {
+      const delayMs = typeof options.cleanupStartDelayMs === 'number'
+        ? options.cleanupStartDelayMs
+        : (process.env.NODE_ENV === 'test' ? 50 : 5000);
+      cleanupStartTimeout = setTimeout(() => {
+        runCleanup();
+      }, delayMs);
+      if (cleanupStartTimeout && cleanupStartTimeout.unref) {
+        cleanupStartTimeout.unref();
+      }
+    }
+
+    cleanupInterval = setInterval(() => {
+      runCleanup();
+    }, retentionConfig.intervalMs);
+    if (cleanupInterval && cleanupInterval.unref) {
+      cleanupInterval.unref();
+    }
+  }
+
+  function stopCleanup() {
+    if (cleanupStartTimeout) {
+      clearTimeout(cleanupStartTimeout);
+      cleanupStartTimeout = null;
+    }
+    if (cleanupInterval) {
+      clearInterval(cleanupInterval);
+      cleanupInterval = null;
+    }
+  }
+
   return {
     name: 'site-analytics',
     version: '1.0.0',
-    description: 'Self-hosted page view analytics with admin dashboard',
+    description: 'Self-hosted page view analytics with admin dashboard and auto-retention cleanup',
     dependencies: { 'admin-panel': '*' },
 
     csp: {
@@ -48,6 +151,29 @@ function siteAnalyticsPlugin(options = {}) {
       connectSrc: ['https://cdn.jsdelivr.net'],
     },
 
+    api: {
+      purge(opts = {}) {
+        const knex = db.knex || db;
+        return purgeAnalyticsData(knex, {
+          tableName,
+          errorsTableName,
+          days: opts.days !== undefined ? opts.days : (opts.retentionDays !== undefined ? opts.retentionDays : retentionConfig.days),
+          errorDays: opts.errorDays !== undefined ? opts.errorDays : (opts.errorRetentionDays !== undefined ? opts.errorRetentionDays : retentionConfig.errorDays),
+          ...opts,
+        });
+      },
+      purgeAnalyticsData: (kx, opts) => purgeAnalyticsData(kx || db.knex || db, {
+        tableName,
+        errorsTableName,
+        ...opts,
+      }),
+      startCleanup,
+      stopCleanup,
+      getRetentionConfig() {
+        return { ...retentionConfig };
+      },
+    },
+
     register(ctx) {
       const knex = db.knex || db;
 
@@ -66,6 +192,22 @@ function siteAnalyticsPlugin(options = {}) {
         const script = generateErrorTrackerScript({ endpoint: '/_analytics/report-error' });
         ctx.injectBody(`<script>${script}</script>`, { id: 'site-analytics-error-tracker', priority: 5 });
       }
+
+      if (retentionConfig.enabled && autoCleanupEnabled) {
+        startCleanup();
+      }
+
+      return () => {
+        stopCleanup();
+      };
+    },
+
+    dispose() {
+      stopCleanup();
+    },
+
+    shutdown() {
+      stopCleanup();
     },
 
     onRoutesReady(ctx) {
@@ -91,10 +233,11 @@ function siteAnalyticsPlugin(options = {}) {
 
       adminApi.registerModule({
         id: 'analytics',
+        title: pageTitle,
 
         pages: [{
           id: 'analytics',
-          title: 'Analytics',
+          title: pageTitle,
           path: '/analytics',
           icon: 'chart',
           component: generateAnalyticsComponent(),
@@ -119,6 +262,7 @@ function siteAnalyticsPlugin(options = {}) {
             { method: 'get', path: '/countries', handler: handlers.getCountries },
             { method: 'get', path: '/client-errors', handler: handlers.getClientErrors },
             { method: 'get', path: '/recent', handler: handlers.getRecent },
+            { method: 'post', path: '/purge', handler: handlers.purge },
           ],
         },
       });
@@ -127,3 +271,4 @@ function siteAnalyticsPlugin(options = {}) {
 }
 
 module.exports = siteAnalyticsPlugin;
+module.exports.purgeAnalyticsData = purgeAnalyticsData;

package/plugins/site-analytics/purge.js

@@ -0,0 +1,168 @@
+/**
+ * Analytics Data Purge & Retention Service
+ * Deletes page views and client errors older than a retention cutoff to prevent database bloat.
+ * @module plugins/site-analytics/purge
+ */
+
+'use strict';
+
+/**
+ * Purge old analytics data from database
+ * @param {import('knex').Knex} knex - Knex query builder instance
+ * @param {Object} [options={}] - Purge options
+ * @param {string} [options.tableName='analytics_page_views'] - Page views table name
+ * @param {string} [options.errorsTableName='analytics_client_errors'] - Client errors table name
+ * @param {Date|string|number} [options.olderThan] - Cutoff date for page views
+ * @param {Date|string|number} [options.errorsOlderThan] - Cutoff date for client errors
+ * @param {Date|string|number} [options.errorOlderThan] - Alias for errorsOlderThan
+ * @param {number} [options.days] - Days of page views to keep (if olderThan not specified)
+ * @param {number} [options.retentionDays=90] - Days of page views to keep (alias for days)
+ * @param {number} [options.errorDays] - Days of client errors to keep (if errorsOlderThan not specified)
+ * @param {number} [options.errorRetentionDays=30] - Days of client errors to keep (alias for errorDays)
+ * @param {boolean} [options.purgePageViews=true] - Whether to purge page views
+ * @param {boolean} [options.purgeErrors=true] - Whether to purge client errors
+ * @returns {Promise<{ ok: boolean, success: boolean, viewsDeleted: number, pageViewsDeleted: number, errorsDeleted: number, totalDeleted: number, olderThan: Date, errorOlderThan: Date, viewsCutoff: string, errorsCutoff: string }>}
+ */
+async function purgeAnalyticsData(knex, options = {}) {
+  if (!knex) {
+    throw new Error('purgeAnalyticsData requires a database (knex) instance');
+  }
+
+  const tableName = options.tableName || 'analytics_page_views';
+  const errorsTableName = options.errorsTableName || 'analytics_client_errors';
+  const purgePageViews = options.purgePageViews !== false;
+  const purgeErrors = options.purgeErrors !== false;
+
+  const now = Date.now();
+
+  // Validate days / retentionDays
+  if (options.days !== undefined) {
+    const d = typeof options.days === 'number' ? options.days : Number(options.days);
+    if (Number.isNaN(d) || d <= 0) {
+      throw new Error('purgeAnalyticsData: days must be a positive number');
+    }
+  }
+  if (options.retentionDays !== undefined) {
+    const d = typeof options.retentionDays === 'number' ? options.retentionDays : Number(options.retentionDays);
+    if (Number.isNaN(d) || d <= 0) {
+      throw new Error('purgeAnalyticsData: retentionDays must be a positive number');
+    }
+  }
+
+  // Validate errorDays / errorRetentionDays
+  if (options.errorDays !== undefined) {
+    const ed = typeof options.errorDays === 'number' ? options.errorDays : Number(options.errorDays);
+    if (Number.isNaN(ed) || ed <= 0) {
+      throw new Error('purgeAnalyticsData: errorDays must be a positive number');
+    }
+  }
+  if (options.errorRetentionDays !== undefined) {
+    const ed = typeof options.errorRetentionDays === 'number' ? options.errorRetentionDays : Number(options.errorRetentionDays);
+    if (Number.isNaN(ed) || ed <= 0) {
+      throw new Error('purgeAnalyticsData: errorRetentionDays must be a positive number');
+    }
+  }
+
+  // Calculate or validate page views cutoff
+  let olderThan;
+  if (options.olderThan !== undefined) {
+    olderThan = options.olderThan instanceof Date ? options.olderThan : new Date(options.olderThan);
+    if (Number.isNaN(olderThan.getTime())) {
+      throw new Error('purgeAnalyticsData: invalid olderThan date');
+    }
+  } else {
+    const daysRaw = options.days !== undefined ? options.days : (options.retentionDays !== undefined ? options.retentionDays : 90);
+    const days = Number(daysRaw);
+    olderThan = new Date(now - days * 24 * 60 * 60 * 1000);
+  }
+
+  // Calculate or validate client errors cutoff
+  let errorOlderThan;
+  const rawErrorCutoff = options.errorsOlderThan !== undefined ? options.errorsOlderThan : options.errorOlderThan;
+  if (rawErrorCutoff !== undefined) {
+    errorOlderThan = rawErrorCutoff instanceof Date ? rawErrorCutoff : new Date(rawErrorCutoff);
+    if (Number.isNaN(errorOlderThan.getTime())) {
+      throw new Error('purgeAnalyticsData: invalid errorsOlderThan date');
+    }
+  } else {
+    const errDaysRaw = options.errorDays !== undefined
+      ? options.errorDays
+      : (options.errorRetentionDays !== undefined ? options.errorRetentionDays : 30);
+    const errDays = Number(errDaysRaw);
+    errorOlderThan = new Date(now - errDays * 24 * 60 * 60 * 1000);
+  }
+
+  function applyCutoffFilter(query, columnName, cutoffDate) {
+    const client = knex?.client?.config?.client;
+    const isSqlite = client === 'sqlite3' || client === 'better-sqlite3';
+    if (isSqlite) {
+      const iso = cutoffDate.toISOString();
+      const formatted = iso.replace('T', ' ').replace(/\..+$/, '');
+      return query.where((builder) => {
+        builder
+          .where(columnName, '<', iso)
+          .orWhere(columnName, '<', formatted)
+          .orWhere(columnName, '<', cutoffDate.getTime());
+      });
+    }
+    return query.where(columnName, '<', cutoffDate);
+  }
+
+  let pageViewsDeleted = 0;
+  let errorsDeleted = 0;
+
+  if (purgePageViews) {
+    let hasTable = true;
+    if (knex.schema && typeof knex.schema.hasTable === 'function') {
+      try {
+        hasTable = await knex.schema.hasTable(tableName);
+      } catch (e) {
+        hasTable = false;
+      }
+    }
+    if (hasTable) {
+      try {
+        const deleted = await applyCutoffFilter(knex(tableName), 'created_at', olderThan).delete();
+        pageViewsDeleted = Number(deleted) || 0;
+      } catch (e) {
+        // Table or deletion error handled safely
+      }
+    }
+  }
+
+  if (purgeErrors) {
+    let hasTable = true;
+    if (knex.schema && typeof knex.schema.hasTable === 'function') {
+      try {
+        hasTable = await knex.schema.hasTable(errorsTableName);
+      } catch (e) {
+        hasTable = false;
+      }
+    }
+    if (hasTable) {
+      try {
+        const deleted = await applyCutoffFilter(knex(errorsTableName), 'created_at', errorOlderThan).delete();
+        errorsDeleted = Number(deleted) || 0;
+      } catch (e) {
+        // Table or deletion error handled safely
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    success: true,
+    viewsDeleted: pageViewsDeleted,
+    pageViewsDeleted,
+    errorsDeleted,
+    totalDeleted: pageViewsDeleted + errorsDeleted,
+    olderThan,
+    errorOlderThan,
+    viewsCutoff: olderThan.toISOString(),
+    errorsCutoff: errorOlderThan.toISOString(),
+  };
+}
+
+module.exports = {
+  purgeAnalyticsData,
+};