@xiboplayer/stats 0.2.0 → 0.3.1

package/README.md

@@ -1,15 +1,15 @@
 # @xiboplayer/stats
 
-Proof of play tracking and CMS logging for Xibo Players.
+**Proof of play tracking, stats reporting, and CMS logging.**
 
-## Features
+## Overview
 
-- **StatsCollector**: Track layout and widget playback for proof of play reporting
-- **LogReporter**: Collect and submit application logs to CMS
-- **IndexedDB Storage**: Persistent storage across browser sessions
-- **Offline Support**: Stats and logs are queued when offline and submitted when online
-- **Quota Management**: Automatic cleanup of old data when storage quota is exceeded
-- **XMDS Integration**: Format stats and logs as XML for CMS submission
+Collects and reports display analytics to the Xibo CMS:
+
+- **Proof of play** — per-layout and per-widget duration tracking
+- **Aggregation modes** — individual or aggregated stat submission (configurable from CMS)
+- **Log reporting** — display logs batched and submitted to CMS
+- **Fault alerts** — error deduplication and fault reporting
 
 ## Installation
 
@@ -19,357 +19,20 @@ npm install @xiboplayer/stats
 
 ## Usage
 
-### StatsCollector - Proof of Play Tracking
-
-The StatsCollector tracks when layouts and widgets (media) are played for reporting to the CMS.
-
-```javascript
-import { StatsCollector, formatStats } from '@xiboplayer/stats';
-
-// Initialize collector
-const collector = new StatsCollector();
-await collector.init();
-
-// Track layout playback
-await collector.startLayout(layoutId, scheduleId);
-// ... layout plays for 5 minutes ...
-await collector.endLayout(layoutId, scheduleId);
-
-// Track widget playback
-await collector.startWidget(mediaId, layoutId, scheduleId);
-// ... widget plays for 30 seconds ...
-await collector.endWidget(mediaId, layoutId, scheduleId);
-
-// Submit stats to CMS
-const stats = await collector.getStatsForSubmission(50); // Get up to 50 stats
-const xml = formatStats(stats);
-const success = await xmds.submitStats(xml);
-
-if (success) {
-  await collector.clearSubmittedStats(stats);
-}
-```
-
-#### API Reference
-
-**`new StatsCollector()`**
-
-Create a new stats collector instance.
-
-**`async init()`**
-
-Initialize IndexedDB storage. Must be called before using other methods.
-
-**`async startLayout(layoutId, scheduleId)`**
-
-Start tracking a layout. Creates a new stat entry and marks it as in-progress.
-
-- `layoutId` (number): Layout ID from CMS
-- `scheduleId` (number): Schedule ID that triggered this layout
-
-**`async endLayout(layoutId, scheduleId)`**
-
-End tracking a layout. Calculates duration and saves to database.
-
-- `layoutId` (number): Layout ID from CMS
-- `scheduleId` (number): Schedule ID
-
-**`async startWidget(mediaId, layoutId, scheduleId)`**
-
-Start tracking a widget/media item.
-
-- `mediaId` (number): Media ID from CMS
-- `layoutId` (number): Parent layout ID
-- `scheduleId` (number): Schedule ID
-
-**`async endWidget(mediaId, layoutId, scheduleId)`**
-
-End tracking a widget. Calculates duration and saves to database.
-
-- `mediaId` (number): Media ID from CMS
-- `layoutId` (number): Parent layout ID
-- `scheduleId` (number): Schedule ID
-
-**`async getStatsForSubmission(limit = 50)`**
-
-Get unsubmitted stats ready for submission to CMS.
-
-- `limit` (number): Maximum number of stats to return (default: 50)
-- Returns: Array of stat objects
-
-**`async clearSubmittedStats(stats)`**
-
-Delete stats that were successfully submitted to CMS.
-
-- `stats` (Array): Array of stat objects to delete
-
-**`async getAllStats()`**
-
-Get all stats from database (for debugging).
-
-- Returns: Array of all stat objects
-
-**`async clearAllStats()`**
-
-Clear all stats from database (for testing).
-
-#### Stat Object Structure
-
-```javascript
-{
-  id: 123,                 // Auto-generated ID
-  type: 'layout',          // 'layout' or 'media'
-  layoutId: 456,           // Layout ID from CMS
-  scheduleId: 789,         // Schedule ID
-  mediaId: 111,            // Only for type='media'
-  start: Date,             // Start time
-  end: Date,               // End time
-  duration: 300,           // Duration in seconds
-  count: 1,                // Number of plays (always 1)
-  submitted: 0             // 0 = not submitted, 1 = submitted
-}
-```
-
-### formatStats - XML Formatting
-
-Format stats array as XML for XMDS SubmitStats API.
-
-```javascript
-import { formatStats } from '@xiboplayer/stats';
-
-const stats = await collector.getStatsForSubmission(50);
-const xml = formatStats(stats);
-
-console.log(xml);
-// <stats>
-//   <stat type="layout" fromdt="2026-02-10 12:00:00" todt="2026-02-10 12:05:00"
-//         scheduleid="123" layoutid="456" count="1" duration="300" />
-//   <stat type="media" fromdt="2026-02-10 12:00:00" todt="2026-02-10 12:01:00"
-//         scheduleid="123" layoutid="456" mediaid="789" count="1" duration="60" />
-// </stats>
-```
-
-### LogReporter - CMS Logging
-
-The LogReporter collects application logs and submits them to the CMS via XMDS.
-
-```javascript
-import { LogReporter, formatLogs } from '@xiboplayer/stats';
-
-// Initialize reporter
-const reporter = new LogReporter();
-await reporter.init();
-
-// Log messages
-await reporter.error('Failed to load layout 123', 'PLAYER');
-await reporter.audit('User logged in', 'AUTH');
-await reporter.info('Layout loaded successfully', 'RENDERER');
-await reporter.debug('Cache hit for file ABC', 'CACHE');
-
-// Submit logs to CMS
-const logs = await reporter.getLogsForSubmission(100); // Get up to 100 logs
-const xml = formatLogs(logs);
-const success = await xmds.submitLog(xml);
-
-if (success) {
-  await reporter.clearSubmittedLogs(logs);
-}
-```
-
-#### API Reference
-
-**`new LogReporter()`**
-
-Create a new log reporter instance.
-
-**`async init()`**
-
-Initialize IndexedDB storage. Must be called before using other methods.
-
-**`async log(level, message, category = 'PLAYER')`**
-
-Log a message with specified level.
-
-- `level` (string): Log level - 'error', 'audit', 'info', or 'debug'
-- `message` (string): Log message
-- `category` (string): Log category (default: 'PLAYER')
-
-**`async error(message, category = 'PLAYER')`**
-
-Shorthand for logging an error message.
-
-**`async audit(message, category = 'PLAYER')`**
-
-Shorthand for logging an audit message.
-
-**`async info(message, category = 'PLAYER')`**
-
-Shorthand for logging an info message.
-
-**`async debug(message, category = 'PLAYER')`**
-
-Shorthand for logging a debug message.
-
-**`async getLogsForSubmission(limit = 100)`**
-
-Get unsubmitted logs ready for submission to CMS.
-
-- `limit` (number): Maximum number of logs to return (default: 100)
-- Returns: Array of log objects
-
-**`async clearSubmittedLogs(logs)`**
-
-Delete logs that were successfully submitted to CMS.
-
-- `logs` (Array): Array of log objects to delete
-
-**`async getAllLogs()`**
-
-Get all logs from database (for debugging).
-
-- Returns: Array of all log objects
-
-**`async clearAllLogs()`**
-
-Clear all logs from database (for testing).
-
-#### Log Object Structure
-
 ```javascript
-{
-  id: 123,                 // Auto-generated ID
-  level: 'error',          // 'error', 'audit', 'info', or 'debug'
-  message: 'Error text',   // Log message
-  category: 'PLAYER',      // Log category
-  timestamp: Date,         // When log was created
-  submitted: 0             // 0 = not submitted, 1 = submitted
-}
-```
-
-#### Common Categories
+import { StatsCollector } from '@xiboplayer/stats';
 
-- `PLAYER` - Player lifecycle and general operations
-- `RENDERER` - Layout rendering and widget display
-- `CACHE` - File caching and downloads
-- `XMDS` - CMS communication
-- `AUTH` - Authentication and registration
-- `SCHEDULE` - Schedule management
+const stats = new StatsCollector({ transport });
+stats.init();
 
-### formatLogs - XML Formatting
-
-Format logs array as XML for XMDS SubmitLog API.
-
-```javascript
-import { formatLogs } from '@xiboplayer/stats';
-
-const logs = await reporter.getLogsForSubmission(100);
-const xml = formatLogs(logs);
-
-console.log(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:01:00" category="AUTH" type="audit"
-//        message="User logged in" />
-// </logs>
-```
-
-## Storage
-
-Both StatsCollector and LogReporter use IndexedDB for persistent storage:
-
-- **Database Names**: `xibo-player-stats` and `xibo-player-logs`
-- **Indexes**: Both use an index on the `submitted` field for fast queries
-- **Quota Management**: Automatically cleans old submitted entries when quota is exceeded
-- **Offline Support**: Data persists across browser sessions and restarts
-
-### Storage Limits
-
-- **Chrome**: ~60% of available disk space
-- **Firefox**: ~10% of available disk space
-- **Safari**: ~1GB
-
-When storage quota is exceeded, the oldest 100 submitted entries are automatically deleted.
-
-## Integration with PWA Platform
-
-The stats package is integrated into the PWA player (`xiboplayer-pwa/src/main.ts`):
-
-```typescript
-// Initialize stats collector
-this.statsCollector = new StatsCollector();
-await this.statsCollector.init();
-
-// Track layout events
-this.renderer.on('layoutStart', (layoutId) => {
-  this.statsCollector.startLayout(layoutId, this.currentScheduleId);
-});
-
-this.renderer.on('layoutEnd', (layoutId) => {
-  this.statsCollector.endLayout(layoutId, this.currentScheduleId);
-});
-
-// Track widget events
-this.renderer.on('widgetStart', ({ widgetId, layoutId, mediaId }) => {
-  if (mediaId) {
-    this.statsCollector.startWidget(mediaId, layoutId, this.currentScheduleId);
-  }
-});
-
-this.renderer.on('widgetEnd', ({ widgetId, layoutId, mediaId }) => {
-  if (mediaId) {
-    this.statsCollector.endWidget(mediaId, layoutId, this.currentScheduleId);
-  }
-});
-
-// Submit stats periodically (every 10 minutes)
-setInterval(async () => {
-  const stats = await this.statsCollector.getStatsForSubmission(50);
-  if (stats.length > 0) {
-    const xml = formatStats(stats);
-    const success = await this.xmds.submitStats(xml);
-    if (success) {
-      await this.statsCollector.clearSubmittedStats(stats);
-    }
-  }
-}, 600000);
+// Stats are collected automatically from player events
+// and submitted during each collection cycle
 ```
 
-## Testing
-
-The package includes comprehensive tests using Vitest and fake-indexeddb:
-
-```bash
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-### Test Coverage
-
-- **StatsCollector**: 32 tests covering initialization, layout tracking, widget tracking, submission flow, edge cases, and database operations
-- **LogReporter**: 35 tests covering initialization, log creation, submission flow, edge cases, and database operations
-- **Total**: 67 tests with 100% pass rate
-
-## Compatibility
-
-- **Node.js**: 18+ (for ESM support)
-- **Browsers**: Chrome 58+, Firefox 52+, Safari 12+, Edge 79+
-- **IndexedDB**: Required for persistent storage
-
-## Author
-
-Pau Aliagas <linuxnow@gmail.com>
-
-## Repository
+## Dependencies
 
-https://github.com/xibo/xibo-players/tree/main/packages/stats
+- `@xiboplayer/utils` — logger, events
 
-## License
+---
 
-AGPL-3.0-or-later
+**Part of the [XiboPlayer SDK](https://github.com/xibo-players/xiboplayer)** | [MCP Server](https://github.com/xibo-players/xiboplayer/tree/main/mcp-server) for AI-assisted development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/stats",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.2.0"
+    "@xiboplayer/utils": "0.3.1"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/index.js

@@ -1,4 +1,6 @@
 // @xiboplayer/stats - Proof of play and statistics reporting
+import pkg from '../package.json' with { type: 'json' };
+export const VERSION = pkg.version;
 
 /**
  * Stats collector for proof of play tracking