@excali-boards/boards-api-client 1.1.33 → 1.1.34

package/README.md

@@ -1,88 +1,59 @@
 # 🧰 boards-api-client
 
-A TypeScript client library for interacting with the [Boards Room API](https://github.com/Excali-Boards), the backend behind the collaborative whiteboarding platform. This SDK simplifies API integration for developers building apps on top of Boards infrastructure.
+A comprehensive TypeScript client library for the [Boards Room API](https://github.com/Excali-Boards), featuring both REST API and WebSocket support. Build real-time collaborative applications with ease.
 
 ---
 
-## 🚀 Features
+## Features
 
-* Fully typed API wrapper for the Boards backend
-* CRUD support for:
+- Fully typed REST client (boards, users, permissions, files, sessions, categories, flashcards, metrics, invites)
+- WebSocket client with auto-reconnect, heartbeat, and message queueing
+- React hooks: generic `useWebSocket` and `useExecutor` for code execution streams
+- Zero-config defaults; override `baseUrl` when needed
 
-  * 🏢 Groups and 📂 Categories
-  * 📝 Boards and 🖼️ Rooms
-  * 👤 Users and 🔐 Permissions
-* Real-time room metadata access and user management
-* OAuth-based authentication support
-* Utility endpoints for resolving board references and cleanup
-* Built-in Axios request handler with date transformation
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
-npm install boards-api-client
+pnpm add @excali-boards/boards-api-client
 # or
-pnpm add boards-api-client
+npm install @excali-boards/boards-api-client
 ```
 
----
+## Quick start
 
-## ✨ Usage
-
-### Initialize the client
+### REST
 
 ```ts
-import { BoardsManager } from 'boards-api-client';
+import { BoardsManager } from "@excali-boards/boards-api-client";
 
-const client = new BoardsManager('https://your-api-url.com');
+const api = new BoardsManager("https://api.example.com");
+const boards = await api.boards.list();
 ```
 
-### Access a module
+### WebSocket (generic)
 
 ```ts
-const authToken = 'Bearer YOUR_TOKEN_HERE';
+import { createConnection } from "@excali-boards/boards-api-client";
 
-const groups = await client.groups.getGroups({ auth: authToken });
-console.log(groups);
+const ws = createConnection("/executor", { baseUrl: "localhost:3000" });
+await ws.connect();
+ws.send(1, { code: "print(42)", language: "python" });
+ws.on(3, (data) => console.log("output:", data.output));
 ```
 
-### Common endpoints
-
-* `client.auth.authenticate(...)` — Login a user
-* `client.groups.getAllSorted(...)` — Fetch full hierarchy
-* `client.boards.getBoard(...)` — Fetch single board info
-* `client.admin.updateUserPermissions(...)` — Update admin permissions
-* `client.stats.globalStats(...)` — Fetch global app statistics
-* `client.utils.resolveBoard(...)` — Resolve board ID by name
-
----
+### React hook (executor)
 
-## 🧪 Example
+```tsx
+import { useExecutor } from "@excali-boards/boards-api-client";
 
-```ts
-const data = await client.boards.getBoard({
-  auth: token,
-  groupId: 'grp123',
-  categoryId: 'cat456',
-  boardId: 'brd789'
-});
-
-console.log(data.board.name);
+const { isConnected, startSession, sendInput, outputs } = useExecutor();
 ```
 
----
-
-## 🛠️ Development
+## Integrations
 
-Clone the repo and install dependencies:
-
-```bash
-git clone https://github.com/Excali-Boards/boards-api-client.git
-cd boards-api-client
-pnpm install
-```
+- React/Next: `useWebSocket`, `useExecutor`
+- Node/SSR: `createConnection` without React
+- TypeScript-first: message payloads and REST responses are typed
 
 ---
 

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export * from './core/manager';
 export * from './types';
 export * from './external/types';
 export * from './external/vars';
+export * from './websocket/manager';
+export * from './websocket/client';
+export * from './websocket/types';
 export * from './classes/permissions';
 export * from './classes/categories';
 export * from './classes/flashcards';

package/dist/index.js

@@ -18,6 +18,9 @@ __exportStar(require("./core/manager"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./external/types"), exports);
 __exportStar(require("./external/vars"), exports);
+__exportStar(require("./websocket/manager"), exports);
+__exportStar(require("./websocket/client"), exports);
+__exportStar(require("./websocket/types"), exports);
 __exportStar(require("./classes/permissions"), exports);
 __exportStar(require("./classes/categories"), exports);
 __exportStar(require("./classes/flashcards"), exports);

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/types.ts","../src/classes/admin.ts","../src/classes/boards.ts","../src/classes/calendar.ts","../src/classes/categories.ts","../src/classes/files.ts","../src/classes/flashcards.ts","../src/classes/groups.ts","../src/classes/invites.ts","../src/classes/metrics.ts","../src/classes/permissions.ts","../src/classes/sessions.ts","../src/classes/users.ts","../src/classes/utils.ts","../src/core/manager.ts","../src/core/utils.ts","../src/external/types.ts","../src/external/vars.ts"],"version":"5.9.2"}
+{"root":["../src/index.ts","../src/types.ts","../src/classes/admin.ts","../src/classes/boards.ts","../src/classes/calendar.ts","../src/classes/categories.ts","../src/classes/files.ts","../src/classes/flashcards.ts","../src/classes/groups.ts","../src/classes/invites.ts","../src/classes/metrics.ts","../src/classes/permissions.ts","../src/classes/sessions.ts","../src/classes/users.ts","../src/classes/utils.ts","../src/core/manager.ts","../src/core/utils.ts","../src/external/types.ts","../src/external/vars.ts","../src/websocket/client.ts","../src/websocket/manager.ts","../src/websocket/types.ts","../src/websocket/hooks/useExecutor.ts","../src/websocket/hooks/useWebSocket.ts"],"version":"5.9.2"}

package/dist/websocket/client.d.ts

@@ -0,0 +1,33 @@
+import { WebSocketMessage, WSConnectionState, ExtractOpCode, ExtractDataForOp } from './types.js';
+export type HandlerFunction = (data: unknown) => void;
+export declare class WSClient<TMessage extends WebSocketMessage = WebSocketMessage> {
+    private state;
+    private ws;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private handlers;
+    private messageQueue;
+    private url;
+    private onConnect?;
+    private onDisconnect?;
+    private onError?;
+    constructor(url: string, options?: {
+        onConnect?: () => void;
+        onDisconnect?: (code?: number, reason?: string) => void;
+        onError?: (error: string) => void;
+    });
+    connect(): Promise<void>;
+    disconnect(): void;
+    send<TOp extends ExtractOpCode<TMessage>>(op: TOp, data: ExtractDataForOp<TMessage, TOp>): boolean;
+    private sendInternal;
+    on<TOp extends ExtractOpCode<TMessage>>(op: TOp, handler: (data: ExtractDataForOp<TMessage, TOp>) => void): void;
+    off(op: number): void;
+    getState(): WSConnectionState;
+    private handleMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private shouldReconnect;
+    private scheduleReconnect;
+    private flushMessageQueue;
+}

package/dist/websocket/client.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WSClient = void 0;
+const types_js_1 = require("./types.js");
+class WSClient {
+    state = types_js_1.WSConnectionState.Disconnected;
+    ws = null;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    handlers = new Map();
+    messageQueue = [];
+    url;
+    onConnect;
+    onDisconnect;
+    onError;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.onConnect = options.onConnect;
+        this.onDisconnect = options.onDisconnect;
+        this.onError = options.onError;
+    }
+    async connect() {
+        if (this.state === types_js_1.WSConnectionState.Connecting || this.state === types_js_1.WSConnectionState.Connected) {
+            return;
+        }
+        this.state = types_js_1.WSConnectionState.Connecting;
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(this.url);
+                this.ws.onopen = () => {
+                    this.state = types_js_1.WSConnectionState.Connected;
+                    this.reconnectAttempts = 0;
+                    this.startHeartbeat();
+                    this.flushMessageQueue();
+                    this.onConnect?.();
+                    resolve();
+                };
+                this.ws.onmessage = (event) => {
+                    try {
+                        const message = JSON.parse(event.data);
+                        this.handleMessage(message);
+                    }
+                    catch (error) {
+                        console.error('Failed to parse WebSocket message:', error);
+                    }
+                };
+                this.ws.onclose = (event) => {
+                    this.state = types_js_1.WSConnectionState.Disconnected;
+                    this.stopHeartbeat();
+                    this.onDisconnect?.(event.code, event.reason);
+                    if (this.shouldReconnect(event.code)) {
+                        this.scheduleReconnect();
+                    }
+                };
+                this.ws.onerror = () => {
+                    this.state = types_js_1.WSConnectionState.Error;
+                    this.onError?.('WebSocket connection error');
+                    reject(new Error('WebSocket connection failed'));
+                };
+            }
+            catch (error) {
+                this.state = types_js_1.WSConnectionState.Error;
+                reject(error);
+            }
+        });
+    }
+    disconnect() {
+        this.state = types_js_1.WSConnectionState.Disconnected;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.stopHeartbeat();
+        if (this.ws) {
+            this.ws.close(1000, 'Client disconnect');
+            this.ws = null;
+        }
+        this.messageQueue = [];
+        this.handlers.clear();
+    }
+    send(op, data) {
+        return this.sendInternal(op, data);
+    }
+    sendInternal(op, data) {
+        const message = { op, data };
+        if (this.state !== types_js_1.WSConnectionState.Connected || !this.ws) {
+            if (this.state === types_js_1.WSConnectionState.Connecting) {
+                this.messageQueue.push(message);
+                return true;
+            }
+            return false;
+        }
+        try {
+            this.ws.send(JSON.stringify(message));
+            return true;
+        }
+        catch (error) {
+            console.error('Failed to send WebSocket message:', error);
+            return false;
+        }
+    }
+    on(op, handler) {
+        this.handlers.set(op, handler);
+    }
+    off(op) {
+        this.handlers.delete(op);
+    }
+    getState() {
+        return this.state;
+    }
+    handleMessage(message) {
+        if (message.op === types_js_1.SpecialOPCodes.Ping) {
+            this.sendInternal(types_js_1.SpecialOPCodes.Pong);
+            return;
+        }
+        if (message.op === types_js_1.SpecialOPCodes.Pong) {
+            return;
+        }
+        const handler = this.handlers.get(message.op);
+        if (handler) {
+            try {
+                handler(message.data);
+            }
+            catch (error) {
+                console.error('Error in message handler:', error);
+            }
+        }
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            if (this.state === types_js_1.WSConnectionState.Connected) {
+                this.sendInternal(types_js_1.SpecialOPCodes.Ping);
+            }
+        }, 30000);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    shouldReconnect(code) {
+        if (code === 1000 || this.reconnectAttempts >= 5)
+            return false;
+        return true;
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.state = types_js_1.WSConnectionState.Reconnecting;
+        this.reconnectAttempts++;
+        const delay = 1000 * Math.pow(2, Math.min(this.reconnectAttempts - 1, 4));
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            try {
+                await this.connect();
+            }
+            catch (error) {
+                console.error('Reconnection failed:', error);
+            }
+        }, delay);
+    }
+    flushMessageQueue() {
+        while (this.messageQueue.length > 0 && this.state === types_js_1.WSConnectionState.Connected) {
+            const message = this.messageQueue.shift();
+            this.sendInternal(message.op, message.data);
+        }
+    }
+}
+exports.WSClient = WSClient;

package/dist/websocket/hooks/useExecutor.d.ts

@@ -0,0 +1,58 @@
+export type UseExecutorOptions = {
+    autoConnect?: boolean;
+    baseUrl?: string;
+    onOutput?: (output: string, type: 'stdout' | 'stderr') => void;
+    onSessionComplete?: (exitCode: number) => void;
+    onError?: (error: string) => void;
+};
+export declare function useExecutor(options?: UseExecutorOptions): {
+    connectionState: import("../types").WSConnectionState;
+    error: string | null;
+    isConnected: boolean;
+    connect: () => Promise<import("../client").WSClient<ExecutorWSMessageUnion>>;
+    disconnect: () => void;
+    startSession: (code: string, language: string) => Promise<boolean>;
+    sendInput: (input: string) => boolean;
+    stopSession: () => boolean;
+    sessionId: string | null;
+    outputs: {
+        output: string;
+        type: "stdout" | "stderr";
+        timestamp: number;
+    }[];
+    isSessionActive: boolean;
+};
+export declare enum ExecutorWSOpCodes {
+    StartCodeSession = 1,
+    CodeSessionCreated = 2,
+    CodeOutput = 3,
+    CodeSessionError = 5,
+    CodeSessionCompleted = 6,
+    SendCodeInput = 7,
+    StopCodeSession = 8
+}
+export type ExecutorWSMessage<T extends ExecutorWSOpCodes> = {
+    op: T;
+    data: T extends ExecutorWSOpCodes.StartCodeSession ? {
+        code: string;
+        language: string;
+    } : T extends ExecutorWSOpCodes.CodeSessionCreated ? {
+        sessionId: string;
+    } : T extends ExecutorWSOpCodes.CodeOutput ? {
+        sessionId: string;
+        output: string;
+        type: 'stdout' | 'stderr';
+    } : T extends ExecutorWSOpCodes.CodeSessionError ? {
+        sessionId: string | null;
+        error: string;
+    } : T extends ExecutorWSOpCodes.CodeSessionCompleted ? {
+        sessionId: string;
+        exitCode: number;
+    } : T extends ExecutorWSOpCodes.SendCodeInput ? {
+        sessionId: string;
+        input: string;
+    } : T extends ExecutorWSOpCodes.StopCodeSession ? {
+        sessionId: string;
+    } : never;
+};
+export type ExecutorWSMessageUnion = ExecutorWSMessage<ExecutorWSOpCodes.StartCodeSession> | ExecutorWSMessage<ExecutorWSOpCodes.CodeSessionCreated> | ExecutorWSMessage<ExecutorWSOpCodes.CodeOutput> | ExecutorWSMessage<ExecutorWSOpCodes.CodeSessionError> | ExecutorWSMessage<ExecutorWSOpCodes.CodeSessionCompleted> | ExecutorWSMessage<ExecutorWSOpCodes.SendCodeInput> | ExecutorWSMessage<ExecutorWSOpCodes.StopCodeSession>;

package/dist/websocket/hooks/useExecutor.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutorWSOpCodes = void 0;
+exports.useExecutor = useExecutor;
+const react_1 = require("react");
+const useWebSocket_1 = require("./useWebSocket");
+function useExecutor(options = {}) {
+    const [sessionId, setSessionId] = (0, react_1.useState)(null);
+    const [outputs, setOutputs] = (0, react_1.useState)([]);
+    const { connectionState, error, isConnected, connect, disconnect, send, on, } = (0, useWebSocket_1.useWebSocket)('/executor', {
+        autoConnect: options.autoConnect,
+        baseUrl: options.baseUrl,
+        onError: options.onError,
+    });
+    (0, react_1.useEffect)(() => {
+        if (!isConnected)
+            return;
+        on(ExecutorWSOpCodes.CodeSessionCreated, (data) => {
+            setSessionId(data.sessionId);
+        });
+        on(ExecutorWSOpCodes.CodeOutput, (data) => {
+            const outputEntry = {
+                output: data.output,
+                type: data.type,
+                timestamp: Date.now(),
+            };
+            setOutputs((prev) => [...prev, outputEntry]);
+            options.onOutput?.(data.output, data.type);
+        });
+        on(ExecutorWSOpCodes.CodeSessionCompleted, (data) => {
+            setSessionId(null);
+            options.onSessionComplete?.(data.exitCode);
+        });
+        on(ExecutorWSOpCodes.CodeSessionError, (data) => {
+            options.onError?.(data.error);
+        });
+    }, [isConnected, on, options]);
+    const startSession = (0, react_1.useCallback)(async (code, language) => {
+        if (!isConnected)
+            await connect();
+        setOutputs([]);
+        return send(ExecutorWSOpCodes.StartCodeSession, { code, language });
+    }, [isConnected, connect, send]);
+    const sendInput = (0, react_1.useCallback)((input) => {
+        if (!sessionId)
+            return false;
+        return send(ExecutorWSOpCodes.SendCodeInput, { sessionId, input });
+    }, [sessionId, send]);
+    const stopSession = (0, react_1.useCallback)(() => {
+        if (!sessionId)
+            return false;
+        return send(ExecutorWSOpCodes.StopCodeSession, { sessionId });
+    }, [sessionId, send]);
+    return {
+        connectionState,
+        error,
+        isConnected,
+        connect,
+        disconnect,
+        startSession,
+        sendInput,
+        stopSession,
+        sessionId,
+        outputs,
+        isSessionActive: sessionId !== null,
+    };
+}
+// Executor WebSocket message types and opcodes
+var ExecutorWSOpCodes;
+(function (ExecutorWSOpCodes) {
+    ExecutorWSOpCodes[ExecutorWSOpCodes["StartCodeSession"] = 1] = "StartCodeSession";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["CodeSessionCreated"] = 2] = "CodeSessionCreated";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["CodeOutput"] = 3] = "CodeOutput";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["CodeSessionError"] = 5] = "CodeSessionError";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["CodeSessionCompleted"] = 6] = "CodeSessionCompleted";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["SendCodeInput"] = 7] = "SendCodeInput";
+    ExecutorWSOpCodes[ExecutorWSOpCodes["StopCodeSession"] = 8] = "StopCodeSession";
+})(ExecutorWSOpCodes || (exports.ExecutorWSOpCodes = ExecutorWSOpCodes = {}));

package/dist/websocket/hooks/useWebSocket.d.ts

@@ -0,0 +1,15 @@
+import { WSConnectionState, WSOptions, WebSocketMessage, ExtractOpCode, ExtractDataForOp } from '../types.js';
+import type { WSClient } from '../client.js';
+export declare function useWebSocket<TMessage extends WebSocketMessage = WebSocketMessage>(path: string, options?: WSOptions & {
+    autoConnect?: boolean;
+}): {
+    error: string | null;
+    connectionState: WSConnectionState;
+    client: WSClient<TMessage> | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    connect: () => Promise<WSClient<TMessage>>;
+    disconnect: () => void;
+    send: <TOp extends ExtractOpCode<TMessage>>(op: TOp, data: ExtractDataForOp<TMessage, TOp>) => boolean;
+    on: <TOp extends ExtractOpCode<TMessage>>(op: TOp, handler: (data: ExtractDataForOp<TMessage, TOp>) => void) => void;
+};

package/dist/websocket/hooks/useWebSocket.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWebSocket = useWebSocket;
+const types_js_1 = require("../types.js");
+const react_1 = require("react");
+const manager_js_1 = require("../manager.js");
+function useWebSocket(path, options = {}) {
+    const { autoConnect = true, ...wsOptions } = options;
+    const [connectionState, setConnectionState] = (0, react_1.useState)(types_js_1.WSConnectionState.Disconnected);
+    const [error, setError] = (0, react_1.useState)(null);
+    const clientRef = (0, react_1.useRef)(null);
+    const connect = (0, react_1.useCallback)(async () => {
+        if (clientRef.current?.getState() === types_js_1.WSConnectionState.Connected)
+            return clientRef.current;
+        try {
+            setConnectionState(types_js_1.WSConnectionState.Connecting);
+            const client = (0, manager_js_1.createConnection)(path, {
+                ...wsOptions,
+                onConnect: () => {
+                    setConnectionState(types_js_1.WSConnectionState.Connected);
+                    setError(null);
+                    wsOptions.onConnect?.();
+                },
+                onDisconnect: (code, reason) => {
+                    setConnectionState(types_js_1.WSConnectionState.Disconnected);
+                    clientRef.current = null;
+                    wsOptions.onDisconnect?.(code, reason);
+                },
+                onError: (err) => {
+                    setConnectionState(types_js_1.WSConnectionState.Error);
+                    setError(err);
+                    wsOptions.onError?.(err);
+                },
+            });
+            clientRef.current = client;
+            await client.connect();
+            return client;
+        }
+        catch (err) {
+            setConnectionState(types_js_1.WSConnectionState.Error);
+            setError(err instanceof Error ? err.message : 'Connection failed');
+            throw err;
+        }
+    }, [path, wsOptions]);
+    const disconnect = (0, react_1.useCallback)(() => {
+        clientRef.current?.disconnect();
+        clientRef.current = null;
+        setConnectionState(types_js_1.WSConnectionState.Disconnected);
+    }, []);
+    const send = (0, react_1.useCallback)((op, data) => {
+        return clientRef.current?.send(op, data) ?? false;
+    }, []);
+    const on = (0, react_1.useCallback)((op, handler) => {
+        clientRef.current?.on(op, handler);
+    }, []);
+    (0, react_1.useEffect)(() => {
+        if (autoConnect)
+            connect().catch(console.error);
+        return disconnect;
+    }, [autoConnect, connect, disconnect]);
+    return {
+        error,
+        connectionState,
+        client: clientRef.current,
+        isConnected: connectionState === types_js_1.WSConnectionState.Connected,
+        isConnecting: connectionState === types_js_1.WSConnectionState.Connecting,
+        connect,
+        disconnect,
+        send,
+        on,
+    };
+}

package/dist/websocket/manager.d.ts

@@ -0,0 +1,5 @@
+import { WSOptions, WebSocketMessage } from './types.js';
+import { WSClient } from './client.js';
+export declare function createConnection<TMessage extends WebSocketMessage = WebSocketMessage>(path: string, options?: WSOptions): WSClient<TMessage>;
+export * from './hooks/useExecutor.js';
+export * from './hooks/useWebSocket.js';

package/dist/websocket/manager.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConnection = createConnection;
+const types_js_1 = require("./types.js");
+const client_js_1 = require("./client.js");
+const connections = new Map();
+function createWebSocketUrl(path, baseUrl) {
+    const base = baseUrl || (typeof window !== 'undefined' ? window.location.host : 'localhost:3000');
+    const protocol = base.startsWith('https') || base.includes('443') ? 'wss' : 'ws';
+    return `${protocol}://${base.replace(/^https?:\/\//g, '')}${path}`;
+}
+function createConnection(path, options = {}) {
+    const url = createWebSocketUrl(path, options.baseUrl);
+    const existing = connections.get(path);
+    if (existing && existing.getState() === types_js_1.WSConnectionState.Connected)
+        return existing;
+    const client = new client_js_1.WSClient(url, {
+        onError: options.onError,
+        onConnect: options.onConnect,
+        onDisconnect: (code, reason) => {
+            connections.delete(path);
+            options.onDisconnect?.(code, reason);
+        },
+    });
+    connections.set(path, client);
+    return client;
+}
+// Exports.
+__exportStar(require("./hooks/useExecutor.js"), exports);
+__exportStar(require("./hooks/useWebSocket.js"), exports);

package/dist/websocket/types.d.ts

@@ -0,0 +1,28 @@
+export type WebSocketMessage<T = unknown> = {
+    op: number;
+    data: T;
+};
+export declare enum SpecialOPCodes {
+    Ping = -1,
+    Pong = -2
+}
+export declare enum WSConnectionState {
+    Disconnected = 0,
+    Connecting = 1,
+    Connected = 2,
+    Reconnecting = 3,
+    Error = 4
+}
+export type WSOptions = {
+    baseUrl?: string;
+    onConnect?: () => void;
+    onDisconnect?: (code?: number, reason?: string) => void;
+    onError?: (error: string) => void;
+};
+export type ExtractOpCode<T> = T extends {
+    op: infer U;
+} ? U : never;
+export type ExtractDataForOp<TMessage, TOp> = TMessage extends {
+    op: TOp;
+    data: infer U;
+} ? U : never;

package/dist/websocket/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WSConnectionState = exports.SpecialOPCodes = void 0;
+var SpecialOPCodes;
+(function (SpecialOPCodes) {
+    SpecialOPCodes[SpecialOPCodes["Ping"] = -1] = "Ping";
+    SpecialOPCodes[SpecialOPCodes["Pong"] = -2] = "Pong";
+})(SpecialOPCodes || (exports.SpecialOPCodes = SpecialOPCodes = {}));
+var WSConnectionState;
+(function (WSConnectionState) {
+    WSConnectionState[WSConnectionState["Disconnected"] = 0] = "Disconnected";
+    WSConnectionState[WSConnectionState["Connecting"] = 1] = "Connecting";
+    WSConnectionState[WSConnectionState["Connected"] = 2] = "Connected";
+    WSConnectionState[WSConnectionState["Reconnecting"] = 3] = "Reconnecting";
+    WSConnectionState[WSConnectionState["Error"] = 4] = "Error";
+})(WSConnectionState || (exports.WSConnectionState = WSConnectionState = {}));

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.33",
+	"version": "1.1.34",
 	"name": "@excali-boards/boards-api-client",
 	"description": "A simple API client for the Boards API.",
 	"repository": "https://github.com/Excali-Boards/boards-api-client",
@@ -32,6 +32,7 @@
 	},
 	"devDependencies": {
 		"@types/node": "20.14.13",
+		"@types/react": "^19.2.8",
 		"@typescript-eslint/eslint-plugin": "6.18.0",
 		"@typescript-eslint/parser": "6.18.0",
 		"eslint": "8.56.0",
@@ -44,7 +45,11 @@
 		"@prisma/client": "6.16.2",
 		"axios": "1.12.2",
 		"prisma": "6.16.2",
+		"react": "^18.2.0",
 		"ts-prisma": "1.3.3",
 		"zod": "4.1.9"
+	},
+	"peerDependencies": {
+		"react": "^16.8.0 || ^17.0.0 || ^18.0.0"
 	}
 }

package/prisma/schema/boards.prisma

@@ -43,7 +43,8 @@ model Board {
     categoryId String
     category   Category @relation(fields: [categoryId], references: [categoryId], onDelete: Cascade)
 
-    flashcardDeck FlashcardDeck?
+    flashcardDeck         FlashcardDeck?
+    codeSnippetCollection CodeSnippetCollection?
 
     files           File[]
     boardPermission BoardPermission[]

package/prisma/schema/codesnippets.prisma

@@ -0,0 +1,33 @@
+model CodeSnippetCollection {
+    dbId         String @id @default(uuid())
+    collectionId String @unique
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    boardId String @unique
+    board   Board  @relation(fields: [boardId], references: [boardId], onDelete: Cascade)
+
+    snippets CodeSnippet[]
+
+    @@index([boardId])
+}
+
+model CodeSnippet {
+    dbId      String @id @default(uuid())
+    snippetId String @unique
+
+    title       String
+    description String @default("")
+    code        String @db.Text
+    language    String @default("cpp")
+    index       Int
+
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+
+    collectionId String
+    collection   CodeSnippetCollection @relation(fields: [collectionId], references: [collectionId], onDelete: Cascade)
+
+    @@index([collectionId])
+}