@principal-ai/control-tower-core 0.2.1 → 0.3.0

package/dist/server/BaseServer.d.ts

@@ -8,8 +8,20 @@ import type { PresenceManager } from "../abstractions/PresenceManager.js";
 import type { RoomManager } from "../abstractions/RoomManager.js";
 import type { IStorageAdapter } from "../abstractions/StorageAdapter.js";
 import type { ITransportAdapter } from "../abstractions/TransportAdapter.js";
-import type { Event, ExperimentalFeatureConfig, ExperimentalUsageEvent, Lock, Room, RoomConfig } from "../types/index.js";
+import type { Event, ExperimentalFeatureConfig, ExperimentalUsageEvent, Lock, Message, Room, RoomConfig } from "../types/index.js";
 import { ExperimentalAPI } from "./ExperimentalAPI.js";
+/**
+ * Custom message handler for application-specific message types.
+ *
+ * Called when a message type is not recognized by the built-in handler.
+ * Return true if the message was handled, false to fall through to the default error response.
+ *
+ * @param clientId - The ID of the client that sent the message
+ * @param message - The message received
+ * @param sendResponse - Function to send a response back to the client (preserves message.id for correlation)
+ * @returns Promise<boolean> - true if handled, false otherwise
+ */
+export type CustomMessageHandler = (clientId: string, message: Message, sendResponse: (response: Record<string, unknown>) => Promise<void>) => Promise<boolean>;
 export interface ServerConfig {
     transport: ITransportAdapter;
     auth?: IAuthAdapter;
@@ -22,6 +34,11 @@ export interface ServerConfig {
     webSocketPath?: string;
     webSocketServer?: WebSocketServer;
     experimental?: ExperimentalFeatureConfig;
+    /**
+     * Custom message handler for application-specific message types.
+     * Called when a message type is not recognized by the built-in handler.
+     */
+    customMessageHandler?: CustomMessageHandler;
 }
 export interface ConnectedClient {
     id: string;

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

@@ -458,11 +458,25 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
                             timestamp: Date.now(),
                         });
                         break;
-                    default:
+                    default: {
+                        // Try custom message handler if configured
+                        if (this.config.customMessageHandler) {
+                            const sendResponse = async (response) => {
+                                await this.sendToClient(clientId, {
+                                    id: message.id,
+                                    ...response,
+                                });
+                            };
+                            const handled = await this.config.customMessageHandler(clientId, message, sendResponse);
+                            if (handled)
+                                break;
+                        }
+                        // Fall through to error if not handled
                         await this.sendToClient(clientId, {
                             type: "error",
                             error: `Unknown message type: ${message.type}`,
                         });
+                    }
                 }
             }
             catch (error) {

package/dist/server/ServerBuilder.d.ts

@@ -8,7 +8,7 @@ import type { RoomManager } from "../abstractions/RoomManager.js";
 import type { IStorageAdapter } from "../abstractions/StorageAdapter.js";
 import type { ITransportAdapter } from "../abstractions/TransportAdapter.js";
 import type { ExperimentalFeatureConfig, RoomConfig } from "../types/index.js";
-import { BaseServer } from "./BaseServer.js";
+import { BaseServer, type CustomMessageHandler } from "./BaseServer.js";
 export declare class ServerBuilder {
     private transport?;
     private auth?;
@@ -21,6 +21,7 @@ export declare class ServerBuilder {
     private webSocketPath?;
     private webSocketServer?;
     private experimentalFeatures?;
+    private customMessageHandler?;
     withTransport(transport: ITransportAdapter): this;
     withAuth(auth: IAuthAdapter): this;
     withStorage(storage: IStorageAdapter): this;
@@ -48,6 +49,26 @@ export declare class ServerBuilder {
      * @see docs/EXPERIMENTAL_BROADCAST.md
      */
     withExperimentalFeatures(features: ExperimentalFeatureConfig): this;
+    /**
+     * Set a custom message handler for application-specific message types.
+     *
+     * The handler is called when a message type is not recognized by the built-in handlers.
+     * Return true from the handler if the message was handled, false to fall through
+     * to the default error response.
+     *
+     * @example
+     * ```typescript
+     * builder.withCustomMessageHandler(async (clientId, message, sendResponse) => {
+     *   if (message.type === 'presence:get_users') {
+     *     const users = await getPresenceUsers();
+     *     await sendResponse({ type: 'presence:users', payload: { users } });
+     *     return true;
+     *   }
+     *   return false;
+     * });
+     * ```
+     */
+    withCustomMessageHandler(handler: CustomMessageHandler): this;
     build(): BaseServer;
     /**
      * Wire presence extension hooks to server events

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;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"}
+{"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,EACN,UAAU,EACV,KAAK,oBAAoB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,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;IACzD,OAAO,CAAC,oBAAoB,CAAC,CAAuB;IAEpD,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;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAK7D,KAAK,IAAI,UAAU;IAqEnB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;CAyClC"}

package/dist/server/ServerBuilder.js

@@ -65,6 +65,29 @@ class ServerBuilder {
         this.experimentalFeatures = features;
         return this;
     }
+    /**
+     * Set a custom message handler for application-specific message types.
+     *
+     * The handler is called when a message type is not recognized by the built-in handlers.
+     * Return true from the handler if the message was handled, false to fall through
+     * to the default error response.
+     *
+     * @example
+     * ```typescript
+     * builder.withCustomMessageHandler(async (clientId, message, sendResponse) => {
+     *   if (message.type === 'presence:get_users') {
+     *     const users = await getPresenceUsers();
+     *     await sendResponse({ type: 'presence:users', payload: { users } });
+     *     return true;
+     *   }
+     *   return false;
+     * });
+     * ```
+     */
+    withCustomMessageHandler(handler) {
+        this.customMessageHandler = handler;
+        return this;
+    }
     build() {
         if (!this.transport) {
             throw new Error("Transport adapter is required");
@@ -95,6 +118,7 @@ class ServerBuilder {
                 warnOnExperimentalUse: true,
                 trackUsageMetrics: false,
             },
+            customMessageHandler: this.customMessageHandler,
         };
         const server = new BaseServer_js_1.BaseServer(config);
         // Auto-enhance DefaultRoomManager with broadcasting capabilities

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { BaseServer, type ConnectedClient, type ServerConfig, type ServerEvents, } from "./BaseServer.js";
+export { BaseServer, type ConnectedClient, type CustomMessageHandler, type ServerConfig, type ServerEvents, } from "./BaseServer.js";
 export { ExperimentalAPI } from "./ExperimentalAPI.js";
 export { ServerBuilder } from "./ServerBuilder.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,YAAY,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

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"}