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

package/dist/adapters/websocket/WebSocketTransportAdapter.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 WebSocketTransportConfig {
+    authTimeout?: number;
+    closeOnAuthFailure?: boolean;
+    requireAuth?: boolean;
+}
+export declare class WebSocketTransportAdapter 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?: WebSocketTransportConfig);
+    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=WebSocketTransportAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketTransportAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/websocket/WebSocketTransportAdapter.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,wBAAwB;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,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,CAA2B;gBAE7B,MAAM,CAAC,EAAE,wBAAwB;IAU7C,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"}

package/dist/adapters/websocket/WebSocketTransportAdapter.js

@@ -0,0 +1,386 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransportAdapter = void 0;
+const ws_1 = require("ws");
+class WebSocketTransportAdapter {
+    constructor(config) {
+        this.state = 'disconnected';
+        this.messageHandlers = new Set();
+        this.errorHandlers = new Set();
+        this.closeHandlers = new Set();
+        // Client management
+        this.clients = new Map();
+        this.mode = 'standalone';
+        this.config = {
+            authTimeout: config?.authTimeout ?? 5000,
+            closeOnAuthFailure: config?.closeOnAuthFailure ?? false,
+            requireAuth: config?.requireAuth ?? false,
+            ...config
+        };
+    }
+    // Set the auth adapter
+    setAuthAdapter(auth) {
+        this.authAdapter = auth;
+        // Use auth adapter's preference only if requireAuth is not already true
+        // This allows explicit requireAuth: true in config to take precedence
+        if (auth.isAuthRequired && !this.config.requireAuth) {
+            this.config.requireAuth = auth.isAuthRequired();
+        }
+        // For authTimeout, use adapter's value if not explicitly set (not matching default)
+        if (auth.getAuthTimeout && this.config.authTimeout === 5000) {
+            this.config.authTimeout = auth.getAuthTimeout();
+        }
+    }
+    // Standalone mode implementation
+    async connect(url, _options) {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            throw new Error('Already connected or connecting');
+        }
+        this.state = 'connecting';
+        this.serverUrl = url;
+        this.mode = 'standalone';
+        try {
+            // Extract port from URL
+            const urlObj = new URL(url);
+            const port = parseInt(urlObj.port) || (urlObj.protocol === 'wss:' ? 443 : 80);
+            // Create WebSocket server
+            this.wss = new ws_1.WebSocketServer({ port });
+            this.wss.on('connection', (ws, req) => {
+                this.handleConnection(ws, req);
+            });
+            this.wss.on('error', (error) => {
+                this.errorHandlers.forEach(handler => handler(error));
+            });
+            this.wss.on('close', () => {
+                this.state = 'disconnected';
+                this.closeHandlers.forEach(handler => handler(1000, 'Server closed'));
+            });
+            this.state = 'connected';
+        }
+        catch (error) {
+            this.state = 'disconnected';
+            throw error;
+        }
+    }
+    // Integration mode implementation
+    async attach(server, path = '/ws') {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            throw new Error('Already connected or connecting');
+        }
+        this.state = 'connecting';
+        this.attachedServer = server;
+        this.webSocketPath = path;
+        this.mode = 'integration';
+        try {
+            // Create WebSocket server attached to the existing HTTP server
+            this.wss = new ws_1.WebSocketServer({
+                server,
+                path,
+                perMessageDeflate: false
+            });
+            this.wss.on('connection', (ws, req) => {
+                this.handleConnection(ws, req);
+            });
+            this.wss.on('error', (error) => {
+                this.errorHandlers.forEach(handler => handler(error));
+            });
+            this.state = 'connected';
+        }
+        catch (error) {
+            this.state = 'disconnected';
+            throw error;
+        }
+    }
+    async attachToWebSocketServer(wss) {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            throw new Error('Already connected or connecting');
+        }
+        this.state = 'connecting';
+        this.attachedWss = wss;
+        this.mode = 'integration';
+        try {
+            this.wss = wss;
+            this.wss.on('connection', (ws, req) => {
+                this.handleConnection(ws, req);
+            });
+            this.wss.on('error', (error) => {
+                this.errorHandlers.forEach(handler => handler(error));
+            });
+            this.state = 'connected';
+        }
+        catch (error) {
+            this.state = 'disconnected';
+            throw error;
+        }
+    }
+    async handleConnection(ws, req) {
+        const clientId = this.generateId();
+        // Step 1: Try header authentication if auth adapter is available
+        let authenticated = false;
+        let authResult = null;
+        if (this.authAdapter && req.headers.authorization) {
+            const token = this.extractBearerToken(req.headers.authorization);
+            if (token) {
+                try {
+                    authResult = await this.authAdapter.authenticate({
+                        type: 'bearer',
+                        token: token
+                    });
+                    authenticated = authResult.success;
+                }
+                catch {
+                    // Header auth failed but don't reject connection
+                }
+            }
+        }
+        // Step 2: Create client with auth state
+        const client = {
+            id: clientId,
+            ws,
+            authenticated,
+            userId: authResult?.userId || (authResult?.user?.userId),
+            metadata: authResult?.metadata || authResult?.user?.metadata,
+            connectedAt: Date.now()
+        };
+        this.clients.set(clientId, client);
+        // Step 3: Set up message handling
+        ws.on('message', (data) => {
+            this.handleClientMessage(clientId, data);
+        });
+        ws.on('error', (error) => {
+            this.errorHandlers.forEach(handler => handler(error));
+        });
+        ws.on('close', (_code, _reason) => {
+            // Clear auth timeout if exists
+            if (client.authTimeout) {
+                clearTimeout(client.authTimeout);
+            }
+            this.clients.delete(clientId);
+        });
+        // Step 4: Set auth timeout if not authenticated and auth is required
+        if (!authenticated && this.config.requireAuth && this.authAdapter) {
+            client.authTimeout = setTimeout(() => {
+                if (!client.authenticated) {
+                    ws.close(1008, 'Authentication timeout');
+                    this.clients.delete(clientId);
+                }
+            }, this.config.authTimeout);
+        }
+        // Step 5: Notify about connection (with auth status)
+        const connectionMessage = {
+            id: this.generateId(),
+            type: 'connection',
+            payload: {
+                clientId,
+                authenticated,
+                userId: client.userId,
+                metadata: client.metadata
+            },
+            timestamp: Date.now()
+        };
+        this.messageHandlers.forEach(handler => handler(connectionMessage));
+    }
+    async handleClientMessage(clientId, data) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return;
+        try {
+            const message = JSON.parse(data.toString());
+            // Special handling for authentication messages
+            if (message.type === 'authenticate' && !client.authenticated && this.authAdapter) {
+                await this.handleAuthMessage(client, message);
+                return;
+            }
+            // Reject messages from unauthenticated clients if auth is required
+            if (this.config.requireAuth && !client.authenticated) {
+                this.sendToClient(client, {
+                    id: this.generateId(),
+                    type: 'error',
+                    payload: { error: 'Authentication required' },
+                    timestamp: Date.now()
+                });
+                return;
+            }
+            // Add clientId to message payload for routing
+            const enrichedMessage = {
+                ...message,
+                payload: {
+                    ...message.payload,
+                    clientId
+                }
+            };
+            this.messageHandlers.forEach(handler => handler(enrichedMessage));
+        }
+        catch (error) {
+            this.errorHandlers.forEach(handler => handler(error));
+        }
+    }
+    async handleAuthMessage(client, message) {
+        if (!this.authAdapter) {
+            this.sendToClient(client, {
+                id: this.generateId(),
+                type: 'auth_error',
+                payload: { error: 'No auth adapter configured' },
+                timestamp: Date.now()
+            });
+            return;
+        }
+        try {
+            const credentials = message.payload;
+            const result = await this.authAdapter.authenticate(credentials);
+            if (result.success) {
+                // Clear auth timeout
+                if (client.authTimeout) {
+                    clearTimeout(client.authTimeout);
+                    client.authTimeout = undefined;
+                }
+                // Update client state
+                client.authenticated = true;
+                client.userId = result.userId || result.user?.userId;
+                client.metadata = result.metadata || result.user?.metadata;
+                // Send success response
+                this.sendToClient(client, {
+                    id: this.generateId(),
+                    type: 'auth_success',
+                    payload: {
+                        userId: client.userId,
+                        metadata: client.metadata
+                    },
+                    timestamp: Date.now()
+                });
+                // Notify handlers about authentication
+                const authMessage = {
+                    id: this.generateId(),
+                    type: 'client_authenticated',
+                    payload: {
+                        clientId: client.id,
+                        userId: client.userId,
+                        metadata: client.metadata
+                    },
+                    timestamp: Date.now()
+                };
+                this.messageHandlers.forEach(handler => handler(authMessage));
+            }
+            else {
+                // Send error response
+                this.sendToClient(client, {
+                    id: this.generateId(),
+                    type: 'auth_error',
+                    payload: { error: result.error || 'Authentication failed' },
+                    timestamp: Date.now()
+                });
+                // Optionally close connection
+                if (this.config.closeOnAuthFailure) {
+                    client.ws.close(1008, 'Authentication failed');
+                    this.clients.delete(client.id);
+                }
+            }
+        }
+        catch (error) {
+            this.sendToClient(client, {
+                id: this.generateId(),
+                type: 'auth_error',
+                payload: { error: error.message },
+                timestamp: Date.now()
+            });
+        }
+    }
+    extractBearerToken(authHeader) {
+        if (authHeader.startsWith('Bearer ')) {
+            return authHeader.substring(7);
+        }
+        return null;
+    }
+    sendToClient(client, message) {
+        if (client.ws.readyState === ws_1.WebSocket.OPEN) {
+            client.ws.send(JSON.stringify(message));
+        }
+    }
+    async disconnect() {
+        if (this.state === 'disconnected') {
+            return;
+        }
+        this.state = 'disconnecting';
+        // Close all client connections
+        for (const [_clientId, client] of this.clients) {
+            try {
+                if (client.authTimeout) {
+                    clearTimeout(client.authTimeout);
+                }
+                client.ws.close(1000, 'Server shutting down');
+            }
+            catch {
+                // Ignore errors when closing individual connections
+            }
+        }
+        this.clients.clear();
+        // Close the WebSocket server (only if we created it)
+        if (this.wss && this.mode === 'standalone') {
+            await new Promise((resolve) => {
+                this.wss.close(() => resolve());
+            });
+        }
+        this.state = 'disconnected';
+        this.wss = undefined;
+        this.attachedServer = undefined;
+        this.attachedWss = undefined;
+    }
+    async send(message) {
+        if (this.state !== 'connected') {
+            throw new Error('Not connected');
+        }
+        // Extract clientId from message payload for routing
+        const payload = message.payload;
+        const { clientId, ...clientMessage } = payload;
+        if (!clientId) {
+            throw new Error('Message must contain clientId in payload for routing');
+        }
+        const client = this.clients.get(clientId);
+        if (!client) {
+            throw new Error(`Client ${clientId} not found`);
+        }
+        if (client.ws.readyState !== ws_1.WebSocket.OPEN) {
+            throw new Error(`Client ${clientId} connection is not open`);
+        }
+        const messageToSend = {
+            ...message,
+            payload: clientMessage
+        };
+        client.ws.send(JSON.stringify(messageToSend));
+    }
+    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';
+    }
+    // Utility methods
+    getConnectedClients() {
+        return Array.from(this.clients.values());
+    }
+    getAuthenticatedClients() {
+        return Array.from(this.clients.values()).filter(c => c.authenticated);
+    }
+    getClientCount() {
+        return this.clients.size;
+    }
+    getMode() {
+        return this.mode;
+    }
+    isAuthRequired() {
+        return this.config.requireAuth ?? false;
+    }
+    generateId() {
+        return Math.random().toString(36).substring(2) + Date.now().toString(36);
+    }
+}
+exports.WebSocketTransportAdapter = WebSocketTransportAdapter;

package/dist/client/BaseClient.d.ts

@@ -78,6 +78,7 @@ export declare class BaseClient extends TypedEventEmitter<ClientEvents> {
     private reconnectTimer;
     private lastConnectionUrl;
     private lastToken;
+    private pendingRequests;
     constructor(config: ClientConfig);
     /**
      * Connect to the server with an optional authentication token.
@@ -105,6 +106,28 @@ export declare class BaseClient extends TypedEventEmitter<ClientEvents> {
     broadcast(event: Event): Promise<void>;
     requestLock(request: LockRequest): Promise<void>;
     releaseLock(lockId: string): Promise<void>;
+    /**
+     * Send a request message and wait for a response.
+     *
+     * This enables request/response patterns over WebSocket by correlating
+     * the response message with the request via the message ID.
+     *
+     * @param type The message type to send
+     * @param payload The message payload
+     * @param timeoutMs Timeout in milliseconds (default: 5000)
+     * @returns Promise that resolves with the response payload
+     * @throws Error if the request times out or the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const response = await client.request<PresenceGetUsersResponse>(
+     *   'presence:get_users',
+     *   {}
+     * );
+     * console.log(response.users);
+     * ```
+     */
+    request<T>(type: string, payload: unknown, timeoutMs?: number): Promise<T>;
     getConnectionState(): ConnectionState;
     getRoomState(): RoomState | null;
     getPresence(): RoomUser[];

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

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

package/dist/client/BaseClient.js

@@ -16,6 +16,8 @@ class BaseClient extends EventEmitter_js_1.TypedEventEmitter {
         this.reconnectTimer = null;
         this.lastConnectionUrl = null;
         this.lastToken = null;
+        // Request/response tracking for request() method
+        this.pendingRequests = new Map();
         this.config = config;
         this.transport = config.transport;
         this.auth = config.auth;
@@ -222,6 +224,56 @@ class BaseClient extends EventEmitter_js_1.TypedEventEmitter {
         };
         await this.transport.send(message);
     }
+    // Request/Response Pattern
+    /**
+     * Send a request message and wait for a response.
+     *
+     * This enables request/response patterns over WebSocket by correlating
+     * the response message with the request via the message ID.
+     *
+     * @param type The message type to send
+     * @param payload The message payload
+     * @param timeoutMs Timeout in milliseconds (default: 5000)
+     * @returns Promise that resolves with the response payload
+     * @throws Error if the request times out or the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const response = await client.request<PresenceGetUsersResponse>(
+     *   'presence:get_users',
+     *   {}
+     * );
+     * console.log(response.users);
+     * ```
+     */
+    async request(type, payload, timeoutMs = 5000) {
+        if (this.connectionState !== "connected") {
+            throw new Error("Client must be connected to send requests");
+        }
+        const id = this.generateId();
+        const message = {
+            id,
+            type,
+            payload,
+            timestamp: Date.now(),
+        };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request '${type}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingRequests.set(id, {
+                resolve: resolve,
+                reject,
+                timeout,
+            });
+            this.transport.send(message).catch((error) => {
+                this.pendingRequests.delete(id);
+                clearTimeout(timeout);
+                reject(error);
+            });
+        });
+    }
     // State Getters
     getConnectionState() {
         return this.connectionState;
@@ -242,6 +294,14 @@ class BaseClient extends EventEmitter_js_1.TypedEventEmitter {
     }
     // Private Methods
     async handleMessage(message) {
+        // Check for pending request response (matched by message id)
+        if (message.id && this.pendingRequests.has(message.id)) {
+            const pending = this.pendingRequests.get(message.id);
+            clearTimeout(pending.timeout);
+            this.pendingRequests.delete(message.id);
+            pending.resolve(message.payload);
+            return;
+        }
         try {
             switch (message.type) {
                 case "auth_result":

package/dist/client/PresenceClient.d.ts

@@ -5,7 +5,7 @@
  * Automatically handles connection, authentication, and presence event forwarding.
  */
 import { TypedEventEmitter } from "../abstractions/EventEmitter.js";
-import type { UserPresence } from "../types/presence.js";
+import type { SerializableUserPresence } from "../types/presence.js";
 import { BaseClient, type ClientConfig } from "./BaseClient.js";
 export interface PresenceClientConfig {
     /**
@@ -118,23 +118,58 @@ export declare class PresenceClient extends TypedEventEmitter<PresenceClientEven
      */
     disconnect(): Promise<void>;
     /**
-     * Get all online users
+     * Get all online users with their presence data
      *
-     * Note: This requires a corresponding API endpoint on your server.
+     * @returns Array of user presence objects
      */
-    getOnlineUsers(): Promise<UserPresence[]>;
+    getOnlineUsers(): Promise<SerializableUserPresence[]>;
+    /**
+     * Get presence information for a specific user
+     *
+     * @param userId The user ID to look up
+     * @returns User presence or null if not found
+     */
+    getUserPresence(userId: string): Promise<SerializableUserPresence | null>;
+    /**
+     * Get all users in a specific repository
+     *
+     * @param owner Repository owner
+     * @param repo Repository name
+     * @returns Array of user presence objects
+     */
+    getRepoUsers(owner: string, repo: string): Promise<SerializableUserPresence[]>;
     /**
      * Set user status
      *
-     * Note: This requires a corresponding API endpoint on your server.
+     * @param status The status to set ('online' or 'away')
+     * @param statusMessage Optional status message
      */
-    setStatus(status: "online" | "away", message?: string): Promise<void>;
+    setStatus(status: "online" | "away", statusMessage?: string): Promise<void>;
     /**
-     * Set visibility
+     * Set visibility (invisible/lurker mode)
      *
-     * Note: This requires a corresponding API endpoint on your server.
+     * @param visible Whether the user should be visible to others
      */
     setVisibility(visible: boolean): Promise<void>;
+    /**
+     * Report that a repository was opened
+     *
+     * @param repoId Repository ID (format: "owner/repo")
+     * @param branch Branch name
+     */
+    reportRepoOpened(repoId: string, branch: string): Promise<void>;
+    /**
+     * Report that a repository was closed
+     *
+     * @param repoId Repository ID (format: "owner/repo")
+     */
+    reportRepoClosed(repoId: string): Promise<void>;
+    /**
+     * Report that a repository is now focused/active
+     *
+     * @param repoId Repository ID (format: "owner/repo")
+     */
+    reportRepoFocused(repoId: string): Promise<void>;
     /**
      * Get the underlying BaseClient
      */

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

@@ -1 +1 @@
-{"version":3,"file":"PresenceClient.d.ts","sourceRoot":"","sources":["../../src/client/PresenceClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACpC;;;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;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC;;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;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAe,SAAQ,iBAAiB,CAAC,oBAAoB,CAAC;IAC1E,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;CAwD5B"}
+{"version":3,"file":"PresenceClient.d.ts","sourceRoot":"","sources":["../../src/client/PresenceClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAKX,wBAAwB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACpC;;;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;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC;;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;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAe,SAAQ,iBAAiB,CAAC,oBAAoB,CAAC;IAC1E,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,wBAAwB,EAAE,CAAC;IAQ3D;;;;;OAKG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAQ/E;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAQpF;;;;;OAKG;IACG,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjF;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpD;;;;;OAKG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrE;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrD;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD;;OAEG;IACH,SAAS,IAAI,UAAU;IAIvB;;OAEG;IACH,WAAW,IAAI,OAAO;IAMtB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAwD5B"}