@xiboplayer/stats 0.3.6 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/stats",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Proof of play tracking, stats reporting, and CMS logging",
   "type": "module",
   "main": "./src/index.js",
@@ -9,7 +9,7 @@
     "./collector": "./src/stats-collector.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.3.6"
+    "@xiboplayer/utils": "0.4.0"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/index.js

@@ -12,4 +12,4 @@ export { StatsCollector, formatStats } from './stats-collector.js';
  * Log reporter for CMS logging
  * @module @xiboplayer/stats/logger
  */
-export { LogReporter, formatLogs } from './log-reporter.js';
+export { LogReporter, formatLogs, formatFaults } from './log-reporter.js';

package/src/log-reporter.js

@@ -171,7 +171,7 @@ export class LogReporter {
 
     this._reportedFaults.set(code, Date.now());
 
-    await this.log('error', reason, 'PLAYER', {
+    await this.log('error', reason, 'event', {
       alertType: 'Player Fault',
       eventType: code
     });
@@ -179,6 +179,46 @@ export class LogReporter {
     log.info(`Fault reported: ${code} - ${reason}`);
   }
 
+  /**
+   * Get unsubmitted fault entries for dedicated fault submission.
+   * Returns log entries that have alertType='Player Fault' and submitted=0.
+   * These are the high-priority entries that should be submitted faster
+   * than the normal log collection cycle.
+   *
+   * @param {number} [limit=10] - Maximum faults to return per batch
+   * @returns {Promise<Array>} Array of fault log objects
+   */
+  async getFaultsForSubmission(limit = 10) {
+    if (!this.db) return [];
+
+    return new Promise((resolve, reject) => {
+      const transaction = this.db.transaction([LOGS_STORE], 'readonly');
+      const store = transaction.objectStore(LOGS_STORE);
+      const index = store.index('submitted');
+
+      const request = index.openCursor(IDBKeyRange.only(0));
+      const faults = [];
+
+      request.onsuccess = (event) => {
+        const cursor = event.target.result;
+
+        if (cursor && faults.length < limit) {
+          if (cursor.value.alertType === 'Player Fault') {
+            faults.push(cursor.value);
+          }
+          cursor.continue();
+        } else {
+          resolve(faults);
+        }
+      };
+
+      request.onerror = () => {
+        log.error('Failed to retrieve faults:', request.error);
+        reject(new Error(`Failed to retrieve faults: ${request.error}`));
+      };
+    });
+  }
+
   /**
    * Log an error message
    *
@@ -234,13 +274,12 @@ export class LogReporter {
   /**
    * Get logs ready for submission to CMS
    *
-   * Returns unsubmitted logs up to the specified limit.
-   * Logs are ordered by ID (oldest first).
+   * Returns unsubmitted logs up to the spec limit of 50 per batch.
    *
-   * @param {number} limit - Maximum number of logs to return (default: 100)
+   * @param {number} [limit=50] - Maximum number of logs to return (spec max: 50)
    * @returns {Promise<Array>} Array of log objects
    */
-  async getLogsForSubmission(limit = 100) {
+  async getLogsForSubmission(limit = 50) {
     if (!this.db) {
       log.warn('Logs database not initialized');
       return [];
@@ -262,7 +301,7 @@ export class LogReporter {
           logs.push(cursor.value);
           cursor.continue();
         } else {
-          log.debug(`Retrieved ${logs.length} unsubmitted logs`);
+          log.debug(`Retrieved ${logs.length} unsubmitted logs (limit: ${limit})`);
           resolve(logs);
         }
       };
@@ -274,6 +313,25 @@ export class LogReporter {
     });
   }
 
+  /**
+   * Count unsubmitted logs in the database.
+   * @returns {Promise<number>}
+   */
+  async _countUnsubmitted() {
+    return new Promise((resolve) => {
+      try {
+        const transaction = this.db.transaction([LOGS_STORE], 'readonly');
+        const store = transaction.objectStore(LOGS_STORE);
+        const index = store.index('submitted');
+        const request = index.count(IDBKeyRange.only(0));
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => resolve(0);
+      } catch (_) {
+        resolve(0);
+      }
+    });
+  }
+
   /**
    * Clear submitted logs from database
    *
@@ -457,11 +515,15 @@ export class LogReporter {
  *
  * Converts array of log objects to XML format expected by CMS.
  *
- * XML format:
+ * XML format (spec-compliant):
  * ```xml
  * <logs>
- *   <log date="2026-02-10 12:00:00" category="PLAYER" type="error"
- *        message="Failed to load layout 123" />
+ *   <log date="2026-02-10 12:00:00" category="error">
+ *     <thread>main</thread>
+ *     <method>collect</method>
+ *     <message>Failed to load layout 123</message>
+ *     <scheduleID>0</scheduleID>
+ *   </log>
  * </logs>
  * ```
  *
@@ -482,12 +544,14 @@ export function formatLogs(logs) {
     // Format date as "YYYY-MM-DD HH:MM:SS"
     const date = formatDateTime(logEntry.timestamp);
 
-    // Build attributes
+    // Spec categories: only "error" and "audit" are valid
+    const category = (logEntry.level === 'error' || logEntry.level === 'audit')
+      ? logEntry.level : 'audit';
+
+    // Build attributes on <log> element
     const attrs = [
       `date="${escapeXml(date)}"`,
-      `category="${escapeXml(logEntry.category)}"`,
-      `type="${escapeXml(logEntry.level)}"`,
-      `message="${escapeXml(logEntry.message)}"`
+      `category="${escapeXml(category)}"`
     ];
 
     // Fault alert fields (triggers CMS dashboard alerts)
@@ -498,12 +562,45 @@ export function formatLogs(logs) {
       attrs.push(`eventType="${escapeXml(logEntry.eventType)}"`);
     }
 
-    return `  <log ${attrs.join(' ')} />`;
+    // Build child elements (spec format: thread, method, message, scheduleID)
+    const thread = escapeXml(logEntry.thread || 'main');
+    const method = escapeXml(logEntry.method || logEntry.category || 'PLAYER');
+    const message = escapeXml(logEntry.message);
+    const scheduleId = escapeXml(String(logEntry.scheduleId || '0'));
+
+    return `  <log ${attrs.join(' ')}>\n    <thread>${thread}</thread>\n    <method>${method}</method>\n    <message>${message}</message>\n    <scheduleID>${scheduleId}</scheduleID>\n  </log>`;
   });
 
   return `<logs>\n${logElements.join('\n')}\n</logs>`;
 }
 
+/**
+ * Format fault log entries as JSON for XMDS ReportFaults submission.
+ *
+ * Converts fault log objects (from getFaultsForSubmission) into the JSON
+ * string format expected by xmds.reportFaults().
+ *
+ * @param {Array} faults - Array of fault log objects from getFaultsForSubmission()
+ * @returns {string} JSON string for XMDS ReportFaults
+ *
+ * @example
+ * const faults = await reporter.getFaultsForSubmission();
+ * if (faults.length > 0) {
+ *   const json = formatFaults(faults);
+ *   await xmds.reportFaults(json);
+ * }
+ */
+export function formatFaults(faults) {
+  if (!faults || faults.length === 0) return '[]';
+
+  return JSON.stringify(faults.map(f => ({
+    code: f.eventType || 'UNKNOWN',
+    reason: f.message || '',
+    date: formatDateTime(f.timestamp),
+    layoutId: f.scheduleId || 0
+  })));
+}
+
 /**
  * Format Date object as "YYYY-MM-DD HH:MM:SS"
  * @private

package/src/log-reporter.test.js

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { LogReporter, formatLogs } from './log-reporter.js';
+import { LogReporter, formatLogs, formatFaults } from './log-reporter.js';
 
 describe('LogReporter', () => {
   let reporter;
@@ -286,6 +286,56 @@ describe('LogReporter', () => {
     });
   });
 
+  describe('getFaultsForSubmission', () => {
+    it('should return only fault entries (not regular logs)', async () => {
+      await reporter.info('Normal log', 'PLAYER');
+      await reporter.error('Regular error', 'PLAYER');
+      await reporter.reportFault('LAYOUT_FAIL', 'Layout failed');
+      await reporter.reportFault('MEDIA_FAIL', 'Media failed');
+
+      const faults = await reporter.getFaultsForSubmission();
+      expect(faults.length).toBe(2);
+      expect(faults.every(f => f.alertType === 'Player Fault')).toBe(true);
+    });
+
+    it('should respect limit parameter', async () => {
+      await reporter.reportFault('FAULT_1', 'Fault 1', 1);
+      await new Promise(r => setTimeout(r, 5));
+      await reporter.reportFault('FAULT_2', 'Fault 2', 1);
+      await new Promise(r => setTimeout(r, 5));
+      await reporter.reportFault('FAULT_3', 'Fault 3', 1);
+
+      const faults = await reporter.getFaultsForSubmission(2);
+      expect(faults.length).toBe(2);
+    });
+
+    it('should return empty array when no faults exist', async () => {
+      await reporter.info('Normal log', 'PLAYER');
+      await reporter.error('Regular error', 'PLAYER');
+
+      const faults = await reporter.getFaultsForSubmission();
+      expect(faults).toEqual([]);
+    });
+
+    it('should not return faults that have been cleared', async () => {
+      await reporter.reportFault('TEST_FAULT', 'Test');
+
+      const faults = await reporter.getFaultsForSubmission();
+      expect(faults.length).toBe(1);
+
+      await reporter.clearSubmittedLogs(faults);
+
+      const remaining = await reporter.getFaultsForSubmission();
+      expect(remaining).toEqual([]);
+    });
+
+    it('should return empty array when db is not initialized', async () => {
+      const r = new LogReporter();
+      const faults = await r.getFaultsForSubmission();
+      expect(faults).toEqual([]);
+    });
+  });
+
   describe('database operations', () => {
     it('should get all logs', async () => {
       await reporter.error('Error 1', 'PLAYER');
@@ -333,9 +383,11 @@ describe('formatLogs', () => {
     const xml = formatLogs(logs);
     expect(xml).toContain('<logs>');
     expect(xml).toContain('</logs>');
-    expect(xml).toContain('type="error"');
-    expect(xml).toContain('message="Test error"');
-    expect(xml).toContain('category="PLAYER"');
+    expect(xml).toContain('category="error"');
+    expect(xml).toContain('<message>Test error</message>');
+    expect(xml).toContain('<method>PLAYER</method>');
+    expect(xml).toContain('<thread>main</thread>');
+    expect(xml).toContain('<scheduleID>0</scheduleID>');
     expect(xml).toContain('date=');
   });
 
@@ -375,7 +427,7 @@ describe('formatLogs', () => {
     expect(xml).toContain('&apos;');
   });
 
-  it('should escape XML special characters in category', () => {
+  it('should escape XML special characters in method', () => {
     const logs = [{
       level: 'error',
       message: 'Test',
@@ -384,7 +436,8 @@ describe('formatLogs', () => {
     }];
 
     const xml = formatLogs(logs);
-    expect(xml).toContain('category="PLAYER&lt;&gt;"');
+    // category field from log entry becomes <method> child element
+    expect(xml).toContain('<method>PLAYER&lt;&gt;</method>');
   });
 
   it('should format dates correctly', () => {
@@ -400,7 +453,7 @@ describe('formatLogs', () => {
     expect(xml).toMatch(/date="\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}"/);
   });
 
-  it('should handle all log levels', () => {
+  it('should map log levels to spec categories (error/audit only)', () => {
     const logs = [
       { level: 'error', message: 'Error', category: 'PLAYER', timestamp: new Date() },
       { level: 'audit', message: 'Audit', category: 'PLAYER', timestamp: new Date() },
@@ -409,10 +462,12 @@ describe('formatLogs', () => {
     ];
 
     const xml = formatLogs(logs);
-    expect(xml).toContain('type="error"');
-    expect(xml).toContain('type="audit"');
-    expect(xml).toContain('type="info"');
-    expect(xml).toContain('type="debug"');
+    // Spec only allows "error" and "audit" as categories
+    expect(xml).toContain('category="error"');
+    expect(xml).toContain('category="audit"');
+    // info and debug should be mapped to "audit"
+    const auditCount = (xml.match(/category="audit"/g) || []).length;
+    expect(auditCount).toBe(3); // audit + info + debug
   });
 
   it('should include alertType and eventType in XML output for faults', () => {
@@ -481,4 +536,85 @@ describe('formatLogs', () => {
     const xml = formatLogs(logs);
     expect(xml).toContain(longMessage);
   });
+
+  it('should use custom thread, method, and scheduleId when provided', () => {
+    const logs = [{
+      level: 'error',
+      message: 'Widget failed',
+      category: 'RENDERER',
+      thread: 'worker-2',
+      method: 'renderWidget',
+      scheduleId: 42,
+      timestamp: new Date('2026-02-10T12:00:00Z')
+    }];
+
+    const xml = formatLogs(logs);
+    expect(xml).toContain('<thread>worker-2</thread>');
+    expect(xml).toContain('<method>renderWidget</method>');
+    expect(xml).toContain('<scheduleID>42</scheduleID>');
+  });
+
+  it('should produce spec-compliant XML structure with child elements', () => {
+    const logs = [{
+      level: 'error',
+      message: 'Test',
+      category: 'PLAYER',
+      timestamp: new Date('2026-02-10T12:00:00Z')
+    }];
+
+    const xml = formatLogs(logs);
+    // Should NOT have message as attribute (old format)
+    expect(xml).not.toMatch(/message="/);
+    // Should have message as child element (spec format)
+    expect(xml).toMatch(/<message>Test<\/message>/);
+    // Should have closing </log> tag (not self-closing)
+    expect(xml).toContain('</log>');
+  });
+});
+
+describe('formatFaults', () => {
+  it('should format empty faults', () => {
+    expect(formatFaults([])).toBe('[]');
+    expect(formatFaults(null)).toBe('[]');
+  });
+
+  it('should format fault entries as JSON', () => {
+    const faults = [{
+      eventType: 'LAYOUT_LOAD_FAILED',
+      message: 'Failed to load layout 123',
+      timestamp: new Date('2026-02-10T12:00:00Z'),
+      scheduleId: 5
+    }];
+
+    const json = formatFaults(faults);
+    const parsed = JSON.parse(json);
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].code).toBe('LAYOUT_LOAD_FAILED');
+    expect(parsed[0].reason).toBe('Failed to load layout 123');
+    expect(parsed[0].date).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+    expect(parsed[0].layoutId).toBe(5);
+  });
+
+  it('should handle missing fields with defaults', () => {
+    const faults = [{ timestamp: new Date() }];
+
+    const json = formatFaults(faults);
+    const parsed = JSON.parse(json);
+    expect(parsed[0].code).toBe('UNKNOWN');
+    expect(parsed[0].reason).toBe('');
+    expect(parsed[0].layoutId).toBe(0);
+  });
+
+  it('should format multiple faults', () => {
+    const faults = [
+      { eventType: 'FAULT_1', message: 'First', timestamp: new Date(), scheduleId: 1 },
+      { eventType: 'FAULT_2', message: 'Second', timestamp: new Date(), scheduleId: 2 }
+    ];
+
+    const json = formatFaults(faults);
+    const parsed = JSON.parse(json);
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].code).toBe('FAULT_1');
+    expect(parsed[1].code).toBe('FAULT_2');
+  });
 });

package/src/stats-collector.js

@@ -109,14 +109,22 @@ export class StatsCollector {
    *
    * @param {number} layoutId - Layout ID from CMS
    * @param {number} scheduleId - Schedule ID that triggered this layout
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.enableStat=true] - Whether stats are enabled for this layout
    * @returns {Promise<void>}
    */
-  async startLayout(layoutId, scheduleId) {
+  async startLayout(layoutId, scheduleId, options) {
     if (!this.db) {
       log.warn('Stats database not initialized');
       return;
     }
 
+    // Respect enableStat flag from XLF (layout/widget level stat suppression)
+    if (options?.enableStat === false) {
+      log.debug(`Stats disabled for layout ${layoutId} (enableStat=false)`);
+      return;
+    }
+
     // Key excludes scheduleId: only one layout instance can be in-progress at a time,
     // and scheduleId may change mid-play when a collection cycle completes.
     const key = `layout-${layoutId}`;
@@ -126,7 +134,7 @@ export class StatsCollector {
       const prev = this.inProgressStats.get(key);
       prev.end = new Date();
       prev.duration = Math.floor((prev.end - prev.start) / 1000);
-      await this._saveStat(prev);
+      await this._saveStatSplit(prev);
       this.inProgressStats.delete(key);
       log.debug(`Layout ${layoutId} replay - ended previous cycle (${prev.duration}s)`);
     }
@@ -174,9 +182,9 @@ export class StatsCollector {
     stat.end = new Date();
     stat.duration = Math.floor((stat.end - stat.start) / 1000);
 
-    // Save to database
+    // Save to database (splitting at hour boundaries for CMS aggregation)
     try {
-      await this._saveStat(stat);
+      await this._saveStatSplit(stat);
       this.inProgressStats.delete(key);
       log.debug(`Ended tracking layout ${layoutId} (${stat.duration}s)`);
     } catch (error) {
@@ -195,14 +203,23 @@ export class StatsCollector {
    * @param {number} mediaId - Media ID from CMS
    * @param {number} layoutId - Parent layout ID
    * @param {number} scheduleId - Schedule ID
+   * @param {string|number} [widgetId] - Widget ID (for non-library widgets with no mediaId)
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.enableStat=true] - Whether stats are enabled for this widget
    * @returns {Promise<void>}
    */
-  async startWidget(mediaId, layoutId, scheduleId) {
+  async startWidget(mediaId, layoutId, scheduleId, widgetId, options) {
     if (!this.db) {
       log.warn('Stats database not initialized');
       return;
     }
 
+    // Respect enableStat flag from XLF (layout/widget level stat suppression)
+    if (options?.enableStat === false) {
+      log.debug(`Stats disabled for widget ${mediaId} (enableStat=false)`);
+      return;
+    }
+
     // Key excludes scheduleId: it may change mid-play during collection cycles.
     const key = `media-${mediaId}-${layoutId}`;
 
@@ -211,7 +228,7 @@ export class StatsCollector {
       const prev = this.inProgressStats.get(key);
       prev.end = new Date();
       prev.duration = Math.floor((prev.end - prev.start) / 1000);
-      await this._saveStat(prev);
+      await this._saveStatSplit(prev);
       this.inProgressStats.delete(key);
       log.debug(`Widget ${mediaId} replay - ended previous cycle (${prev.duration}s)`);
     }
@@ -219,6 +236,7 @@ export class StatsCollector {
     const stat = {
       type: 'media',
       mediaId,
+      widgetId: widgetId || null,
       layoutId,
       scheduleId,
       start: new Date(),
@@ -261,9 +279,9 @@ export class StatsCollector {
     stat.end = new Date();
     stat.duration = Math.floor((stat.end - stat.start) / 1000);
 
-    // Save to database
+    // Save to database (splitting at hour boundaries for CMS aggregation)
     try {
-      await this._saveStat(stat);
+      await this._saveStatSplit(stat);
       this.inProgressStats.delete(key);
       log.debug(`Ended tracking widget ${mediaId} (${stat.duration}s)`);
     } catch (error) {
@@ -272,6 +290,48 @@ export class StatsCollector {
     }
   }
 
+  /**
+   * Record an event stat (point-in-time engagement data)
+   *
+   * Creates an instant stat entry with no duration. Used for tracking
+   * interactive touches, webhook triggers, and other engagement events.
+   * Unlike layout/widget stats, events have no start/end cycle.
+   *
+   * @param {string} tag - Event tag describing the interaction (e.g. 'touch', 'webhook')
+   * @param {number} layoutId - Layout ID where the event occurred
+   * @param {number} widgetId - Widget ID that triggered the event
+   * @param {number} scheduleId - Schedule ID for the current schedule
+   * @returns {Promise<void>}
+   */
+  async recordEvent(tag, layoutId, widgetId, scheduleId) {
+    if (!this.db) {
+      log.warn('Stats database not initialized');
+      return;
+    }
+
+    const now = new Date();
+    const stat = {
+      type: 'event',
+      tag,
+      layoutId,
+      widgetId,
+      scheduleId,
+      start: now,
+      end: now,
+      duration: 0,
+      count: 1,
+      submitted: 0
+    };
+
+    try {
+      await this._saveStat(stat);
+      log.debug(`Recorded event '${tag}' for widget ${widgetId} in layout ${layoutId}`);
+    } catch (error) {
+      log.error(`Failed to record event '${tag}':`, error);
+      throw error;
+    }
+  }
+
   /**
    * Get stats ready for submission to CMS
    *
@@ -382,7 +442,7 @@ export class StatsCollector {
       const hour = stat.start instanceof Date
         ? stat.start.toISOString().slice(0, 13)
         : new Date(stat.start).toISOString().slice(0, 13);
-      const key = `${stat.type}|${stat.layoutId}|${stat.mediaId || ''}|${stat.scheduleId}|${hour}`;
+      const key = `${stat.type}|${stat.layoutId}|${stat.mediaId || ''}|${stat.widgetId || ''}|${stat.tag || ''}|${stat.scheduleId}|${hour}`;
 
       if (groups.has(key)) {
         const group = groups.get(key);
@@ -495,6 +555,65 @@ export class StatsCollector {
     });
   }
 
+  /**
+   * Split a stat record at hour boundaries.
+   * If a stat spans multiple hours (e.g. 12:50→13:10), it is split into
+   * separate records at each hour boundary for correct CMS aggregation.
+   * Returns an array of one or more stat objects.
+   * @param {Object} stat - Finalized stat with start, end, duration
+   * @returns {Object[]}
+   * @private
+   */
+  _splitAtHourBoundaries(stat) {
+    const start = stat.start;
+    const end = stat.end;
+
+    // No split needed if start and end are in the same hour
+    if (start.getFullYear() === end.getFullYear() &&
+        start.getMonth() === end.getMonth() &&
+        start.getDate() === end.getDate() &&
+        start.getHours() === end.getHours()) {
+      return [stat];
+    }
+
+    const results = [];
+    let segStart = new Date(start.getTime());
+
+    while (segStart < end) {
+      // Next hour boundary: top of the next hour from segStart
+      const nextHour = new Date(segStart.getTime());
+      nextHour.setMinutes(0, 0, 0);
+      nextHour.setHours(nextHour.getHours() + 1);
+
+      const segEnd = nextHour < end ? nextHour : end;
+      const duration = Math.floor((segEnd - segStart) / 1000);
+
+      results.push({
+        ...stat,
+        start: new Date(segStart.getTime()),
+        end: new Date(segEnd.getTime()),
+        duration,
+        count: 1
+      });
+
+      segStart = segEnd;
+    }
+
+    return results;
+  }
+
+  /**
+   * Save a stat to IndexedDB, splitting at hour boundaries first.
+   * @param {Object} stat - Finalized stat with start, end, duration
+   * @private
+   */
+  async _saveStatSplit(stat) {
+    const parts = this._splitAtHourBoundaries(stat);
+    for (const part of parts) {
+      await this._saveStat(part);
+    }
+  }
+
   /**
    * Clean old stats when quota is exceeded
    * Deletes oldest 100 submitted stats
@@ -581,9 +700,25 @@ export function formatStats(stats) {
       `layoutid="${stat.layoutId}"`,
     ];
 
-    // Add mediaId for media stats
-    if (stat.type === 'media' && stat.mediaId) {
-      attrs.push(`mediaid="${stat.mediaId}"`);
+    // Add mediaId and widgetId for media/widget stats
+    if (stat.type === 'media') {
+      if (stat.mediaId) {
+        attrs.push(`mediaid="${stat.mediaId}"`);
+      }
+      // Include widgetId for non-library widgets (native widgets have no mediaId)
+      if (stat.widgetId) {
+        attrs.push(`widgetid="${stat.widgetId}"`);
+      }
+    }
+
+    // Add tag and widgetId for event stats
+    if (stat.type === 'event') {
+      if (stat.tag) {
+        attrs.push(`tag="${escapeXml(stat.tag)}"`);
+      }
+      if (stat.widgetId) {
+        attrs.push(`widgetid="${stat.widgetId}"`);
+      }
     }
 
     // Add count and duration

package/src/stats-collector.test.js

@@ -189,6 +189,70 @@ describe('StatsCollector', () => {
     });
   });
 
+  describe('event tracking', () => {
+    it('should record an event stat', async () => {
+      await collector.recordEvent('touch', 123, 456, 789);
+
+      const stats = await collector.getAllStats();
+      expect(stats.length).toBe(1);
+      expect(stats[0].type).toBe('event');
+      expect(stats[0].tag).toBe('touch');
+      expect(stats[0].layoutId).toBe(123);
+      expect(stats[0].widgetId).toBe(456);
+      expect(stats[0].scheduleId).toBe(789);
+      expect(stats[0].duration).toBe(0);
+      expect(stats[0].count).toBe(1);
+      expect(stats[0].submitted).toBe(0);
+      expect(stats[0].start).toBeInstanceOf(Date);
+      expect(stats[0].end).toBeInstanceOf(Date);
+    });
+
+    it('should record multiple events', async () => {
+      await collector.recordEvent('touch', 123, 456, 789);
+      await collector.recordEvent('webhook', 123, 456, 789);
+      await collector.recordEvent('touch', 123, 457, 789);
+
+      const stats = await collector.getAllStats();
+      expect(stats.length).toBe(3);
+      expect(stats.every(s => s.type === 'event')).toBe(true);
+    });
+
+    it('should not store event in inProgressStats', async () => {
+      await collector.recordEvent('touch', 123, 456, 789);
+
+      expect(collector.inProgressStats.size).toBe(0);
+    });
+
+    it('should be retrievable for submission', async () => {
+      await collector.recordEvent('touch', 123, 456, 789);
+
+      const stats = await collector.getStatsForSubmission();
+      expect(stats.length).toBe(1);
+      expect(stats[0].type).toBe('event');
+      expect(stats[0].tag).toBe('touch');
+    });
+
+    it('should handle missing db gracefully', async () => {
+      const c = new StatsCollector();
+      // Should not throw
+      await c.recordEvent('touch', 123, 456, 789);
+    });
+
+    it('should coexist with layout and widget stats', async () => {
+      await collector.startLayout(123, 789);
+      await collector.endLayout(123, 789);
+      await collector.startWidget(111, 123, 789);
+      await collector.endWidget(111, 123, 789);
+      await collector.recordEvent('touch', 123, 456, 789);
+
+      const stats = await collector.getAllStats();
+      expect(stats.length).toBe(3);
+      expect(stats.some(s => s.type === 'layout')).toBe(true);
+      expect(stats.some(s => s.type === 'media')).toBe(true);
+      expect(stats.some(s => s.type === 'event')).toBe(true);
+    });
+  });
+
   describe('stats submission flow', () => {
     it('should get unsubmitted stats', async () => {
       // Create some stats
@@ -442,6 +506,45 @@ describe('formatStats', () => {
     expect(xml).toMatch(/todt="\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}"/);
   });
 
+  it('should format event stat', () => {
+    const stats = [{
+      type: 'event',
+      tag: 'touch',
+      layoutId: 123,
+      widgetId: 456,
+      scheduleId: 789,
+      start: new Date('2026-02-10T12:00:00Z'),
+      end: new Date('2026-02-10T12:00:00Z'),
+      duration: 0,
+      count: 1
+    }];
+
+    const xml = formatStats(stats);
+    expect(xml).toContain('type="event"');
+    expect(xml).toContain('tag="touch"');
+    expect(xml).toContain('widgetid="456"');
+    expect(xml).toContain('layoutid="123"');
+    expect(xml).toContain('scheduleid="789"');
+    expect(xml).toContain('duration="0"');
+  });
+
+  it('should escape XML in event tag', () => {
+    const stats = [{
+      type: 'event',
+      tag: 'touch&click<script>',
+      layoutId: 123,
+      widgetId: 456,
+      scheduleId: 789,
+      start: new Date('2026-02-10T12:00:00Z'),
+      end: new Date('2026-02-10T12:00:00Z'),
+      duration: 0,
+      count: 1
+    }];
+
+    const xml = formatStats(stats);
+    expect(xml).toContain('tag="touch&amp;click&lt;script&gt;"');
+  });
+
   it('should handle missing end date', () => {
     const stats = [{
       type: 'layout',
@@ -458,4 +561,129 @@ describe('formatStats', () => {
     expect(xml).toContain('fromdt=');
     expect(xml).toContain('todt=');
   });
+
+  it('should include widgetId for media stats with no mediaId (native widgets)', () => {
+    const stats = [{
+      type: 'media',
+      mediaId: null,
+      widgetId: 42,
+      layoutId: 123,
+      scheduleId: 456,
+      start: new Date('2026-02-10T12:00:00Z'),
+      end: new Date('2026-02-10T12:01:00Z'),
+      duration: 60,
+      count: 1
+    }];
+
+    const xml = formatStats(stats);
+    expect(xml).toContain('type="media"');
+    expect(xml).toContain('widgetid="42"');
+    expect(xml).not.toContain('mediaid=');
+  });
+
+  it('should include both mediaid and widgetid for library widgets', () => {
+    const stats = [{
+      type: 'media',
+      mediaId: 789,
+      widgetId: 42,
+      layoutId: 123,
+      scheduleId: 456,
+      start: new Date('2026-02-10T12:00:00Z'),
+      end: new Date('2026-02-10T12:01:00Z'),
+      duration: 60,
+      count: 1
+    }];
+
+    const xml = formatStats(stats);
+    expect(xml).toContain('mediaid="789"');
+    expect(xml).toContain('widgetid="42"');
+  });
+});
+
+describe('_splitAtHourBoundaries', () => {
+  let collector;
+
+  beforeEach(async () => {
+    collector = new StatsCollector();
+    await collector.init();
+  });
+
+  afterEach(() => {
+    if (collector?.db) collector.db.close();
+  });
+
+  it('should not split a stat within the same hour', () => {
+    const stat = {
+      type: 'layout', layoutId: 1, scheduleId: 1, count: 1, submitted: 0,
+      start: new Date('2026-02-10T12:10:00Z'),
+      end: new Date('2026-02-10T12:50:00Z'),
+      duration: 2400
+    };
+    const parts = collector._splitAtHourBoundaries(stat);
+    expect(parts).toHaveLength(1);
+    expect(parts[0].duration).toBe(2400);
+  });
+
+  it('should split a stat spanning two hours', () => {
+    const stat = {
+      type: 'layout', layoutId: 1, scheduleId: 1, count: 1, submitted: 0,
+      start: new Date('2026-02-10T12:50:00Z'),
+      end: new Date('2026-02-10T13:10:00Z'),
+      duration: 1200
+    };
+    const parts = collector._splitAtHourBoundaries(stat);
+    expect(parts).toHaveLength(2);
+    expect(parts[0].duration).toBe(600);  // 12:50 → 13:00
+    expect(parts[1].duration).toBe(600);  // 13:00 → 13:10
+    expect(parts[0].end.toISOString()).toBe('2026-02-10T13:00:00.000Z');
+    expect(parts[1].start.toISOString()).toBe('2026-02-10T13:00:00.000Z');
+  });
+
+  it('should split a stat spanning three hours', () => {
+    const stat = {
+      type: 'layout', layoutId: 1, scheduleId: 1, count: 1, submitted: 0,
+      start: new Date('2026-02-10T11:30:00Z'),
+      end: new Date('2026-02-10T13:15:00Z'),
+      duration: 6300
+    };
+    const parts = collector._splitAtHourBoundaries(stat);
+    expect(parts).toHaveLength(3);
+    expect(parts[0].duration).toBe(1800); // 11:30 → 12:00
+    expect(parts[1].duration).toBe(3600); // 12:00 → 13:00
+    expect(parts[2].duration).toBe(900);  // 13:00 → 13:15
+    // Durations sum to original
+    const total = parts.reduce((s, p) => s + p.duration, 0);
+    expect(total).toBe(6300);
+  });
+
+  it('should split at day boundary (midnight)', () => {
+    const stat = {
+      type: 'layout', layoutId: 1, scheduleId: 1, count: 1, submitted: 0,
+      start: new Date('2026-02-10T23:50:00Z'),
+      end: new Date('2026-02-11T00:10:00Z'),
+      duration: 1200
+    };
+    const parts = collector._splitAtHourBoundaries(stat);
+    expect(parts).toHaveLength(2);
+    expect(parts[0].duration).toBe(600);
+    expect(parts[1].duration).toBe(600);
+  });
+
+  it('should preserve all stat fields in split records', () => {
+    const stat = {
+      type: 'media', layoutId: 5, mediaId: 42, scheduleId: 7, count: 1, submitted: 0,
+      start: new Date('2026-02-10T12:50:00Z'),
+      end: new Date('2026-02-10T13:10:00Z'),
+      duration: 1200
+    };
+    const parts = collector._splitAtHourBoundaries(stat);
+    for (const part of parts) {
+      expect(part.type).toBe('media');
+      expect(part.layoutId).toBe(5);
+      expect(part.mediaId).toBe(42);
+      expect(part.scheduleId).toBe(7);
+      expect(part.count).toBe(1);
+      expect(part.submitted).toBe(0);
+    }
+  });
 });