webspresso 0.0.52 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {

package/plugins/site-analytics/admin-component.js

@@ -218,6 +218,7 @@ var AnalyticsPage = {
       analyticsApi('top-pages', days),
       analyticsApi('bot-activity', days),
       analyticsApi('countries', days),
+      analyticsApi('client-errors', days),
       analyticsApi('recent', days),
     ]).then(function(results) {
       vnode.state.stats = results[0];
@@ -225,7 +226,8 @@ var AnalyticsPage = {
       vnode.state.topPages = results[2];
       vnode.state.botActivity = results[3];
       vnode.state.countries = results[4];
-      vnode.state.recent = results[5];
+      vnode.state.clientErrors = results[5];
+      vnode.state.recent = results[6];
       vnode.state.loading = false;
 
       if (chartInstance) {
@@ -384,6 +386,33 @@ var AnalyticsPage = {
             ]),
           ]),
 
+          // Client Errors
+          m('div.bg-white.rounded-lg.shadow.mb-6', [
+            m('div.px-5.py-4.border-b.border-gray-100.flex.items-center.justify-between', [
+              m('h3.text-sm.font-semibold.text-gray-900.flex.items-center.gap-2', [
+                m('span', '⚠️'),
+                'Client Errors',
+              ]),
+              m('span.text-xs.text-gray-400', 'Last ' + s.days + ' days'),
+            ]),
+            m('div.p-4.max-h-64.overflow-y-auto', [
+              !s.clientErrors || s.clientErrors.length === 0
+                ? m('p.text-gray-400.text-sm.text-center.py-6', 'No client errors')
+                : s.clientErrors.slice(0, 15).map(function(err) {
+                    return m('div.border-b.border-gray-50.pb-3.mb-3.last:border-0.last:mb-0.last:pb-0', [
+                      m('div.flex.items-start.gap-2', [
+                        m('span.text-xs.px-1.5.py-0.5.rounded.bg-red-100.text-red-700', err.error_type || 'error'),
+                        m('span.text-xs.text-gray-500', relativeTime(err.created_at)),
+                      ]),
+                      m('p.text-sm.text-gray-800.font-mono.break-all.mt-1', {
+                        title: err.stack || err.message,
+                      }, (err.message || '').slice(0, 120) + (err.message && err.message.length > 120 ? '…' : '')),
+                      err.path && m('p.text-xs.text-gray-500.mt-0.5', err.path),
+                    ]);
+                  }),
+            ]),
+          ]),
+
           // Country Stats
           m('div.bg-white.rounded-lg.shadow.mb-6', [
             m('div.px-5.py-4.border-b.border-gray-100.flex.items-center.justify-between', [

package/plugins/site-analytics/api-handlers.js

@@ -11,7 +11,11 @@
  * @param {string} [options.tableName='analytics_page_views']
  */
 function createAnalyticsApiHandlers(options) {
-  const { knex, tableName = 'analytics_page_views' } = options;
+  const {
+    knex,
+    tableName = 'analytics_page_views',
+    errorsTableName = 'analytics_client_errors',
+  } = options;
 
   function parseDays(req) {
     const days = parseInt(req.query.days) || 30;
@@ -208,6 +212,32 @@ function createAnalyticsApiHandlers(options) {
     }
   }
 
+  /**
+   * GET /client-errors - Recent client-side JS errors
+   */
+  async function getClientErrors(req, res) {
+    try {
+      const days = parseDays(req);
+      const since = sinceDate(days);
+      const limit = Math.min(parseInt(req.query.limit) || 50, 200);
+
+      const hasTable = await knex.schema.hasTable(errorsTableName);
+      if (!hasTable) {
+        return res.json([]);
+      }
+
+      const rows = await knex(errorsTableName)
+        .select('id', 'error_type', 'message', 'stack', 'path', 'created_at')
+        .where('created_at', '>=', since)
+        .orderBy('created_at', 'desc')
+        .limit(limit);
+
+      res.json(rows);
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
   /**
    * GET /recent - Recent page views
    */
@@ -233,6 +263,7 @@ function createAnalyticsApiHandlers(options) {
     getTopPages,
     getBotActivity,
     getCountries,
+    getClientErrors,
     getRecent,
   };
 }

package/plugins/site-analytics/client-error-handler.js

@@ -0,0 +1,84 @@
+/**
+ * Client Error Report Handler
+ * Receives error reports from browser and stores in DB
+ * @module plugins/site-analytics/client-error-handler
+ */
+
+const DEFAULT_TABLE = 'analytics_client_errors';
+
+/**
+ * Create the client errors table
+ */
+async function ensureErrorsTable(knex, tableName = DEFAULT_TABLE) {
+  const exists = await knex.schema.hasTable(tableName);
+  if (!exists) {
+    await knex.schema.createTable(tableName, (table) => {
+      table.bigIncrements('id').primary();
+      table.string('error_type', 50).index(); // 'error' | 'unhandledrejection'
+      table.string('message', 500).index();
+      table.text('stack');
+      table.string('path', 500).index();
+      table.string('referrer', 500);
+      table.text('user_agent');
+      table.string('source', 500); // script url
+      table.integer('line');
+      table.integer('column');
+      table.timestamp('created_at').defaultTo(knex.fn.now()).index();
+    });
+  }
+}
+
+/**
+ * Create error report handler
+ * @param {Object} options
+ * @param {Object} options.knex - Knex instance
+ * @param {string} [options.tableName='analytics_client_errors']
+ */
+function createErrorReportHandler(options) {
+  const { knex, tableName = DEFAULT_TABLE } = options;
+  let tableReady = false;
+
+  return async function errorReportHandler(req, res) {
+    if (req.method !== 'POST') {
+      return res.status(405).json({ error: 'Method not allowed' });
+    }
+
+    try {
+      if (!tableReady) {
+        await ensureErrorsTable(knex, tableName);
+        tableReady = true;
+      }
+
+      const body = req.body || {};
+      const { type, message, stack, path, referrer, userAgent, source, line, column } = body;
+
+      if (!message && !stack) {
+        return res.status(400).json({ error: 'message or stack required' });
+      }
+
+      await knex(tableName).insert({
+        error_type: type || 'error',
+        message: String(message || '').slice(0, 500),
+        stack: stack ? String(stack).slice(0, 5000) : null,
+        path: path ? String(path).slice(0, 500) : null,
+        referrer: referrer ? String(referrer).slice(0, 500) : null,
+        user_agent: userAgent ? String(userAgent).slice(0, 1000) : null,
+        source: source ? String(source).slice(0, 500) : null,
+        line: line != null ? parseInt(line) : null,
+        column: column != null ? parseInt(column) : null,
+        created_at: knex.fn.now(),
+      });
+
+      res.status(202).json({ ok: true });
+    } catch (e) {
+      console.error('[site-analytics] Client error report failed:', e.message);
+      res.status(500).json({ error: 'Report failed' });
+    }
+  };
+}
+
+module.exports = {
+  createErrorReportHandler,
+  ensureErrorsTable,
+  DEFAULT_TABLE,
+};

package/plugins/site-analytics/client-error-tracker.js

@@ -0,0 +1,69 @@
+/**
+ * Client Error Tracker
+ * Generates inline script to catch JS errors and unhandled rejections, reports to backend
+ * @module plugins/site-analytics/client-error-tracker
+ */
+
+/**
+ * Generate client-side error tracking script
+ * @param {Object} options
+ * @param {string} [options.endpoint='/_analytics/report-error'] - POST endpoint for error reports
+ * @returns {string} Inline script content
+ */
+function generateErrorTrackerScript(options = {}) {
+  const endpoint = options.endpoint || '/_analytics/report-error';
+
+  return `
+(function() {
+  var endpoint = ${JSON.stringify(endpoint)};
+  var reported = {};
+  var MAX_STACK = 2000;
+
+  function report(type, message, stack, extra) {
+    var key = type + ':' + (message || '').slice(0, 100);
+    if (reported[key]) return;
+    reported[key] = true;
+
+    var payload = {
+      type: type,
+      message: String(message || 'Unknown error').slice(0, 500),
+      stack: stack ? String(stack).slice(0, MAX_STACK) : null,
+      path: window.location.pathname || '/',
+      referrer: document.referrer || null,
+      userAgent: navigator.userAgent || null
+    };
+    if (extra) {
+      for (var k in extra) payload[k] = extra[k];
+    }
+
+    try {
+      fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+        keepalive: true
+      }).catch(function(){});
+    } catch (e) {}
+  }
+
+  window.onerror = function(msg, url, line, col, err) {
+    report('error', err ? err.message : msg, err ? err.stack : null, { line: line, column: col, source: url });
+    return false;
+  };
+
+  window.addEventListener('unhandledrejection', function(e) {
+    var msg = e.reason;
+    var stack = null;
+    if (msg && typeof msg === 'object') {
+      stack = msg.stack;
+      msg = msg.message || String(msg);
+    } else {
+      msg = String(msg);
+    }
+    report('unhandledrejection', msg, stack);
+  });
+})();
+`.trim();
+}
+
+module.exports = { generateErrorTrackerScript };

package/plugins/site-analytics/index.js

@@ -7,6 +7,8 @@
 const { createTrackingMiddleware } = require('./tracking');
 const { createAnalyticsApiHandlers } = require('./api-handlers');
 const { generateAnalyticsComponent } = require('./admin-component');
+const { generateErrorTrackerScript } = require('./client-error-tracker');
+const { createErrorReportHandler } = require('./client-error-handler');
 
 /**
  * Site Analytics Plugin Factory
@@ -15,6 +17,10 @@ const { generateAnalyticsComponent } = require('./admin-component');
  * @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
+ * @param {number} [options.batchSize=20] - Flush page view queue when it reaches this size
+ * @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
  * @returns {Object} Plugin definition
  */
 function siteAnalyticsPlugin(options = {}) {
@@ -23,6 +29,8 @@ function siteAnalyticsPlugin(options = {}) {
     excludePaths = [],
     trackBots = true,
     tableName = 'analytics_page_views',
+    trackClientErrors = true,
+    errorsTableName = 'analytics_client_errors',
   } = options;
 
   if (!db) {
@@ -48,12 +56,26 @@ function siteAnalyticsPlugin(options = {}) {
         excludePaths,
         trackBots,
         tableName,
+        batchSize: options.batchSize ?? 20,
+        flushIntervalMs: options.flushIntervalMs ?? 3000,
       });
 
       ctx.app.use(trackingMiddleware);
+
+      if (trackClientErrors) {
+        const script = generateErrorTrackerScript({ endpoint: '/_analytics/report-error' });
+        ctx.injectBody(`<script>${script}</script>`, { id: 'site-analytics-error-tracker', priority: 5 });
+      }
     },
 
     onRoutesReady(ctx) {
+      // Client error report endpoint (must be in onRoutesReady - addRoute only mounts there)
+      if (trackClientErrors) {
+        const knex = db.knex || db;
+        const errorHandler = createErrorReportHandler({ knex, tableName: errorsTableName });
+        ctx.addRoute('post', '/_analytics/report-error', errorHandler);
+      }
+
       const adminApi = ctx.usePlugin('admin-panel');
       if (!adminApi) {
         console.warn('[site-analytics] admin-panel plugin not found, skipping admin page registration');
@@ -61,7 +83,11 @@ function siteAnalyticsPlugin(options = {}) {
       }
 
       const knex = db.knex || db;
-      const handlers = createAnalyticsApiHandlers({ knex, tableName });
+      const handlers = createAnalyticsApiHandlers({
+        knex,
+        tableName,
+        errorsTableName,
+      });
 
       adminApi.registerModule({
         id: 'analytics',
@@ -90,6 +116,7 @@ function siteAnalyticsPlugin(options = {}) {
             { method: 'get', path: '/top-pages', handler: handlers.getTopPages },
             { method: 'get', path: '/bot-activity', handler: handlers.getBotActivity },
             { method: 'get', path: '/countries', handler: handlers.getCountries },
+            { method: 'get', path: '/client-errors', handler: handlers.getClientErrors },
             { method: 'get', path: '/recent', handler: handlers.getRecent },
           ],
         },

package/plugins/site-analytics/tracking.js

@@ -36,6 +36,8 @@ function getClientIp(req) {
  * @param {string[]} [options.excludePaths] - Paths to exclude from tracking
  * @param {boolean} [options.trackBots=true] - Whether to record bot visits
  * @param {string} [options.tableName='analytics_page_views'] - DB table name
+ * @param {number} [options.batchSize=20] - Flush when queue reaches this size
+ * @param {number} [options.flushIntervalMs=3000] - Flush interval for low traffic
  */
 function createTrackingMiddleware(options) {
   const {
@@ -43,10 +45,14 @@ function createTrackingMiddleware(options) {
     excludePaths = [],
     trackBots = true,
     tableName = 'analytics_page_views',
+    batchSize = 20,
+    flushIntervalMs = 3000,
   } = options;
 
   const allExcludes = [...DEFAULT_EXCLUDE, ...excludePaths];
   let tableReady = false;
+  const queue = [];
+  let flushScheduled = false;
 
   async function ensureTable() {
     if (tableReady) return;
@@ -101,6 +107,37 @@ function createTrackingMiddleware(options) {
     return sessionId;
   }
 
+  async function flushQueue() {
+    if (queue.length === 0) return;
+    const batch = queue.splice(0, queue.length);
+
+    try {
+      await ensureTable();
+      for (const row of batch) {
+        row.created_at = knex.fn.now();
+      }
+      await knex(tableName).insert(batch);
+    } catch (e) {
+      console.error('[site-analytics] Batch insert failed:', e.message);
+      // Re-queue failed items (optional - could drop to avoid loops)
+      queue.unshift(...batch);
+    }
+  }
+
+  function scheduleFlush() {
+    if (flushScheduled || queue.length === 0) return;
+    flushScheduled = true;
+    setTimeout(() => {
+      flushScheduled = false;
+      flushQueue().catch(() => {});
+    }, flushIntervalMs);
+  }
+
+  // Periodic flush (catches low-traffic case)
+  setInterval(() => {
+    if (queue.length > 0) flushQueue().catch(() => {});
+  }, flushIntervalMs).unref();
+
   return async function trackingMiddleware(req, res, next) {
     next();
 
@@ -111,8 +148,6 @@ function createTrackingMiddleware(options) {
     if (allExcludes.some(prefix => path.startsWith(prefix))) return;
 
     try {
-      await ensureTable();
-
       const userAgent = req.headers['user-agent'] || '';
       const ip = getClientIp(req);
       const { isBot, botName } = detectBot(userAgent);
@@ -125,7 +160,7 @@ function createTrackingMiddleware(options) {
       const country = detectCountry(req);
       const referrer = req.headers['referer'] || req.headers['referrer'] || null;
 
-      await knex(tableName).insert({
+      queue.push({
         session_id: sessionId,
         visitor_id: visitorId,
         path,
@@ -135,8 +170,13 @@ function createTrackingMiddleware(options) {
         country,
         is_bot: isBot,
         bot_name: botName,
-        created_at: knex.fn.now(),
       });
+
+      if (queue.length >= batchSize) {
+        flushQueue().catch(() => {});
+      } else {
+        scheduleFlush();
+      }
     } catch (e) {
       // Non-blocking: don't let tracking errors affect the app
     }