@agatx/serenada-core 0.6.10

package/src/SignalingProvider.ts

@@ -0,0 +1,207 @@
+import type { ParticipantConnectionStatus } from './signaling/types.js';
+
+export interface ProviderCapabilities {
+    handlesReconnection?: boolean;
+}
+
+export interface ConnectionInfo {
+    transport?: string;
+}
+
+export interface JoinOptions {
+    reconnectPeerId?: string;
+    maxParticipants?: number;
+    displayName?: string;
+    /**
+     * Host-supplied stable identity. Distinct from `peerId`/cid (which is per-call
+     * and server-issued) — lets host applications correlate a participant to
+     * their own user identity (avatar lookup, telemetry).
+     */
+    appPeerId?: string;
+}
+
+export interface SignalingProviderParticipant {
+    peerId: string;
+    joinedAt?: number;
+    displayName?: string;
+    /** Host-supplied stable identity — see {@link JoinOptions.appPeerId}. */
+    appPeerId?: string;
+    audioEnabled?: boolean;
+    videoEnabled?: boolean;
+    // Wire-reported signaling transport status. Absent = active.
+    connectionStatus?: ParticipantConnectionStatus;
+}
+
+export interface JoinedEvent {
+    peerId: string;
+    participants: SignalingProviderParticipant[];
+    hostPeerId?: string;
+    maxParticipants?: number;
+}
+
+export interface RoomStateEvent {
+    participants: SignalingProviderParticipant[];
+    hostPeerId?: string;
+    maxParticipants?: number;
+}
+
+export interface PeerEvent {
+    peerId: string;
+    joinedAt?: number;
+    displayName?: string;
+    /** Host-supplied stable identity — see {@link JoinOptions.appPeerId}. */
+    appPeerId?: string;
+}
+
+export interface PeerMessage {
+    from: string;
+    type: string;
+    payload: unknown;
+}
+
+export interface RoomEndedEvent {
+    by?: string;
+    reason: string;
+}
+
+export interface SignalingErrorEvent {
+    code: string;
+    message: string;
+}
+
+/**
+ * Server tells an active peer that a previously-suspended peer has reattached
+ * AND there was pending negotiation traffic to it during the suspension. The
+ * SDK should perform glare-safe fresh negotiation / ICE restart for the named
+ * CID. The wire payload field `with` is mapped to the explicit `withCid` here
+ * to avoid the JavaScript reserved-word association and to match the Android
+ * / iOS event shapes.
+ */
+export interface NegotiationDirtyEvent {
+    /** The CID that needs fresh renegotiation. */
+    withCid: string;
+}
+
+/** Server tells the sender it could not deliver a relay because the target had no transport. */
+export interface RelayFailedEvent {
+    /** Server-assigned reason code, e.g. `"target_suspended"`. */
+    reason: string;
+    /** Target CIDs the relay could not reach. */
+    targets: string[];
+    /** Original signaling type that failed, e.g. `"offer" | "answer" | "ice"`. */
+    of?: string;
+}
+
+export interface SignalingProviderEventMap {
+    connected: ConnectionInfo | undefined;
+    disconnected: string | undefined;
+    joined: JoinedEvent;
+    roomStateUpdated: RoomStateEvent;
+    peerJoined: PeerEvent;
+    peerLeft: PeerEvent;
+    message: PeerMessage;
+    roomEnded: RoomEndedEvent;
+    error: SignalingErrorEvent;
+    iceServersChanged: RTCIceServer[];
+    negotiationDirty: NegotiationDirtyEvent;
+    relayFailed: RelayFailedEvent;
+}
+
+export type SignalingProviderEventName = keyof SignalingProviderEventMap;
+
+export interface SignalingProvider {
+    readonly version: number;
+    readonly capabilities?: ProviderCapabilities;
+    connect(): void;
+    disconnect(): void;
+    joinRoom(roomId: string, options?: JoinOptions): void;
+    leaveRoom(): void;
+    endRoom(): void;
+    sendToPeer(peerId: string, type: string, payload: unknown): void;
+    broadcast(type: string, payload: unknown): void;
+    getIceServers(): Promise<RTCIceServer[]>;
+    /**
+     * Optional hook: install a gate that returns `false` to skip a scheduled
+     * TURN-credential refresh. Providers without periodic refresh (e.g.,
+     * loopback/test) may omit this.
+     */
+    setTurnRefreshGate?(gate: (() => Promise<boolean>) | null): void;
+    on<K extends SignalingProviderEventName>(
+        event: K,
+        cb: (data: SignalingProviderEventMap[K]) => void,
+    ): void;
+    off<K extends SignalingProviderEventName>(
+        event: K,
+        cb: (data: SignalingProviderEventMap[K]) => void,
+    ): void;
+}
+
+export class SignalingProviderEmitter implements SignalingProvider {
+    readonly version = 1;
+    readonly capabilities?: ProviderCapabilities;
+    private readonly listeners = new Map<SignalingProviderEventName, Set<(data: unknown) => void>>();
+
+    connect(): void {
+        throw new Error('Not implemented');
+    }
+
+    disconnect(): void {
+        throw new Error('Not implemented');
+    }
+
+    joinRoom(_roomId: string, _options?: JoinOptions): void {
+        throw new Error('Not implemented');
+    }
+
+    leaveRoom(): void {
+        throw new Error('Not implemented');
+    }
+
+    endRoom(): void {
+        throw new Error('Not implemented');
+    }
+
+    sendToPeer(_peerId: string, _type: string, _payload: unknown): void {
+        throw new Error('Not implemented');
+    }
+
+    broadcast(_type: string, _payload: unknown): void {
+        throw new Error('Not implemented');
+    }
+
+    async getIceServers(): Promise<RTCIceServer[]> {
+        throw new Error('Not implemented');
+    }
+
+    on<K extends SignalingProviderEventName>(
+        event: K,
+        cb: (data: SignalingProviderEventMap[K]) => void,
+    ): void {
+        let listeners = this.listeners.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(event, listeners);
+        }
+        listeners.add(cb as (data: unknown) => void);
+    }
+
+    off<K extends SignalingProviderEventName>(
+        event: K,
+        cb: (data: SignalingProviderEventMap[K]) => void,
+    ): void {
+        this.listeners.get(event)?.delete(cb as (data: unknown) => void);
+    }
+
+    protected emit<K extends SignalingProviderEventName>(
+        event: K,
+        data: SignalingProviderEventMap[K],
+    ): void {
+        const listeners = this.listeners.get(event);
+        if (!listeners) {
+            return;
+        }
+        for (const listener of listeners) {
+            listener(data);
+        }
+    }
+}

package/src/api/roomApi.ts

@@ -0,0 +1,16 @@
+import { buildApiUrl } from '../serverUrls.js';
+
+export const createRoomId = async (serverHost: string): Promise<string> => {
+    const apiUrl = buildApiUrl(serverHost, '/api/room-id');
+
+    const res = await fetch(apiUrl, { method: 'POST' });
+    if (!res.ok) {
+        throw new Error(`Room ID request failed: ${res.status}`);
+    }
+
+    const data = await res.json();
+    if (!data?.roomId) {
+        throw new Error('Room ID missing from response');
+    }
+    return data.roomId;
+};

package/src/cameraModes.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_CAMERA_MODES, type ConfigurableCameraMode, type SerenadaConfig } from './types.js';
+
+/**
+ * Resolve the configured {@link SerenadaConfig.cameraModes} list into the set
+ * of modes actually available on this platform, in the configured order.
+ * Web never supports `composite`, so it is silently dropped. `screenShare`
+ * is likewise rejected (screen sharing is controlled separately). Duplicates
+ * are dropped, preserving the first occurrence. Returning an empty array is
+ * valid and signals that video is disabled entirely.
+ */
+export function resolveCameraModes(configured: readonly ConfigurableCameraMode[] | undefined): ConfigurableCameraMode[] {
+    const source = configured ?? DEFAULT_CAMERA_MODES;
+    const seen = new Set<ConfigurableCameraMode>();
+    const result: ConfigurableCameraMode[] = [];
+    for (const mode of source) {
+        if (mode === 'composite') continue;
+        if (mode !== 'selfie' && mode !== 'world') continue;
+        if (seen.has(mode)) continue;
+        seen.add(mode);
+        result.push(mode);
+    }
+    return result;
+}
+
+/** Next mode in the cycle, or `null` if cycling is not possible. */
+export function nextCameraMode(
+    modes: readonly ConfigurableCameraMode[],
+    current: ConfigurableCameraMode,
+): ConfigurableCameraMode | null {
+    if (modes.length <= 1) return null;
+    const index = modes.indexOf(current);
+    if (index === -1) return modes[0];
+    return modes[(index + 1) % modes.length];
+}

package/src/configValidation.ts

@@ -0,0 +1,35 @@
+import type { SignalingProvider } from './SignalingProvider.js';
+import type { SerenadaConfig } from './types.js';
+
+export const SUPPORTED_SIGNALING_PROVIDER_VERSION = 1;
+
+export interface ResolvedSerenadaConfig {
+    serverHost: string | null;
+    signalingProvider: SignalingProvider | null;
+}
+
+export function resolveSerenadaConfig(config: SerenadaConfig): ResolvedSerenadaConfig {
+    const trimmedHost = typeof config.serverHost === 'string' ? config.serverHost.trim() : '';
+    const serverHost = trimmedHost.length > 0 ? trimmedHost : null;
+    const signalingProvider = config.signalingProvider ?? null;
+
+    if (serverHost && signalingProvider) {
+        throw new Error('Provide exactly one of serverHost or signalingProvider');
+    }
+    if (!serverHost && !signalingProvider) {
+        throw new Error('Provide exactly one of serverHost or signalingProvider');
+    }
+    if (signalingProvider && signalingProvider.version !== SUPPORTED_SIGNALING_PROVIDER_VERSION) {
+        throw new Error(`Unsupported signalingProvider version: ${signalingProvider.version}`);
+    }
+
+    return { serverHost, signalingProvider };
+}
+
+export function requireServerHost(config: SerenadaConfig): string {
+    const { serverHost } = resolveSerenadaConfig(config);
+    if (!serverHost) {
+        throw new Error('requires serverHost');
+    }
+    return serverHost;
+}

package/src/constants.ts

@@ -0,0 +1,77 @@
+/**
+ * Canonical WebRTC resilience constants shared across all Serenada clients.
+ * @internal
+ * @module
+ */
+
+// Signaling
+export const RECONNECT_BACKOFF_BASE_MS = 500;
+export const RECONNECT_BACKOFF_CAP_MS = 5000;
+export const CONNECT_TIMEOUT_MS = 2000;
+export const PING_INTERVAL_MS = 12000;
+export const PONG_MISS_THRESHOLD = 2;
+export const WS_FALLBACK_CONSECUTIVE_FAILURES = 3;
+
+// Join
+export const JOIN_CONNECT_KICKSTART_MS = 1200;
+export const JOIN_RECOVERY_MS = 4000;
+export const JOIN_HARD_TIMEOUT_MS = 15000;
+
+// Peer Connection
+export const OFFER_TIMEOUT_MS = 8000;
+export const ICE_RESTART_COOLDOWN_MS = 10000;
+export const NON_HOST_FALLBACK_DELAY_MS = 4000;
+export const NON_HOST_FALLBACK_MAX_ATTEMPTS = 2;
+export const ICE_CANDIDATE_BUFFER_MAX = 50;
+
+// TURN
+export const TURN_FETCH_TIMEOUT_MS = 2000;
+export const TURN_REFRESH_TRIGGER_RATIO = 0.8;
+export const ICE_FETCH_RETRY_DELAYS_MS = [0, 1000, 2000, 4000];
+
+// Session
+export const ENDING_SCREEN_MS = 3000;
+
+// Snapshot
+export const SNAPSHOT_PREPARE_TIMEOUT_MS = 2000;
+
+// Foreground / Doze recovery
+// After the app returns to foreground from background, the SDK issues a
+// synthetic ping and waits this long for a pong before force-closing the
+// transport and triggering the normal reconnect path.
+export const FOREGROUND_FORCE_PING_TIMEOUT_MS = 2000;
+
+// Post-reconnect snapshot resync
+// After signaling reconnects, the SDK waits this long for an authoritative
+// `room_state` snapshot before falling back to firing ICE restart against the
+// last-known peer map.
+export const EPOCH_RESYNC_TIMEOUT_MS = 5000;
+
+// Suspended-peer presentation
+// After a remote peer transitions to `signalingStatus="suspended"`, the SDK
+// starts a per-CID UI presentation timer. When this timer expires the
+// participant is flagged `presumedLost=true` so call UIs can move them out
+// of the active grid. The peer connection itself stays open so media can
+// resume immediately if the peer reattaches.
+export const PEER_SUSPENDED_UI_TIMEOUT_MS = 30000;
+
+// Server hard-eviction window
+// Mirrors `suspendHardEvictionTimeout` on the Go server. Used SDK-side to
+// compute `estimatedHardEvictionAtMs` for the `signalingState.suspended`
+// surface so apps can render a countdown.
+export const SUSPEND_HARD_EVICTION_TIMEOUT_MS = 600000;
+
+// Media-liveness emission cadence
+// Active SDKs broadcast `media_liveness{cids:[..]}` every interval for
+// remote CIDs whose inbound media is currently flowing. The server uses
+// this hint to defer hard-eviction of suspended peers whose media is still
+// being received. 10s leaves headroom under the server's 30s freshness
+// window (`mediaLivenessFreshnessWindow`) for missed emissions.
+export const MEDIA_LIVENESS_INTERVAL_MS = 10000;
+
+// Connection Status
+export const CONNECTION_RETRYING_DELAY_MS = 10_000;
+
+// Local Video Recovery
+export const LOCAL_VIDEO_RESUME_GAP_MS = 15_000;
+export const LOCAL_VIDEO_HEARTBEAT_INTERVAL_MS = 5_000;

package/src/formatError.ts

@@ -0,0 +1,5 @@
+/** Safely extract a human-readable message from an unknown catch-block value. */
+export function formatError(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    return String(err);
+}

package/src/iceServers.ts

@@ -0,0 +1,20 @@
+export function normalizeIceServers(iceServers: RTCIceServer[], turnsOnly: boolean): RTCIceServer[] {
+    const normalized: RTCIceServer[] = [];
+    for (const iceServer of iceServers) {
+        const urls = Array.isArray(iceServer.urls) ? iceServer.urls : [iceServer.urls];
+        const filteredUrls = urls.filter((url): url is string => {
+            if (typeof url !== 'string' || url.length === 0) {
+                return false;
+            }
+            return !turnsOnly || url.toLowerCase().startsWith('turns:');
+        });
+        if (filteredUrls.length === 0) {
+            continue;
+        }
+        normalized.push({
+            ...iceServer,
+            urls: filteredUrls,
+        });
+    }
+    return normalized;
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * @agatx/serenada-core — headless call engine.
+ * Vanilla TypeScript — no React dependency.
+ */
+export const SERENADA_CORE_VERSION = '0.6.10';
+
+// Public API
+export { SerenadaCore } from './SerenadaCore.js';
+export { SerenadaSession } from './SerenadaSession.js';
+export { SerenadaDiagnostics } from './SerenadaDiagnostics.js';
+export { RoomWatcher } from './RoomWatcher.js';
+export { SerenadaServerProvider } from './SerenadaServerProvider.js';
+export { SignalingProviderEmitter } from './SignalingProvider.js';
+
+// Factory functions (match documented API)
+import { SerenadaCore as _SerenadaCore } from './SerenadaCore.js';
+import { SerenadaDiagnostics as _SerenadaDiagnostics } from './SerenadaDiagnostics.js';
+import type { SerenadaConfig } from './types.js';
+export function createSerenadaCore(config: SerenadaConfig): _SerenadaCore { return new _SerenadaCore(config); }
+export function createSerenadaDiagnostics(config: SerenadaConfig): _SerenadaDiagnostics { return new _SerenadaDiagnostics(config); }
+
+// Public types
+export { DEFAULT_CAMERA_MODES } from './types.js';
+export type {
+    CallPhase,
+    ConnectionStatus,
+    ActiveTransport,
+    CameraMode,
+    ConfigurableCameraMode,
+    MediaCapability,
+    PeerConnectionState,
+    Participant,
+    LocalParticipant,
+    CallError,
+    CallErrorCode,
+    CallState,
+    SerenadaConfig,
+    CreateRoomResult,
+    SerenadaSessionHandle,
+    CallStats,
+    DiagnosticCheckResult,
+    DiagnosticsReport,
+    CheckOutcome,
+    ConnectivityReport,
+    IceProbeReport,
+    RoomOccupancy,
+    RoomWatcherState,
+    SerenadaLogLevel,
+    SerenadaLogger,
+} from './types.js';
+export type { RecoveryRecord } from './recoveryStorage.js';
+export type {
+    ProviderCapabilities,
+    ConnectionInfo,
+    JoinOptions,
+    SignalingProviderParticipant,
+    JoinedEvent,
+    RoomStateEvent,
+    PeerEvent,
+    PeerMessage,
+    RoomEndedEvent,
+    SignalingErrorEvent,
+    SignalingProviderEventMap,
+    SignalingProviderEventName,
+    SignalingProvider,
+} from './SignalingProvider.js';
+
+export { ConsoleSerenadaLogger } from './ConsoleLogger.js';
+
+// Public utilities
+export {
+    computeLayout, computeStageLayout, clampStageTileAspectRatio,
+    MIN_STAGE_TILE_ASPECT, MAX_STAGE_TILE_ASPECT, DEFAULT_STAGE_TILE_ASPECT, STAGE_TILE_GAP_PX,
+} from './layout/computeLayout.js';
+export type {
+    CallScene,
+    SceneParticipant,
+    ContentSource,
+    UserLayoutPrefs,
+    Insets,
+    LayoutMode,
+    FitMode,
+    LayoutResult,
+    TileLayout,
+    PipLayout,
+    Rect,
+    StageTileSpec,
+    StageTileLayout,
+    StageRowLayout,
+} from './layout/computeLayout.js';
+
+/** @internal Signaling types re-exported for advanced usage */
+export type { TransportKind } from './signaling/transports/types.js';
+/** @internal */
+export type { RoomState, SignalingMessage } from './signaling/types.js';
+/** @internal */
+export type {
+    JoinedPayload,
+    ErrorPayload,
+    TurnRefreshedPayload,
+    OfferPayload,
+    AnswerPayload,
+    IceCandidatePayload,
+} from './signaling/payloads.js';
+/** @internal */
+export {
+    parseJoinedPayload,
+    parseRoomStatePayload,
+    parseErrorPayload,
+    parseTurnRefreshedPayload,
+    parseOfferPayload,
+    parseAnswerPayload,
+    parseIceCandidatePayload,
+} from './signaling/payloads.js';
+/** @internal */
+export type { RoomStatus, RoomStatuses } from './signaling/roomStatuses.js';
+/** @internal */
+export { getRoomStatusState, mergeRoomStatusesPayload, mergeRoomStatusUpdatePayload } from './signaling/roomStatuses.js';
+/** @internal */
+export { parseTransportOrder } from './signaling/transportConfig.js';
+
+/**
+ * @internal
+ * Resilience constants
+ */
+export {
+    RECONNECT_BACKOFF_BASE_MS, RECONNECT_BACKOFF_CAP_MS,
+    CONNECT_TIMEOUT_MS, PING_INTERVAL_MS, PONG_MISS_THRESHOLD,
+    WS_FALLBACK_CONSECUTIVE_FAILURES,
+    JOIN_CONNECT_KICKSTART_MS, JOIN_RECOVERY_MS, JOIN_HARD_TIMEOUT_MS,
+    OFFER_TIMEOUT_MS, ICE_RESTART_COOLDOWN_MS,
+    NON_HOST_FALLBACK_DELAY_MS, NON_HOST_FALLBACK_MAX_ATTEMPTS,
+    ICE_CANDIDATE_BUFFER_MAX,
+    TURN_FETCH_TIMEOUT_MS, TURN_REFRESH_TRIGGER_RATIO, ICE_FETCH_RETRY_DELAYS_MS,
+    SNAPSHOT_PREPARE_TIMEOUT_MS,
+    CONNECTION_RETRYING_DELAY_MS,
+    LOCAL_VIDEO_RESUME_GAP_MS, LOCAL_VIDEO_HEARTBEAT_INTERVAL_MS,
+} from './constants.js';
+
+/** @internal Local video recovery utilities */
+export { shouldForceLocalVideoRefresh, shouldRecoverLocalVideo } from './media/localVideoRecovery.js';
+
+// Audio level monitoring (used by call UI for activity indicators)
+export { AudioLevelMonitor } from './media/AudioLevelMonitor.js';
+export type { AudioLevelMonitorOptions } from './media/AudioLevelMonitor.js';
+
+/** @internal */
+export { createRoomId } from './api/roomApi.js';
+/** @internal */
+export { buildApiUrl, buildRoomUrl, resolveServerBaseUrl, resolveServerUrls } from './serverUrls.js';
+
+/** @internal Advanced host-app usage */
+export { SignalingEngine } from './signaling/SignalingEngine.js';
+/** @internal */
+export type { SignalingEngineConfig } from './signaling/SignalingEngine.js';