@principal-ai/control-tower-core 0.2.0 → 0.2.2

package/dist/server/BaseServer.d.ts

@@ -26,6 +26,12 @@ export interface ServerConfig {
 export interface ConnectedClient {
     id: string;
     userId: string;
+    /**
+     * Device ID for presence tracking.
+     * By default equals clientId, but can be overridden via setClientDeviceId()
+     * to support multi-window scenarios where multiple clients share a device.
+     */
+    deviceId: string;
     /**
      * Set of room IDs the client is currently in
      *
@@ -204,14 +210,36 @@ export declare class BaseServer extends TypedEventEmitter<ServerEvents> {
      * @returns Array of client IDs
      */
     getClientIdsForUser(userId: string): string[];
+    /**
+     * Get all client IDs for a user in a specific room
+     *
+     * @param roomId - Room identifier
+     * @param userId - User identifier
+     * @returns Array of client IDs
+     */
+    getClientIdsInRoom(roomId: string, userId: string): string[];
     /**
      * Get device ID from client ID
      *
-     * In Control Tower architecture, clientId === deviceId
+     * By default, deviceId === clientId. Use setClientDeviceId() to override
+     * for multi-window scenarios where multiple clients share a device.
      *
      * @param clientId - Client identifier
-     * @returns Device ID (same as clientId)
+     * @returns Device ID for this client
      */
     getDeviceIdFromClientId(clientId: string): string;
+    /**
+     * Set the device ID for a client
+     *
+     * Use this to associate a custom deviceId with a client, e.g., when
+     * the deviceId comes from a JWT token and differs from the WebSocket clientId.
+     * This is useful for multi-window scenarios where multiple WebSocket clients
+     * share the same device/user session.
+     *
+     * @param clientId - Client identifier
+     * @param deviceId - Device identifier to associate with this client
+     * @returns true if the client was found and updated, false otherwise
+     */
+    setClientDeviceId(clientId: string, deviceId: string): boolean;
 }
 //# sourceMappingURL=BaseServer.d.ts.map

package/dist/server/BaseServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseServer.d.ts","sourceRoot":"","sources":["../../src/server/BaseServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseServer.d.ts","sourceRoot":"","sources":["../../src/server/BaseServer.ts"],"names":[],"mappings":"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"}

package/dist/server/BaseServer.js

@@ -254,6 +254,7 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
         const client = {
             id: payload.clientId,
             userId: payload.userId || "",
+            deviceId: payload.clientId, // Default to clientId, can be overridden via setClientDeviceId()
             roomIds,
             get roomId() {
                 return roomIds.size > 0 ? roomIds.values().next().value || null : null;
@@ -340,6 +341,7 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
         const client = {
             id: clientId,
             userId: "",
+            deviceId: clientId, // Default to clientId, can be overridden via setClientDeviceId()
             roomIds,
             get roomId() {
                 return roomIds.size > 0 ? roomIds.values().next().value || null : null;
@@ -371,10 +373,10 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
         // Unregister from presence manager
         if (this.presenceManager?.isEnabled() && client.userId) {
             try {
-                const presence = await this.presenceManager.disconnectDevice(client.userId, clientId);
+                const presence = await this.presenceManager.disconnectDevice(client.userId, client.deviceId);
                 await this.emit("presence_device_disconnected", {
                     userId: client.userId,
-                    deviceId: clientId,
+                    deviceId: client.deviceId,
                     timestamp: Date.now(),
                 });
                 // Broadcast presence update if user went offline or into grace period
@@ -385,7 +387,7 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
                         type: "presence:user_offline",
                         payload: {
                             userId: client.userId,
-                            deviceId: clientId,
+                            deviceId: client.deviceId,
                             status: presence?.status || "offline",
                             gracePeriod: presenceConfig.gracePeriod,
                         },
@@ -399,8 +401,23 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
                 });
             }
         }
-        // Leave all rooms the client is in
+        // Leave all rooms the client is in and broadcast to other room members
         for (const roomId of client.roomIds) {
+            // Broadcast member_left to other room members
+            try {
+                await this.experimental.broadcastWhere((c) => c.roomIds.has(roomId) && c.id !== clientId, {
+                    type: "member_left",
+                    payload: {
+                        roomId,
+                        userId: client.userId,
+                        clientId,
+                        timestamp: Date.now(),
+                    },
+                });
+            }
+            catch {
+                // Experimental broadcast not enabled, skip silently
+            }
             await this.roomManager.leaveRoom(roomId, client.userId);
             await this.emit("client_left_room", { clientId, roomId });
         }
@@ -422,7 +439,7 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
                 if (this.presenceManager?.isEnabled() &&
                     client.userId &&
                     client.authenticated) {
-                    await this.updatePresenceActivity(client.userId, clientId, "message");
+                    await this.updatePresenceActivity(client.userId, client.deviceId, "message");
                 }
                 switch (message.type) {
                     case "authenticate":
@@ -619,6 +636,22 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
             if (!client.roomIds.has(roomId)) {
                 continue;
             }
+            // Broadcast to other room members BEFORE removing this client
+            // Use experimental broadcast if enabled, otherwise silently skip
+            try {
+                await this.experimental.broadcastWhere((c) => c.roomIds.has(roomId) && c.id !== clientId, {
+                    type: "member_left",
+                    payload: {
+                        roomId,
+                        userId: client.userId,
+                        clientId,
+                        timestamp: Date.now(),
+                    },
+                });
+            }
+            catch {
+                // Experimental broadcast not enabled, skip silently
+            }
             await this.roomManager.leaveRoom(roomId, client.userId);
             client.roomIds.delete(roomId);
             await this.emit("client_left_room", { clientId, roomId });
@@ -818,16 +851,52 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
     getClientIdsForUser(userId) {
         return Array.from(this.userClientMap.get(userId) || []);
     }
+    /**
+     * Get all client IDs for a user in a specific room
+     *
+     * @param roomId - Room identifier
+     * @param userId - User identifier
+     * @returns Array of client IDs
+     */
+    getClientIdsInRoom(roomId, userId) {
+        const allClientIds = this.getClientIdsForUser(userId);
+        return allClientIds.filter(clientId => {
+            const client = this.clients.get(clientId);
+            return client && client.roomIds.has(roomId);
+        });
+    }
     /**
      * Get device ID from client ID
      *
-     * In Control Tower architecture, clientId === deviceId
+     * By default, deviceId === clientId. Use setClientDeviceId() to override
+     * for multi-window scenarios where multiple clients share a device.
      *
      * @param clientId - Client identifier
-     * @returns Device ID (same as clientId)
+     * @returns Device ID for this client
      */
     getDeviceIdFromClientId(clientId) {
-        return clientId;
+        const client = this.clients.get(clientId);
+        return client?.deviceId ?? clientId;
+    }
+    /**
+     * Set the device ID for a client
+     *
+     * Use this to associate a custom deviceId with a client, e.g., when
+     * the deviceId comes from a JWT token and differs from the WebSocket clientId.
+     * This is useful for multi-window scenarios where multiple WebSocket clients
+     * share the same device/user session.
+     *
+     * @param clientId - Client identifier
+     * @param deviceId - Device identifier to associate with this client
+     * @returns true if the client was found and updated, false otherwise
+     */
+    setClientDeviceId(clientId, deviceId) {
+        const client = this.clients.get(clientId);
+        if (client) {
+            client.deviceId = deviceId;
+            return true;
+        }
+        return false;
     }
 }
 exports.BaseServer = BaseServer;

package/dist/server/ServerBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerBuilder.d.ts","sourceRoot":"","sources":["../../src/server/ServerBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAEhE,qBAAa,aAAa;IACzB,OAAO,CAAC,SAAS,CAAC,CAAoB;IACtC,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAA2B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,oBAAoB,CAAC,CAA4B;IAEzD,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAKjD,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAKlC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK3C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C;;;;;;;OAOG;IACH,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI;IAK3D,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAKxD,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAKtD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKrC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAK/C;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAKnE,KAAK,IAAI,UAAU;IAkDnB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;CAyClC"}
+{"version":3,"file":"ServerBuilder.d.ts","sourceRoot":"","sources":["../../src/server/ServerBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAEhE,qBAAa,aAAa;IACzB,OAAO,CAAC,SAAS,CAAC,CAAoB;IACtC,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAA2B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,oBAAoB,CAAC,CAA4B;IAEzD,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAKjD,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAKlC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK3C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C;;;;;;;OAOG;IACH,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI;IAK3D,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAKxD,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAKtD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKrC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAK/C;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAKnE,KAAK,IAAI,UAAU;IAoEnB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;CAyClC"}

package/dist/server/ServerBuilder.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServerBuilder = void 0;
+const ConnectedRoomManager_js_1 = require("../abstractions/ConnectedRoomManager.js");
 const DefaultPresenceManager_js_1 = require("../abstractions/DefaultPresenceManager.js");
 const BaseServer_js_1 = require("./BaseServer.js");
 class ServerBuilder {
@@ -96,6 +97,16 @@ class ServerBuilder {
             },
         };
         const server = new BaseServer_js_1.BaseServer(config);
+        // Auto-enhance DefaultRoomManager with broadcasting capabilities
+        // This happens after server construction so we have access to server methods
+        if (this.roomManager.constructor.name === 'DefaultRoomManager') {
+            // Create enhanced room manager with server callbacks
+            const connectedManager = new ConnectedRoomManager_js_1.ConnectedRoomManager((clientId, message) => server.sendToClient(clientId, message), (roomId, userId) => server.getClientIdsInRoom(roomId, userId));
+            // Copy existing room state
+            connectedManager.rooms = this.roomManager.rooms;
+            // Replace the room manager in the server
+            server.roomManager = connectedManager;
+        }
         // Auto-link presence manager to server for broadcasting
         if (this.presenceManager instanceof DefaultPresenceManager_js_1.DefaultPresenceManager) {
             this.presenceManager.setServer(server);

package/dist/telemetry/EventValidationIntegration.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Event Validation Integration for Control Tower
+ *
+ * This demonstrates how to integrate event schema validation
+ * into the Control Tower server for type-safe telemetry.
+ *
+ * Usage:
+ * 1. Install: npm install @principal-ai/principal-view-core
+ * 2. Import canvas and types
+ * 3. Create validated event emitters
+ * 4. Use in server event handlers
+ */
+import type { ExtendedCanvas } from '@principal-ai/principal-view-core';
+import type { WebsocketAdapter, Server, MessageHandler, AuthAdapter, ClientLifecycle, ClientResponse, NodeEmitterByName } from '@generated/client-connection-auth.types';
+/**
+ * Control Tower Telemetry Service
+ *
+ * Provides type-safe, validated event emission for all Control Tower operations.
+ */
+export declare class ControlTowerTelemetry {
+    private validator;
+    private canvas;
+    websocketAdapter: NodeEmitterByName<WebsocketAdapter.Event>;
+    server: NodeEmitterByName<Server.Event>;
+    messageHandler: NodeEmitterByName<MessageHandler.Event>;
+    authAdapter: NodeEmitterByName<AuthAdapter.Event>;
+    clientLifecycle: NodeEmitterByName<ClientLifecycle.Event>;
+    clientResponse: NodeEmitterByName<ClientResponse.Event>;
+    constructor(canvas: ExtendedCanvas, options?: {
+        /** Strict mode throws on validation errors (for tests) */
+        strict?: boolean;
+        /** Custom event handler */
+        onEvent?: (nodeId: string, eventName: string, attributes: Record<string, any>) => void;
+    });
+    /**
+     * Get available event names for a component
+     */
+    getEventNames(component: 'websocket-adapter' | 'server' | 'message-handler' | 'auth-adapter' | 'client-lifecycle' | 'client-response'): string[];
+    /**
+     * Validate an event manually (for testing)
+     */
+    validate(component: string, eventName: string, attributes: Record<string, any>): any;
+}
+/**
+ * Example: Integrating with BaseServer
+ *
+ * This shows how you would integrate telemetry into the BaseServer class.
+ */
+export declare class TelemetryIntegrationExample {
+    private telemetry;
+    constructor(canvas: ExtendedCanvas);
+    /**
+     * Example: Handle WebSocket connection received
+     */
+    handleConnectionReceived(connectionId: string, origin?: string): void;
+    /**
+     * Example: Handle WebSocket connection established
+     */
+    handleConnectionEstablished(connectionId: string, transportType: string): void;
+    /**
+     * Example: Handle client connected to server
+     */
+    handleClientConnected(clientId: string, transportType: string): void;
+    /**
+     * Example: Handle client awaiting authentication
+     */
+    handleClientAwaitingAuth(clientId: string, timeoutMs?: number): void;
+    /**
+     * Example: Handle message received
+     */
+    handleMessageReceived(clientId: string, messageType: string, messageSize?: number): void;
+    /**
+     * Example: Handle message validated
+     */
+    handleMessageValidated(clientId: string, messageType: string): void;
+    /**
+     * Example: Handle message validation failure
+     */
+    handleMessageValidationFailed(clientId: string, messageType: string, errorMessage: string, errorField?: string): void;
+    /**
+     * Example: Handle auth validation started
+     */
+    handleAuthValidationStarted(clientId: string, authMethod?: string): void;
+    /**
+     * Example: Handle auth validation success
+     */
+    handleAuthValidationSuccess(clientId: string, userId: string, authMethod?: string, duration?: number): void;
+    /**
+     * Example: Handle auth validation failure
+     */
+    handleAuthValidationFailed(clientId: string, errorCode: string, errorMessage: string): void;
+    /**
+     * Example: Handle client state changed
+     */
+    handleClientStateChanged(clientId: string, fromState: string, toState: string, duration?: number): void;
+    /**
+     * Example: Handle client authenticated
+     */
+    handleClientAuthenticated(clientId: string, userId: string, totalDuration?: number): void;
+    /**
+     * Example: Handle client disconnected
+     */
+    handleClientDisconnected(clientId: string, reason: string, sessionDuration: number, wasAuthenticated: boolean): void;
+    /**
+     * Example: Handle response sent to client
+     */
+    handleResponseSent(clientId: string, responseType: string, size?: number): void;
+    /**
+     * Example: Handle response send failure
+     */
+    handleResponseSendFailed(clientId: string, errorMessage: string): void;
+}
+/**
+ * Load canvas from file
+ */
+export declare function loadControlTowerCanvas(): ExtendedCanvas;
+/**
+ * Create telemetry service instance
+ *
+ * @example
+ * ```typescript
+ * const telemetry = createTelemetryService();
+ *
+ * telemetry.clientLifecycle('client.connected', {
+ *   'client.id': 'abc123',
+ *   'transport.type': 'websocket',
+ *   'connection.time': Date.now(),
+ * });
+ * ```
+ */
+export declare function createTelemetryService(options?: {
+    strict?: boolean;
+    onEvent?: (nodeId: string, eventName: string, attributes: Record<string, any>) => void;
+}): ControlTowerTelemetry;
+//# sourceMappingURL=EventValidationIntegration.d.ts.map

package/dist/telemetry/EventValidationIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventValidationIntegration.d.ts","sourceRoot":"","sources":["../../src/telemetry/EventValidationIntegration.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/EventValidationIntegration.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Event Validation Integration for Control Tower
+ *
+ * This demonstrates how to integrate event schema validation
+ * into the Control Tower server for type-safe telemetry.
+ *
+ * Usage:
+ * 1. Install: npm install @principal-ai/principal-view-core
+ * 2. Import canvas and types
+ * 3. Create validated event emitters
+ * 4. Use in server event handlers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryIntegrationExample = exports.ControlTowerTelemetry = void 0;
+exports.loadControlTowerCanvas = loadControlTowerCanvas;
+exports.createTelemetryService = createTelemetryService;
+const principal_view_core_1 = require("@principal-ai/principal-view-core");
+/**
+ * Control Tower Telemetry Service
+ *
+ * Provides type-safe, validated event emission for all Control Tower operations.
+ */
+class ControlTowerTelemetry {
+    constructor(canvas, options = {}) {
+        this.canvas = canvas;
+        this.validator = new principal_view_core_1.EventValidator(canvas);
+        const defaultHandler = (nodeId, eventName, attributes) => {
+            // Default: log to console (replace with your telemetry backend)
+            console.log(`[${nodeId}] ${eventName}`, attributes);
+        };
+        const eventHandler = options.onEvent || defaultHandler;
+        // Create type-safe emitters for each component
+        this.websocketAdapter = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'websocket-adapter', (eventName, attributes) => eventHandler('websocket-adapter', eventName, attributes), { strict: options.strict ?? false });
+        this.server = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'server', (eventName, attributes) => eventHandler('server', eventName, attributes), { strict: options.strict ?? false });
+        this.messageHandler = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'message-handler', (eventName, attributes) => eventHandler('message-handler', eventName, attributes), { strict: options.strict ?? false });
+        this.authAdapter = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'auth-adapter', (eventName, attributes) => eventHandler('auth-adapter', eventName, attributes), { strict: options.strict ?? false });
+        this.clientLifecycle = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'client-lifecycle', (eventName, attributes) => eventHandler('client-lifecycle', eventName, attributes), { strict: options.strict ?? false });
+        this.clientResponse = (0, principal_view_core_1.createValidatedEmitter)(this.validator, 'client-response', (eventName, attributes) => eventHandler('client-response', eventName, attributes), { strict: options.strict ?? false });
+    }
+    /**
+     * Get available event names for a component
+     */
+    getEventNames(component) {
+        return this.validator.getNodeEventNames(component);
+    }
+    /**
+     * Validate an event manually (for testing)
+     */
+    validate(component, eventName, attributes) {
+        return this.validator.validate(component, eventName, attributes);
+    }
+}
+exports.ControlTowerTelemetry = ControlTowerTelemetry;
+/**
+ * Example: Integrating with BaseServer
+ *
+ * This shows how you would integrate telemetry into the BaseServer class.
+ */
+class TelemetryIntegrationExample {
+    constructor(canvas) {
+        // Create telemetry service
+        this.telemetry = new ControlTowerTelemetry(canvas, {
+            strict: false, // Permissive in production
+            onEvent: (nodeId, eventName, attributes) => {
+                // Send to your telemetry backend (OpenTelemetry, DataDog, etc.)
+                console.log(`[TELEMETRY] ${nodeId}.${eventName}`, attributes);
+            },
+        });
+    }
+    /**
+     * Example: Handle WebSocket connection received
+     */
+    handleConnectionReceived(connectionId, origin) {
+        this.telemetry.websocketAdapter('connection.received', {
+            'connection.id': connectionId,
+            'connection.origin': origin,
+        });
+    }
+    /**
+     * Example: Handle WebSocket connection established
+     */
+    handleConnectionEstablished(connectionId, transportType) {
+        this.telemetry.websocketAdapter('connection.established', {
+            'connection.id': connectionId,
+            'transport.type': transportType,
+        });
+    }
+    /**
+     * Example: Handle client connected to server
+     */
+    handleClientConnected(clientId, transportType) {
+        this.telemetry.server('client.connected', {
+            'client.id': clientId,
+            'transport.type': transportType,
+            'connection.timestamp': Date.now(),
+        });
+    }
+    /**
+     * Example: Handle client awaiting authentication
+     */
+    handleClientAwaitingAuth(clientId, timeoutMs) {
+        this.telemetry.server('client.awaiting_auth', {
+            'client.id': clientId,
+            'auth.timeout_ms': timeoutMs,
+        });
+    }
+    /**
+     * Example: Handle message received
+     */
+    handleMessageReceived(clientId, messageType, messageSize) {
+        this.telemetry.messageHandler('message.received', {
+            'client.id': clientId,
+            'message.type': messageType,
+            'message.size_bytes': messageSize,
+        });
+    }
+    /**
+     * Example: Handle message validated
+     */
+    handleMessageValidated(clientId, messageType) {
+        this.telemetry.messageHandler('message.validated', {
+            'client.id': clientId,
+            'message.type': messageType,
+        });
+    }
+    /**
+     * Example: Handle message validation failure
+     */
+    handleMessageValidationFailed(clientId, messageType, errorMessage, errorField) {
+        this.telemetry.messageHandler('message.validation_failed', {
+            'client.id': clientId,
+            'message.type': messageType,
+            'validation.error': errorMessage,
+            'validation.field': errorField,
+        });
+    }
+    /**
+     * Example: Handle auth validation started
+     */
+    handleAuthValidationStarted(clientId, authMethod) {
+        this.telemetry.authAdapter('auth.validation_started', {
+            'client.id': clientId,
+            'auth.method': authMethod,
+        });
+    }
+    /**
+     * Example: Handle auth validation success
+     */
+    handleAuthValidationSuccess(clientId, userId, authMethod, duration) {
+        this.telemetry.authAdapter('auth.validation_success', {
+            'client.id': clientId,
+            'user.id': userId,
+            'auth.method': authMethod,
+            'validation.duration_ms': duration,
+        });
+    }
+    /**
+     * Example: Handle auth validation failure
+     */
+    handleAuthValidationFailed(clientId, errorCode, errorMessage) {
+        this.telemetry.authAdapter('auth.validation_failed', {
+            'client.id': clientId,
+            'auth.error_code': errorCode,
+            'auth.error_message': errorMessage,
+        });
+    }
+    /**
+     * Example: Handle client state changed
+     */
+    handleClientStateChanged(clientId, fromState, toState, duration) {
+        this.telemetry.clientLifecycle('client.state_changed', {
+            'client.id': clientId,
+            'state.from': fromState,
+            'state.to': toState,
+            'state.duration_ms': duration,
+        });
+    }
+    /**
+     * Example: Handle client authenticated
+     */
+    handleClientAuthenticated(clientId, userId, totalDuration) {
+        // ✅ Type-safe: TypeScript knows exact attributes for this event
+        this.telemetry.clientLifecycle('client.authenticated', {
+            'client.id': clientId,
+            'user.id': userId,
+            'connection.total_duration_ms': totalDuration,
+        });
+        // ❌ TypeScript error: missing required field
+        // this.telemetry.clientLifecycle('client.authenticated', {
+        //   'client.id': clientId,
+        //   // Missing 'user.id' - TypeScript error!
+        // });
+    }
+    /**
+     * Example: Handle client disconnected
+     */
+    handleClientDisconnected(clientId, reason, sessionDuration, wasAuthenticated) {
+        this.telemetry.clientLifecycle('client.disconnected', {
+            'client.id': clientId,
+            'disconnect.reason': reason,
+            'session.total_duration_ms': sessionDuration,
+            'client.was_authenticated': wasAuthenticated,
+        });
+    }
+    /**
+     * Example: Handle response sent to client
+     */
+    handleResponseSent(clientId, responseType, size) {
+        this.telemetry.clientResponse('response.sent', {
+            'client.id': clientId,
+            'response.type': responseType,
+            'response.size_bytes': size,
+        });
+    }
+    /**
+     * Example: Handle response send failure
+     */
+    handleResponseSendFailed(clientId, errorMessage) {
+        this.telemetry.clientResponse('response.send_failed', {
+            'client.id': clientId,
+            'error.message': errorMessage,
+        });
+    }
+}
+exports.TelemetryIntegrationExample = TelemetryIntegrationExample;
+/**
+ * Load canvas from file
+ */
+function loadControlTowerCanvas() {
+    const fs = require('fs');
+    const path = require('path');
+    const canvasPath = path.join(__dirname, '../../.principal-views/client-connection-auth.otel.canvas');
+    return JSON.parse(fs.readFileSync(canvasPath, 'utf-8'));
+}
+/**
+ * Create telemetry service instance
+ *
+ * @example
+ * ```typescript
+ * const telemetry = createTelemetryService();
+ *
+ * telemetry.clientLifecycle('client.connected', {
+ *   'client.id': 'abc123',
+ *   'transport.type': 'websocket',
+ *   'connection.time': Date.now(),
+ * });
+ * ```
+ */
+function createTelemetryService(options) {
+    const canvas = loadControlTowerCanvas();
+    return new ControlTowerTelemetry(canvas, options);
+}

package/dist/telemetry/EventValidationIntegration.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Event Validation Integration Tests
+ *
+ * Demonstrates the Control Tower telemetry integration working end-to-end.
+ */
+export {};
+//# sourceMappingURL=EventValidationIntegration.test.d.ts.map

package/dist/telemetry/EventValidationIntegration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventValidationIntegration.test.d.ts","sourceRoot":"","sources":["../../src/telemetry/EventValidationIntegration.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}