@principal-ai/control-tower-core 0.1.6 → 0.1.8

package/README.md

@@ -36,6 +36,7 @@ console.log('Server started on port 8080');
 - **Real-time Events**: Event broadcasting and history
 - **Extensible**: Abstract interfaces for custom implementations
 - **TypeScript**: Full type safety with generated declarations
+- **Experimental APIs**: Opt-in broadcast features for rapid prototyping (see [Experimental Features](#experimental-features))
 
 ## API Reference
 
@@ -79,6 +80,121 @@ class CustomRoomManager extends RoomManager {
 }
 ```
 
+## Experimental Features
+
+⚠️ **For Development Use Only**
+
+Control Tower Core provides experimental broadcast APIs for rapid prototyping and internal tooling. These APIs allow broadcasting messages beyond room boundaries.
+
+### Enabling Experimental Features
+
+```typescript
+import { ServerBuilder } from '@principal-ai/control-tower-core';
+
+const server = new ServerBuilder()
+  .withTransport(transportAdapter)
+  .withRoomManager(roomManager)
+  .withLockManager(lockManager)
+  .withExperimentalFeatures({
+    enableBroadcast: true  // Enable experimental broadcast APIs
+  })
+  .build();
+```
+
+### Using Experimental Broadcast
+
+```typescript
+// Broadcast to all connected clients
+await server.experimental.broadcast({
+  type: 'system:announcement',
+  data: { message: 'Server maintenance in 5 minutes' }
+});
+
+// Broadcast to authenticated users only
+await server.experimental.broadcastAuthenticated({
+  type: 'presence:user_online',
+  data: { userId: 'alice' }
+});
+
+// Broadcast with custom filtering
+await server.experimental.broadcastWhere(
+  (client) => client.userId.startsWith('admin_'),
+  { type: 'admin:alert', data: { ... } }
+);
+
+// Send to specific users
+await server.experimental.sendToUsers(
+  ['user1', 'user2'],
+  { type: 'notification:mention', data: { ... } }
+);
+```
+
+### Important Notes
+
+- **Experimental APIs may change or be removed** without major version bumps
+- **Not recommended for production** applications
+- Use for prototyping, then submit a [feature request](docs/FEATURE_REQUEST_TEMPLATE.md) to graduate to stable API
+- See [full documentation](docs/EXPERIMENTAL_BROADCAST.md) for details
+
+## Testing
+
+Control Tower Core provides comprehensive test utilities for building reliable applications.
+
+### MockTransportAdapter
+
+The `MockTransportAdapter` provides test helpers for simulating client-server interactions:
+
+```typescript
+import { MockTransportAdapter } from '@principal-ai/control-tower-core';
+
+const transport = new MockTransportAdapter();
+
+// Simulate a client connection
+await transport.simulateConnection('client-id', {
+  authenticated: true,
+  userId: 'user-123',
+  metadata: { deviceType: 'desktop' }
+});
+
+// Simulate client messages
+await transport.simulateClientMessage('client-id', 'join_room', {
+  roomId: 'room-1'
+});
+
+// Simulate incoming server messages (for client tests)
+transport.simulateIncomingMessage({
+  type: 'room_joined',
+  payload: { roomId: 'room-1', state: { ... } }
+});
+
+// Track connection attempts (useful for reconnection tests)
+const attempts = transport.getConnectionAttempts();
+transport.resetConnectionAttempts();
+
+// Get messages sent to specific clients
+const messages = transport.getSentMessages('client-id');
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test file
+bun test tests/BaseServer.test.ts
+
+# Run with coverage
+bun test --coverage
+```
+
+## Documentation
+
+- [Experimental Broadcast APIs](docs/EXPERIMENTAL_BROADCAST.md)
+- [Feature Request Template](docs/FEATURE_REQUEST_TEMPLATE.md)
+- [Architecture Design](DESIGN.md)
+- [Changelog](CHANGELOG.md)
+
 ## License
 
 MIT

package/dist/abstractions/DefaultPresenceManager.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Default In-Memory Presence Manager
+ *
+ * Reference implementation of PresenceManager using in-memory storage.
+ * Suitable for single-server deployments and development.
+ *
+ * For multi-server deployments, implement a custom PresenceManager
+ * backed by Redis or another shared data store.
+ */
+import { PresenceManager } from './PresenceManager.js';
+import type { UserPresence, DeviceInfo, PresenceStatus, PresenceConfig, PresenceChangeEvent, ActivityUpdate } from '../types/presence.js';
+export declare class DefaultPresenceManager extends PresenceManager {
+    private userPresences;
+    private deviceToUser;
+    private gracePeriodEntries;
+    constructor(config?: PresenceConfig);
+    connectDevice(userId: string, deviceId: string, deviceInfo?: Partial<DeviceInfo>): Promise<UserPresence>;
+    disconnectDevice(userId: string, deviceId: string): Promise<UserPresence | null>;
+    updateActivity(update: ActivityUpdate): Promise<UserPresence>;
+    getUserPresence(userId: string): Promise<UserPresence | null>;
+    getUsersPresence(userIds: string[]): Promise<Map<string, UserPresence>>;
+    getOnlineUsers(): Promise<UserPresence[]>;
+    getUserDevices(userId: string): Promise<DeviceInfo[]>;
+    setUserStatus(userId: string, status: PresenceStatus): Promise<UserPresence>;
+    processHeartbeats(): Promise<PresenceChangeEvent[]>;
+    clear(): Promise<void>;
+    /**
+     * Get count of users in grace period (useful for monitoring)
+     */
+    getGracePeriodCount(): number;
+    /**
+     * Get total connected device count
+     */
+    getConnectedDeviceCount(): number;
+    /**
+     * Get total unique user count
+     */
+    getUniqueUserCount(): number;
+}
+//# sourceMappingURL=DefaultPresenceManager.d.ts.map

package/dist/abstractions/DefaultPresenceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultPresenceManager.d.ts","sourceRoot":"","sources":["../../src/abstractions/DefaultPresenceManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAW9B,qBAAa,sBAAuB,SAAQ,eAAe;IACzD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,kBAAkB,CAAuC;gBAErD,MAAM,CAAC,EAAE,cAAc;IAI7B,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC,YAAY,CAAC;IA+DlB,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA6CzB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IA4B7D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAI7D,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAavE,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAYzC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IASrD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAU5E,iBAAiB,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA4EnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;OAEG;IACH,uBAAuB,IAAI,MAAM;IAIjC;;OAEG;IACH,kBAAkB,IAAI,MAAM;CAG7B"}

package/dist/abstractions/DefaultPresenceManager.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Default In-Memory Presence Manager
+ *
+ * Reference implementation of PresenceManager using in-memory storage.
+ * Suitable for single-server deployments and development.
+ *
+ * For multi-server deployments, implement a custom PresenceManager
+ * backed by Redis or another shared data store.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultPresenceManager = void 0;
+const PresenceManager_js_1 = require("./PresenceManager.js");
+class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
+    constructor(config) {
+        super(config);
+        this.userPresences = new Map();
+        this.deviceToUser = new Map();
+        this.gracePeriodEntries = new Map();
+    }
+    async connectDevice(userId, deviceId, deviceInfo) {
+        const now = Date.now();
+        // Check if user is in grace period (reconnecting)
+        const gracePeriodEntry = this.gracePeriodEntries.get(userId);
+        if (gracePeriodEntry) {
+            // Restore from grace period
+            this.gracePeriodEntries.delete(userId);
+            const presence = gracePeriodEntry.previousPresence;
+            // Add the new device
+            const device = {
+                deviceId,
+                type: deviceInfo?.type,
+                connectedAt: now,
+                lastActivity: now,
+                metadata: deviceInfo?.metadata
+            };
+            presence.devices.set(deviceId, device);
+            presence.status = 'online';
+            presence.lastActivity = now;
+            this.userPresences.set(userId, presence);
+            this.deviceToUser.set(deviceId, userId);
+            return presence;
+        }
+        // Get or create user presence
+        let presence = this.userPresences.get(userId);
+        if (!presence) {
+            // New user
+            presence = {
+                userId,
+                status: 'online',
+                devices: new Map(),
+                firstConnectedAt: now,
+                lastActivity: now,
+                metadata: {}
+            };
+            this.userPresences.set(userId, presence);
+        }
+        // Add device
+        const device = {
+            deviceId,
+            type: deviceInfo?.type,
+            connectedAt: now,
+            lastActivity: now,
+            metadata: deviceInfo?.metadata
+        };
+        presence.devices.set(deviceId, device);
+        presence.status = this.calculatePresenceStatus(presence.devices, now);
+        presence.lastActivity = now;
+        this.deviceToUser.set(deviceId, userId);
+        return presence;
+    }
+    async disconnectDevice(userId, deviceId) {
+        const presence = this.userPresences.get(userId);
+        if (!presence) {
+            return null;
+        }
+        // Remove device
+        presence.devices.delete(deviceId);
+        this.deviceToUser.delete(deviceId);
+        const now = Date.now();
+        // If no devices left, start grace period
+        if (presence.devices.size === 0) {
+            if (this.config.gracePeriod > 0) {
+                // Move to grace period
+                this.gracePeriodEntries.set(userId, {
+                    userId,
+                    disconnectedAt: now,
+                    previousPresence: presence
+                });
+                this.userPresences.delete(userId);
+                return null;
+            }
+            else {
+                // No grace period, remove completely
+                this.userPresences.delete(userId);
+                return null;
+            }
+        }
+        // Still has devices, update status
+        presence.status = this.calculatePresenceStatus(presence.devices, now);
+        // Update lastActivity to most recent device activity
+        let mostRecentActivity = 0;
+        for (const device of presence.devices.values()) {
+            if (device.lastActivity > mostRecentActivity) {
+                mostRecentActivity = device.lastActivity;
+            }
+        }
+        presence.lastActivity = mostRecentActivity;
+        return presence;
+    }
+    async updateActivity(update) {
+        const { userId, deviceId, timestamp } = update;
+        const presence = this.userPresences.get(userId);
+        if (!presence) {
+            throw new Error(`User ${userId} not found in presence system`);
+        }
+        const device = presence.devices.get(deviceId);
+        if (!device) {
+            throw new Error(`Device ${deviceId} not found for user ${userId}`);
+        }
+        // Update device activity
+        device.lastActivity = timestamp;
+        // Update user activity
+        if (timestamp > presence.lastActivity) {
+            presence.lastActivity = timestamp;
+        }
+        // Recalculate status
+        const previousStatus = presence.status;
+        presence.status = this.calculatePresenceStatus(presence.devices, timestamp);
+        return presence;
+    }
+    async getUserPresence(userId) {
+        return this.userPresences.get(userId) || null;
+    }
+    async getUsersPresence(userIds) {
+        const result = new Map();
+        for (const userId of userIds) {
+            const presence = this.userPresences.get(userId);
+            if (presence) {
+                result.set(userId, presence);
+            }
+        }
+        return result;
+    }
+    async getOnlineUsers() {
+        const online = [];
+        for (const presence of this.userPresences.values()) {
+            if (presence.status === 'online') {
+                online.push(presence);
+            }
+        }
+        return online;
+    }
+    async getUserDevices(userId) {
+        const presence = this.userPresences.get(userId);
+        if (!presence) {
+            return [];
+        }
+        return Array.from(presence.devices.values());
+    }
+    async setUserStatus(userId, status) {
+        const presence = this.userPresences.get(userId);
+        if (!presence) {
+            throw new Error(`User ${userId} not found in presence system`);
+        }
+        presence.status = status;
+        return presence;
+    }
+    async processHeartbeats() {
+        const now = Date.now();
+        const changes = [];
+        // Process active presences
+        for (const [userId, presence] of this.userPresences.entries()) {
+            const devicesToRemove = [];
+            // Check each device for timeout
+            for (const [deviceId, device] of presence.devices.entries()) {
+                if (this.shouldDisconnectDevice(device, now)) {
+                    devicesToRemove.push(deviceId);
+                }
+            }
+            // Remove timed-out devices
+            for (const deviceId of devicesToRemove) {
+                presence.devices.delete(deviceId);
+                this.deviceToUser.delete(deviceId);
+            }
+            // Update status after removing devices
+            const previousStatus = presence.status;
+            const newStatus = this.calculatePresenceStatus(presence.devices, now);
+            if (newStatus !== previousStatus) {
+                presence.status = newStatus;
+                changes.push({
+                    userId,
+                    previousStatus,
+                    status: newStatus,
+                    timestamp: now,
+                    reason: 'heartbeat_timeout'
+                });
+            }
+            // If no devices left, move to grace period
+            if (presence.devices.size === 0) {
+                if (this.config.gracePeriod > 0) {
+                    this.gracePeriodEntries.set(userId, {
+                        userId,
+                        disconnectedAt: now,
+                        previousPresence: presence
+                    });
+                }
+                this.userPresences.delete(userId);
+            }
+        }
+        // Process grace period expirations
+        const expiredGracePeriods = [];
+        for (const [userId, entry] of this.gracePeriodEntries.entries()) {
+            const gracePeriodElapsed = now - entry.disconnectedAt;
+            if (gracePeriodElapsed > this.config.gracePeriod) {
+                expiredGracePeriods.push(userId);
+                changes.push({
+                    userId,
+                    previousStatus: entry.previousPresence.status,
+                    status: 'offline',
+                    timestamp: now,
+                    reason: 'grace_period_expired'
+                });
+            }
+        }
+        // Remove expired grace period entries
+        for (const userId of expiredGracePeriods) {
+            this.gracePeriodEntries.delete(userId);
+        }
+        return changes;
+    }
+    async clear() {
+        this.userPresences.clear();
+        this.deviceToUser.clear();
+        this.gracePeriodEntries.clear();
+    }
+    /**
+     * Get count of users in grace period (useful for monitoring)
+     */
+    getGracePeriodCount() {
+        return this.gracePeriodEntries.size;
+    }
+    /**
+     * Get total connected device count
+     */
+    getConnectedDeviceCount() {
+        return this.deviceToUser.size;
+    }
+    /**
+     * Get total unique user count
+     */
+    getUniqueUserCount() {
+        return this.userPresences.size + this.gracePeriodEntries.size;
+    }
+}
+exports.DefaultPresenceManager = DefaultPresenceManager;

package/dist/abstractions/PresenceManager.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Presence Manager Abstract Class
+ *
+ * Manages global user presence tracking independent of room membership.
+ * Supports multi-device connections, activity monitoring, and grace periods.
+ */
+import type { UserPresence, DeviceInfo, PresenceStatus, PresenceConfig, PresenceChangeEvent, ActivityUpdate } from '../types/presence.js';
+/**
+ * Abstract class for managing user presence
+ *
+ * Implementations should handle:
+ * - Multi-device tracking per user
+ * - Activity/heartbeat monitoring
+ * - Grace period for disconnects
+ * - Presence state persistence (if needed)
+ */
+export declare abstract class PresenceManager {
+    protected config: Required<PresenceConfig>;
+    constructor(config?: PresenceConfig);
+    /**
+     * Register a new device connection for a user
+     *
+     * @param userId - User identifier
+     * @param deviceId - Device/client identifier
+     * @param deviceInfo - Optional device metadata
+     * @returns The updated user presence
+     */
+    abstract connectDevice(userId: string, deviceId: string, deviceInfo?: Partial<DeviceInfo>): Promise<UserPresence>;
+    /**
+     * Unregister a device connection
+     *
+     * May trigger grace period if this is the user's last device.
+     *
+     * @param userId - User identifier
+     * @param deviceId - Device/client identifier
+     * @returns The updated user presence, or null if user is completely offline
+     */
+    abstract disconnectDevice(userId: string, deviceId: string): Promise<UserPresence | null>;
+    /**
+     * Update activity timestamp for a device
+     *
+     * Used for heartbeats and activity tracking.
+     *
+     * @param update - Activity update information
+     * @returns The updated user presence
+     */
+    abstract updateActivity(update: ActivityUpdate): Promise<UserPresence>;
+    /**
+     * Get presence state for a user
+     *
+     * @param userId - User identifier
+     * @returns User presence, or null if not found
+     */
+    abstract getUserPresence(userId: string): Promise<UserPresence | null>;
+    /**
+     * Get presence state for multiple users
+     *
+     * @param userIds - Array of user identifiers
+     * @returns Map of userId to UserPresence
+     */
+    abstract getUsersPresence(userIds: string[]): Promise<Map<string, UserPresence>>;
+    /**
+     * Get all online users
+     *
+     * @returns Array of user presences with status 'online'
+     */
+    abstract getOnlineUsers(): Promise<UserPresence[]>;
+    /**
+     * Get all devices for a user
+     *
+     * @param userId - User identifier
+     * @returns Array of device info
+     */
+    abstract getUserDevices(userId: string): Promise<DeviceInfo[]>;
+    /**
+     * Manually set user status
+     *
+     * @param userId - User identifier
+     * @param status - New presence status
+     * @returns The updated user presence
+     */
+    abstract setUserStatus(userId: string, status: PresenceStatus): Promise<UserPresence>;
+    /**
+     * Check for stale connections and update presence accordingly
+     *
+     * This should be called periodically to:
+     * - Mark idle devices as 'away'
+     * - Disconnect devices that haven't sent heartbeats
+     * - Expire grace periods
+     *
+     * @returns Array of presence change events
+     */
+    abstract processHeartbeats(): Promise<PresenceChangeEvent[]>;
+    /**
+     * Clear all presence data
+     *
+     * Useful for testing and cleanup.
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Get configuration
+     */
+    getConfig(): Readonly<Required<PresenceConfig>>;
+    /**
+     * Check if presence tracking is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Calculate presence status based on device states
+     *
+     * Helper method for implementations to determine overall user status.
+     *
+     * @param devices - Map of devices for a user
+     * @param now - Current timestamp
+     * @returns Calculated presence status
+     */
+    protected calculatePresenceStatus(devices: Map<string, DeviceInfo>, now?: number): PresenceStatus;
+    /**
+     * Check if a device should be disconnected due to missed heartbeats
+     *
+     * @param device - Device info
+     * @param now - Current timestamp
+     * @returns true if device should be disconnected
+     */
+    protected shouldDisconnectDevice(device: DeviceInfo, now?: number): boolean;
+}
+//# sourceMappingURL=PresenceManager.d.ts.map

package/dist/abstractions/PresenceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresenceManager.d.ts","sourceRoot":"","sources":["../../src/abstractions/PresenceManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;GAQG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;gBAE/B,MAAM,CAAC,EAAE,cAAc;IAanC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC,YAAY,CAAC;IAExB;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAE/B;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAEtE;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAEtE;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAEhF;;;;OAIG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAElD;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAE9D;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAErF;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAE5D;;;;OAIG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAI/C;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;;;OAQG;IACH,SAAS,CAAC,uBAAuB,CAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,GAAG,GAAE,MAAmB,GACvB,cAAc;IAmBjB;;;;;;OAMG;IACH,SAAS,CAAC,sBAAsB,CAC9B,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE,MAAmB,GACvB,OAAO;CAIX"}

package/dist/abstractions/PresenceManager.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Presence Manager Abstract Class
+ *
+ * Manages global user presence tracking independent of room membership.
+ * Supports multi-device connections, activity monitoring, and grace periods.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresenceManager = void 0;
+/**
+ * Abstract class for managing user presence
+ *
+ * Implementations should handle:
+ * - Multi-device tracking per user
+ * - Activity/heartbeat monitoring
+ * - Grace period for disconnects
+ * - Presence state persistence (if needed)
+ */
+class PresenceManager {
+    constructor(config) {
+        // Set defaults
+        this.config = {
+            enabled: config?.enabled ?? false,
+            heartbeatInterval: config?.heartbeatInterval ?? 30000,
+            awayThreshold: config?.awayThreshold ?? 2,
+            disconnectThreshold: config?.disconnectThreshold ?? 3,
+            gracePeriod: config?.gracePeriod ?? 30000,
+            trackDeviceActivity: config?.trackDeviceActivity ?? true,
+            broadcastPresenceUpdates: config?.broadcastPresenceUpdates ?? true
+        };
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Check if presence tracking is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Calculate presence status based on device states
+     *
+     * Helper method for implementations to determine overall user status.
+     *
+     * @param devices - Map of devices for a user
+     * @param now - Current timestamp
+     * @returns Calculated presence status
+     */
+    calculatePresenceStatus(devices, now = Date.now()) {
+        if (devices.size === 0) {
+            return 'offline';
+        }
+        const heartbeatTimeout = this.config.heartbeatInterval * this.config.awayThreshold;
+        // Check if ANY device is active (within heartbeat threshold)
+        for (const device of devices.values()) {
+            const timeSinceActivity = now - device.lastActivity;
+            if (timeSinceActivity < heartbeatTimeout) {
+                return 'online';
+            }
+        }
+        // All devices are idle
+        return 'away';
+    }
+    /**
+     * Check if a device should be disconnected due to missed heartbeats
+     *
+     * @param device - Device info
+     * @param now - Current timestamp
+     * @returns true if device should be disconnected
+     */
+    shouldDisconnectDevice(device, now = Date.now()) {
+        const timeout = this.config.heartbeatInterval * this.config.disconnectThreshold;
+        return (now - device.lastActivity) > timeout;
+    }
+}
+exports.PresenceManager = PresenceManager;

package/dist/abstractions/index.d.ts

@@ -6,4 +6,6 @@ export { RoomManager } from './RoomManager.js';
 export { LockManager } from './LockManager.js';
 export { DefaultRoomManager } from './DefaultRoomManager.js';
 export { DefaultLockManager } from './DefaultLockManager.js';
+export { PresenceManager } from './PresenceManager.js';
+export { DefaultPresenceManager } from './DefaultPresenceManager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/abstractions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abstractions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abstractions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/abstractions/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultLockManager = exports.DefaultRoomManager = exports.LockManager = exports.RoomManager = exports.TypedEventEmitter = void 0;
+exports.DefaultPresenceManager = exports.PresenceManager = exports.DefaultLockManager = exports.DefaultRoomManager = exports.LockManager = exports.RoomManager = exports.TypedEventEmitter = void 0;
 var EventEmitter_js_1 = require("./EventEmitter.js");
 Object.defineProperty(exports, "TypedEventEmitter", { enumerable: true, get: function () { return EventEmitter_js_1.TypedEventEmitter; } });
 var RoomManager_js_1 = require("./RoomManager.js");
@@ -11,3 +11,7 @@ var DefaultRoomManager_js_1 = require("./DefaultRoomManager.js");
 Object.defineProperty(exports, "DefaultRoomManager", { enumerable: true, get: function () { return DefaultRoomManager_js_1.DefaultRoomManager; } });
 var DefaultLockManager_js_1 = require("./DefaultLockManager.js");
 Object.defineProperty(exports, "DefaultLockManager", { enumerable: true, get: function () { return DefaultLockManager_js_1.DefaultLockManager; } });
+var PresenceManager_js_1 = require("./PresenceManager.js");
+Object.defineProperty(exports, "PresenceManager", { enumerable: true, get: function () { return PresenceManager_js_1.PresenceManager; } });
+var DefaultPresenceManager_js_1 = require("./DefaultPresenceManager.js");
+Object.defineProperty(exports, "DefaultPresenceManager", { enumerable: true, get: function () { return DefaultPresenceManager_js_1.DefaultPresenceManager; } });