@xloon/xms-client 0.1.0

package/dist/signaling.d.ts

@@ -0,0 +1,52 @@
+import type { EventData, EventName, MethodName, MethodParams, MethodResult } from './protocol.js';
+/**
+ * The subset of the WebSocket interface signalingClient depends on. Letting
+ * the constructor accept a factory that produces this shape (rather than
+ * hard-coding `new WebSocket(url)`) is what makes request/response
+ * correlation unit-testable without a real server or a jsdom WebSocket
+ * implementation -- tests inject a hand-written fake.
+ */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export type ConnectionState = 'idle' | 'connecting' | 'open' | 'closed';
+type EventHandler<E extends EventName> = (data: EventData[E]) => void;
+export declare class SignalingClient {
+    private readonly url;
+    private readonly wsFactory;
+    private ws;
+    private state;
+    private nextRequestId;
+    private readonly pending;
+    private readonly eventListeners;
+    private readonly openHandlers;
+    private readonly closeHandlers;
+    private readonly errorHandlers;
+    constructor(url: string, wsFactory?: WebSocketFactory);
+    getState(): ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): void;
+    /**
+     * Sends a correlated request and resolves/rejects when the matching
+     * {type:"response", id} arrives. Rejects with the server's `error` object
+     * when `ok:false`, and with a synthetic ProtocolError if the connection is
+     * not open or closes before a response arrives -- never silently hangs.
+     */
+    request<M extends MethodName>(method: M, params: MethodParams[M]): Promise<MethodResult[M]>;
+    /** Subscribes to an unsolicited server event. Returns an unsubscribe function. */
+    on<E extends EventName>(event: E, handler: EventHandler<E>): () => void;
+    onOpen(handler: () => void): () => void;
+    onClose(handler: (event: CloseEvent) => void): () => void;
+    onError(handler: (event: Event) => void): () => void;
+    private generateRequestId;
+    private rejectAllPending;
+    private handleMessage;
+}
+export {};

package/dist/signaling.js

@@ -0,0 +1,165 @@
+const CONNECTION_CLOSED_ERROR = {
+    code: 'CONNECTION_CLOSED',
+    message: 'The signaling WebSocket connection closed before a response was received.',
+};
+const NOT_CONNECTED_ERROR = {
+    code: 'NOT_CONNECTED',
+    message: 'The signaling WebSocket is not connected.',
+};
+function defaultWebSocketFactory(url) {
+    return new WebSocket(url);
+}
+export class SignalingClient {
+    url;
+    wsFactory;
+    ws = null;
+    state = 'idle';
+    nextRequestId = 0;
+    pending = new Map();
+    eventListeners = new Map();
+    openHandlers = new Set();
+    closeHandlers = new Set();
+    errorHandlers = new Set();
+    constructor(url, wsFactory = defaultWebSocketFactory) {
+        this.url = url;
+        this.wsFactory = wsFactory;
+    }
+    getState() {
+        return this.state;
+    }
+    connect() {
+        if (this.state === 'open') {
+            return Promise.resolve();
+        }
+        this.state = 'connecting';
+        return new Promise((resolve, reject) => {
+            const ws = this.wsFactory(this.url);
+            this.ws = ws;
+            ws.onopen = () => {
+                this.state = 'open';
+                for (const handler of this.openHandlers)
+                    handler();
+                resolve();
+            };
+            ws.onmessage = (event) => {
+                this.handleMessage(event.data);
+            };
+            ws.onerror = (event) => {
+                for (const handler of this.errorHandlers)
+                    handler(event);
+                if (this.state === 'connecting') {
+                    reject(new Error('Signaling WebSocket failed to connect.'));
+                }
+            };
+            ws.onclose = (event) => {
+                this.state = 'closed';
+                this.rejectAllPending(CONNECTION_CLOSED_ERROR);
+                for (const handler of this.closeHandlers)
+                    handler(event);
+            };
+        });
+    }
+    disconnect() {
+        this.ws?.close();
+    }
+    /**
+     * Sends a correlated request and resolves/rejects when the matching
+     * {type:"response", id} arrives. Rejects with the server's `error` object
+     * when `ok:false`, and with a synthetic ProtocolError if the connection is
+     * not open or closes before a response arrives -- never silently hangs.
+     */
+    request(method, params) {
+        if (!this.ws || this.state !== 'open') {
+            return Promise.reject(NOT_CONNECTED_ERROR);
+        }
+        const id = this.generateRequestId();
+        const message = { type: 'request', id, method, params };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            try {
+                this.ws.send(JSON.stringify(message));
+            }
+            catch (err) {
+                this.pending.delete(id);
+                reject({ code: 'SEND_FAILED', message: `Failed to send request: ${String(err)}` });
+            }
+        });
+    }
+    /** Subscribes to an unsolicited server event. Returns an unsubscribe function. */
+    on(event, handler) {
+        let handlers = this.eventListeners.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.eventListeners.set(event, handlers);
+        }
+        handlers.add(handler);
+        return () => {
+            handlers.delete(handler);
+        };
+    }
+    onOpen(handler) {
+        this.openHandlers.add(handler);
+        return () => this.openHandlers.delete(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.add(handler);
+        return () => this.closeHandlers.delete(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    generateRequestId() {
+        this.nextRequestId += 1;
+        return `c-${this.nextRequestId.toString(36)}`;
+    }
+    rejectAllPending(error) {
+        for (const { reject } of this.pending.values()) {
+            reject(error);
+        }
+        this.pending.clear();
+    }
+    handleMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (err) {
+            console.error('signalingClient: received malformed JSON message', raw, err);
+            return;
+        }
+        if (message.type === 'response') {
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                console.warn(`signalingClient: response for unknown/expired request id "${message.id}"`, message);
+                return;
+            }
+            this.pending.delete(message.id);
+            if (message.ok) {
+                pending.resolve(message.result);
+            }
+            else {
+                pending.reject(message.error);
+            }
+            return;
+        }
+        if (message.type === 'event') {
+            const handlers = this.eventListeners.get(message.event);
+            if (!handlers || handlers.size === 0) {
+                // No listener registered for this event -- expected for events no
+                // currently-mounted component cares about; nothing to correlate
+                // since events never carry a request id.
+                return;
+            }
+            for (const handler of handlers) {
+                handler(message.data);
+            }
+            return;
+        }
+        console.warn('signalingClient: received message with unknown "type"', message);
+    }
+}
+//# sourceMappingURL=signaling.js.map

package/dist/signaling.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xloon/xms-client",
+  "version": "0.1.0",
+  "description": "Browser client SDK for the Xloon Media Server (XMS)",
+  "license": "Apache-2.0",
+  "keywords": [
+    "webrtc",
+    "sfu",
+    "video-conferencing",
+    "xms",
+    "xloon"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "jsdom": "^30.1.1",
+    "typescript": "~6.0.2",
+    "vitest": "^5.0.2"
+  }
+}