@signalling/sdk 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,1568 @@
+/**
+ * Public types for `@signalling/sdk`.
+ *
+ * Every type in this file maps to a wire-protocol artefact on the
+ * signalling HTTP / WebSocket API. Keep field names aligned with the
+ * server’s JSON contracts. See `docs/` in this package for integration
+ * context.
+ */
+/**
+ * Authentication mode the SDK will use.
+ *
+ * - `bff` — Browser-for-frontend cookie flow. The backend holds Keycloak
+ *   tokens; the browser only carries an opaque `session_id` cookie + a
+ *   per-request DPoP proof. This is the default and only fully supported
+ *   mode in v1.
+ * - `bearer` — Native client style: the integrator already owns an OIDC
+ *   access token and provides it via the `getAccessToken` callback. The
+ *   SDK adds the `Authorization: DPoP <jwt>` header and binds the proof
+ *   via the `ath` claim. Reserved for a later milestone.
+ */
+type AuthMode = 'bff' | 'bearer';
+/**
+ * Severity passed to a logger. Order matches RFC-style log levels.
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Optional structured logger hook. The SDK never writes to `console`
+ * directly; it always goes through this interface so integrators can
+ * pipe logs into their own observability stack.
+ */
+interface Logger {
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+/**
+ * Configuration object passed to `SignallingSDK.create()`.
+ *
+ * @example
+ * ```ts
+ * const sdk = await SignallingSDK.create({
+ *   baseUrl: "https://api.example.com",
+ *   authMode: "bff",
+ *   appId:   "customer-app-123",
+ *   logLevel: "info",
+ * });
+ * ```
+ */
+interface SignallingSDKConfig {
+    /**
+     * Fully-qualified scheme + host of the backend (e.g. `https://api.confrnce.io`).
+     * Trailing slash is normalised away. The SDK derives WebSocket URLs by
+     * swapping `http` → `ws` / `https` → `wss` on this value.
+     */
+    baseUrl: string;
+    /**
+     * Optional tenant / application identifier. Sent to the backend on
+     * select endpoints when present; reserved for the multi-tenant rollout.
+     */
+    appId?: string;
+    /**
+     * Auth mode. Defaults to `bff`.
+     */
+    authMode?: AuthMode;
+    /**
+     * Bearer-mode hook. Required when `authMode === 'bearer'`; ignored
+     * otherwise. Must return a fresh OIDC access token (refresh-rotated
+     * by the integrator).
+     */
+    getAccessToken?: () => Promise<string>;
+    /**
+     * Override the global `fetch`. Useful for tests / SSR / polyfilled
+     * runtimes. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Custom logger. Defaults to a console-backed logger gated by `logLevel`.
+     */
+    logger?: Logger;
+    /**
+     * Minimum log level emitted by the default logger. Ignored when a
+     * custom `logger` is provided. Defaults to `'warn'`.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Convenience flag: `true` is shorthand for `logLevel: 'debug'`.
+     * Setting both — `logLevel` wins.
+     */
+    debug?: boolean;
+}
+/**
+ * Lifecycle status of a user account. Mirrors `models.UserStatus` in the
+ * backend (`backend/models/user.go`) — values are emitted UPPERCASE on the
+ * wire. Keycloak owns the authentication state; this enum is the app-level
+ * status used for bans / suspensions / soft-delete that shouldn't round-trip
+ * through Keycloak.
+ */
+type UserStatus = 'ACTIVE' | 'PENDING_VERIFICATION' | 'SUSPENDED' | 'BANNED' | 'DELETED';
+/**
+ * A user record as returned by `GET /me` and `GET /users/search`.
+ * Mirrors the JSON projection of `backend/models/user.go::User` — fields
+ * marked `json:"-"` on the Go struct (`ID`, `KeycloakSubjectID`) are
+ * intentionally NOT present on the wire and are NOT modeled here.
+ */
+interface UserProfile {
+    username: string;
+    firstName: string;
+    lastName?: string | null;
+    email?: string | null;
+    emailVerified?: boolean;
+    phone?: string | null;
+    phoneVerified?: boolean;
+    avatarUrl?: string | null;
+    status?: UserStatus;
+    statusReason?: string | null;
+    isStaff?: boolean;
+    lastLoginAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * A connected client (one per browser tab / device) as embedded inside
+ * `models.Room.Clients`. Mirrors the JSON projection of
+ * `backend/models/client.go::Client` — `UserID` is `json:"-"` on the Go
+ * struct and is NOT exposed on the wire (look up via `user.username`
+ * instead).
+ *
+ * `roomId` is the snowflake id rendered as a string at this layer (see
+ * note on `Room.id`).
+ */
+interface RoomClient {
+    clientId: string;
+    roomId: string;
+    user?: UserProfile;
+    joinedAt?: string;
+}
+/**
+ * Room as returned by `GET /viewroom/{roomId}`.
+ * Mirrors the JSON projection of `backend/models/room.go::Room`.
+ *
+ * NOTE on `id`: the backend serializes the snowflake id as a JSON number
+ * (`int64`). JavaScript's `number` cannot represent integers above 2^53
+ * losslessly, so the SDK normalises the snowflake to `string` at the API
+ * boundary. Treat the value as opaque; never do arithmetic on it. (A
+ * future revision may switch to `bigint` once we add a json-bigint
+ * dependency — until then the string normalisation matches the
+ * conventional workaround used by every JS consumer of this API.)
+ */
+interface Room {
+    id: string;
+    status: string;
+    host?: UserProfile;
+    currentScreenSharerClientId?: string;
+    clients: RoomClient[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Response of `POST /createroom` and `POST /joinroom/{roomId}`.
+ * The SDK keeps these as separate types — the backend does too — even
+ * though their shapes coincide today.
+ *
+ * `roomId` is normalised to `string` at the API boundary; see the note on
+ * `Room.id`.
+ */
+interface CreateRoomResponse {
+    roomId: string;
+    clientId: string;
+}
+interface JoinRoomResponse {
+    roomId: string;
+    clientId: string;
+}
+/**
+ * Response of `POST /v1/turn/credentials`.
+ * Mirrors `nat/internal/turn::TurnCredential` and the wire-protocol doc
+ * at `docs/wire-protocol-turn-credentials.md`.
+ */
+interface TurnCredential {
+    username: string;
+    credential: string;
+    urls: string[];
+    ttl: number;
+}
+/**
+ * Response of `POST /auth/ws-ticket`.
+ */
+interface WSTicket {
+    ticket: string;
+    nonce: string;
+    expiresIn: number;
+}
+/**
+ * Response of `GET /room/{roomId}/{clientId}/permissions`
+ * and `PUT` of the same path.
+ *
+ * `roomId` is normalised to `string` at the API boundary; see the note
+ * on `Room.id`.
+ */
+interface ClientPermissions {
+    roomId: string;
+    clientId: string;
+    canAudio: boolean;
+    canVideo: boolean;
+    canScreenShare: boolean;
+}
+/**
+ * Body of `PATCH /me`.
+ */
+interface UpdateProfileRequest {
+    firstName?: string;
+    lastName?: string;
+    avatarUrl?: string;
+    phone?: string;
+    username?: string;
+}
+/**
+ * Wire envelope for room WebSocket messages.
+ * Mirrors `backend/websocket/hub.go::WSMessage`.
+ *
+ * `payload` is intentionally `unknown` — message-type-specific shapes
+ * live below as discriminated unions when emitted as events.
+ */
+interface WSMessage<TPayload = unknown> {
+    type: string;
+    from: string;
+    to: string;
+    payload: TPayload;
+}
+/**
+ * Server-originated signal payload (`type: 'signal'`, `from: 'server'`).
+ * The `action` field discriminates between concrete events the backend
+ * emits today. The taxonomy of "server signals" is kept distinct from
+ * "peer signals" because the trust model differs — server signals are
+ * authoritative; peer signals are anything one client decides to send
+ * through the relay.
+ */
+type ServerSignalPayload = {
+    action: 'join';
+    newClientId: string;
+    newClientName?: string;
+    newClientAvatar?: string;
+} | {
+    action: 'leave';
+    leftClientId: string;
+    leftClientName?: string;
+} | {
+    action: 'hostChanged';
+    newHostId: string;
+} | {
+    action: 'stopScreenShare';
+} | {
+    action: 'permissionsUpdated';
+    canAudio: boolean;
+    canVideo: boolean;
+    canScreenShare: boolean;
+};
+/**
+ * Peer-originated signal payload (`type: 'signal'`, `from: <clientId>`).
+ * These ride the same `signal` envelope as server signals but are emitted
+ * by other clients in the room, NOT the backend. Receivers should validate
+ * fields and never assume authority — a malicious peer could craft any of
+ * these.
+ *
+ *  - `mediaState` is broadcast on local mic/cam toggle and tracked per
+ *     peer so other UIs can render mute/camera-off indicators.
+ *  - `mediaStopped` is broadcast when a peer ends all local media (camera
+ *     and screen share) — the receiver tears down both streams.
+ *  - `screenShareStream` announces the `MediaStream.id` the sender is about
+ *     to send so the receiver can route the resulting track to a separate
+ *     "screen share" surface instead of treating it as camera.
+ *  - `screenShareStopped` mirrors `screenShareStream` on the teardown side.
+ *  - `chat` is the room-WS chat message (auto-broadcast by `Call.sendChat`).
+ */
+type PeerSignalPayload = {
+    action: 'mediaState';
+    video: boolean;
+    audio: boolean;
+} | {
+    action: 'mediaStopped';
+} | {
+    action: 'screenShareStream';
+    streamId: string;
+} | {
+    action: 'screenShareStopped';
+    streamId: string;
+} | {
+    action: 'chat';
+    id: string;
+    fromName: string;
+    text: string;
+    timestamp: string;
+};
+/**
+ * SDP payload — used in `type: 'sdp'` and SFU-mode `sfu-offer` / `sfu-answer`
+ * messages. Mirrors `backend/sfu::SDPPayload`.
+ */
+interface SdpPayload {
+    type: 'offer' | 'answer';
+    sdp: string;
+}
+/**
+ * ICE candidate payload — used in `type: 'ice'` and SFU-mode `sfu-ice`
+ * messages. Matches the JSON serialisation produced by
+ * `RTCPeerConnection.onicecandidate`.
+ */
+interface IceCandidatePayload {
+    candidate: string;
+    sdpMid?: string | null;
+    sdpMLineIndex?: number | null;
+    usernameFragment?: string | null;
+}
+/**
+ * Constraints accepted by `SignallingSDK.calls.joinRoom`. The SDK
+ * forwards them to `getUserMedia` after acquiring the local stream.
+ */
+interface MediaConstraints {
+    audio?: boolean | MediaTrackConstraints;
+    video?: boolean | MediaTrackConstraints;
+}
+/**
+ * Configuration accepted by `sdk.calls.joinRoom`.
+ */
+interface CallConfig {
+    /** Snowflake room id returned by `sdk.rooms.create()` or shared out-of-band. */
+    roomId: number | string;
+    /** Local media constraints. Omit to skip `getUserMedia` (e.g. listen-only). */
+    media?: MediaConstraints;
+    /**
+     * If true the SDK will attempt to join the room's SFU pipeline by
+     * sending `sfu-join` after the WS handshake. Defaults to `false`
+     * (peer-to-peer / mesh mode).
+     */
+    useSfu?: boolean;
+}
+/**
+ * A single chat message delivered over the room WebSocket. Created by
+ * `Call.sendChat` on the sender and emitted as the `'chat'` event on
+ * each receiver. `id` is generated by the sender; `fromName` is filled
+ * in from the cached user profile when present (falls back to clientId).
+ */
+interface ChatMessage {
+    id: string;
+    from: string;
+    fromName: string;
+    text: string;
+    timestamp: string;
+}
+/**
+ * Per-peer media on/off state. Reflects the most recent `mediaState`
+ * signal seen from that peer; an absent entry means the peer has not
+ * yet announced its state and SHOULD be treated as `{ video: true,
+ * audio: true }` (the implicit default for newly-joined clients).
+ */
+interface PeerMediaState {
+    video: boolean;
+    audio: boolean;
+}
+/**
+ * Strongly-typed event map emitted by the room `Call` object returned
+ * by `sdk.calls.joinRoom`.
+ */
+interface CallEventMap {
+    /** A new peer joined the room. */
+    'peer.joined': {
+        clientId: string;
+        name?: string;
+        avatarUrl?: string;
+    };
+    /** A peer left the room (intentionally or via disconnect). */
+    'peer.left': {
+        clientId: string;
+        name?: string;
+    };
+    /** The room host changed (the original host left). */
+    'host.changed': {
+        newHostClientId: string;
+    };
+    /** The server told us we are no longer the active screen-sharer. */
+    'screen-share.stop': void;
+    /** The host updated our media permissions. */
+    'permissions.updated': Omit<ClientPermissions, 'roomId' | 'clientId'>;
+    /** Remote camera `MediaStream` arrived from a peer. Fired once per peer. */
+    'stream.added': {
+        clientId: string;
+        stream: MediaStream;
+    };
+    /** Remote peer's camera `MediaStream` is gone. */
+    'stream.removed': {
+        clientId: string;
+    };
+    /** Remote peer started screen sharing — emitted distinct from `stream.added`. */
+    'screen-share.added': {
+        clientId: string;
+        stream: MediaStream;
+    };
+    /** Remote peer stopped screen sharing. */
+    'screen-share.removed': {
+        clientId: string;
+    };
+    /** Peer's mic/camera enable state changed (via their `mediaState` broadcast). */
+    'peer.media-state-changed': {
+        clientId: string;
+        state: PeerMediaState;
+    };
+    /** Peer ended all media (camera + screen share) but is still in the room. */
+    'peer.media-stopped': {
+        clientId: string;
+    };
+    /** A chat message arrived (room WS signal with `action: 'chat'`). */
+    'chat': ChatMessage;
+    /**
+     * Underlying WebSocket closed. `fatal === true` when the close code is
+     * one the SDK will NOT auto-retry (auth failed, room/client missing,
+     * DPoP replay, etc.) — UIs should render an end-of-session state
+     * rather than a spinner. See `WSCloseCode` and the `NO_RETRY_CODES`
+     * set in `WebSocketClient`.
+     */
+    'connection.closed': {
+        code: number;
+        reason: string;
+        fatal: boolean;
+    };
+    /** Underlying WebSocket reconnected after a transient drop. */
+    'connection.reopened': void;
+    /** Catch-all for anything we don't model — useful for debugging. */
+    'raw': WSMessage;
+}
+/**
+ * A confirmed friend, as returned by `sdk.friends.list()` and embedded
+ * in `'friend.added'` events. Mirrors the JSON projection emitted by
+ * the global WS `friend_list` response — `{friendshipId, username,
+ * isOnline}`.
+ *
+ * The backend addresses peers by **username** (not user id) on the
+ * global WS — internal numeric ids are never on the wire. Pass
+ * `username` back as the `to` field of any outbound frame.
+ */
+interface Friend {
+    friendshipId: string;
+    /** Peer's public username — the addressing handle for global-WS frames. */
+    username: string;
+    isOnline: boolean;
+}
+/**
+ * A pending incoming friend request. Returned by `sdk.friends.pending()`
+ * and emitted as the payload of `'friend.request-received'` events.
+ * `requester` is the requesting peer's username.
+ */
+interface PendingFriendRequest {
+    friendshipId: string;
+    requester: string;
+    createdAt: string;
+}
+/**
+ * Strongly-typed event map emitted by `sdk.friends` (and the call-invite
+ * surface on `sdk.calls`). Friends maintain a stateful cache inside the
+ * SDK; events fire whenever that cache changes.
+ */
+interface FriendsEventMap {
+    /** Cached friends list changed (after refresh, accept, remove, etc.). */
+    'friends.changed': {
+        friends: Friend[];
+    };
+    /** A new incoming friend request landed in the pending bucket. */
+    'friend.request-received': PendingFriendRequest;
+    /** Pending requests cache changed (after refresh, accept, reject, etc.). */
+    'friends.pending-changed': {
+        pending: PendingFriendRequest[];
+    };
+    /** A friend we previously requested has accepted us — they're now in `friends`. */
+    'friend.added': Friend;
+    /** A friend was removed (either side). */
+    'friend.removed': {
+        friendshipId: string;
+    };
+    /** Backend reported an error processing one of our frames. */
+    'friends.error': {
+        originalType: string;
+        error: string;
+    };
+}
+/**
+ * An incoming room invitation from a friend. Emitted by `sdk.calls` when
+ * the global WS receives a `call_invite` frame addressed to us.
+ */
+interface IncomingCallInvite {
+    /** Username of the inviter (the public handle the backend addresses peers by). */
+    callerUsername: string;
+    /** The room id the inviter wants us to join (string-normalised snowflake). */
+    roomId: string;
+}
+/**
+ * Event map for the call-invite surface exposed on `sdk.calls`.
+ */
+interface CallInviteEventMap {
+    'call.invite-received': IncomingCallInvite;
+}
+/**
+ * Thrown by `ApiClient` when the backend returns a non-2xx status.
+ * The original `Response` is preserved for callers who need to inspect
+ * headers (e.g. to read the new `DPoP-Nonce`).
+ */
+declare class SignallingApiError extends Error {
+    /** HTTP status code returned by the backend. */
+    readonly status: number;
+    /** Stable, machine-readable error code (matches `ErrorResponse.code`). */
+    readonly code?: string;
+    /** Field name when this is a validation error. */
+    readonly field?: string;
+    /** Raw response body, parsed as JSON when possible. */
+    readonly body: unknown;
+    /** Original `Response` for advanced callers. */
+    readonly response: Response;
+    constructor(message: string, response: Response, body: unknown);
+}
+/**
+ * Thrown by `WebSocketClient` when the WS upgrade or DPoP first-frame
+ * handshake fails.
+ */
+declare class SignallingWebSocketError extends Error {
+    /** Application close code (4400-4409 for DPoP, 4xxx-domain for room checks). */
+    readonly code?: number;
+    constructor(message: string, code?: number);
+}
+
+/**
+ * `DPoPManager` owns the lifetime of the device's signing key plus a
+ * single nonce cache. It is meant to be instantiated exactly once per
+ * `SignallingSDK` instance.
+ */
+declare class DPoPManager {
+    private keypair;
+    private cachedJWK;
+    private readonly nonces;
+    private initPromise;
+    /**
+     * Eagerly load (or create) the keypair. Safe to call multiple times —
+     * concurrent callers all wait on the same `Promise`. Recommended at
+     * SDK boot so the first authed request doesn't pay the keygen cost.
+     */
+    init(): Promise<void>;
+    private loadOrGenerate;
+    /**
+     * Build a DPoP proof JWS for the given request.
+     *
+     * @param method   HTTP verb in upper-case (`GET`, `POST`, ...).
+     *                 For WS upgrades pass `GET`.
+     * @param url      Full URL **including** query for HTTP requests, or
+     *                 with the query stripped for WebSocket upgrades.
+     *                 The caller should pre-canonicalise — `htu` must
+     *                 byte-match the URL the server reconstructs.
+     * @param accessTokenHash Optional `ath` claim — `b64url(SHA256(token))`.
+     *                 Required in bearer (mobile) flows; omitted in BFF.
+     */
+    generateProof(method: string, url: string, accessTokenHash?: string): Promise<string>;
+    /**
+     * Update the cached nonce after every backend response. Pass the
+     * `Headers` object (or anything with `get`) — `null` is a no-op.
+     */
+    updateNonceFromResponse(headers: Headers | {
+        get: (n: string) => string | null;
+    }): void;
+    /**
+     * Manually set the cached nonce. Used by `WebSocketClient` after it
+     * extracts the WS-ticket-embedded nonce.
+     */
+    setNonce(nonce: string | null | undefined): void;
+    /**
+     * Drop both the cached nonce and the persisted keypair. The integrator
+     * should call this on logout to ensure the next login binds a fresh key.
+     */
+    reset(): Promise<void>;
+    /**
+     * Compute the SHA-256 base64url-encoded thumbprint of the OAuth
+     * access token, suitable for use as the `ath` claim on bearer flows.
+     */
+    static accessTokenHash(token: string): Promise<string>;
+}
+
+/**
+ * `ApiClient` is the SDK's REST surface over the signalling HTTP API.
+ *
+ * Every method maps 1:1 onto a documented backend route. The class only knows about
+ * HTTP — nothing in here is aware of rooms, peers, or media.
+ *
+ * Three things differ from a vanilla `fetch`:
+ *
+ *  1. **DPoP injection.** Every authenticated request carries a fresh
+ *     `DPoP: <jws>` header generated by `DPoPManager`. Bearer flows
+ *     also pull an access token from the integrator's callback and add
+ *     `Authorization: DPoP <token>` plus the `ath` claim.
+ *
+ *  2. **Nonce retry.** When the backend responds with `401` and the body
+ *     code is `use_dpop_nonce`, the new `DPoP-Nonce` header is cached
+ *     and the request is retried exactly once. Anything else is
+ *     surfaced as a `SignallingApiError`.
+ *
+ *  3. **Cookie inclusion.** BFF mode sets `credentials: 'include'` so
+ *     the opaque `session_id` cookie travels with every request.
+ *
+ * The auth / DPoP threat model is summarized in `docs/auth.md`.
+ */
+declare class ApiClient {
+    private readonly dpop;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly logger;
+    private readonly authMode;
+    private readonly getAccessToken?;
+    constructor(config: SignallingSDKConfig, dpop: DPoPManager, logger: Logger);
+    /** Absolute URL the SDK uses for a relative path. Exposed for WS/auth code. */
+    url(path: string): string;
+    /** Backend base URL (origin only, no trailing slash). */
+    get origin(): string;
+    /**
+     * `POST /auth/dpop/bind` — completes the DPoP bind step. The backend
+     * consumes the `bind_token`, materialises the session row, and sets
+     * the `session_id` cookie on the response. Returns the `return_to`
+     * URL the integrator originally requested (or empty string if none).
+     *
+     * Called by `AuthClient.completeBind`.
+     */
+    dpopBind(bindToken: string): Promise<{
+        returnTo: string;
+    }>;
+    /** `GET /me` — returns the authenticated user's profile. */
+    getCurrentUser(): Promise<UserProfile>;
+    /** `PATCH /me` — partial profile update. */
+    updateProfile(updates: UpdateProfileRequest): Promise<UserProfile>;
+    /** `POST /auth/logout` — revokes the current session at Keycloak + locally. */
+    logout(): Promise<void>;
+    /** `POST /auth/logout-all` — revokes every session for this user. */
+    logoutAll(): Promise<void>;
+    /** `POST /auth/ws-ticket` — short-lived JWT to open a WebSocket. */
+    issueWSTicket(): Promise<WSTicket>;
+    /** `GET /users/search?email=...` — looks up a user by email. */
+    searchUserByEmail(email: string): Promise<UserProfile>;
+    /**
+     * `POST /createroom` — creates a new room and host client.
+     *
+     * The backend serializes `roomId` as a JSON number (`int64`); we
+     * stringify it at the boundary so the snowflake survives the
+     * `JSON.parse` → `number` round-trip. See the note on `Room.id` in
+     * the types file. The stringification happens AFTER `JSON.parse`,
+     * so values above 2^53 have already lost precision — matching the
+     * conventional JS workaround; a future revision will switch to a
+     * BigInt-aware parser.
+     */
+    createRoom(): Promise<CreateRoomResponse>;
+    /** `POST /joinroom/{roomId}` — joins an existing room as a new client. */
+    joinRoom(roomId: number | string): Promise<JoinRoomResponse>;
+    /** `GET /viewroom/{roomId}` — returns full room state with participants. */
+    viewRoom(roomId: number | string): Promise<Room>;
+    /** `DELETE /leaveroom/{roomId}/{clientId}` — leaves the room. */
+    leaveRoom(roomId: number | string, clientId: string): Promise<void>;
+    /** `POST /room/{roomId}/{clientId}/screen-share/start` */
+    startScreenShare(roomId: number | string, clientId: string): Promise<{
+        status: string;
+        previousSharer?: string;
+    }>;
+    /** `POST /room/{roomId}/{clientId}/screen-share/stop` */
+    stopScreenShare(roomId: number | string, clientId: string): Promise<{
+        status: string;
+    }>;
+    /** `GET /room/{roomId}/{clientId}/permissions` */
+    getPermissions(roomId: number | string, clientId: string): Promise<ClientPermissions>;
+    /** `PUT /room/{roomId}/{clientId}/permissions` (host-only). */
+    updatePermissions(roomId: number | string, clientId: string, updates: Partial<Pick<ClientPermissions, 'canAudio' | 'canVideo' | 'canScreenShare'>>): Promise<ClientPermissions>;
+    /** `POST /v1/turn/credentials` — fresh, tenant-scoped STUN/TURN credentials. */
+    getTurnCredentials(ttlSeconds?: number): Promise<TurnCredential>;
+    private request;
+}
+
+/**
+ * Tiny strongly-typed event emitter used by `RoomManager`, `WebRTCManager`,
+ * and the `Call` object returned by `sdk.calls.joinRoom`. Kept in `internal/`
+ * so we can swap implementations without breaking the public API.
+ *
+ * `TEventMap` is intentionally typed with a loose constraint — concrete
+ * event maps (`CallEventMap`, `WebRTCEventMap`) are *closed* interfaces
+ * (no string-index signature) and TypeScript would reject them under
+ * `extends Record<string, unknown>`. Per-method generics give callers
+ * full type-safety where it matters.
+ */
+type Listener<T> = (payload: T) => void;
+declare class TypedEventEmitter<TEventMap extends Record<string, any>> {
+    private listeners;
+    on<K extends keyof TEventMap>(event: K, fn: Listener<TEventMap[K]>): () => void;
+    off<K extends keyof TEventMap>(event: K, fn: Listener<TEventMap[K]>): void;
+    once<K extends keyof TEventMap>(event: K, fn: Listener<TEventMap[K]>): void;
+    /** @internal — used only by the SDK itself, not part of the public API. */
+    emit<K extends keyof TEventMap>(event: K, payload: TEventMap[K]): void;
+    /** Remove every listener (e.g. on disconnect / SDK teardown). */
+    clear(): void;
+}
+
+/**
+ * Events emitted by `AuthClient`.
+ */
+interface AuthEventMap {
+    /** `getCurrentUser` succeeded — payload is the resolved user. */
+    'state.authenticated': UserProfile;
+    /** `getCurrentUser` returned 401 — payload is the original error. */
+    'state.unauthenticated': SignallingApiError | null;
+    /** `logout` / `logoutAll` finished. */
+    'state.signed-out': void;
+}
+/**
+ * `AuthClient` orchestrates the BFF authentication flow (see `docs/auth.md`).
+ * The flow looks like this in a
+ * browser:
+ *
+ *   1. SDK consumer calls `auth.login()` — the user is redirected to
+ *      `${baseUrl}/auth/login` which handles PKCE + Keycloak.
+ *   2. Keycloak redirects back via `${baseUrl}/auth/callback`, which
+ *      writes a 60-second `bind_ticket` and redirects the browser to
+ *      `${frontendOrigin}/auth/complete#bind_token=…`.
+ *   3. The SPA's `/auth/complete` page calls `auth.completeBind(token)`
+ *      which generates / loads the DPoP keypair and POSTs
+ *      `/auth/dpop/bind` to materialise the session cookie.
+ *   4. From then on every authenticated call carries the session cookie
+ *      and a fresh DPoP proof, both transparently injected by `ApiClient`.
+ *
+ * The same SDK works in the bearer / mobile flow if the integrator
+ * configures `authMode: 'bearer'` and supplies `getAccessToken`.
+ */
+declare class AuthClient extends TypedEventEmitter<AuthEventMap> {
+    private readonly config;
+    private readonly api;
+    private readonly dpop;
+    private readonly logger;
+    private cachedUser;
+    constructor(config: SignallingSDKConfig, api: ApiClient, dpop: DPoPManager, logger: Logger);
+    /**
+     * Synchronous accessor for the cached user profile. Returns `null`
+     * until `getCurrentUser()` has resolved at least once. Used by
+     * downstream modules (`Call.sendChat`, friends UI) that need the
+     * display name without paying the round-trip latency of a fresh
+     * fetch.
+     */
+    get cachedCurrentUser(): UserProfile | null;
+    /**
+     * BFF login — navigates the user to the backend's OIDC entry point.
+     * Optionally accepts a `returnTo` URL the backend will append as a
+     * query parameter; the backend validates this against the configured
+     * allowed origins.
+     *
+     * Bearer mode does not use this method — the integrator runs OIDC +
+     * PKCE themselves on the native side.
+     */
+    login(returnTo?: string): void;
+    /**
+     * Read the bind token from the current URL fragment (the format
+     * Keycloak's callback produces: `/auth/complete#bind_token=…`). Useful
+     * shortcut so SPAs can call:
+     *
+     * ```ts
+     * const token = sdk.auth.bindTokenFromFragment();
+     * if (token) await sdk.auth.completeBind(token);
+     * ```
+     */
+    bindTokenFromFragment(fragment?: string): string | null;
+    /**
+     * Complete the DPoP bind step. Generates a keypair (if needed) and
+     * POSTs the bind ticket to `/auth/dpop/bind`. On success the backend
+     * sets a `session_id` cookie and returns the `return_to` URL the
+     * integrator originally requested.
+     *
+     * **Multi-tab safety.** The whole bind transaction (keypair lookup +
+     * POST + ticket consume) is serialised through the Web Locks API
+     * under the name `signalling-sdk-dpop-bind-flow`. Without this, two
+     * tabs that both navigate to the bind landing page race the bind
+     * ticket — only one wins, the other gets `bind_ticket_consumed`. The
+     * lock uses a distinct name from the keypair-generation lock inside
+     * `DPoPManager` because Web Locks are NOT reentrant within a single
+     * client (reusing the same name would deadlock).
+     *
+     * **Nonce churn.** The backend may respond with one of three nonce
+     * challenge codes (`use_dpop_nonce`, `invalid_nonce`, `expired_nonce`)
+     * before accepting the request. `ApiClient.request` retries
+     * automatically on all three.
+     *
+     * **Failure recovery.** On a non-recoverable bind failure the SDK
+     * resets the DPoP key state (clears the IndexedDB keypair and nonce
+     * cache) so the next attempt generates fresh material — matching the
+     * behaviour the desktop's hand-rolled `/auth/complete` page used to
+     * implement. The original error is re-thrown either way.
+     */
+    completeBind(bindToken: string): Promise<{
+        returnTo: string;
+    }>;
+    /**
+     * Resolve the currently signed-in user. Returns `null` when the
+     * session is missing or expired. Caches the result so multiple
+     * components can call it without thrashing the backend.
+     */
+    getCurrentUser(force?: boolean): Promise<UserProfile | null>;
+    /** Convenience boolean wrapper around `getCurrentUser`. */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * `PATCH /me` — partial profile update. The cached `currentUser` is
+     * refreshed in place and `state.authenticated` is re-emitted so any
+     * React provider listening to that event re-renders the new profile
+     * without an extra round-trip. The semantic is "the canonical user
+     * just changed; here it is" — exactly what `state.authenticated`
+     * means, so we reuse it instead of inventing a new event.
+     */
+    updateProfile(updates: UpdateProfileRequest): Promise<UserProfile>;
+    /** `POST /auth/logout` — single-device sign-out. */
+    logout(): Promise<void>;
+    /** `POST /auth/logout-all` — sign out everywhere. */
+    logoutAll(): Promise<void>;
+    /**
+     * Navigate to Keycloak's account console (change password,
+     * manage MFA, view active sessions). BFF-only.
+     */
+    openAccountConsole(): void;
+    private afterSignOut;
+}
+
+/**
+ * Close codes the backend uses **after** a successful WS upgrade.
+ * Close codes align with the server’s WebSocket DPoP / negotiate layers
+ * (4400–4409, 4500, etc.).
+ */
+declare const WSCloseCode: {
+    /** First frame wasn't valid JSON / wrong type. */
+    readonly BAD_FIRST_FRAME: 4400;
+    /** Ticket bad/expired or proof failed verification. */
+    readonly AUTH_FAILED: 4401;
+    /** Post-upgrade authorization failed (e.g. client not in room). */
+    readonly FORBIDDEN: 4403;
+    /** Post-upgrade resource lookup failed (room/client missing). */
+    readonly NOT_FOUND: 4404;
+    /** No first frame within 5 seconds. */
+    readonly HANDSHAKE_TIMEOUT: 4408;
+    /** First-frame `jti` already seen — replay detected. */
+    readonly REPLAY: 4409;
+    /** Post-upgrade internal error. */
+    readonly INTERNAL: 4500;
+};
+/**
+ * Returns `true` when a WebSocket close code is one the SDK refuses to
+ * auto-retry. UIs should render an end-of-session state on a fatal
+ * close instead of a "reconnecting" spinner. Mirror of the
+ * `NO_RETRY_CODES` set used internally for backoff decisions.
+ */
+declare function isFatalCloseCode(code: number): boolean;
+/**
+ * Internal events emitted by `WebSocketClient`. Higher-level modules
+ * (`RoomManager`, `WebRTCManager`) subscribe to these.
+ */
+interface WebSocketEventMap {
+    /** WS handshake (upgrade + DPoP first-frame + ack) completed. */
+    open: void;
+    /** Underlying socket closed. `code`/`reason` are the WS close info. */
+    close: {
+        code: number;
+        reason: string;
+    };
+    /** Network or decoding error. */
+    error: Error;
+    /** Any application-level message (after the handshake). */
+    message: WSMessage;
+    /** Catch-all bucketed by message type. Listeners for, e.g., `sdp` get only SDP frames. */
+    [eventType: `type:${string}`]: WSMessage;
+}
+/**
+ * Two endpoint shapes — the room WS and the global notification WS.
+ * The SDK exposes only the room shape today; `connectGlobal` is reserved
+ * for a later milestone.
+ */
+type WebSocketTarget = {
+    kind: 'room';
+    roomId: number | string;
+    clientId: string;
+} | {
+    kind: 'global';
+};
+interface WebSocketClientOptions {
+    /** Maximum reconnect attempts after a transient drop. Default: 5. */
+    maxReconnects?: number;
+    /** Base delay (ms) for exponential backoff. Default: 1000. */
+    reconnectBaseDelayMs?: number;
+}
+/**
+ * Manages the lifecycle of a single authenticated WebSocket. Wraps the
+ * full handshake protocol described in `docs/auth.md` and your backend’s
+ * WebSocket upgrade spec:
+ *
+ *   1. `POST /auth/ws-ticket` — get a 10-second JWT bound to the device
+ *      key plus a server-issued nonce.
+ *   2. Open the socket using `?ticket=<jwt>` (the only place the ticket
+ *      can travel — browsers can't set headers on WS upgrades).
+ *   3. Within 5 seconds send the DPoP first frame
+ *      `{ "type": "dpop_handshake", "proof": "..." }` whose proof's
+ *      `htu` exactly matches the WS URL with the query stripped.
+ *   4. Wait for `{ "type": "dpop_handshake_ack" }` before any application
+ *      frames. Any other first response = treat as a fatal error.
+ *
+ * After the handshake, the wire is plain `WSMessage` envelopes
+ * `{ type, from, to, payload }`.
+ */
+declare class WebSocketClient extends TypedEventEmitter<WebSocketEventMap> {
+    private readonly api;
+    private readonly dpop;
+    private readonly logger;
+    private socket;
+    private target;
+    private acked;
+    private explicitlyClosed;
+    private reconnectAttempts;
+    private readonly options;
+    constructor(api: ApiClient, dpop: DPoPManager, logger: Logger, options?: WebSocketClientOptions);
+    /** True once the DPoP first-frame handshake has been acked by the server. */
+    get isReady(): boolean;
+    /**
+     * Open and authenticate a room WebSocket. The `clientId` must be the
+     * one returned from `POST /joinroom/{roomId}` for the same session.
+     */
+    connectRoom(roomId: number | string, clientId: string): Promise<void>;
+    /**
+     * Open and authenticate the global notification WebSocket.
+     * Reserved for the friends / presence work; no app-level frames are
+     * defined on this socket today.
+     */
+    connectGlobal(): Promise<void>;
+    private connect;
+    /** Send an application frame. The handshake must have completed. */
+    send(message: WSMessage): void;
+    /** Close the socket and disable automatic reconnects. */
+    disconnect(code?: number, reason?: string): void;
+    private urlFor;
+}
+
+/**
+ * Snapshot of the local membership in a room. Held by `RoomManager` for
+ * the lifetime of a single `joinRoom` call so other modules
+ * (`WebRTCManager`, the `Call` event surface, screen-share helpers)
+ * have one source of truth for `roomId` + `clientId`.
+ */
+interface ActiveMembership {
+    roomId: number | string;
+    clientId: string;
+}
+/**
+ * `RoomManager` is the ergonomic wrapper around the room REST endpoints.
+ * It also keeps
+ * track of the **local** `clientId` so callers don't have to thread it
+ * through every method that needs it (screen share, permissions, leave).
+ *
+ * It does **not** manage WebRTC peer connections — that lives in
+ * `WebRTCManager`. It does **not** open the WebSocket — that's
+ * `WebSocketClient`. Composition happens in the top-level `SignallingSDK`.
+ */
+declare class RoomManager {
+    private readonly api;
+    private readonly ws;
+    private readonly logger;
+    private active;
+    constructor(api: ApiClient, ws: WebSocketClient, logger: Logger);
+    /** Currently joined room snapshot, or `null` if not in a room. */
+    get current(): ActiveMembership | null;
+    /** `POST /createroom` — creates a room and returns `{ roomId, clientId }`. */
+    create(): Promise<CreateRoomResponse>;
+    /**
+     * `POST /joinroom/{roomId}` — joins an existing room and stores the
+     * resulting `clientId` for subsequent calls. Does NOT open a WebSocket;
+     * use `connectSocket` for that.
+     */
+    join(roomId: number | string): Promise<JoinRoomResponse>;
+    /**
+     * Open the room WebSocket for the active membership. Performs the
+     * full ticket → upgrade → DPoP first-frame handshake.
+     *
+     * Throws if the caller hasn't `create()`d / `join()`ed a room first.
+     */
+    connectSocket(): Promise<void>;
+    /** `GET /viewroom/{roomId}` — returns the full room snapshot. */
+    view(roomId?: number | string): Promise<Room>;
+    /**
+     * `DELETE /leaveroom/{roomId}/{clientId}` + closes the WebSocket.
+     * Always tries to clean up local state even if the network call fails.
+     */
+    leave(): Promise<void>;
+    startScreenShare(): Promise<{
+        status: string;
+        previousSharer?: string;
+    }>;
+    stopScreenShare(): Promise<{
+        status: string;
+    }>;
+    /** Permissions for the local client. */
+    myPermissions(): Promise<ClientPermissions>;
+    /**
+     * Update permissions for any client in the room. Fails with `403` if
+     * the local user is not the host.
+     */
+    updatePermissions(targetClientId: string, updates: Partial<Pick<ClientPermissions, 'canAudio' | 'canVideo' | 'canScreenShare'>>): Promise<ClientPermissions>;
+}
+
+/**
+ * Events emitted by `WebRTCManager`. Surfaced through the `Call` object
+ * returned by `sdk.calls.joinRoom`.
+ */
+interface WebRTCEventMap {
+    /** A remote camera `MediaStream` arrived from `peerId`. */
+    'stream.added': {
+        clientId: string;
+        stream: MediaStream;
+    };
+    /** The peer connection's camera stream is gone. */
+    'stream.removed': {
+        clientId: string;
+    };
+    /** Remote peer started a screen-share stream (separate surface from camera). */
+    'screen-share.added': {
+        clientId: string;
+        stream: MediaStream;
+    };
+    /** Remote peer's screen-share stream ended. */
+    'screen-share.removed': {
+        clientId: string;
+    };
+    /** Peer broadcast a `mediaState` signal — their mic/cam enable toggled. */
+    'peer.media-state-changed': {
+        clientId: string;
+        state: PeerMediaState;
+    };
+    /** Peer broadcast `mediaStopped` — they ended all local media. */
+    'peer.media-stopped': {
+        clientId: string;
+    };
+    /** Underlying RTCPeerConnection state change. */
+    'peer.connection-state': {
+        clientId: string;
+        state: RTCPeerConnectionState;
+    };
+    /** A negotiation attempt failed irrecoverably. */
+    'peer.failed': {
+        clientId: string;
+        error: Error;
+    };
+}
+/**
+ * Identity of the local client — supplied by the orchestrator
+ * (`SignallingSDK`) so the WebRTC manager can correctly address
+ * outbound `WSMessage` envelopes.
+ */
+interface LocalIdentity {
+    clientId: string;
+}
+/**
+ * `WebRTCManager` orchestrates `RTCPeerConnection` instances on top of
+ * the room WebSocket. The wire format mirrors what the room WebSocket
+ * handler expects:
+ *
+ *   - `{type: 'sdp',    from, to, payload: { type, sdp } }`
+ *   - `{type: 'ice',    from, to, payload: { candidate, ... } }`
+ *   - `{type: 'signal', from: 'server' | clientId, to, payload: { action, ... } }`
+ *
+ * SDP messages are routed peer-to-peer by the backend; the only thing
+ * the server inspects is the `to` field. Each remote peer gets its own
+ * `RTCPeerConnection` keyed by `clientId`.
+ *
+ * **Camera vs screen-share segregation.** Both streams ride the same
+ * `RTCPeerConnection`. Each peer broadcasts a `screenShareStream` signal
+ * carrying the `MediaStream.id` BEFORE adding its screen tracks; the
+ * receiver records that id and routes the matching incoming
+ * `MediaStream` to the `screen-share.added` event rather than
+ * `stream.added`. A matching `screenShareStopped` signal clears the
+ * mapping when the sharer ends.
+ *
+ * **Peer-state side channel.** Peers also broadcast `mediaState` /
+ * `mediaStopped` signals (purely informational — the backend does not
+ * validate or replicate them). The manager records the most recent
+ * state per peer so UIs can render mute / camera-off indicators
+ * without relying on the inbound track being absent (which it usually
+ * isn't — `setMicEnabled(false)` only disables the track locally).
+ */
+declare class WebRTCManager extends TypedEventEmitter<WebRTCEventMap> {
+    private readonly ws;
+    private readonly logger;
+    private readonly peers;
+    private readonly peerMediaStates;
+    /** Maps each peer's announced screen `MediaStream.id` to that peer's clientId. */
+    private readonly screenStreamIds;
+    /** Senders we added when we started screen-sharing — used so we can drop them on stop. */
+    private readonly screenSenders;
+    private localStream;
+    private localScreenStream;
+    private iceServers;
+    private local;
+    private wsUnsubs;
+    constructor(ws: WebSocketClient, logger: Logger);
+    /**
+     * Wire up the manager to a freshly authenticated WebSocket. Must be
+     * called after the WS handshake completes and the local `clientId`
+     * is known. Safe to call again with a different identity — the old
+     * subscriptions are removed first.
+     */
+    bind(local: LocalIdentity): void;
+    /** Drop all WS subscriptions and tear down every peer connection. */
+    unbind(): void;
+    /**
+     * Read-only access to the live peer-connection map. Exposed for
+     * integrators that need to read RTCStatsReport (`pc.getStats()`),
+     * inspect senders for adaptive bitrate, or attach analyser nodes for
+     * active-speaker detection — operations that are out of scope for the
+     * SDK but still need first-class peer access. The returned `Map` is
+     * a live view; do NOT mutate it.
+     */
+    getPeerConnections(): ReadonlyMap<string, RTCPeerConnection>;
+    /** Read-only access to the current local camera `MediaStream`. */
+    getLocalStream(): MediaStream | null;
+    /** Read-only access to the current local screen-share `MediaStream`, if any. */
+    getLocalScreenStream(): MediaStream | null;
+    /**
+     * Read-only access to the latest `mediaState` we've seen per peer. An
+     * absent entry means the peer has not announced yet — treat as
+     * `{ video: true, audio: true }` (the implicit default).
+     */
+    getPeerMediaStates(): ReadonlyMap<string, PeerMediaState>;
+    /** Inject TURN credentials. The next created peer connection will pick them up. */
+    setTurnCredentials(credentials: TurnCredential | TurnCredential[] | null): void;
+    /**
+     * Replace the local outbound camera `MediaStream`. Tracks are added /
+     * replaced on every existing peer connection. Screen-share tracks are
+     * NOT touched — they're tracked separately via `addScreenStream`.
+     */
+    setLocalStream(stream: MediaStream | null): Promise<void>;
+    /**
+     * Begin sharing a screen `MediaStream` to all current peers
+     * **alongside** the existing camera tracks (the Zoom / Meet pattern).
+     *
+     * Wire protocol (matches the backend's relayed signal contract):
+     *   1. For each peer, send `{action: 'screenShareStream', streamId}`
+     *      on the room WS so the receiver knows the next `ontrack` whose
+     *      stream id matches is screen, not camera.
+     *   2. Add the screen tracks to that peer's `RTCPeerConnection`.
+     *   3. Renegotiate (createOffer / setLocalDescription / send SDP).
+     *
+     * Idempotent — calling twice without an intervening
+     * `removeScreenStream` is a no-op.
+     */
+    addScreenStream(stream: MediaStream): Promise<void>;
+    /**
+     * Stop sharing the local screen `MediaStream`. Removes the screen
+     * senders from every peer connection and broadcasts
+     * `screenShareStopped` so receivers can tear down their screen
+     * surface immediately. Idempotent — no-op when nothing is shared.
+     */
+    removeScreenStream(): Promise<void>;
+    /**
+     * Broadcast our mic/cam enable state to every peer in the room.
+     * Auto-called by `Call.setMicEnabled` / `Call.setCameraEnabled` so
+     * peer UIs can render mute / camera-off indicators without inspecting
+     * the inbound track (which usually keeps flowing in disabled state).
+     */
+    broadcastMediaState(state: PeerMediaState): void;
+    /**
+     * Announce that we've ended all local media. Receivers tear down both
+     * our camera and screen-share surfaces. Called by `Call.leave` and by
+     * `Call.setLocalStream(null)`.
+     */
+    broadcastMediaStopped(): void;
+    /**
+     * Initiate an offer toward the given remote client. Used by the
+     * caller side of the mesh-mode handshake (typically when a `peer.joined`
+     * signal arrives and the local end is the more-recently-connected peer).
+     */
+    callPeer(remoteClientId: string): Promise<void>;
+    /** Tear down the connection to a single peer. */
+    hangupPeer(remoteClientId: string): void;
+    private handleSdp;
+    private handleIce;
+    /**
+     * Handle every inbound `type: 'signal'` frame. The server emits some
+     * signals (`from: 'server'`) and peers emit others (`from: <clientId>`).
+     * We discriminate by `msg.from` because the backend's relayed
+     * envelope reuses the same `type` field.
+     */
+    private handleSignal;
+    private handleServerSignal;
+    /**
+     * Peer-originated signals (relayed by the server, but content is
+     * untrusted). Currently covers media on/off state, mediaStopped, and
+     * screen-share streamId routing. Chat signals are intentionally NOT
+     * handled here — the `Call` event surface forwards them via the
+     * generic `raw` event so the WebRTC layer stays focused on RTC.
+     */
+    private handlePeerSignal;
+    private getOrCreatePeer;
+    /**
+     * Send a directed signaling envelope onto the WebSocket. Wraps
+     * `WSMessage` so call sites can stay short and the wire format is
+     * enforced in one place.
+     */
+    private sendSignaling;
+    /**
+     * Broadcast a peer-signal payload to every current peer. The relayed
+     * envelope uses `type: 'signal'` with the local clientId as `from`.
+     */
+    private broadcastSignal;
+}
+
+/**
+ * Categorised view of `MediaDeviceInfo[]` for easier consumption.
+ */
+interface DeviceInventory {
+    cameras: MediaDeviceInfo[];
+    microphones: MediaDeviceInfo[];
+    speakers: MediaDeviceInfo[];
+}
+/**
+ * Thin, defensive wrapper around `navigator.mediaDevices`. Centralised
+ * so the SDK doesn't sprinkle feature-detection checks at every call
+ * site and so unit tests have one mocking surface to stub.
+ *
+ * The manager intentionally does NOT cache the local `MediaStream` —
+ * that's `WebRTCManager`'s job (it has to push tracks into existing
+ * peer connections when a new stream arrives).
+ */
+declare class DeviceManager {
+    /**
+     * Acquire a stream from the user's mic / camera. Accepts either a
+     * boolean shorthand (legacy SDK call sites) or full
+     * `MediaTrackConstraints` for fine-grained device selection.
+     */
+    getLocalStream(constraints?: MediaConstraints): Promise<MediaStream>;
+    /** Convenience overload kept for backwards-compatibility with v0 docs. */
+    getUserMedia(audio?: boolean, video?: boolean): Promise<MediaStream>;
+    /**
+     * Prompt the user for a screen-share / window-share stream.
+     */
+    getScreenShare(opts?: DisplayMediaStreamOptions): Promise<MediaStream>;
+    /** Raw enumeration of every connected media device. */
+    listDevices(): Promise<MediaDeviceInfo[]>;
+    /** Categorised view: cameras, microphones, speakers. */
+    listInventory(): Promise<DeviceInventory>;
+    /**
+     * Subscribe to device-list changes (e.g. user plugged in a USB mic).
+     * Returns an unsubscribe function.
+     */
+    onDeviceChange(cb: () => void): () => void;
+    /**
+     * Stop every track on a stream — important to call when the user
+     * unmounts the local preview, otherwise the camera light stays on.
+     */
+    stopStream(stream: MediaStream | null | undefined): void;
+    private assertSupported;
+}
+
+/**
+ * `FriendsManager` is the SDK's stateful wrapper around the global-WS
+ * friend protocol. It owns:
+ *
+ *  - A cache of the local user's friends and pending incoming requests.
+ *  - The periodic refresh that keeps online-status indicators alive.
+ *  - The translation between wire-shaped frames (with backend's actual
+ *    field names) and the SDK's typed event surface.
+ *
+ * The manager is **lazy** — `SignallingSDK` constructs it on first
+ * access of `sdk.friends`. Construction opens the global WS, runs the
+ * normal DPoP-protected handshake, and begins listening for inbound
+ * frames.
+ *
+ * Wire shapes (matched against `backend/global/handler.go`):
+ *
+ *   - server → us
+ *     `friend_list`        `{friends: [{friendshipId, username, isOnline}]}`
+ *     `friend_pending`     `{requests: [{friendshipId, requester, createdAt}]}`
+ *     `friend_request_ack` `{friendshipId, addressee, status}`
+ *     `friend_accept_ack`  `{friendshipId, friend, status}`
+ *     `friend_reject_ack`  `{friendshipId, status}`
+ *     `friend_remove_ack`  `{friendshipId, status}`
+ *     `error`              `{originalType, error}`
+ *
+ *   - peer push (forwarded by server)
+ *     `friend_request`     `{friendshipId, requester}`  from = requester username
+ *     `friend_accepted`    `{friendshipId, acceptedBy}` from = acceptor username
+ *
+ *   - us → server
+ *     `friend_list`        no payload
+ *     `friend_pending`     no payload
+ *     `friend_request`     to = addressee username
+ *     `friend_accept`      `{friendshipId}`
+ *     `friend_reject`      `{friendshipId}`
+ *     `friend_remove`      `{friendshipId}`
+ */
+declare class FriendsManager extends TypedEventEmitter<FriendsEventMap> {
+    private readonly ws;
+    private readonly logger;
+    private friends;
+    private pending;
+    private wsUnsubs;
+    private refreshTimer;
+    private firstQueryTimer;
+    private readonly refreshIntervalMs;
+    constructor(ws: WebSocketClient, logger: Logger, options?: {
+        refreshIntervalMs?: number;
+    });
+    /**
+     * Bind to the global WS — subscribes to inbound frames and kicks off
+     * the first `friend_list` / `friend_pending` query (after a small
+     * delay so the WS handshake has time to settle). Idempotent.
+     */
+    bind(): void;
+    /**
+     * Drop subscriptions and cancel the refresh timer. Call before
+     * disposing the SDK so timers don't keep the process alive.
+     */
+    unbind(): void;
+    /** Current friends cache. Mutating the returned array is a no-op (it's a copy). */
+    list(): Friend[];
+    /** Current pending-requests cache. */
+    pendingRequests(): PendingFriendRequest[];
+    /** Force a refresh of both `friends` and `pending` caches. */
+    refresh(): void;
+    /** Send a friend request to a peer by their **username**. */
+    sendRequest(username: string): void;
+    /** Accept a pending friend request by friendship id. */
+    accept(friendshipId: string): void;
+    /** Reject a pending friend request by friendship id. */
+    reject(friendshipId: string): void;
+    /** Remove an existing friendship by id. */
+    remove(friendshipId: string): void;
+    private schedulePostConnectQueries;
+    private startRefreshLoop;
+    private cancelRefreshOnly;
+    private cancelTimers;
+    private clearLocalState;
+    private send;
+    private handleMessage;
+}
+
+/**
+ * `CallInviteManager` handles `call_invite` frames on the global WS.
+ * Used by `sdk.calls.invite()` (outbound) and the
+ * `'call.invite-received'` event on `sdk.calls` (inbound). Lives on
+ * the global socket — separate from `Call`, which lives on the room
+ * socket. The two are intentionally not coupled: you can receive an
+ * invite while not in any call, and you can ignore the invite without
+ * ever entering a call.
+ *
+ * Wire shape (per `backend/global/handler.go::handleCallInvite`):
+ *
+ *   out: `{ type: 'call_invite', to: '<recipient-username>', payload: { roomId } }`
+ *   in:  `{ type: 'call_invite', from: '<caller-username>',  payload: { roomId } }`
+ *
+ * The backend resolves `to` (username) to a hub key server-side; the
+ * sender never sees the recipient's internal id.
+ */
+declare class CallInviteManager extends TypedEventEmitter<CallInviteEventMap> {
+    private readonly ws;
+    private readonly logger;
+    private wsUnsubs;
+    constructor(ws: WebSocketClient, logger: Logger);
+    /** Subscribe to the global WS. Idempotent. */
+    bind(): void;
+    /** Drop subscriptions. */
+    unbind(): void;
+    /**
+     * Invite a friend to join the given room. The recipient is addressed
+     * by username; the SDK forwards the request over the global WS and
+     * the backend pushes a `call_invite` frame to the recipient.
+     *
+     * No delivery acknowledgement today — fire-and-forget. The backend
+     * logs a warning if the recipient is offline; future revisions may
+     * emit a `'call.invite-undelivered'` event so consumers can show
+     * "user is offline" UI.
+     */
+    invite(toUsername: string, roomId: number | string): void;
+    private handleMessage;
+}
+
+/**
+ * `Call` is the high-level handle returned by `sdk.calls.joinRoom`.
+ * It bundles the active membership, the typed event surface, and
+ * convenience methods so integrators don't juggle managers.
+ *
+ * Local mic / camera enable state is owned by the Call (not the SDK or
+ * the React layer) because the wire protocol couples toggle UX to a
+ * peer broadcast (`mediaState`). Calling `setMicEnabled` / `setCameraEnabled`
+ * therefore both flips the local track AND fires the peer signal —
+ * keeping the two in lockstep removes the most common source of stale
+ * remote mute-indicator bugs.
+ */
+declare class Call extends TypedEventEmitter<CallEventMap> {
+    readonly roomId: number | string;
+    readonly clientId: string;
+    private readonly rooms;
+    private readonly webrtc;
+    private readonly ws;
+    private readonly devices;
+    private readonly auth;
+    /** The local camera stream sent to peers — `null` if joined listen-only. */
+    localStream: MediaStream | null;
+    /** Tracks the latest video/audio enable state so the toggles can broadcast it. */
+    private localMediaState;
+    /** @internal */
+    constructor(roomId: number | string, clientId: string, rooms: RoomManager, webrtc: WebRTCManager, ws: WebSocketClient, devices: DeviceManager, auth: AuthClient);
+    /**
+     * Snapshot of remote peers' announced mic/cam state, keyed by clientId.
+     * Live view backed by `WebRTCManager.getPeerMediaStates()`.
+     */
+    get peers(): ReadonlyMap<string, PeerMediaState>;
+    /** Local mic enable state. Reflects the last call to `setMicEnabled`. */
+    get isAudioEnabled(): boolean;
+    /** Local camera enable state. */
+    get isVideoEnabled(): boolean;
+    /** Local screen-share stream, or `null` when not sharing. */
+    get localScreenStream(): MediaStream | null;
+    /** True iff this client is currently broadcasting a screen-share stream. */
+    get isScreenSharing(): boolean;
+    /**
+     * Toggle local audio. Disables the outgoing audio track AND fires a
+     * `mediaState` signal so peers can update their mute indicators.
+     * The remote audio track keeps flowing on the wire — that's expected
+     * (WebRTC pauses the track at the source, not the line).
+     */
+    setMicEnabled(enabled: boolean): void;
+    /** Toggle local video. Broadcasts a `mediaState` signal — see `setMicEnabled`. */
+    setCameraEnabled(enabled: boolean): void;
+    /**
+     * Replace the local camera stream (e.g. after a device switch). Does NOT
+     * touch the screen-share stream — call `stopScreenShare` separately if
+     * needed. Passing `null` stops local camera media and broadcasts a
+     * `mediaStopped` signal.
+     */
+    setLocalStream(stream: MediaStream | null): Promise<void>;
+    /**
+     * Begin sharing the screen ALONGSIDE the existing camera tracks.
+     * Picks a screen via `DeviceManager.getScreenShare`, announces the
+     * stream id to every peer (`screenShareStream` signal), adds the
+     * tracks, and renegotiates each peer connection — all owned by
+     * `WebRTCManager.addScreenStream`. Also POSTs the screen-share-start
+     * endpoint so the backend can track the active sharer per room.
+     *
+     * If a different client is already sharing, the backend will boot
+     * them via a `stopScreenShare` server signal — we surface that to
+     * the previous sharer via `'screen-share.stop'`.
+     *
+     * Browser `onended` (user clicks the system "Stop sharing" pill) is
+     * wired up so we cleanly call `stopScreenShare` on that path too.
+     */
+    startScreenShare(): Promise<MediaStream>;
+    /** Stop the active screen share — both remotely and locally. */
+    stopScreenShare(): Promise<void>;
+    /**
+     * Broadcast a chat message to every peer in the room. Fills in
+     * `fromName` from the cached `UserProfile` if available (falls back
+     * to the local `clientId`). Returns the constructed `ChatMessage` so
+     * the caller can append it to their own UI without waiting for any
+     * echo (the SDK does NOT echo chat to the sender).
+     */
+    sendChat(text: string): ChatMessage;
+    private deriveLocalDisplayName;
+    /** Disconnect from the room — closes WS, tears down peers, hits API. */
+    leave(): Promise<void>;
+}
+/**
+ * `SignallingSDK` — the single public entry point.
+ *
+ * ```ts
+ * const sdk = await SignallingSDK.create({
+ *   baseUrl: "https://api.example.com",
+ *   authMode: "bff",
+ * });
+ *
+ * await sdk.auth.login();
+ * // ...after the BFF callback completes...
+ * const token = sdk.auth.bindTokenFromFragment();
+ * if (token) await sdk.auth.completeBind(token);
+ *
+ * const room = await sdk.rooms.create();
+ * const call = await sdk.calls.joinRoom({
+ *   roomId: room.roomId,
+ *   media: { audio: true, video: true },
+ * });
+ *
+ * call.on('peer.joined', (peer) => console.log('joined:', peer));
+ * call.on('stream.added', ({ clientId, stream }) => attach(clientId, stream));
+ * ```
+ *
+ * **Two WebSocket connections.** The SDK keeps the room WS (joined via
+ * `calls.joinRoom`) and the global WS (used by `sdk.friends` /
+ * `sdk.calls.invite`) on separate `WebSocketClient` instances —
+ * concurrent, independently authenticated, independently reconnecting.
+ * The global WS is lazily opened on first use.
+ */
+declare class SignallingSDK {
+    readonly auth: AuthClient;
+    readonly rooms: RoomManager;
+    readonly devices: DeviceManager;
+    readonly api: ApiClient;
+    readonly dpop: DPoPManager;
+    /** Room WebSocket — the `calls.joinRoom` machinery binds to this one. */
+    readonly ws: WebSocketClient;
+    readonly webrtc: WebRTCManager;
+    readonly logger: Logger;
+    private readonly config;
+    /** Tracks the active call so a second `joinRoom` can clean up the previous one. */
+    private activeCall;
+    /** Bridge subscriptions between (WS, WebRTC) → active Call. Cleared on leave. */
+    private callBridges;
+    private globalWs;
+    private friendsManager;
+    private callInviteManager;
+    private constructor();
+    /**
+     * Create and initialise a new SDK instance. Eagerly loads the DPoP
+     * keypair from IndexedDB so the first authed request doesn't pay the
+     * keygen cost.
+     */
+    static create(config: SignallingSDKConfig): Promise<SignallingSDK>;
+    /**
+     * Friends + presence surface. First access opens the global WS,
+     * runs the DPoP handshake, and starts the periodic friends-list
+     * refresh. Subsequent accesses return the same instance.
+     */
+    get friends(): FriendsManager;
+    /**
+     * High-level call orchestration:
+     *   - `joinRoom(config)` — combines join-over-REST, TURN fetch, local
+     *     media acquisition, WS handshake, and WebRTC wiring into a
+     *     single `Call` handle.
+     *   - `invite(toUsername, roomId)` — sends a `call_invite` frame on the
+     *     global WS so a friend gets a real-time invitation push.
+     *   - `on('call.invite-received', cb)` — subscribes to inbound
+     *     invitations from friends. Opens the global WS on first
+     *     subscribe so consumers don't need to manually start it.
+     */
+    get calls(): {
+        joinRoom: (config: CallConfig) => Promise<Call>;
+        invite: (toUsername: string, roomId: number | string) => void;
+        on: <K extends "call.invite-received">(event: K, listener: (payload: IncomingCallInvite) => void) => (() => void);
+    };
+    private ensureCallInviteManager;
+    /**
+     * Lazily construct and connect the global WS. The global socket lives
+     * for the SDK instance lifetime; it carries friend protocol frames
+     * and call invites, independently of any active room.
+     */
+    private ensureGlobalConnected;
+    /**
+     * Implementation of `calls.joinRoom`. Kept as a method on the SDK so
+     * arrow-functions on the `calls` getter don't trap a stale `this`.
+     */
+    private joinRoom;
+    /**
+     * Wire WS / WebRTC event streams into the `Call` event map. Each
+     * subscription returns its own unsubscribe; we collect them so a
+     * subsequent `leave()` / `joinRoom()` can detach cleanly.
+     */
+    private bindCallEvents;
+    private dispatchServerSignal;
+    private dispatchPeerSignal;
+    /**
+     * Placeholder hook for the SFU rollout. Returns `false` today; will
+     * become a config-driven switch once the SFU client is exposed.
+     */
+    private shouldUseSfu;
+}
+
+export { type ActiveMembership, ApiClient, AuthClient, type AuthEventMap, type AuthMode, Call, type CallConfig, type CallEventMap, type CallInviteEventMap, CallInviteManager, type ChatMessage, type ClientPermissions, type CreateRoomResponse, DPoPManager, type DeviceInventory, DeviceManager, type Friend, type FriendsEventMap, FriendsManager, type IceCandidatePayload, type IncomingCallInvite, type JoinRoomResponse, type LocalIdentity, type LogLevel, type Logger, type MediaConstraints, type PeerMediaState, type PeerSignalPayload, type PendingFriendRequest, type Room, type RoomClient, RoomManager, type SdpPayload, type ServerSignalPayload, SignallingApiError, SignallingSDK, type SignallingSDKConfig, SignallingWebSocketError, type TurnCredential, type UpdateProfileRequest, type UserProfile, type UserStatus, WSCloseCode, type WSMessage, type WSTicket, type WebRTCEventMap, WebRTCManager, WebSocketClient, type WebSocketClientOptions, type WebSocketEventMap, type WebSocketTarget, isFatalCloseCode };