@xiboplayer/schedule 0.1.0

package/src/integration.test.js

@@ -0,0 +1,351 @@
+/**
+ * Integration tests - Schedule + Interrupt Scheduler
+ * Tests the integration between @xiboplayer/schedule and interrupt processing
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ScheduleManager } from '@xiboplayer/schedule';
+import { InterruptScheduler } from './interrupts.js';
+
+describe('Schedule + Interrupt Integration', () => {
+  let scheduleManager;
+  let interruptScheduler;
+
+  beforeEach(() => {
+    interruptScheduler = new InterruptScheduler();
+    scheduleManager = new ScheduleManager({ interruptScheduler });
+  });
+
+  // Helper to create mock schedule
+  const createSchedule = (layouts) => ({
+    layouts: layouts.map((l, idx) => ({
+      id: l.id || idx + 1,
+      file: l.file || idx + 100,
+      duration: l.duration || 60,
+      shareOfVoice: l.shareOfVoice || 0,
+      priority: l.priority || 0,
+      fromdt: l.fromdt || '2026-01-01 00:00:00',
+      todt: l.todt || '2027-01-01 00:00:00',
+      maxPlaysPerHour: l.maxPlaysPerHour || 0
+    }))
+  });
+
+  describe('Basic interrupt integration', () => {
+    it('should process interrupts automatically', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 10 }, // Interrupt
+        { file: 20, duration: 60, shareOfVoice: 0 }   // Normal
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Should have both interrupts and normal layouts
+      expect(layouts.length).toBeGreaterThan(0);
+
+      const interruptCount = layouts.filter(f => f === 10).length;
+      const normalCount = layouts.filter(f => f === 20).length;
+
+      // 10% = 360s / 60s = 6 interrupt plays
+      expect(interruptCount).toBe(6);
+
+      // Remaining 3240s / 60s = 54 normal plays
+      expect(normalCount).toBe(54);
+    });
+
+    it('should work without interrupt scheduler', () => {
+      // Create schedule manager without interrupt scheduler
+      const basicManager = new ScheduleManager();
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 10 },
+        { file: 20, duration: 60, shareOfVoice: 0 }
+      ]);
+
+      basicManager.setSchedule(schedule);
+      const layouts = basicManager.getCurrentLayouts();
+
+      // Without interrupt scheduler, both layouts treated equally
+      expect(layouts).toContain(10);
+      expect(layouts).toContain(20);
+    });
+
+    it('should handle schedule with only normal layouts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 0 },
+        { file: 20, duration: 60, shareOfVoice: 0 }
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Should return both files
+      expect(layouts).toContain(10);
+      expect(layouts).toContain(20);
+    });
+
+    it('should handle schedule with only interrupts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 100 }
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Should fill hour with interrupts
+      expect(layouts.length).toBeGreaterThan(0);
+      expect(layouts.every(f => f === 10)).toBe(true);
+    });
+  });
+
+  describe('Priority + Interrupts', () => {
+    it('should respect priority before processing interrupts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 10, priority: 5 },  // Lower priority interrupt
+        { file: 20, duration: 60, shareOfVoice: 0, priority: 10 }   // Higher priority normal
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Only priority 10 should be included
+      expect(layouts.every(f => f === 20)).toBe(true);
+    });
+
+    it('should process interrupts among same-priority layouts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 25, priority: 10 }, // Interrupt
+        { file: 20, duration: 60, shareOfVoice: 25, priority: 10 }, // Interrupt
+        { file: 30, duration: 60, shareOfVoice: 0, priority: 10 }   // Normal
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const int1Count = layouts.filter(f => f === 10).length;
+      const int2Count = layouts.filter(f => f === 20).length;
+      const normalCount = layouts.filter(f => f === 30).length;
+
+      // Each interrupt: 25% = 900s / 60s = 15 plays
+      expect(int1Count).toBe(15);
+      expect(int2Count).toBe(15);
+
+      // Remaining: 1800s / 60s = 30 normal plays
+      expect(normalCount).toBe(30);
+    });
+  });
+
+  describe('Campaigns + Interrupts', () => {
+    it('should process interrupts from campaigns', () => {
+      scheduleManager.setSchedule({
+        campaigns: [
+          {
+            id: 1,
+            priority: 10,
+            fromdt: '2026-01-01 00:00:00',
+            todt: '2027-01-01 00:00:00',
+            layouts: [
+              { file: 10, duration: 60, shareOfVoice: 10 },
+              { file: 20, duration: 60, shareOfVoice: 0 }
+            ]
+          }
+        ]
+      });
+
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const interruptCount = layouts.filter(f => f === 10).length;
+      const normalCount = layouts.filter(f => f === 20).length;
+
+      // Interrupt: 10% = 360s / 60s = 6 plays
+      expect(interruptCount).toBe(6);
+
+      // Normal fills remaining time
+      expect(normalCount).toBeGreaterThan(0);
+    });
+
+    it('should handle mixed campaigns and standalone interrupts', () => {
+      scheduleManager.setSchedule({
+        campaigns: [
+          {
+            id: 1,
+            priority: 10,
+            fromdt: '2026-01-01 00:00:00',
+            todt: '2027-01-01 00:00:00',
+            layouts: [
+              { file: 10, duration: 60, shareOfVoice: 0 } // Normal in campaign
+            ]
+          }
+        ],
+        layouts: [
+          {
+            id: 2,
+            file: 20,
+            duration: 60,
+            shareOfVoice: 10, // Interrupt standalone
+            priority: 10,
+            fromdt: '2026-01-01 00:00:00',
+            todt: '2027-01-01 00:00:00'
+          }
+        ]
+      });
+
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const normalCount = layouts.filter(f => f === 10).length;
+      const interruptCount = layouts.filter(f => f === 20).length;
+
+      // Both should be present
+      expect(normalCount).toBeGreaterThan(0);
+      expect(interruptCount).toBeGreaterThan(0);
+
+      // Interrupt: 10% = 6 plays
+      expect(interruptCount).toBe(6);
+    });
+  });
+
+  describe('Time-based filtering + Interrupts', () => {
+    it('should filter out-of-date interrupts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 50, todt: '2020-01-01 00:00:00' }, // Expired interrupt
+        { file: 20, duration: 60, shareOfVoice: 0 } // Active normal
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Only normal layout should be present
+      expect(layouts.every(f => f === 20)).toBe(true);
+    });
+
+    it('should handle dayparting with interrupts', () => {
+      const now = new Date();
+      const currentHour = now.getHours();
+      const fromTime = new Date();
+      fromTime.setHours(currentHour - 1, 0, 0, 0);
+      const toTime = new Date();
+      toTime.setHours(currentHour + 1, 0, 0, 0);
+
+      scheduleManager.setSchedule({
+        layouts: [
+          {
+            id: 1,
+            file: 10,
+            duration: 60,
+            shareOfVoice: 20,
+            priority: 0,
+            fromdt: fromTime.toISOString(),
+            todt: toTime.toISOString(),
+            recurrenceType: 'Week',
+            recurrenceRepeatsOn: '1,2,3,4,5,6,7' // All days
+          },
+          {
+            id: 2,
+            file: 20,
+            duration: 60,
+            shareOfVoice: 0,
+            priority: 0,
+            fromdt: fromTime.toISOString(),
+            todt: toTime.toISOString()
+          }
+        ]
+      });
+
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Should have both layouts
+      expect(layouts.length).toBeGreaterThan(0);
+
+      const interruptCount = layouts.filter(f => f === 10).length;
+
+      // 20% = 720s / 60s = 12 plays
+      expect(interruptCount).toBe(12);
+    });
+  });
+
+  describe('maxPlaysPerHour + Interrupts', () => {
+    it('should respect maxPlaysPerHour for normal layouts', () => {
+      const schedule = createSchedule([
+        { file: 10, duration: 60, shareOfVoice: 10 }, // Interrupt
+        { file: 20, duration: 60, shareOfVoice: 0, maxPlaysPerHour: 5 } // Normal with limit
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+
+      // Record plays to trigger maxPlaysPerHour
+      for (let i = 0; i < 5; i++) {
+        scheduleManager.recordPlay(2); // Layout ID 2
+      }
+
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      // Normal layout should be filtered out
+      const normalCount = layouts.filter(f => f === 20).length;
+      expect(normalCount).toBe(0);
+
+      // Only interrupts should remain
+      expect(layouts.every(f => f === 10)).toBe(true);
+    });
+  });
+
+  describe('Real-world scenarios', () => {
+    it('should handle typical digital signage with 5% ads', () => {
+      const schedule = createSchedule([
+        { file: 100, duration: 120, shareOfVoice: 5 },   // 5% ads
+        { file: 200, duration: 120, shareOfVoice: 0 },   // Content 1
+        { file: 300, duration: 120, shareOfVoice: 0 }    // Content 2
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const adCount = layouts.filter(f => f === 100).length;
+      const adDuration = adCount * 120;
+
+      // 5% of hour = 180 seconds (may overshoot slightly due to rounding)
+      expect(adDuration).toBeGreaterThanOrEqual(180);
+      expect(adDuration).toBeLessThan(300); // Reasonable upper bound
+
+      // Should have content layouts
+      expect(layouts.filter(f => f === 200).length).toBeGreaterThan(0);
+      expect(layouts.filter(f => f === 300).length).toBeGreaterThan(0);
+    });
+
+    it('should handle lunch hour with special promotions', () => {
+      const schedule = createSchedule([
+        { file: 1000, duration: 30, shareOfVoice: 20 }, // Lunch specials: 20%
+        { file: 2000, duration: 120, shareOfVoice: 0 }  // Regular menu
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const specialCount = layouts.filter(f => f === 1000).length;
+      const specialDuration = specialCount * 30;
+
+      // 20% of hour = 720 seconds
+      expect(specialDuration).toBe(720);
+
+      // Should have regular content
+      expect(layouts.filter(f => f === 2000).length).toBeGreaterThan(0);
+    });
+
+    it('should handle emergency alerts (high shareOfVoice)', () => {
+      const schedule = createSchedule([
+        { file: 9999, duration: 60, shareOfVoice: 75 }, // Emergency alert: 75%
+        { file: 1000, duration: 60, shareOfVoice: 0 }   // Normal content
+      ]);
+
+      scheduleManager.setSchedule(schedule);
+      const layouts = scheduleManager.getCurrentLayouts();
+
+      const alertCount = layouts.filter(f => f === 9999).length;
+      const contentCount = layouts.filter(f => f === 1000).length;
+
+      // Alert: 75% = 2700s / 60s = 45 plays
+      expect(alertCount).toBe(45);
+
+      // Content: 25% = 900s / 60s = 15 plays
+      expect(contentCount).toBe(15);
+    });
+  });
+});

package/src/interrupts.js

@@ -0,0 +1,298 @@
+/**
+ * Interrupt Layout Scheduler (Share of Voice)
+ *
+ * Implements the shareOfVoice algorithm from upstream electron-player.
+ * Interrupts are layouts that must play for a percentage of each hour.
+ *
+ * Algorithm:
+ * 1. Separate interrupts from normal layouts
+ * 2. Calculate how many times each interrupt must play per hour
+ * 3. Fill remaining time with normal layouts
+ * 4. Interleave interrupts and normal layouts evenly
+ *
+ * Based on: electron-player/src/main/common/scheduleManager.ts (lines 181-321)
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+
+const logger = createLogger('schedule:interrupts');
+
+/**
+ * Interrupt Scheduler
+ * Handles shareOfVoice layouts that must play for a percentage of each hour
+ */
+export class InterruptScheduler {
+  constructor() {
+    // Track committed duration per interrupt layout
+    this.interruptCommittedDurations = new Map(); // layoutId -> seconds
+  }
+
+  /**
+   * Check if a layout is an interrupt (has shareOfVoice > 0)
+   * @param {Object} layout - Layout object with shareOfVoice property
+   * @returns {boolean} True if layout is an interrupt
+   */
+  isInterrupt(layout) {
+    return !!(layout.shareOfVoice && layout.shareOfVoice > 0);
+  }
+
+  /**
+   * Reset committed duration tracking (call this every hour)
+   */
+  resetCommittedDurations() {
+    this.interruptCommittedDurations.clear();
+    logger.debug('Reset interrupt committed durations');
+  }
+
+  /**
+   * Get committed duration for a layout
+   * @param {string} layoutId - Layout ID
+   * @returns {number} Committed duration in seconds
+   */
+  getCommittedDuration(layoutId) {
+    return this.interruptCommittedDurations.get(layoutId) || 0;
+  }
+
+  /**
+   * Add committed duration for a layout
+   * @param {string} layoutId - Layout ID
+   * @param {number} duration - Duration to add in seconds
+   */
+  addCommittedDuration(layoutId, duration) {
+    const current = this.getCommittedDuration(layoutId);
+    this.interruptCommittedDurations.set(layoutId, current + duration);
+  }
+
+  /**
+   * Check if interrupt layout has satisfied its shareOfVoice requirement
+   * @param {Object} layout - Layout with shareOfVoice and duration
+   * @returns {boolean} True if satisfied
+   */
+  isInterruptDurationSatisfied(layout) {
+    if (!layout.shareOfVoice) {
+      return true; // Not an interrupt
+    }
+
+    const layoutId = layout.id || layout.file;
+    const requiredSeconds = (layout.shareOfVoice / 100) * 3600; // shareOfVoice is percentage
+    const committedSeconds = this.getCommittedDuration(layoutId);
+
+    return committedSeconds >= requiredSeconds;
+  }
+
+  /**
+   * Calculate how many seconds this interrupt needs to play per hour
+   * @param {Object} layout - Layout with shareOfVoice
+   * @returns {number} Required seconds per hour
+   */
+  getRequiredSeconds(layout) {
+    if (!layout.shareOfVoice) {
+      return 0;
+    }
+    return (layout.shareOfVoice / 100) * 3600;
+  }
+
+  /**
+   * Process interrupt layouts and combine with normal layouts
+   * Implements the shareOfVoice algorithm from upstream
+   *
+   * @param {Array} normalLayouts - Normal scheduled layouts
+   * @param {Array} interruptLayouts - Interrupt layouts with shareOfVoice
+   * @returns {Array} Combined layout loop for the hour
+   */
+  processInterrupts(normalLayouts, interruptLayouts) {
+    if (!interruptLayouts || interruptLayouts.length === 0) {
+      logger.debug('No interrupt layouts, returning normal layouts');
+      return normalLayouts;
+    }
+
+    if (!normalLayouts || normalLayouts.length === 0) {
+      logger.warn('No normal layouts available, interrupts will fill entire hour');
+      return this.fillHourWithInterrupts(interruptLayouts);
+    }
+
+    logger.info(`Processing ${interruptLayouts.length} interrupt layouts with ${normalLayouts.length} normal layouts`);
+
+    // Reset committed durations for this calculation
+    for (const layout of interruptLayouts) {
+      const layoutId = layout.id || layout.file;
+      this.interruptCommittedDurations.set(layoutId, 0);
+    }
+
+    const resolvedInterruptLayouts = [];
+    let interruptSecondsInHour = 0;
+    let index = 0;
+    let satisfied = false;
+
+    // Step 1: Build interrupt loop by cycling through interrupts until all are satisfied
+    while (!satisfied) {
+      // Gone all the way around? Check if all satisfied
+      if (index >= interruptLayouts.length) {
+        index = 0;
+
+        // Check if all interrupts are satisfied
+        let allSatisfied = true;
+        for (const layout of interruptLayouts) {
+          if (!this.isInterruptDurationSatisfied(layout)) {
+            allSatisfied = false;
+            break;
+          }
+        }
+
+        if (allSatisfied) {
+          satisfied = true;
+          break;
+        }
+      }
+
+      const currentInterrupt = interruptLayouts[index];
+
+      // If this interrupt is not satisfied, add it to the loop
+      if (!this.isInterruptDurationSatisfied(currentInterrupt)) {
+        const layoutId = currentInterrupt.id || currentInterrupt.file;
+        this.addCommittedDuration(layoutId, currentInterrupt.duration);
+        interruptSecondsInHour += currentInterrupt.duration;
+        resolvedInterruptLayouts.push(currentInterrupt);
+      }
+
+      index++;
+    }
+
+    logger.debug(`Resolved ${resolvedInterruptLayouts.length} interrupt plays (${interruptSecondsInHour}s total)`);
+
+    // Step 2: If interrupts fill the entire hour, return only interrupts
+    if (interruptSecondsInHour >= 3600) {
+      logger.info('Interrupts fill entire hour (>= 3600s), no room for normal layouts');
+      return resolvedInterruptLayouts;
+    }
+
+    // Step 3: Fill remaining time with normal layouts
+    const normalSecondsInHour = 3600 - interruptSecondsInHour;
+    const resolvedNormalLayouts = this.fillTimeWithLayouts(normalLayouts, normalSecondsInHour);
+
+    logger.debug(`Resolved ${resolvedNormalLayouts.length} normal plays (${normalSecondsInHour}s target)`);
+
+    // Step 4: Interleave interrupts and normal layouts
+    const loop = this.interleaveLayouts(resolvedNormalLayouts, resolvedInterruptLayouts);
+
+    logger.info(`Final loop: ${loop.length} layouts (${resolvedNormalLayouts.length} normal + ${resolvedInterruptLayouts.length} interrupts)`);
+
+    return loop;
+  }
+
+  /**
+   * Fill time with layouts by repeating them until duration is reached
+   * @param {Array} layouts - Layouts to use
+   * @param {number} targetSeconds - Target duration in seconds
+   * @returns {Array} Resolved layout array
+   */
+  fillTimeWithLayouts(layouts, targetSeconds) {
+    const resolved = [];
+    let remainingSeconds = targetSeconds;
+    let index = 0;
+
+    while (remainingSeconds > 0) {
+      if (index >= layouts.length) {
+        index = 0; // Loop back
+      }
+
+      const layout = layouts[index];
+      resolved.push(layout);
+      remainingSeconds -= layout.duration;
+      index++;
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Fill entire hour with interrupt layouts only
+   * @param {Array} interruptLayouts - Interrupt layouts
+   * @returns {Array} Layout loop
+   */
+  fillHourWithInterrupts(interruptLayouts) {
+    return this.fillTimeWithLayouts(interruptLayouts, 3600);
+  }
+
+  /**
+   * Interleave normal and interrupt layouts evenly
+   * Based on upstream algorithm (scheduleManager.ts lines 268-316)
+   *
+   * @param {Array} normalLayouts - Normal layouts
+   * @param {Array} interruptLayouts - Interrupt layouts
+   * @returns {Array} Interleaved layout array
+   */
+  interleaveLayouts(normalLayouts, interruptLayouts) {
+    const loop = [];
+    const pickCount = Math.max(normalLayouts.length, interruptLayouts.length);
+
+    // Calculate pick intervals
+    // Normal: ceiling (pick more often from normal)
+    // Interrupt: floor (pick less often from interrupts)
+    const normalPick = Math.ceil(1.0 * pickCount / normalLayouts.length);
+    const interruptPick = Math.floor(1.0 * pickCount / interruptLayouts.length);
+
+    logger.debug(`Interleaving: pickCount=${pickCount}, normalPick=${normalPick}, interruptPick=${interruptPick}`);
+
+    let normalIndex = 0;
+    let interruptIndex = 0;
+    let totalSecondsAllocated = 0;
+
+    for (let i = 0; i < pickCount; i++) {
+      // Pick from normal list
+      if (i % normalPick === 0) {
+        // Allow wrapping around
+        if (normalIndex >= normalLayouts.length) {
+          normalIndex = 0;
+        }
+        loop.push(normalLayouts[normalIndex]);
+        totalSecondsAllocated += normalLayouts[normalIndex].duration;
+        normalIndex++;
+      }
+
+      // Pick from interrupt list (only if we haven't picked them all yet)
+      if (i % interruptPick === 0 && interruptIndex < interruptLayouts.length) {
+        loop.push(interruptLayouts[interruptIndex]);
+        totalSecondsAllocated += interruptLayouts[interruptIndex].duration;
+        interruptIndex++;
+      }
+    }
+
+    // Fill remaining time with normal layouts (due to ceiling/floor rounding)
+    while (totalSecondsAllocated < 3600) {
+      if (normalIndex >= normalLayouts.length) {
+        normalIndex = 0;
+      }
+      loop.push(normalLayouts[normalIndex]);
+      totalSecondsAllocated += normalLayouts[normalIndex].duration;
+      normalIndex++;
+    }
+
+    logger.debug(`Interleaved ${loop.length} layouts, total duration: ${totalSecondsAllocated}s`);
+
+    return loop;
+  }
+
+  /**
+   * Separate layouts into normal and interrupt arrays
+   * @param {Array} layouts - All layouts
+   * @returns {Object} { normalLayouts, interruptLayouts }
+   */
+  separateLayouts(layouts) {
+    const normalLayouts = [];
+    const interruptLayouts = [];
+
+    for (const layout of layouts) {
+      if (this.isInterrupt(layout)) {
+        interruptLayouts.push(layout);
+      } else {
+        normalLayouts.push(layout);
+      }
+    }
+
+    return { normalLayouts, interruptLayouts };
+  }
+}
+
+// Export singleton instance for convenience
+export const interruptScheduler = new InterruptScheduler();