@mostrom/meeting-detector 1.0.4 → 1.0.5

package/README.md

@@ -9,7 +9,9 @@ Real-time meeting detection for macOS desktop apps using TCC (Transparency, Cons
 - 🔍 **Process attribution**: Identifies which app is using camera/microphone with PID
 - 🎛️ **Event-driven**: Clean Node.js API with TypeScript support
 - 🚫 **Smart deduplication**: Prevents spam from multi-process apps like Teams
-- 📱 **Front app correlation**: Shows which app is currently in focus
+- 🔁 **Lifecycle hooks**: Emits `meeting_started`, `meeting_changed`, and `meeting_ended`
+- 🧠 **Uncertainty-safe**: Uses `Unknown`/no-detection instead of guessing
+- 🔒 **Privacy-first**: Redacts sensitive metadata by default
 
 ## Installation
 
@@ -71,10 +73,19 @@ import type { MeetingSignal } from '@mostrom/meeting-detector';
 const detector = new MeetingDetector({ debug: true });
 
 detector.onMeeting((signal: MeetingSignal) => {
-  console.log(`${signal.process} is using ${signal.service}`);
-  if (signal.verdict === 'requested') {
-    console.log('🔴 Meeting started');
-  }
+  console.log('Raw signal:', signal.service, signal.verdict);
+});
+
+detector.onMeetingStarted((event) => {
+  console.log(`✅ Started: ${event.platform}`);
+});
+
+detector.onMeetingChanged((event) => {
+  console.log(`🔄 Changed: ${event.previous_platform} -> ${event.platform}`);
+});
+
+detector.onMeetingEnded((event) => {
+  console.log(`⏹️ Ended: ${event.platform} (${event.reason})`);
 });
 
 detector.onError((error) => {
@@ -104,10 +115,16 @@ new MeetingDetector(options?: MeetingDetectorOptions)
 - `stop()` - Stop monitoring  
 - `isRunning()` - Check if running
 - `onMeeting(callback)` - Add meeting event listener
+- `onMeetingStarted(callback)` - Add meeting started listener
+- `onMeetingChanged(callback)` - Add meeting changed listener
+- `onMeetingEnded(callback)` - Add meeting ended listener
 - `onError(callback)` - Add error event listener
 
 #### Events
-- `meeting` - Emitted when meeting state changes
+- `meeting` - Emitted for normalized raw meeting signals
+- `meeting_started` - Emitted when active meeting starts
+- `meeting_changed` - Emitted when active platform changes
+- `meeting_ended` - Emitted when meeting ends (timeout/stop)
 - `error` - Emitted on errors
 - `exit` - Emitted when process exits
 
@@ -115,34 +132,61 @@ new MeetingDetector(options?: MeetingDetectorOptions)
 
 ```json
 {
-  "event": "meeting_signal",
-  "timestamp": "2025-09-01T14:30:29Z",
-  "service": "microphone",
-  "verdict": "requested", 
-  "process": "Microsoft Teams WebView Helper",
-  "pid": "7390",
-  "front_app": "MSTeams",
-  "camera_active": true
+  "event": "meeting_started",
+  "timestamp": "2026-03-07T12:30:29.000Z",
+  "platform": "Microsoft Teams",
+  "confidence": "high",
+  "reason": "signal"
 }
 ```
 
 ## TypeScript Types
 
 ```typescript
+type MeetingPlatform =
+  | 'Microsoft Teams'
+  | 'Zoom'
+  | 'Google Meet'
+  | 'Slack'
+  | 'Cisco Webex'
+  | 'Unknown';
+
 interface MeetingSignal {
   event: 'meeting_signal';
   timestamp: string;
-  service: 'microphone' | 'camera' | '';
+  service: string;
   verdict: 'requested' | 'allowed' | 'denied' | '';
+  preflight?: boolean;
   process: string;
   pid: string;
+  parent_pid: string;
+  process_path: string;
   front_app: string;
+  window_title: string;
+  session_id: string;
   camera_active: boolean;
+  chrome_url?: string;
+}
+
+interface MeetingLifecycleEvent {
+  event: 'meeting_started' | 'meeting_changed' | 'meeting_ended';
+  timestamp: string;
+  platform: MeetingPlatform;
+  previous_platform?: MeetingPlatform;
+  confidence: 'high' | 'medium' | 'low';
+  reason: 'signal' | 'switch' | 'timeout' | 'stop';
+  raw_signal?: MeetingSignal;
 }
 
 interface MeetingDetectorOptions {
-  scriptPath?: string;  // Path to bash script (default: './meeting-detect.sh')
-  debug?: boolean;      // Enable debug logging (default: false)
+  scriptPath?: string;
+  debug?: boolean;
+  sessionDeduplicationMs?: number;
+  meetingEndTimeoutMs?: number;
+  emitUnknown?: boolean;
+  includeSensitiveMetadata?: boolean;
+  includeRawSignalInLifecycle?: boolean;
+  startupProbe?: boolean;
 }
 ```
 
@@ -179,4 +223,4 @@ The detector runs a bash script that monitors macOS TCC (privacy) logs for micro
 
 ## License
 
-MIT
+MIT

package/dist/detector.d.ts

@@ -1,9 +1,17 @@
 import { EventEmitter } from 'node:events';
-import { MeetingDetectorOptions, MeetingEventCallback, ErrorEventCallback } from './types.js';
+import { MeetingDetectorOptions, MeetingEventCallback, ErrorEventCallback, MeetingLifecycleCallback } from './types.js';
 export declare class MeetingDetector extends EventEmitter {
+    private static readonly LOW_CONFIDENCE_WINDOW_MS;
+    private static readonly LOW_CONFIDENCE_FALLBACK_MIN_SIGNALS;
+    private static readonly LOW_CONFIDENCE_FALLBACK_MIN_DURATION_MS;
+    private static readonly PRECHECK_PRONE_SERVICES;
     private process?;
     private options;
     private activeSessions;
+    private pendingConfidence;
+    private serviceContext;
+    private activeMeeting;
+    private meetingEndTimer?;
     constructor(options?: MeetingDetectorOptions);
     /**
      * Start monitoring for meeting signals
@@ -26,6 +34,12 @@ export declare class MeetingDetector extends EventEmitter {
      * Add an error event listener
      */
     onError(callback: ErrorEventCallback): void;
+    /**
+     * Add lifecycle event listeners
+     */
+    onMeetingStarted(callback: MeetingLifecycleCallback): void;
+    onMeetingChanged(callback: MeetingLifecycleCallback): void;
+    onMeetingEnded(callback: MeetingLifecycleCallback): void;
     /**
      * Comprehensive filtering to prevent false positives
      * Filters out:
@@ -36,6 +50,20 @@ export declare class MeetingDetector extends EventEmitter {
      * - Google Meet signals without valid meeting URL patterns
      */
     private shouldIgnoreSignal;
+    private sanitizeSignalForOutput;
+    private normalizePlatform;
+    private getSignalConfidence;
+    private emitMeetingLifecycle;
+    private scheduleMeetingEndCheck;
+    private handleMeetingEndTimeout;
+    private updateMeetingLifecycle;
+    private getServiceKey;
+    private isFrontAppConsistentWithService;
+    private stabilizeSignalContext;
+    private isLowConfidenceSignal;
+    private hasStrongMeetingEvidence;
+    private cleanupExpiredPendingConfidence;
+    private resolveConfidence;
     /**
      * Generate a unique session key based on the signal properties
      */
@@ -50,7 +78,14 @@ export declare class MeetingDetector extends EventEmitter {
      */
     private cleanupExpiredSessions;
     private parseSignal;
+    private includesAny;
     private transformAppName;
+    /**
+     * Check at startup whether a supported meeting is already active.
+     * Emits a synthetic meeting_started lifecycle event if found.
+     * This handles the case where the detector starts while a call is already in progress.
+     */
+    private probeActiveMeetingAtStartup;
 }
 export declare function detector(callback: MeetingEventCallback, options?: MeetingDetectorOptions): MeetingDetector;
 //# sourceMappingURL=detector.d.ts.map

package/dist/detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAiB,sBAAsB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAO7G,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,cAAc,CAAuC;gBAEjD,OAAO,GAAE,sBAA2B;IAgBhD;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI;IAuEnD;;OAEG;IACI,IAAI,IAAI,IAAI;IAcnB;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAItD;;OAEG;IACI,OAAO,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAIlD;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IA0E1B;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,gBAAgB;CAqDzB;AAGD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAI1G"}
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAEL,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAElB,wBAAwB,EAEzB,MAAM,YAAY,CAAC;AA0BpB,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAS;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mCAAmC,CAAK;IAChE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uCAAuC,CAAS;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAK5C;IAEH,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,iBAAiB,CAAmD;IAC5E,OAAO,CAAC,cAAc,CAA0C;IAChE,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,eAAe,CAAC,CAAiB;gBAE7B,OAAO,GAAE,sBAA2B;IAqBhD;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI;IAoHnD;;OAEG;IACI,IAAI,IAAI,IAAI;IAyBnB;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAItD;;OAEG;IACI,OAAO,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAIlD;;OAEG;IACI,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI1D,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI1D,cAAc,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI/D;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAiF1B,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,oBAAoB;IAqB5B,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,uBAAuB;IAkB/B,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,+BAA+B;IAuBvC,OAAO,CAAC,sBAAsB;IAiC9B,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,+BAA+B;IAQvC,OAAO,CAAC,iBAAiB;IA0BzB;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,WAAW;IA6BnB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,gBAAgB;IAiFxB;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;CAyFpC;AAGD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAI1G"}