@principal-ai/control-tower-core 0.1.12 → 0.1.14

package/dist/abstractions/DefaultPresenceManager.d.ts

@@ -9,17 +9,40 @@
  */
 import { PresenceManager } from './PresenceManager.js';
 import type { UserPresence, DeviceInfo, PresenceStatus, PresenceConfig, PresenceChangeEvent, ActivityUpdate } from '../types/presence.js';
-export declare class DefaultPresenceManager extends PresenceManager {
+import type { PresenceExtension, ExtendedUserPresence } from './PresenceExtension.js';
+import type { BaseServer } from '../server/BaseServer.js';
+export declare class DefaultPresenceManager<TExtendedData = Record<string, unknown>> extends PresenceManager {
     private userPresences;
     private deviceToUser;
     private gracePeriodEntries;
-    constructor(config?: PresenceConfig);
+    private extensions;
+    private server?;
+    constructor(config?: PresenceConfig & {
+        extensions?: PresenceExtension<TExtendedData>[];
+    });
+    /**
+     * Set server reference for auto-broadcasting
+     *
+     * This is called automatically by ServerBuilder.
+     * @internal
+     */
+    setServer(server: BaseServer): void;
+    /**
+     * Initialize all extensions
+     * @internal
+     */
+    initializeExtensions(): Promise<void>;
+    /**
+     * Destroy all extensions
+     * @internal
+     */
+    destroyExtensions(): Promise<void>;
     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>;
+    getUserPresence(userId: string): Promise<ExtendedUserPresence<TExtendedData> | null>;
     getUsersPresence(userIds: string[]): Promise<Map<string, UserPresence>>;
-    getOnlineUsers(): Promise<UserPresence[]>;
+    getOnlineUsers(): Promise<ExtendedUserPresence<TExtendedData>[]>;
     getUserDevices(userId: string): Promise<DeviceInfo[]>;
     setUserStatus(userId: string, status: PresenceStatus): Promise<UserPresence>;
     processHeartbeats(): Promise<PresenceChangeEvent[]>;

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

@@ -1 +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"}
+{"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;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAW1D,qBAAa,sBAAsB,CAAC,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,eAAe;IAClG,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,kBAAkB,CAAuC;IACjE,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,MAAM,CAAC,CAAa;gBAEhB,MAAM,CAAC,EAAE,cAAc,GAAG;QACpC,UAAU,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,EAAE,CAAC;KACjD;IAKD;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAInC;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3C;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC,YAAY,CAAC;IAmHlB,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAuEzB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAiC7D,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IAyBpF,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAavE,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC,aAAa,CAAC,EAAE,CAAC;IA4BhE,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;IAS5B;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;OAEG;IACH,uBAAuB,IAAI,MAAM;IAIjC;;OAEG;IACH,kBAAkB,IAAI,MAAM;CAG7B"}

package/dist/abstractions/DefaultPresenceManager.js

@@ -17,9 +17,39 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         this.userPresences = new Map();
         this.deviceToUser = new Map();
         this.gracePeriodEntries = new Map();
+        this.extensions = [];
+        this.extensions = config?.extensions || [];
+    }
+    /**
+     * Set server reference for auto-broadcasting
+     *
+     * This is called automatically by ServerBuilder.
+     * @internal
+     */
+    setServer(server) {
+        this.server = server;
+    }
+    /**
+     * Initialize all extensions
+     * @internal
+     */
+    async initializeExtensions() {
+        for (const ext of this.extensions) {
+            await ext.initialize?.();
+        }
+    }
+    /**
+     * Destroy all extensions
+     * @internal
+     */
+    async destroyExtensions() {
+        for (const ext of this.extensions) {
+            await ext.destroy?.();
+        }
     }
     async connectDevice(userId, deviceId, deviceInfo) {
         const now = Date.now();
+        const isFirstDevice = !this.userPresences.has(userId) && !this.gracePeriodEntries.has(userId);
         // Check if user is in grace period (reconnecting)
         const gracePeriodEntry = this.gracePeriodEntries.get(userId);
         if (gracePeriodEntry) {
@@ -39,10 +69,35 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
             presence.lastActivity = now;
             this.userPresences.set(userId, presence);
             this.deviceToUser.set(deviceId, userId);
+            // Call extension hooks
+            if (isFirstDevice) {
+                for (const ext of this.extensions) {
+                    await ext.onUserOnline?.(userId, deviceId, deviceInfo?.metadata || {});
+                }
+            }
+            else {
+                for (const ext of this.extensions) {
+                    await ext.onDeviceConnected?.(userId, deviceId, deviceInfo?.metadata || {});
+                }
+            }
+            // Auto-broadcast
+            if (this.config.broadcastPresenceUpdates && this.server) {
+                const experimental = this.server.experimental;
+                await experimental?.broadcastAuthenticated({
+                    type: 'presence:user_online',
+                    payload: {
+                        userId,
+                        deviceId,
+                        status: 'online',
+                        timestamp: now
+                    }
+                });
+            }
             return presence;
         }
         // Get or create user presence
         let presence = this.userPresences.get(userId);
+        const wasOnline = presence !== undefined;
         if (!presence) {
             // New user
             presence = {
@@ -67,6 +122,30 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         presence.status = this.calculatePresenceStatus(presence.devices, now);
         presence.lastActivity = now;
         this.deviceToUser.set(deviceId, userId);
+        // Call extension hooks
+        if (!wasOnline) {
+            for (const ext of this.extensions) {
+                await ext.onUserOnline?.(userId, deviceId, deviceInfo?.metadata || {});
+            }
+        }
+        else {
+            for (const ext of this.extensions) {
+                await ext.onDeviceConnected?.(userId, deviceId, deviceInfo?.metadata || {});
+            }
+        }
+        // Auto-broadcast if user came online
+        if (!wasOnline && this.config.broadcastPresenceUpdates && this.server) {
+            const experimental = this.server.experimental;
+            await experimental?.broadcastAuthenticated({
+                type: 'presence:user_online',
+                payload: {
+                    userId,
+                    deviceId,
+                    status: 'online',
+                    timestamp: now
+                }
+            });
+        }
         return presence;
     }
     async disconnectDevice(userId, deviceId) {
@@ -78,8 +157,27 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         presence.devices.delete(deviceId);
         this.deviceToUser.delete(deviceId);
         const now = Date.now();
+        const isLastDevice = presence.devices.size === 0;
         // If no devices left, start grace period
-        if (presence.devices.size === 0) {
+        if (isLastDevice) {
+            // Call extension hooks for user going offline
+            for (const ext of this.extensions) {
+                await ext.onUserOffline?.(userId, deviceId);
+            }
+            // Auto-broadcast user offline
+            if (this.config.broadcastPresenceUpdates && this.server) {
+                const experimental = this.server.experimental;
+                await experimental?.broadcastAuthenticated({
+                    type: 'presence:user_offline',
+                    payload: {
+                        userId,
+                        deviceId,
+                        status: 'offline',
+                        timestamp: now,
+                        gracePeriod: this.config.gracePeriod
+                    }
+                });
+            }
             if (this.config.gracePeriod > 0) {
                 // Move to grace period
                 this.gracePeriodEntries.set(userId, {
@@ -96,6 +194,10 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
                 return null;
             }
         }
+        // Still has devices - call device disconnected hook
+        for (const ext of this.extensions) {
+            await ext.onDeviceDisconnected?.(userId, deviceId);
+        }
         // Still has devices, update status
         presence.status = this.calculatePresenceStatus(presence.devices, now);
         // Update lastActivity to most recent device activity
@@ -109,7 +211,7 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         return presence;
     }
     async updateActivity(update) {
-        const { userId, deviceId, timestamp } = update;
+        const { userId, deviceId, timestamp, activityType } = update;
         const presence = this.userPresences.get(userId);
         if (!presence) {
             throw new Error(`User ${userId} not found in presence system`);
@@ -127,10 +229,32 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         // Recalculate status
         const previousStatus = presence.status;
         presence.status = this.calculatePresenceStatus(presence.devices, timestamp);
+        // Call extension hooks
+        for (const ext of this.extensions) {
+            await ext.onActivity?.(userId, deviceId, activityType || 'heartbeat');
+        }
         return presence;
     }
     async getUserPresence(userId) {
-        return this.userPresences.get(userId) || null;
+        const basePresence = this.userPresences.get(userId);
+        if (!basePresence) {
+            return null;
+        }
+        // Merge extended data from all extensions
+        if (this.extensions.length > 0) {
+            const extendedData = {};
+            for (const ext of this.extensions) {
+                const data = await ext.getExtendedData?.(userId);
+                if (data) {
+                    Object.assign(extendedData, data);
+                }
+            }
+            return {
+                ...basePresence,
+                extended: extendedData
+            };
+        }
+        return basePresence;
     }
     async getUsersPresence(userIds) {
         const result = new Map();
@@ -146,7 +270,22 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         const online = [];
         for (const presence of this.userPresences.values()) {
             if (presence.status === 'online') {
-                online.push(presence);
+                // Check visibility with extensions
+                let visible = true;
+                for (const ext of this.extensions) {
+                    const shouldShow = await ext.shouldBeVisible?.(presence.userId);
+                    if (shouldShow === false) {
+                        visible = false;
+                        break;
+                    }
+                }
+                if (visible) {
+                    // Get full presence with extended data
+                    const fullPresence = await this.getUserPresence(presence.userId);
+                    if (fullPresence) {
+                        online.push(fullPresence);
+                    }
+                }
             }
         }
         return online;
@@ -230,6 +369,8 @@ class DefaultPresenceManager extends PresenceManager_js_1.PresenceManager {
         return changes;
     }
     async clear() {
+        // Destroy extensions first
+        await this.destroyExtensions();
         this.userPresences.clear();
         this.deviceToUser.clear();
         this.gracePeriodEntries.clear();

package/dist/abstractions/PresenceExtension.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Presence Extension Interface
+ *
+ * Allows applications to extend presence tracking with custom data and behavior
+ * without needing to create a separate presence manager.
+ *
+ * Extensions are called at key lifecycle points and can:
+ * - Add custom data to user presence
+ * - Control visibility of users
+ * - React to room joins/leaves
+ * - Track application-specific presence state
+ */
+import type { UserPresence } from '../types/presence.js';
+/**
+ * Extension for adding custom presence data and behavior
+ *
+ * @template TExtendedData - Type of extended presence data
+ */
+export interface PresenceExtension<TExtendedData = Record<string, unknown>> {
+    /**
+     * Called when a user comes online (first device connects)
+     *
+     * @param userId - User identifier
+     * @param deviceId - Device/client identifier
+     * @param metadata - Connection metadata
+     */
+    onUserOnline?(userId: string, deviceId: string, metadata: Record<string, unknown>): Promise<void> | void;
+    /**
+     * Called when a user goes offline (last device disconnects)
+     *
+     * Note: This is called when the user enters grace period or fully disconnects.
+     *
+     * @param userId - User identifier
+     * @param deviceId - Last device that disconnected
+     */
+    onUserOffline?(userId: string, deviceId: string): Promise<void> | void;
+    /**
+     * Called when a device connects for an already-online user
+     *
+     * @param userId - User identifier
+     * @param deviceId - New device identifier
+     * @param metadata - Connection metadata
+     */
+    onDeviceConnected?(userId: string, deviceId: string, metadata: Record<string, unknown>): Promise<void> | void;
+    /**
+     * Called when a device disconnects but user remains online
+     *
+     * @param userId - User identifier
+     * @param deviceId - Device that disconnected
+     */
+    onDeviceDisconnected?(userId: string, deviceId: string): Promise<void> | void;
+    /**
+     * Called when a client joins a room
+     *
+     * This is useful for tracking room-specific presence data.
+     *
+     * @param userId - User identifier
+     * @param roomId - Room identifier
+     * @param deviceId - Device/client identifier
+     */
+    onRoomJoined?(userId: string, roomId: string, deviceId: string): Promise<void> | void;
+    /**
+     * Called when a client leaves a room
+     *
+     * @param userId - User identifier
+     * @param roomId - Room identifier
+     * @param deviceId - Device/client identifier
+     */
+    onRoomLeft?(userId: string, roomId: string, deviceId: string): Promise<void> | void;
+    /**
+     * Get extended presence data for a user
+     *
+     * This data will be merged into the UserPresence object.
+     *
+     * @param userId - User identifier
+     * @returns Extended presence data, or null if none
+     */
+    getExtendedData?(userId: string): Promise<TExtendedData | null> | TExtendedData | null;
+    /**
+     * Determine if a user should be visible to others
+     *
+     * This allows filtering users from presence lists.
+     * If multiple extensions return false, the user is hidden.
+     *
+     * @param userId - User identifier
+     * @returns true if user should be visible, false to hide
+     */
+    shouldBeVisible?(userId: string): Promise<boolean> | boolean;
+    /**
+     * Called when user activity is detected
+     *
+     * @param userId - User identifier
+     * @param deviceId - Device/client identifier
+     * @param activityType - Type of activity
+     */
+    onActivity?(userId: string, deviceId: string, activityType: 'heartbeat' | 'message' | 'user_action'): Promise<void> | void;
+    /**
+     * Lifecycle: Called when extension is initialized
+     *
+     * Use this for setup tasks like loading initial state.
+     */
+    initialize?(): Promise<void> | void;
+    /**
+     * Lifecycle: Called when extension is destroyed
+     *
+     * Use this for cleanup tasks like persisting state.
+     */
+    destroy?(): Promise<void> | void;
+}
+/**
+ * Extended user presence with custom data
+ *
+ * @template TExtendedData - Type of extended presence data
+ */
+export interface ExtendedUserPresence<TExtendedData = Record<string, unknown>> extends UserPresence {
+    /**
+     * Extended data from presence extensions
+     */
+    extended?: TExtendedData;
+}
+//# sourceMappingURL=PresenceExtension.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PresenceExtension.d.ts","sourceRoot":"","sources":["../../src/abstractions/PresenceExtension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE;;;;;;OAMG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;;;OAOG;IACH,aAAa,CAAC,CACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;;OAMG;IACH,iBAAiB,CAAC,CAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;OAKG;IACH,oBAAoB,CAAC,CACnB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;;;;OAQG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;;OAMG;IACH,UAAU,CAAC,CACT,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;;;;OAOG;IACH,eAAe,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,aAAa,GAAG,IAAI,CAAC;IAEvF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAE7D;;;;;;OAMG;IACH,UAAU,CAAC,CACT,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GACpD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3E,SAAQ,YAAY;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B"}

package/dist/abstractions/PresenceExtension.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Presence Extension Interface
+ *
+ * Allows applications to extend presence tracking with custom data and behavior
+ * without needing to create a separate presence manager.
+ *
+ * Extensions are called at key lifecycle points and can:
+ * - Add custom data to user presence
+ * - Control visibility of users
+ * - React to room joins/leaves
+ * - Track application-specific presence state
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/abstractions/index.d.ts

@@ -8,4 +8,5 @@ export { DefaultRoomManager } from './DefaultRoomManager.js';
 export { DefaultLockManager } from './DefaultLockManager.js';
 export { PresenceManager } from './PresenceManager.js';
 export { DefaultPresenceManager } from './DefaultPresenceManager.js';
+export { type PresenceExtension, type ExtendedUserPresence } from './PresenceExtension.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;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,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;AACrE,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,wBAAwB,CAAC"}

package/dist/adapters/websocket/WebSocketServerTransportAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSocketServerTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/websocket/WebSocketServerTransportAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,YAAY,EACZ,YAAY,EAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEhD,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,8BAA8B;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,+BAAgC,YAAW,iBAAiB;IACvE,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAgC;IAGrD,OAAO,CAAC,GAAG,CAAC,CAAkB;IAC9B,OAAO,CAAC,SAAS,CAAC,CAAS;IAG3B,OAAO,CAAC,cAAc,CAAC,CAA2B;IAClD,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAS;IAG/B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,IAAI,CAA8C;IAG1D,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,MAAM,CAAiC;gBAEnC,MAAM,CAAC,EAAE,8BAA8B;IAUnD,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAclC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,IAAI,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC7E,uBAAuB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YA2BpD,gBAAgB;YA6EhB,mBAAmB;YAuCnB,iBAAiB;IA4E/B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,YAAY;IAMd,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC3B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B3C,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIxC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIpC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIpC,QAAQ,IAAI,eAAe;IAI3B,WAAW,IAAI,OAAO;IAKtB,mBAAmB,IAAI,gBAAgB,EAAE;IAIzC,uBAAuB,IAAI,gBAAgB,EAAE;IAI7C,cAAc,IAAI,MAAM;IAIxB,OAAO,IAAI,YAAY,GAAG,aAAa;IAIvC,cAAc,IAAI,OAAO;IAIzB,OAAO,CAAC,UAAU;CAGnB"}
+{"version":3,"file":"WebSocketServerTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/websocket/WebSocketServerTransportAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,YAAY,EACZ,YAAY,EAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEhD,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,8BAA8B;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,+BAAgC,YAAW,iBAAiB;IACvE,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAgC;IAGrD,OAAO,CAAC,GAAG,CAAC,CAAkB;IAC9B,OAAO,CAAC,SAAS,CAAC,CAAS;IAG3B,OAAO,CAAC,cAAc,CAAC,CAA2B;IAClD,OAAO,CAAC,WAAW,CAAC,CAAkB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAS;IAG/B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,IAAI,CAA8C;IAG1D,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,MAAM,CAAiC;gBAEnC,MAAM,CAAC,EAAE,8BAA8B;IAUnD,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAclC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,IAAI,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC7E,uBAAuB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YA2BpD,gBAAgB;YA6EhB,mBAAmB;YAuCnB,iBAAiB;IA4E/B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,YAAY;IAMd,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC3B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA4C3C,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIxC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIpC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIpC,QAAQ,IAAI,eAAe;IAI3B,WAAW,IAAI,OAAO;IAKtB,mBAAmB,IAAI,gBAAgB,EAAE;IAIzC,uBAAuB,IAAI,gBAAgB,EAAE;IAI7C,cAAc,IAAI,MAAM;IAIxB,OAAO,IAAI,YAAY,GAAG,aAAa;IAIvC,cAAc,IAAI,OAAO;IAIzB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/adapters/websocket/WebSocketServerTransportAdapter.js

@@ -342,10 +342,24 @@ class WebSocketServerTransportAdapter {
         if (client.ws.readyState !== ws_1.WebSocket.OPEN) {
             throw new Error(`Client ${clientId} connection is not open`);
         }
-        const messageToSend = {
-            ...message,
-            payload: clientMessage
-        };
+        // Fully unwrap the server_message envelope
+        // The server_message wrapper is used internally for routing between BaseServer and transport
+        // We need to extract the actual message from inside the wrapper before sending to the client
+        const messageToSend = message.type === 'server_message' && clientMessage.type
+            ? {
+                id: message.id,
+                type: clientMessage.type,
+                payload: clientMessage.payload || (() => {
+                    // If there's no explicit payload field, use all remaining fields except 'type'
+                    const { type, ...rest } = clientMessage;
+                    return rest;
+                })(),
+                timestamp: message.timestamp
+            }
+            : {
+                ...message,
+                payload: clientMessage
+            };
         client.ws.send(JSON.stringify(messageToSend));
     }
     onMessage(handler) {

package/dist/client/PresenceClient.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Presence Client Helper
+ *
+ * Simplifies client-side presence integration for web/Electron applications.
+ * Automatically handles connection, authentication, and presence event forwarding.
+ */
+import { BaseClient, type ClientConfig } from './BaseClient.js';
+import { TypedEventEmitter } from '../abstractions/EventEmitter.js';
+import type { UserPresence } from '../types/presence.js';
+export interface PresenceClientConfig {
+    /**
+     * Base client configuration
+     * Provide the full client config including transport and auth adapters
+     */
+    clientConfig: ClientConfig;
+    /**
+     * WebSocket URL to connect to
+     */
+    wsUrl: string;
+    /**
+     * Automatically connect on construction
+     * @default false
+     */
+    autoConnect?: boolean;
+    /**
+     * Automatically reconnect on disconnect
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Global presence room ID
+     * @default '__global_presence__'
+     */
+    globalRoomId?: string;
+}
+export interface PresenceClientEvents {
+    /**
+     * User came online
+     */
+    userOnline: {
+        userId: string;
+        devices: unknown[];
+    };
+    /**
+     * User went offline
+     */
+    userOffline: {
+        userId: string;
+    };
+    /**
+     * User's presence status changed
+     */
+    statusChanged: {
+        userId: string;
+        status: string;
+        statusMessage?: string;
+    };
+    /**
+     * Connected to presence system
+     */
+    connected: {};
+    /**
+     * Disconnected from presence system
+     */
+    disconnected: {};
+    /**
+     * Error occurred
+     */
+    error: {
+        error: Error;
+    };
+    [key: string]: unknown;
+}
+/**
+ * High-level presence client for easy integration
+ *
+ * Example:
+ * ```typescript
+ * import { PresenceClient } from '@principal-ai/control-tower-core';
+ * import { WebSocketClientTransportAdapter } from '@principal-ai/control-tower-core';
+ * import { ClientBuilder } from '@principal-ai/control-tower-core';
+ *
+ * const transport = new WebSocketClientTransportAdapter();
+ *
+ * const client = new ClientBuilder()
+ *   .withTransport(transport)
+ *   .build();
+ *
+ * const presence = new PresenceClient({
+ *   clientConfig: client,
+ *   wsUrl: 'ws://localhost:3000/ws',
+ *   autoConnect: true,
+ *   autoReconnect: true
+ * });
+ *
+ * presence.on('userOnline', (data) => {
+ *   console.log(`${data.userId} came online`);
+ * });
+ *
+ * presence.on('userOffline', (data) => {
+ *   console.log(`${data.userId} went offline`);
+ * });
+ * ```
+ */
+export declare class PresenceClient extends TypedEventEmitter<PresenceClientEvents> {
+    private client;
+    private wsUrl;
+    private autoReconnectEnabled;
+    private globalRoomId;
+    private reconnectTimeout?;
+    constructor(config: PresenceClientConfig);
+    /**
+     * Connect to the presence system
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the presence system
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get all online users
+     *
+     * Note: This requires a corresponding API endpoint on your server.
+     */
+    getOnlineUsers(): Promise<UserPresence[]>;
+    /**
+     * Set user status
+     *
+     * Note: This requires a corresponding API endpoint on your server.
+     */
+    setStatus(status: 'online' | 'away', message?: string): Promise<void>;
+    /**
+     * Set visibility
+     *
+     * Note: This requires a corresponding API endpoint on your server.
+     */
+    setVisibility(visible: boolean): Promise<void>;
+    /**
+     * Get the underlying BaseClient
+     */
+    getClient(): BaseClient;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Set up event forwarding from BaseClient
+     * @private
+     */
+    private setupEventForwarding;
+}
+//# sourceMappingURL=PresenceClient.d.ts.map

package/dist/client/PresenceClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresenceClient.d.ts","sourceRoot":"","sources":["../../src/client/PresenceClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAEnD;;OAEG;IACH,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAEhC;;OAEG;IACH,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE1E;;OAEG;IACH,SAAS,EAAE,EAAE,CAAC;IAEd;;OAEG;IACH,YAAY,EAAE,EAAE,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;IAExB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAe,SAAQ,iBAAiB,CAAC,oBAAoB,CAAC;IACzE,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,oBAAoB,CAAU;IACtC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAC,CAAiB;gBAE9B,MAAM,EAAE,oBAAoB;IAiBxC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBjC;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAS/C;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS3E;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;OAEG;IACH,SAAS,IAAI,UAAU;IAIvB;;OAEG;IACH,WAAW,IAAI,OAAO;IAMtB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAoD7B"}