@principal-ai/control-tower-core 0.1.9 → 0.1.11

package/dist/adapters/websocket/WebSocketClientTransportAdapter.d.ts

@@ -0,0 +1,78 @@
+import type { ITransportAdapter } from '../../abstractions/TransportAdapter.js';
+import type { ConnectionState, ConnectionOptions, Message, MessageHandler, ErrorHandler, CloseHandler } from '../../types/index.js';
+import { WebSocket } from 'ws';
+export interface WebSocketClientConfig {
+    /**
+     * Additional headers to send with the WebSocket connection request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Connection timeout in milliseconds
+     * @default 30000
+     */
+    connectionTimeout?: number;
+    /**
+     * Enable automatic ping/pong for connection health checks
+     * @default true
+     */
+    enableHeartbeat?: boolean;
+    /**
+     * Heartbeat interval in milliseconds
+     * @default 30000
+     */
+    heartbeatInterval?: number;
+}
+/**
+ * WebSocket client transport adapter for connecting to remote WebSocket servers.
+ *
+ * This adapter creates an outgoing WebSocket connection and is intended for use
+ * with BaseClient. For server-side operations (accepting incoming connections),
+ * use WebSocketServerTransportAdapter instead.
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketClientTransportAdapter();
+ * const client = new ClientBuilder()
+ *   .withTransport(transport)
+ *   .build();
+ *
+ * await client.connect('ws://localhost:3000');
+ * ```
+ */
+export declare class WebSocketClientTransportAdapter implements ITransportAdapter {
+    private ws?;
+    private state;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private config;
+    private heartbeatTimer?;
+    private connectionTimer?;
+    constructor(config?: WebSocketClientConfig);
+    connect(url: string, options?: ConnectionOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: Message): Promise<void>;
+    onMessage(handler: MessageHandler): void;
+    onError(handler: ErrorHandler): void;
+    onClose(handler: CloseHandler): void;
+    getState(): ConnectionState;
+    isConnected(): boolean;
+    /**
+     * Get the underlying WebSocket instance
+     * Useful for advanced use cases
+     */
+    getWebSocket(): WebSocket | undefined;
+    /**
+     * Set custom headers for the WebSocket connection
+     * Must be called before connect()
+     */
+    setHeaders(headers: Record<string, string>): void;
+    /**
+     * Add an authorization header for authentication
+     * Must be called before connect()
+     */
+    setAuthToken(token: string): void;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+//# sourceMappingURL=WebSocketClientTransportAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketClientTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/websocket/WebSocketClientTransportAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAE/B,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,+BAAgC,YAAW,iBAAiB;IACvE,OAAO,CAAC,EAAE,CAAC,CAAY;IACvB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAC,CAAiB;gBAE7B,MAAM,CAAC,EAAE,qBAAqB;IASpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2GhE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsC3B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3C,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;IAItB;;;OAGG;IACH,YAAY,IAAI,SAAS,GAAG,SAAS;IAIrC;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAOjD;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMjC,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,aAAa;CAMtB"}

package/dist/adapters/websocket/WebSocketClientTransportAdapter.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketClientTransportAdapter = void 0;
+const ws_1 = require("ws");
+/**
+ * WebSocket client transport adapter for connecting to remote WebSocket servers.
+ *
+ * This adapter creates an outgoing WebSocket connection and is intended for use
+ * with BaseClient. For server-side operations (accepting incoming connections),
+ * use WebSocketServerTransportAdapter instead.
+ *
+ * @example
+ * ```typescript
+ * const transport = new WebSocketClientTransportAdapter();
+ * const client = new ClientBuilder()
+ *   .withTransport(transport)
+ *   .build();
+ *
+ * await client.connect('ws://localhost:3000');
+ * ```
+ */
+class WebSocketClientTransportAdapter {
+    constructor(config) {
+        this.state = 'disconnected';
+        this.messageHandlers = new Set();
+        this.errorHandlers = new Set();
+        this.closeHandlers = new Set();
+        this.config = {
+            headers: config?.headers ?? {},
+            connectionTimeout: config?.connectionTimeout ?? 30000,
+            enableHeartbeat: config?.enableHeartbeat ?? true,
+            heartbeatInterval: config?.heartbeatInterval ?? 30000
+        };
+    }
+    async connect(url, options) {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            throw new Error('Already connected or connecting');
+        }
+        this.state = 'connecting';
+        return new Promise((resolve, reject) => {
+            try {
+                // Create WebSocket client connection
+                const wsOptions = {};
+                // Add custom headers if provided
+                if (Object.keys(this.config.headers).length > 0) {
+                    wsOptions.headers = this.config.headers;
+                }
+                this.ws = new ws_1.WebSocket(url, wsOptions);
+                // Set up connection timeout
+                this.connectionTimer = setTimeout(() => {
+                    if (this.state === 'connecting') {
+                        this.ws?.terminate();
+                        this.state = 'disconnected';
+                        const error = new Error('Connection timeout');
+                        this.errorHandlers.forEach(handler => handler(error));
+                        reject(error);
+                    }
+                }, this.config.connectionTimeout);
+                // Handle connection open
+                this.ws.on('open', () => {
+                    if (this.connectionTimer) {
+                        clearTimeout(this.connectionTimer);
+                        this.connectionTimer = undefined;
+                    }
+                    this.state = 'connected';
+                    // Start heartbeat if enabled
+                    if (this.config.enableHeartbeat) {
+                        this.startHeartbeat();
+                    }
+                    resolve();
+                });
+                // Handle incoming messages
+                this.ws.on('message', (data) => {
+                    try {
+                        const message = JSON.parse(data.toString());
+                        this.messageHandlers.forEach(handler => handler(message));
+                    }
+                    catch (error) {
+                        this.errorHandlers.forEach(handler => handler(error));
+                    }
+                });
+                // Handle errors
+                this.ws.on('error', (error) => {
+                    if (this.connectionTimer) {
+                        clearTimeout(this.connectionTimer);
+                        this.connectionTimer = undefined;
+                    }
+                    this.errorHandlers.forEach(handler => handler(error));
+                    // If error occurs during connection, reject the promise
+                    if (this.state === 'connecting') {
+                        this.state = 'disconnected';
+                        reject(error);
+                    }
+                });
+                // Handle connection close
+                this.ws.on('close', (code, reason) => {
+                    if (this.connectionTimer) {
+                        clearTimeout(this.connectionTimer);
+                        this.connectionTimer = undefined;
+                    }
+                    this.stopHeartbeat();
+                    const wasConnected = this.state === 'connected';
+                    this.state = 'disconnected';
+                    if (wasConnected) {
+                        this.closeHandlers.forEach(handler => handler(code, reason.toString()));
+                    }
+                });
+                // Handle pong responses for heartbeat
+                if (this.config.enableHeartbeat) {
+                    this.ws.on('pong', () => {
+                        // Connection is alive
+                    });
+                }
+            }
+            catch (error) {
+                if (this.connectionTimer) {
+                    clearTimeout(this.connectionTimer);
+                    this.connectionTimer = undefined;
+                }
+                this.state = 'disconnected';
+                reject(error);
+            }
+        });
+    }
+    async disconnect() {
+        if (this.state === 'disconnected') {
+            return;
+        }
+        this.state = 'disconnecting';
+        this.stopHeartbeat();
+        if (this.connectionTimer) {
+            clearTimeout(this.connectionTimer);
+            this.connectionTimer = undefined;
+        }
+        if (this.ws) {
+            // Close with normal closure code
+            this.ws.close(1000, 'Client disconnecting');
+            // Wait for close event or timeout
+            await new Promise((resolve) => {
+                const timeout = setTimeout(() => {
+                    this.ws?.terminate();
+                    resolve();
+                }, 5000);
+                const onClose = () => {
+                    clearTimeout(timeout);
+                    resolve();
+                };
+                this.ws?.once('close', onClose);
+            });
+            this.ws = undefined;
+        }
+        this.state = 'disconnected';
+    }
+    async send(message) {
+        if (this.state !== 'connected') {
+            throw new Error('Not connected');
+        }
+        if (!this.ws || this.ws.readyState !== ws_1.WebSocket.OPEN) {
+            throw new Error('WebSocket connection is not open');
+        }
+        try {
+            const data = JSON.stringify(message);
+            this.ws.send(data);
+        }
+        catch (error) {
+            this.errorHandlers.forEach(handler => handler(error));
+            throw error;
+        }
+    }
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.add(handler);
+    }
+    getState() {
+        return this.state;
+    }
+    isConnected() {
+        return this.state === 'connected' && this.ws?.readyState === ws_1.WebSocket.OPEN;
+    }
+    /**
+     * Get the underlying WebSocket instance
+     * Useful for advanced use cases
+     */
+    getWebSocket() {
+        return this.ws;
+    }
+    /**
+     * Set custom headers for the WebSocket connection
+     * Must be called before connect()
+     */
+    setHeaders(headers) {
+        if (this.state !== 'disconnected') {
+            throw new Error('Cannot set headers while connected');
+        }
+        this.config.headers = { ...this.config.headers, ...headers };
+    }
+    /**
+     * Add an authorization header for authentication
+     * Must be called before connect()
+     */
+    setAuthToken(token) {
+        this.setHeaders({ Authorization: `Bearer ${token}` });
+    }
+    // Private methods
+    startHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+        }
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws && this.ws.readyState === ws_1.WebSocket.OPEN) {
+                this.ws.ping();
+            }
+        }, this.config.heartbeatInterval);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+}
+exports.WebSocketClientTransportAdapter = WebSocketClientTransportAdapter;

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

@@ -0,0 +1,60 @@
+import type { ITransportAdapter } from '../../abstractions/TransportAdapter.js';
+import type { IAuthAdapter } from '../../abstractions/AuthAdapter.js';
+import type { ConnectionState, ConnectionOptions, Message, MessageHandler, ErrorHandler, CloseHandler } from '../../types/index.js';
+import type { Server as HttpServer } from 'http';
+import type { Server as HttpsServer } from 'https';
+import { WebSocketServer, WebSocket } from 'ws';
+interface ClientConnection {
+    id: string;
+    ws: WebSocket;
+    userId?: string;
+    authenticated: boolean;
+    metadata?: Record<string, unknown>;
+    authTimeout?: NodeJS.Timeout;
+    connectedAt: number;
+}
+export interface WebSocketServerTransportConfig {
+    authTimeout?: number;
+    closeOnAuthFailure?: boolean;
+    requireAuth?: boolean;
+}
+export declare class WebSocketServerTransportAdapter implements ITransportAdapter {
+    private state;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private wss?;
+    private serverUrl?;
+    private attachedServer?;
+    private attachedWss?;
+    private webSocketPath?;
+    private clients;
+    private mode;
+    private authAdapter?;
+    private config;
+    constructor(config?: WebSocketServerTransportConfig);
+    setAuthAdapter(auth: IAuthAdapter): void;
+    connect(url: string, _options?: ConnectionOptions): Promise<void>;
+    attach(server: HttpServer | HttpsServer, path?: string): Promise<void>;
+    attachToWebSocketServer(wss: WebSocketServer): Promise<void>;
+    private handleConnection;
+    private handleClientMessage;
+    private handleAuthMessage;
+    private extractBearerToken;
+    private sendToClient;
+    disconnect(): Promise<void>;
+    send(message: Message): Promise<void>;
+    onMessage(handler: MessageHandler): void;
+    onError(handler: ErrorHandler): void;
+    onClose(handler: CloseHandler): void;
+    getState(): ConnectionState;
+    isConnected(): boolean;
+    getConnectedClients(): ClientConnection[];
+    getAuthenticatedClients(): ClientConnection[];
+    getClientCount(): number;
+    getMode(): 'standalone' | 'integration';
+    isAuthRequired(): boolean;
+    private generateId;
+}
+export {};
+//# sourceMappingURL=WebSocketServerTransportAdapter.d.ts.map

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

@@ -0,0 +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"}