@strevokit/meeting-sdk 0.0.0-stage → 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+/** Why the engine closed. */
+export declare type CloseReason = "left" | "meeting_ended" | "session_replaced" | "connection_lost" | "join_failed" | "error";
+
+/**
+ * Engine lifecycle state. `closed` is terminal: create a new engine to join again.
+ *
+ * After a recoverable meeting-service interruption while `joined`, the engine moves to `reconnecting`
+ * and attempts automatic recovery. Success returns to `joined` (same self identity; `joined` is not
+ * re-emitted). Exhaustion or hard failure moves to `closed` with `connection_lost`. Deliberate leave,
+ * meeting ended, and session replaced cancel recovery and close accordingly.
+ */
+export declare type ConnectionState = "idle" | "connecting" | "joining" | "joined" | "reconnecting" | "leaving" | "closed";
+
+/**
+ * Creates a meeting engine for one participant. Pass the join token your backend issued and the realtime
+ * service URL, then call `join()`.
+ *
+ * @throws TypeError when `realtimeUrl` or `joinTimeoutMs` is malformed.
+ * @throws MeetingError `join_token_invalid` when the token is not a valid join token, or
+ * `unsupported_environment` when the browser has no WebSocket support.
+ */
+export declare function createMeetingEngine(options: MeetingEngineOptions): MeetingEngine;
+
+/** Local captures available for rendering, such as a self-preview. `null` when that capture is off. */
+export declare interface LocalMedia {
+    readonly camera: MediaStream | null;
+    readonly microphone: MediaStream | null;
+    readonly screen: MediaStream | null;
+}
+
+/** Status of the audio and video connection to another participant. */
+export declare type MediaConnectionStatus = "connecting" | "connected" | "interrupted" | "failed";
+
+/**
+ * Which device to use for {@link MeetingEngine.enableCamera} or {@link MeetingEngine.unmute}. Omit `deviceId` to use
+ * the browser's default device.
+ */
+export declare interface MediaDeviceOptions {
+    /** A `deviceId` from `navigator.mediaDevices.enumerateDevices()`. */
+    readonly deviceId?: string;
+}
+
+/** A kind of local or remote media. */
+export declare type MediaKind = "camera" | "microphone" | "screen";
+
+/** `true` means on: camera on, microphone unmuted, screen being shared. */
+export declare interface MediaState {
+    readonly camera: boolean;
+    readonly microphone: boolean;
+    readonly screen: boolean;
+}
+
+/** A meeting session for one participant. One engine joins at most once. */
+export declare interface MeetingEngine {
+    /** Current lifecycle state. */
+    readonly state: ConnectionState;
+    /** Set once `joined` fires; `null` before. */
+    readonly self: SelfParticipant | null;
+    /** Other participants currently present (never includes self). */
+    readonly participants: readonly Participant[];
+    /** Current local media state. */
+    readonly localMediaState: MediaState;
+    /** Current local captures, for rendering. */
+    readonly localMedia: LocalMedia;
+    /** Media currently received from a participant. All fields are `null` when nothing is available. */
+    remoteMedia(participantId: string): RemoteMedia;
+    /** Status of the audio and video connection to a participant, or `null` when there is none. */
+    mediaConnectionStatus(participantId: string): MediaConnectionStatus | null;
+    /** Connect and join the meeting. Resolves once admitted and the participant list is known. */
+    join(): Promise<void>;
+    /** Leave the meeting and release every device. Never rejects. */
+    leave(): Promise<void>;
+    /** End the meeting for everyone. Only hosts may end a meeting. Resolves once the meeting has ended. */
+    endMeeting(): Promise<void>;
+    /**
+     * Start the camera. With `options.deviceId`, use that camera; when the camera is already on with another device,
+     * switch to it without turning the camera off. Rejects with `device_not_found` when the device is missing, leaving
+     * the current camera running.
+     */
+    enableCamera(options?: MediaDeviceOptions): Promise<void>;
+    /** Stop the camera and release it. */
+    disableCamera(): Promise<void>;
+    /** Mute the microphone. */
+    mute(): Promise<void>;
+    /**
+     * Unmute the microphone, capturing it on first use. With `options.deviceId`, use that microphone; when it is already
+     * unmuted with another device, switch to it without muting. Rejects with `device_not_found` when the device is
+     * missing, leaving the current microphone running.
+     */
+    unmute(options?: MediaDeviceOptions): Promise<void>;
+    /** Start sharing the screen. Only hosts may share. */
+    startScreenShare(): Promise<void>;
+    /** Stop sharing the screen. */
+    stopScreenShare(): Promise<void>;
+    /** Subscribe to one event type. Returns an unsubscribe function. */
+    on<K extends MeetingEventType>(type: K, listener: MeetingEventListener<K>): () => void;
+    /** Release everything immediately: devices, connection, listeners. Emits nothing. Idempotent. */
+    dispose(): void;
+}
+
+/** Options for {@link createMeetingEngine}. */
+export declare interface MeetingEngineOptions {
+    /** Join token issued by your backend for this participant. Kept in memory only and never logged. */
+    token: string;
+    /**
+     * Realtime service base URL, for example `wss://realtime.example.com`. `ws://` is accepted only for
+     * `localhost` and `127.0.0.1`. No path, query, or fragment.
+     */
+    realtimeUrl: string;
+    /** Milliseconds to wait for admission before `join()` rejects with `join_timeout`. Default 15000, range 1000–60000. */
+    joinTimeoutMs?: number;
+    /** Optional diagnostics sink. The SDK never passes the join token or raw exception text to it. */
+    logger?: MeetingLogger;
+    /**
+     * Optional. Called when a new meeting-service connection needs a join token and the in-memory token
+     * cannot be used. Must resolve to a server-issued join token for the same participant. Reject to fail
+     * recovery. The returned token is kept in memory only and never logged.
+     */
+    getJoinToken?: () => Promise<string>;
+    /**
+     * Optional. Continuous unsuccessful recovery budget in milliseconds. Default 120000.
+     * Values outside 1000–600000 are clamped to that range.
+     */
+    reconnectWindowMs?: number;
+}
+
+/**
+ * The single error type raised by the SDK. `message` is a short English sentence that is safe to show to users;
+ * branch on `code` rather than on `message`.
+ */
+export declare class MeetingError extends Error {
+    readonly name: "MeetingError";
+    /** Stable machine-readable code. */
+    readonly code: MeetingErrorCode;
+    /** True when retrying the same action later (with a fresh token for join errors) may succeed. */
+    readonly retryable: boolean;
+    constructor(code: MeetingErrorCode);
+}
+
+/**
+ * Every code a {@link MeetingError} can carry. Codes are stable strings; new codes may be added in minor
+ * versions, so handle unknown codes generically.
+ */
+export declare type MeetingErrorCode = "join_token_invalid" | "join_token_expired" | "origin_not_allowed" | "connection_failed" | "join_timeout" | "join_cancelled" | "connection_lost" | "session_replaced" | "service_unavailable" | "rate_limited" | "meeting_ended" | "protocol_error" | "already_joined" | "engine_closed" | "not_joined" | "not_permitted" | "permission_denied" | "device_not_found" | "device_unavailable" | "screen_share_cancelled" | "unsupported_environment" | "media_connection_failed" | "media_participant_limit";
+
+/** Listener for one event type. */
+export declare type MeetingEventListener<K extends MeetingEventType> = (event: MeetingEventMap[K]) => void;
+
+/**
+ * Payload of every event, keyed by event type. New event types may be added in minor versions, so do not
+ * treat this map as closed.
+ */
+export declare interface MeetingEventMap {
+    state_changed: {
+        readonly state: ConnectionState;
+        readonly previous: ConnectionState;
+    };
+    joined: {
+        readonly self: SelfParticipant;
+        readonly participants: readonly Participant[];
+    };
+    participant_joined: {
+        readonly participant: Participant;
+    };
+    participant_left: {
+        readonly participantId: string;
+        readonly reason: ParticipantLeftReason;
+    };
+    participant_reconnected: {
+        readonly participantId: string;
+    };
+    participant_media_changed: {
+        readonly participantId: string;
+        readonly kind: MediaKind;
+        readonly enabled: boolean;
+    };
+    local_media_changed: {
+        readonly kind: MediaKind;
+        readonly enabled: boolean;
+        readonly stream: MediaStream | null;
+    };
+    /** Media from another participant became available (`stream`) or stopped being available (`null`). */
+    remote_media_changed: {
+        readonly participantId: string;
+        readonly kind: MediaKind;
+        readonly stream: MediaStream | null;
+    };
+    /** The audio and video connection to another participant changed. `null`: there is no connection any more. */
+    media_connection_changed: {
+        readonly participantId: string;
+        readonly status: MediaConnectionStatus | null;
+    };
+    error: {
+        readonly error: MeetingError;
+    };
+    closed: {
+        readonly reason: CloseReason;
+        readonly error?: MeetingError;
+    };
+}
+
+/** Name of an engine event. */
+export declare type MeetingEventType = keyof MeetingEventMap;
+
+/** Optional diagnostics sink. Every method is optional. */
+export declare interface MeetingLogger {
+    debug?(message: string, fields?: Readonly<Record<string, string | number | boolean>>): void;
+    info?(message: string, fields?: Readonly<Record<string, string | number | boolean>>): void;
+    warn?(message: string, fields?: Readonly<Record<string, string | number | boolean>>): void;
+    error?(message: string, fields?: Readonly<Record<string, string | number | boolean>>): void;
+}
+
+/** Another participant in the meeting. */
+export declare interface Participant {
+    /** Opaque participant ID. */
+    readonly id: string;
+    readonly role: ParticipantRole;
+    readonly displayName?: string;
+    readonly media: MediaState;
+}
+
+/** Why another participant left. Unknown platform reasons are reported as `"other"`. */
+export declare type ParticipantLeftReason = "left" | "disconnected" | "removed" | "meeting_ended" | "other";
+
+/** Role assigned by the platform when the join token was issued. */
+export declare type ParticipantRole = "host" | "participant";
+
+/** Media received from another participant, for rendering. `null` when that media is not available. */
+export declare interface RemoteMedia {
+    readonly camera: MediaStream | null;
+    readonly microphone: MediaStream | null;
+    /**
+     * Live display stream while the remote participant is sharing their screen and peer media has
+     * attached it; otherwise `null`. May be non-null in ordinary one-to-one meetings.
+     */
+    readonly screen: MediaStream | null;
+}
+
+/** The participant using this engine. */
+export declare interface SelfParticipant {
+    /** Opaque participant ID. */
+    readonly id: string;
+    readonly role: ParticipantRole;
+    readonly displayName?: string;
+    /** ISO-8601 UTC timestamp from the platform. */
+    readonly joinedAt: string;
+}
+
+export { }