@agatx/serenada-core 0.6.10

package/src/signaling/payloads.ts

@@ -0,0 +1,215 @@
+import type { ParticipantContentState, ReconnectOutcome, RoomParticipant, RoomState } from './types.js';
+
+export interface JoinedPayload {
+    hostCid: string | null;
+    participants: RoomParticipant[];
+    turnToken?: string;
+    turnTokenTTLMs?: number;
+    reconnectToken?: string;
+    /**
+     * How long (ms) the server is willing to honor `reconnectToken`. SDKs
+     * that persist the token across launches should clear it once this
+     * window has elapsed.
+     */
+    reconnectTokenTTLMs?: number;
+    maxParticipants?: number;
+    /** Server-reported room state epoch. Monotonic. */
+    epoch?: number;
+    /**
+     * Disposition of this join. SDKs use this to decide whether to keep
+     * media-active peer connections (`reattached`/`recovered`) or treat the
+     * call as ground-up new (`fresh`).
+     */
+    reconnect?: ReconnectOutcome;
+}
+
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    /** Optional reason for terminal codes (e.g. ROOM_ENDED → "ended_by_host"). */
+    reason?: string;
+}
+
+/**
+ * Server tells the sender that an offer/answer/ice could not be delivered
+ * because the target was suspended. The SDK should suppress further
+ * negotiation toward those CIDs and wait for a `negotiation_dirty` message
+ * after the peer reattaches.
+ */
+export interface RelayFailedPayload {
+    reason: 'target_suspended' | (string & {});
+    targets: string[];
+    of?: string;
+}
+
+/**
+ * Server tells the sender that a previously-suspended peer has reattached
+ * AND that the sender had pending negotiation traffic to it during the
+ * suspension. The SDK should perform glare-safe fresh negotiation /
+ * ICE restart for the named CID, NOT replay the original SDP.
+ */
+export interface NegotiationDirtyPayload {
+    with: string;
+}
+
+export interface TurnRefreshedPayload {
+    turnToken: string;
+    turnTokenTTLMs?: number;
+}
+
+export interface OfferPayload {
+    from: string;
+    sdp: string;
+    timestamp?: number;
+}
+
+export interface AnswerPayload {
+    from: string;
+    sdp: string;
+}
+
+export interface IceCandidatePayload {
+    from: string;
+    candidate: RTCIceCandidateInit;
+}
+
+function parseContentState(raw: unknown): ParticipantContentState | undefined {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+    const rec = raw as Record<string, unknown>;
+    if (typeof rec.active !== 'boolean') return undefined;
+    return {
+        active: rec.active,
+        contentType: typeof rec.contentType === 'string' && rec.contentType !== '' ? rec.contentType : undefined,
+        updatedAtMs: typeof rec.updatedAtMs === 'number' ? rec.updatedAtMs : undefined,
+        epoch: typeof rec.epoch === 'number' ? rec.epoch : undefined,
+    };
+}
+
+function parseParticipants(raw: unknown): RoomParticipant[] | null {
+    if (!Array.isArray(raw)) return null;
+    const result: RoomParticipant[] = [];
+    for (const p of raw) {
+        if (!p || typeof p !== 'object' || Array.isArray(p)) continue;
+        const rec = p as Record<string, unknown>;
+        if (typeof rec.cid !== 'string' || rec.cid.trim() === '') continue;
+        result.push({
+            cid: rec.cid,
+            joinedAt: typeof rec.joinedAt === 'number' ? rec.joinedAt : undefined,
+            displayName: typeof rec.displayName === 'string' && rec.displayName.trim() !== '' ? rec.displayName : undefined,
+            peerId: typeof rec.peerId === 'string' && rec.peerId.trim() !== '' ? rec.peerId : undefined,
+            audioEnabled: typeof rec.audioEnabled === 'boolean' ? rec.audioEnabled : undefined,
+            videoEnabled: typeof rec.videoEnabled === 'boolean' ? rec.videoEnabled : undefined,
+            // Only the recognized status value is forwarded; absent/unknown
+            // is left undefined and treated as active downstream.
+            connectionStatus: rec.connectionStatus === 'suspended' ? 'suspended' : undefined,
+            contentState: parseContentState(rec.contentState),
+        });
+    }
+    return result;
+}
+
+function parseReconnectOutcome(raw: unknown): ReconnectOutcome | undefined {
+    if (raw === 'fresh' || raw === 'reattached' || raw === 'recovered') return raw;
+    return undefined;
+}
+
+export function parseJoinedPayload(raw: Record<string, unknown> | undefined): JoinedPayload | null {
+    if (!raw) return null;
+    const participants = parseParticipants(raw.participants);
+    if (!participants) return null;
+    return {
+        hostCid: typeof raw.hostCid === 'string' ? raw.hostCid : null,
+        participants,
+        turnToken: typeof raw.turnToken === 'string' ? raw.turnToken : undefined,
+        turnTokenTTLMs: typeof raw.turnTokenTTLMs === 'number' ? raw.turnTokenTTLMs : undefined,
+        reconnectToken: typeof raw.reconnectToken === 'string' ? raw.reconnectToken : undefined,
+        reconnectTokenTTLMs: typeof raw.reconnectTokenTTLMs === 'number' ? raw.reconnectTokenTTLMs : undefined,
+        maxParticipants: typeof raw.maxParticipants === 'number' ? raw.maxParticipants : undefined,
+        epoch: typeof raw.epoch === 'number' ? raw.epoch : undefined,
+        reconnect: parseReconnectOutcome(raw.reconnect),
+    };
+}
+
+export function parseRoomStatePayload(raw: Record<string, unknown> | undefined): RoomState | null {
+    if (!raw) return null;
+    const participants = parseParticipants(raw.participants);
+    if (!participants) return null;
+    return {
+        hostCid: typeof raw.hostCid === 'string' ? raw.hostCid : null,
+        participants,
+        maxParticipants: typeof raw.maxParticipants === 'number' ? raw.maxParticipants : undefined,
+        epoch: typeof raw.epoch === 'number' ? raw.epoch : undefined,
+    };
+}
+
+export function parseErrorPayload(raw: Record<string, unknown> | undefined): ErrorPayload | null {
+    if (!raw) return null;
+    if (typeof raw.message !== 'string') return null;
+    return {
+        code: typeof raw.code === 'string' ? raw.code : 'UNKNOWN',
+        message: raw.message,
+        reason: typeof raw.reason === 'string' && raw.reason !== '' ? raw.reason : undefined,
+    };
+}
+
+export function parseRelayFailedPayload(raw: Record<string, unknown> | undefined): RelayFailedPayload | null {
+    if (!raw) return null;
+    if (typeof raw.reason !== 'string') return null;
+    if (!Array.isArray(raw.targets)) return null;
+    const targets = raw.targets.filter((t): t is string => typeof t === 'string' && t !== '');
+    if (targets.length === 0) return null;
+    return {
+        reason: raw.reason as RelayFailedPayload['reason'],
+        targets,
+        of: typeof raw.of === 'string' && raw.of !== '' ? raw.of : undefined,
+    };
+}
+
+export function parseNegotiationDirtyPayload(raw: Record<string, unknown> | undefined): NegotiationDirtyPayload | null {
+    if (!raw) return null;
+    if (typeof raw.with !== 'string' || raw.with === '') return null;
+    return { with: raw.with };
+}
+
+export function parseTurnRefreshedPayload(raw: Record<string, unknown> | undefined): TurnRefreshedPayload | null {
+    if (!raw) return null;
+    if (typeof raw.turnToken !== 'string') return null;
+    return {
+        turnToken: raw.turnToken,
+        turnTokenTTLMs: typeof raw.turnTokenTTLMs === 'number' ? raw.turnTokenTTLMs : undefined,
+    };
+}
+
+export function parseOfferPayload(raw: Record<string, unknown> | undefined): OfferPayload | null {
+    if (!raw) return null;
+    if (typeof raw.from !== 'string' || raw.from === '') return null;
+    if (typeof raw.sdp !== 'string' || raw.sdp === '') return null;
+    return {
+        from: raw.from,
+        sdp: raw.sdp,
+        timestamp: typeof raw.timestamp === 'number' ? raw.timestamp : undefined,
+    };
+}
+
+export function parseAnswerPayload(raw: Record<string, unknown> | undefined): AnswerPayload | null {
+    if (!raw) return null;
+    if (typeof raw.from !== 'string' || raw.from === '') return null;
+    if (typeof raw.sdp !== 'string' || raw.sdp === '') return null;
+    return {
+        from: raw.from,
+        sdp: raw.sdp,
+    };
+}
+
+export function parseIceCandidatePayload(raw: Record<string, unknown> | undefined): IceCandidatePayload | null {
+    if (!raw) return null;
+    if (typeof raw.from !== 'string' || raw.from === '') return null;
+    const candidate = raw.candidate;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return null;
+    const candObj = candidate as Record<string, unknown>;
+    if (typeof candObj.candidate !== 'string') return null;
+    return {
+        from: raw.from,
+        candidate: candidate as RTCIceCandidateInit,
+    };
+}

package/src/signaling/roomStatuses.ts

@@ -0,0 +1,89 @@
+export type RoomStatus = {
+    count: number;
+    maxParticipants?: number;
+};
+
+export type RoomStatuses = Record<string, RoomStatus>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeMaxParticipants(value: unknown, fallback?: number): number | undefined {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 2) {
+        return value;
+    }
+    if (typeof fallback === 'number' && Number.isFinite(fallback) && fallback >= 2) {
+        return fallback;
+    }
+    return undefined;
+}
+
+function parseRoomStatus(value: unknown, fallbackMaxParticipants?: number): RoomStatus | null {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return {
+            count: value,
+            maxParticipants: normalizeMaxParticipants(fallbackMaxParticipants, 2)
+        };
+    }
+    if (!isRecord(value)) {
+        return null;
+    }
+
+    const count = value.count;
+    if (typeof count !== 'number' || !Number.isFinite(count)) {
+        return null;
+    }
+
+    return {
+        count,
+        maxParticipants: normalizeMaxParticipants(value.maxParticipants, fallbackMaxParticipants)
+    };
+}
+
+export function mergeRoomStatusesPayload(previous: RoomStatuses, payload: unknown): RoomStatuses {
+    if (!isRecord(payload)) {
+        return previous;
+    }
+
+    const next: RoomStatuses = { ...previous };
+    for (const [rid, value] of Object.entries(payload)) {
+        const status = parseRoomStatus(value, previous[rid]?.maxParticipants);
+        if (typeof rid === 'string' && status) {
+            next[rid] = status;
+        }
+    }
+    return next;
+}
+
+export function mergeRoomStatusUpdatePayload(previous: RoomStatuses, payload: unknown): RoomStatuses {
+    if (!isRecord(payload)) {
+        return previous;
+    }
+
+    const rid = payload.rid;
+    const count = payload.count;
+    if (typeof rid !== 'string' || typeof count !== 'number' || !Number.isFinite(count)) {
+        return previous;
+    }
+
+    const maxParticipants = normalizeMaxParticipants(payload.maxParticipants, previous[rid]?.maxParticipants);
+
+    return {
+        ...previous,
+        [rid]: {
+            count,
+            maxParticipants
+        }
+    };
+}
+
+export function getRoomStatusState(status?: RoomStatus | null): 'hidden' | 'waiting' | 'full' {
+    const count = status?.count ?? 0;
+    if (count <= 0) {
+        return 'hidden';
+    }
+
+    const maxParticipants = normalizeMaxParticipants(status?.maxParticipants, 2) ?? 2;
+    return count >= maxParticipants ? 'full' : 'waiting';
+}

package/src/signaling/transportConfig.ts

@@ -0,0 +1,30 @@
+import type { TransportKind } from './transports/types.js';
+
+const DEFAULT_TRANSPORTS: TransportKind[] = ['ws', 'sse'];
+
+const normalizeTransport = (value: string): TransportKind | null => {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'ws' || normalized === 'wss') return 'ws';
+    if (normalized === 'sse') return 'sse';
+    return null;
+};
+
+export const parseTransportOrder = (raw?: string | null): TransportKind[] => {
+    if (!raw) return DEFAULT_TRANSPORTS;
+
+    const parsed = raw
+        .split(',')
+        .map(normalizeTransport)
+        .filter((kind): kind is TransportKind => !!kind);
+
+    if (parsed.length === 0) return DEFAULT_TRANSPORTS;
+
+    const unique: TransportKind[] = [];
+    for (const kind of parsed) {
+        if (!unique.includes(kind)) {
+            unique.push(kind);
+        }
+    }
+
+    return unique;
+};

package/src/signaling/transports/index.ts

@@ -0,0 +1,26 @@
+import type { SerenadaLogger } from '../../types.js';
+import type { SignalingTransport, TransportHandlers, TransportKind } from './types.js';
+import { WebSocketTransport } from './ws.js';
+import { SseTransport } from './sse.js';
+
+export type { SignalingTransport, TransportHandlers, TransportKind } from './types.js';
+export { WebSocketTransport } from './ws.js';
+export { SseTransport } from './sse.js';
+
+export interface CreateTransportOptions {
+    wsUrl: string;
+    httpBaseUrl: string;
+    sseSid?: string;
+    logger?: SerenadaLogger;
+}
+
+export const createSignalingTransport = (
+    kind: TransportKind,
+    handlers: TransportHandlers,
+    options: CreateTransportOptions,
+): SignalingTransport => {
+    if (kind === 'sse') {
+        return new SseTransport(handlers, options.httpBaseUrl, { sid: options.sseSid, logger: options.logger });
+    }
+    return new WebSocketTransport(handlers, options.wsUrl, options.logger);
+};

package/src/signaling/transports/sse.ts

@@ -0,0 +1,146 @@
+import type { SerenadaLogger } from '../../types.js';
+import type { SignalingMessage } from '../types.js';
+import type { SignalingTransport, TransportHandlers, TransportKind } from './types.js';
+import { CONNECT_TIMEOUT_MS } from '../../constants.js';
+import { formatError } from '../../formatError.js';
+
+const createSid = () => {
+    if (window.crypto && window.crypto.getRandomValues) {
+        const bytes = new Uint8Array(8);
+        window.crypto.getRandomValues(bytes);
+        return `S-${Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')}`;
+    }
+    return `S-${Math.random().toString(16).slice(2, 10)}${Math.random().toString(16).slice(2, 10)}`;
+};
+
+export class SseTransport implements SignalingTransport {
+    kind: TransportKind = 'sse';
+    private es: EventSource | null = null;
+    private handlers: TransportHandlers;
+    private open = false;
+    private sid: string;
+    private sseUrl: string;
+    private connectTimeout: number | null = null;
+    private logger?: SerenadaLogger;
+
+    constructor(handlers: TransportHandlers, baseUrl: string, options?: { sid?: string; logger?: SerenadaLogger }) {
+        this.handlers = handlers;
+        this.sid = options?.sid || createSid();
+        this.sseUrl = `${baseUrl}/sse`;
+        this.logger = options?.logger;
+    }
+
+    getSessionId(): string {
+        return this.sid;
+    }
+
+    private clearConnectTimeout() {
+        if (this.connectTimeout) {
+            window.clearTimeout(this.connectTimeout);
+            this.connectTimeout = null;
+        }
+    }
+
+    private detachEventSourceHandlers(es: EventSource) {
+        es.onopen = null;
+        es.onerror = null;
+        es.onmessage = null;
+    }
+
+    connect() {
+        if (typeof EventSource === 'undefined') {
+            this.open = false;
+            this.handlers.onClose('unsupported');
+            return;
+        }
+        const url = new URL(this.sseUrl);
+        url.searchParams.set('sid', this.sid);
+        this.es = new EventSource(url.toString());
+
+        this.connectTimeout = window.setTimeout(() => {
+            if (this.es && this.es.readyState !== EventSource.OPEN) {
+                this.logger?.log('warning', 'Transport', `SSE connection timeout after ${CONNECT_TIMEOUT_MS}ms`);
+                this.es.close();
+                this.es = null;
+                this.open = false;
+                this.handlers.onClose('timeout');
+            }
+        }, CONNECT_TIMEOUT_MS);
+
+        this.es.onopen = () => {
+            this.clearConnectTimeout();
+            this.open = true;
+            this.handlers.onOpen();
+        };
+
+        this.es.onerror = (err) => {
+            if (!this.es) return;
+            if (this.es.readyState === EventSource.CLOSED) {
+                this.clearConnectTimeout();
+                this.open = false;
+                this.handlers.onClose('close', err);
+            }
+        };
+
+        this.es.onmessage = (event) => {
+            try {
+                const msg: SignalingMessage = JSON.parse(event.data);
+                this.handlers.onMessage(msg);
+            } catch (e) {
+                this.logger?.log('error', 'Transport', `Failed to parse SSE message: ${formatError(e)}`);
+            }
+        };
+    }
+
+    close() {
+        this.clearConnectTimeout();
+        const es = this.es;
+        this.es = null;
+        if (es) {
+            this.detachEventSourceHandlers(es);
+            es.close();
+        }
+        this.open = false;
+    }
+
+    forceClose(reason: string) {
+        this.clearConnectTimeout();
+        const es = this.es;
+        this.es = null;
+        if (es) {
+            this.detachEventSourceHandlers(es);
+            es.close();
+        }
+        this.open = false;
+        this.handlers.onClose(reason);
+    }
+
+    isOpen() {
+        return this.open;
+    }
+
+    send(msg: SignalingMessage) {
+        const url = new URL(this.sseUrl);
+        url.searchParams.set('sid', this.sid);
+        fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(msg)
+        })
+            .then(res => {
+                if (res.status === 410) {
+                    this.open = false;
+                    if (this.es) {
+                        this.es.close();
+                        this.es = null;
+                    }
+                    this.handlers.onClose('gone');
+                }
+            })
+            .catch(err => {
+                this.logger?.log('error', 'Transport', `Failed to send SSE message: ${formatError(err)}`);
+            });
+    }
+}

package/src/signaling/transports/types.ts

@@ -0,0 +1,19 @@
+import type { SignalingMessage } from '../types.js';
+
+export type TransportKind = 'ws' | 'sse';
+
+export type TransportHandlers = {
+    onOpen: () => void;
+    onClose: (reason: string, err?: unknown) => void;
+    onMessage: (msg: SignalingMessage) => void;
+};
+
+export interface SignalingTransport {
+    kind: TransportKind;
+    connect: () => void;
+    close: () => void;
+    forceClose?: (reason: string) => void;
+    send: (msg: SignalingMessage) => void;
+    isOpen: () => boolean;
+    getSessionId?: () => string;
+}

package/src/signaling/transports/ws.ts

@@ -0,0 +1,108 @@
+import type { SerenadaLogger } from '../../types.js';
+import type { SignalingMessage } from '../types.js';
+import type { SignalingTransport, TransportHandlers, TransportKind } from './types.js';
+import { CONNECT_TIMEOUT_MS } from '../../constants.js';
+import { formatError } from '../../formatError.js';
+
+export class WebSocketTransport implements SignalingTransport {
+    kind: TransportKind = 'ws';
+    private ws: WebSocket | null = null;
+    private handlers: TransportHandlers;
+    private open = false;
+    private connectTimeout: number | null = null;
+    private wsUrl: string;
+    private logger?: SerenadaLogger;
+
+    constructor(handlers: TransportHandlers, wsUrl: string, logger?: SerenadaLogger) {
+        this.handlers = handlers;
+        this.wsUrl = wsUrl;
+        this.logger = logger;
+    }
+
+    private clearConnectTimeout() {
+        if (this.connectTimeout) {
+            window.clearTimeout(this.connectTimeout);
+            this.connectTimeout = null;
+        }
+    }
+
+    private detachSocketHandlers(ws: WebSocket) {
+        ws.onopen = null;
+        ws.onclose = null;
+        ws.onerror = null;
+        ws.onmessage = null;
+    }
+
+    connect() {
+        this.ws = new WebSocket(this.wsUrl);
+
+        this.connectTimeout = window.setTimeout(() => {
+            if (this.ws && this.ws.readyState !== WebSocket.OPEN) {
+                this.logger?.log('warning', 'Transport', `WS connection timeout after ${CONNECT_TIMEOUT_MS}ms`);
+                this.ws.close();
+                this.open = false;
+                this.handlers.onClose('timeout');
+            }
+        }, CONNECT_TIMEOUT_MS);
+
+        this.ws.onopen = () => {
+            this.clearConnectTimeout();
+            this.open = true;
+            this.handlers.onOpen();
+        };
+
+        this.ws.onclose = (evt) => {
+            this.clearConnectTimeout();
+            this.open = false;
+            this.handlers.onClose('close', evt);
+        };
+
+        this.ws.onerror = (err) => {
+            this.clearConnectTimeout();
+            this.open = false;
+            this.handlers.onClose('error', err);
+        };
+
+        this.ws.onmessage = (event) => {
+            try {
+                const msg: SignalingMessage = JSON.parse(event.data);
+                this.handlers.onMessage(msg);
+            } catch (e) {
+                this.logger?.log('error', 'Transport', `Failed to parse WS message: ${formatError(e)}`);
+            }
+        };
+    }
+
+    close() {
+        this.clearConnectTimeout();
+        const ws = this.ws;
+        this.ws = null;
+        if (ws) {
+            this.detachSocketHandlers(ws);
+            ws.close();
+        }
+        this.open = false;
+    }
+
+    forceClose(reason: string) {
+        this.clearConnectTimeout();
+        const ws = this.ws;
+        this.ws = null;
+        if (ws) {
+            this.detachSocketHandlers(ws);
+            ws.close();
+        }
+        this.open = false;
+        this.handlers.onClose(reason);
+    }
+
+    isOpen() {
+        return !!this.ws && this.open && this.ws.readyState === WebSocket.OPEN;
+    }
+
+    send(msg: SignalingMessage) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+}