@soulcraft/sdk 2.0.0 → 2.0.2

package/dist/modules/hall/types.d.ts

@@ -2,20 +2,25 @@
  * @module modules/hall/types
  * @description Types for the sdk.hall namespace — the Soulcraft real-time communication layer.
  *
- * Hall is a standalone Rust server at `hall.soulcraft.com`. It handles WebRTC SFU
- * (video/audio/data channels), in-process Whisper ASR transcription, BERT concept
- * matching, RFC 6464 speaker detection, and per-track MKV recording.
+ * Hall is a standalone Rust server at `hall.soulcraft.com`. It provides:
+ * - **WebRTC SFU** — video/audio/data channels with RFC 6464 speaker detection
+ * - **Whisper ASR** — in-process transcription with BERT concept matching
+ * - **Pub/Sub** — product-scoped topic routing with presence tracking and replay buffers
+ * - **Media Pipeline** — upload, ffmpeg transcoding, thumbnails, async notifications
+ * - **Broadcast** — three-tier auto-scaling: participant (SFU) → WHEP → LL-HLS
+ * - **Recording** — per-track MKV + optional composite MP4 with webhook notifications
  *
  * The `sdk.hall` namespace has two faces depending on context:
  *
  * **Server mode** (`@soulcraft/sdk/server`) — the product backend (Academy, Workshop, Venue)
- * connects to Hall with a shared secret, creates rooms, and mints short-lived session tokens.
- * Use `createHallModule(options)` from `@soulcraft/sdk/server`.
+ * connects to Hall with a shared secret, creates rooms, manages pub/sub topics, uploads
+ * media, and mints session tokens. Use `createHallModule(options)` from `@soulcraft/sdk/server`.
  *
  * **Client mode** (`@soulcraft/sdk/client`) — a browser kit app joins a room using a session
- * token issued by the product backend. Use `HallRoomClient` from `@soulcraft/sdk/client`.
+ * token, or connects to pub/sub using a pubsub token. Use `joinHallRoom()` or
+ * `joinHallPubsub()` from `@soulcraft/sdk/client`.
  *
- * Products never pass their shared secret to the browser. The token is the only browser credential.
+ * Products never pass their shared secret to the browser. Tokens are the only browser credentials.
  */
 /**
  * Options for the server-side Hall connection (product backend → Hall server).
@@ -54,7 +59,28 @@ export interface ConceptInput {
     /** Kit-defined subtype, if any. */
     subtype?: string;
 }
-/** Options for creating a room. All fields are optional with safe defaults. */
+/**
+ * Options for creating a room. All fields are optional with safe defaults.
+ *
+ * @example Standard room
+ * ```typescript
+ * await hall.createRoom('cohort-123', {
+ *   enableTranscription: true,
+ *   concepts: await loadConcepts(cohortId),
+ * })
+ * ```
+ *
+ * @example Broadcast room (webinar/lecture)
+ * ```typescript
+ * await hall.createRoom('lecture-456', {
+ *   maxParticipants: 5,
+ *   allowBroadcast: true,
+ *   enableRecording: true,
+ *   recordingComposite: true,
+ *   recordingWebhookUrl: 'https://academy.soulcraft.com/api/recordings/complete',
+ * })
+ * ```
+ */
 export interface RoomOptions {
     /** Maximum peers before the SFU stops accepting new connections (default: 30). */
     maxPeers?: number;
@@ -72,6 +98,30 @@ export interface RoomOptions {
      * Pass an empty array to disable concept matching while keeping transcription.
      */
     concepts?: ConceptInput[];
+    /**
+     * Maximum bidirectional participants in broadcast rooms (default: 30).
+     * Overflow joiners are assigned as viewers (WHEP or LL-HLS).
+     * Only meaningful when `allowBroadcast` is true.
+     */
+    maxParticipants?: number;
+    /**
+     * Enable auto-scaling broadcast. When true, overflow joiners become viewers
+     * using WHEP (sub-second latency) or LL-HLS (2–3s, unlimited scale).
+     * Default: false.
+     */
+    allowBroadcast?: boolean;
+    /**
+     * Produce a composite MP4 recording (mixed audio + active speaker video)
+     * in addition to individual per-track MKV files.
+     * Default: false.
+     */
+    recordingComposite?: boolean;
+    /**
+     * Webhook URL for recording completion notification.
+     * Hall POSTs `{ sessionId, manifest }` JSON when recording finishes.
+     * Retried with exponential backoff (3 attempts).
+     */
+    recordingWebhookUrl?: string;
 }
 /**
  * Manifest emitted when recording stops.
@@ -89,6 +139,16 @@ export interface RecordingManifest {
     audioTracks: string[];
     /** Absolute paths to per-participant video track MKV files. */
     videoTracks: string[];
+    /**
+     * Path to the composite MP4 (mixed audio + active speaker video).
+     * Only present when `RoomOptions.recordingComposite` was true.
+     */
+    compositePath?: string;
+    /**
+     * Cloud storage URLs (if cloud upload was configured in `hall.toml`).
+     * Populated after upload completes (GCS, S3, etc.).
+     */
+    cloudUrls?: string[];
 }
 /** A Whisper ASR transcript segment from a peer in the room. */
 export interface TranscriptEvent {
@@ -146,6 +206,179 @@ export interface PeerLeftEvent {
     roomId: string;
     peerId: string;
 }
+/** A single replayed message from a topic's replay buffer. */
+export interface ReplayEntry {
+    /** Sender identifier (product name or peer ID). */
+    senderId: string;
+    /** The message payload. */
+    payload: unknown;
+    /** Unix timestamp in milliseconds when the message was originally sent. */
+    timestampMs: number;
+}
+/** Confirmation of a pub/sub topic subscription. */
+export interface TopicSubscribedEvent {
+    /** Topic that was subscribed to. */
+    topic: string;
+    /** Current number of subscribers on this topic. */
+    subscriberCount: number;
+    /** Replay buffer entries (most recent messages, if any). */
+    replay: ReplayEntry[];
+}
+/** Confirmation of a pub/sub topic unsubscription. */
+export interface TopicUnsubscribedEvent {
+    /** Topic that was unsubscribed from. */
+    topic: string;
+}
+/** A message received on a subscribed pub/sub topic. */
+export interface TopicMessageEvent {
+    /** Topic the message was published to. */
+    topic: string;
+    /** Sender identifier (product name or peer ID). */
+    senderId: string;
+    /** The message payload. */
+    payload: unknown;
+    /** Unix timestamp in milliseconds. */
+    timestampMs: number;
+}
+/** A subscriber joined or left a pub/sub topic. */
+export interface PresenceUpdateEvent {
+    /** Topic the presence event occurred on. */
+    topic: string;
+    /** Peer who joined or left. */
+    peerId: string;
+    /** Whether the peer joined or left. */
+    action: 'joined' | 'left';
+    /** Presence metadata (only present on join). */
+    metadata?: Record<string, unknown>;
+    /** Current subscriber count after this event. */
+    subscriberCount: number;
+}
+/** A single subscriber in a presence snapshot. */
+export interface PresenceEntry {
+    /** Subscriber identifier. */
+    peerId: string;
+    /** Optional presence metadata set at subscribe time. */
+    metadata?: Record<string, unknown>;
+}
+/** Full snapshot of all current subscribers on a topic. */
+export interface PresenceSnapshotEvent {
+    /** Topic queried. */
+    topic: string;
+    /** All current subscribers with their metadata. */
+    subscribers: PresenceEntry[];
+}
+/** Metadata for a processed media file. */
+export interface MediaInfo {
+    /** Unique media identifier. */
+    mediaId: string;
+    /** Product that uploaded this media. */
+    productName: string;
+    /** Original filename from the upload. */
+    originalFilename: string;
+    /** MIME type of the original file. */
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+    /** Duration in seconds (audio/video only). */
+    duration?: number;
+    /** Width × height in pixels (image/video only). */
+    dimensions?: [number, number];
+    /** Whether the file was transcoded from its original format. */
+    transcoded: boolean;
+    /** Processing status. */
+    status: 'processing' | 'ready' | 'error';
+    /** ISO 8601 timestamp when the media was uploaded. */
+    createdAt: string;
+}
+/** Notification that a media file has been processed and is ready. */
+export interface MediaReadyEvent {
+    /** Unique media identifier. */
+    mediaId: string;
+    /** MIME type of the original file. */
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+    /** Duration in seconds (audio/video only). */
+    duration?: number;
+    /** Width × height in pixels (image/video only). */
+    dimensions?: [number, number];
+}
+/** Notification that media processing failed. */
+export interface MediaErrorEvent {
+    /** Media identifier that failed. */
+    mediaId: string;
+    /** Human-readable error description. */
+    error: string;
+}
+/**
+ * Supported transcode target formats for media uploads.
+ * Sent as the `transcode` field in the upload form.
+ */
+export type TranscodeTarget = 'audio/mp3' | 'video/mp4' | 'image/webp';
+/**
+ * Role assigned to a peer in a broadcast room.
+ * - `participant` — full bidirectional WebRTC (can publish and receive media)
+ * - `viewer` — receive-only (WHEP or LL-HLS, cannot publish)
+ */
+export type HallPeerRole = 'participant' | 'viewer';
+/** A viewer was promoted to full participant. */
+export interface PeerPromotedEvent {
+    roomId: string;
+    peerId: string;
+}
+/** A participant was demoted to viewer. */
+export interface PeerDemotedEvent {
+    roomId: string;
+    peerId: string;
+}
+/** Periodic viewer count update for broadcast rooms (every ~5s). */
+export interface ViewerCountEvent {
+    roomId: string;
+    /** Number of full bidirectional participants. */
+    participants: number;
+    /** Number of WHEP (sub-second latency) viewers. */
+    whepViewers: number;
+    /** Number of LL-HLS viewers. */
+    hlsViewers: number;
+}
+/**
+ * Screen share simulcast mode.
+ * - `static` — prioritize resolution (presentations, documents)
+ * - `motion` — prioritize framerate (demos, video playback)
+ */
+export type ScreenShareMode = 'static' | 'motion';
+/** Periodic thumbnail of an active screen share. */
+export interface ScreenShareThumbnailEvent {
+    roomId: string;
+    peerId: string;
+    /** URL to the latest thumbnail image. */
+    thumbnailUrl: string;
+}
+/** A single chat message in room history. */
+export interface ChatMessage {
+    /** Peer who sent the message. */
+    peerId: string;
+    /** Message text. */
+    text: string;
+    /** Unix timestamp in milliseconds. */
+    timestampMs: number;
+}
+/** Response to a `getChatHistory` request. */
+export interface ChatHistoryEvent {
+    roomId: string;
+    /** Chat messages in chronological order. */
+    messages: ChatMessage[];
+}
+/**
+ * Sent to a browser client when their role changes (promoted or demoted).
+ * The SDK handles transport upgrade/downgrade transparently.
+ */
+export interface RoleChangedEvent {
+    /** New role: `"participant"` or `"viewer"`. */
+    role: HallPeerRole;
+    /** Whether the peer can now publish media tracks. */
+    canPublish: boolean;
+}
 /**
  * Messages sent from the product backend to the Hall server over the product WebSocket.
  * Encoded as msgpack with `t` (type tag) and `d` (data) fields — matching Rust serde
@@ -179,6 +412,7 @@ export type HallClientMessage = {
         roomId: string;
         peerId: string;
         ttlSecs?: number | undefined;
+        role?: HallPeerRole | undefined;
     };
 } | {
     t: 'startRecording';
@@ -197,6 +431,60 @@ export type HallClientMessage = {
         channel: string;
         payload: Uint8Array;
     };
+} | {
+    t: 'subscribeTopic';
+    d: {
+        topic: string;
+        metadata?: Record<string, unknown> | undefined;
+    };
+} | {
+    t: 'unsubscribeTopic';
+    d: {
+        topic: string;
+    };
+} | {
+    t: 'broadcastTopic';
+    d: {
+        topic: string;
+        payload: unknown;
+    };
+} | {
+    t: 'getPresence';
+    d: {
+        topic: string;
+    };
+} | {
+    t: 'createPubsubToken';
+    d: {
+        peerId: string;
+        allowedTopics?: string[] | undefined;
+        ttlSecs?: number | undefined;
+    };
+} | {
+    t: 'promotePeer';
+    d: {
+        roomId: string;
+        peerId: string;
+    };
+} | {
+    t: 'demotePeer';
+    d: {
+        roomId: string;
+        peerId: string;
+    };
+} | {
+    t: 'setScreenShareMode';
+    d: {
+        roomId: string;
+        peerId: string;
+        mode: ScreenShareMode;
+    };
+} | {
+    t: 'getChatHistory';
+    d: {
+        roomId: string;
+        lastN?: number | undefined;
+    };
 };
 /**
  * Messages sent from the Hall server to the product backend.
@@ -276,6 +564,48 @@ export type HallServerMessage = {
 } | {
     t: 'peerLeft';
     d: PeerLeftEvent;
+} | {
+    t: 'topicSubscribed';
+    d: TopicSubscribedEvent;
+} | {
+    t: 'topicUnsubscribed';
+    d: TopicUnsubscribedEvent;
+} | {
+    t: 'topicMessage';
+    d: TopicMessageEvent;
+} | {
+    t: 'presenceUpdate';
+    d: PresenceUpdateEvent;
+} | {
+    t: 'presenceSnapshot';
+    d: PresenceSnapshotEvent;
+} | {
+    t: 'pubsubToken';
+    d: {
+        token: string;
+        expiresAt: number;
+    };
+} | {
+    t: 'mediaReady';
+    d: MediaReadyEvent;
+} | {
+    t: 'mediaError';
+    d: MediaErrorEvent;
+} | {
+    t: 'peerPromoted';
+    d: PeerPromotedEvent;
+} | {
+    t: 'peerDemoted';
+    d: PeerDemotedEvent;
+} | {
+    t: 'viewerCount';
+    d: ViewerCountEvent;
+} | {
+    t: 'screenShareThumbnail';
+    d: ScreenShareThumbnailEvent;
+} | {
+    t: 'chatHistory';
+    d: ChatHistoryEvent;
 };
 /** Event map for server-side {@link HallRoom} listeners. */
 export interface HallRoomEvents {
@@ -286,6 +616,13 @@ export interface HallRoomEvents {
     peerJoined: PeerJoinedEvent;
     peerLeft: PeerLeftEvent;
     recordingManifest: RecordingManifest;
+    peerPromoted: PeerPromotedEvent;
+    peerDemoted: PeerDemotedEvent;
+    viewerCount: ViewerCountEvent;
+    screenShareThumbnail: ScreenShareThumbnailEvent;
+    chatHistory: ChatHistoryEvent;
+    mediaReady: MediaReadyEvent;
+    mediaError: MediaErrorEvent;
     closed: {
         roomId: string;
     };
@@ -293,9 +630,9 @@ export interface HallRoomEvents {
 /**
  * The `sdk.hall` namespace on `SoulcraftSDK` in **server mode**.
  *
- * Products call these methods in request handlers to create rooms and issue session
- * tokens that browser clients use to join. Rooms are managed by the Hall server;
- * the product only holds a control-plane connection over WebSocket.
+ * Products call these methods in request handlers to create rooms, manage pub/sub
+ * topics, upload media, and issue session tokens. Rooms and topics are managed by
+ * the Hall server; the product only holds a control-plane connection over WebSocket.
  *
  * Obtain via `createHallModule(options)` from `@soulcraft/sdk/server`.
  *
@@ -330,11 +667,27 @@ export interface HallModule {
      * @throws {Error} If auth fails or the connection cannot be established.
      */
     connect(): Promise<void>;
+    /**
+     * Registers a listener for unexpected disconnects (not triggered by `close()`).
+     *
+     * @param listener - Called with a human-readable disconnect reason.
+     */
+    onDisconnect(listener: (reason: string) => void): void;
+    /**
+     * Registers a listener for successful reconnections.
+     * On reconnect, rooms from before the disconnect are gone — re-create them.
+     */
+    onReconnect(listener: () => void): void;
+    /**
+     * Gracefully closes the Hall connection and releases resources.
+     * Called automatically by `sdk.shutdown()` in server mode.
+     */
+    close(): Promise<void>;
     /**
      * Creates a new room. Errors if a room with the same ID already exists.
      *
      * @param roomId - Unique room identifier (e.g. Brainy session entity ID).
-     * @param options - Room options: peer limit, transcription, recording, concept list.
+     * @param options - Room options: peer limit, transcription, recording, broadcast, concept list.
      * @returns The HallRoom handle — register event listeners on it immediately.
      */
     createRoom(roomId: string, options?: RoomOptions): Promise<HallRoom>;
@@ -357,15 +710,16 @@ export interface HallModule {
      */
     getRoom(roomId: string): HallRoom | undefined;
     /**
-     * Mints a short-lived session token for a browser client.
+     * Mints a short-lived session token for a browser client to join a room.
      * Pass `{ token, hallUrl }` to the browser — never the product secret.
      *
      * @param roomId - The room the browser will join.
      * @param peerId - The peer's unique identifier (e.g. authenticated user ID).
      * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @param role - Optional role hint: `"participant"`, `"viewer"`, or undefined (auto).
      * @returns `{ token, expiresAt }`.
      */
-    createSessionToken(roomId: string, peerId: string, ttlSecs?: number): Promise<{
+    createSessionToken(roomId: string, peerId: string, ttlSecs?: number, role?: HallPeerRole): Promise<{
         token: string;
         expiresAt: number;
     }>;
@@ -384,21 +738,91 @@ export interface HallModule {
      */
     stopRecording(roomId: string): Promise<void>;
     /**
-     * Registers a listener for unexpected disconnects (not triggered by `close()`).
+     * Subscribe to a pub/sub topic. Topics are product-scoped — no cross-product visibility.
+     * The returned event fires on the connection-level `onTopicSubscribed` listener.
      *
-     * @param listener - Called with a human-readable disconnect reason.
+     * @param topic - Topic name to subscribe to.
+     * @param metadata - Optional presence metadata visible to other subscribers.
      */
-    onDisconnect(listener: (reason: string) => void): void;
+    subscribeTopic(topic: string, metadata?: Record<string, unknown>): void;
     /**
-     * Registers a listener for successful reconnections.
-     * On reconnect, rooms from before the disconnect are gone — re-create them.
+     * Unsubscribe from a pub/sub topic.
+     *
+     * @param topic - Topic name to unsubscribe from.
      */
-    onReconnect(listener: () => void): void;
+    unsubscribeTopic(topic: string): void;
     /**
-     * Gracefully closes the Hall connection and releases resources.
-     * Called automatically by `sdk.shutdown()` in server mode.
+     * Broadcast a message to all subscribers of a pub/sub topic.
+     *
+     * @param topic - Topic to broadcast to.
+     * @param payload - Arbitrary JSON payload delivered to all subscribers.
      */
-    close(): Promise<void>;
+    broadcastTopic(topic: string, payload: unknown): void;
+    /**
+     * Request a snapshot of all current subscribers on a topic.
+     * The result fires on the connection-level `onPresenceSnapshot` listener.
+     *
+     * @param topic - Topic to query presence for.
+     */
+    getPresence(topic: string): void;
+    /**
+     * Register a listener for pub/sub events on the product connection.
+     *
+     * @param event - The pub/sub event name.
+     * @param listener - Callback invoked with the typed event payload.
+     */
+    onPubsub<K extends keyof HallPubsubEvents>(event: K, listener: (data: HallPubsubEvents[K]) => void): void;
+    /**
+     * Issue a browser pub/sub token. The browser uses this to connect to
+     * `wss://hall.soulcraft.com/ws/pubsub/{token}` for client-side pub/sub.
+     *
+     * @param peerId - Peer ID the token is issued for.
+     * @param allowedTopics - Optional topic whitelist. If omitted, grants access to all topics.
+     * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @returns `{ token, expiresAt }`.
+     */
+    createPubsubToken(peerId: string, allowedTopics?: string[], ttlSecs?: number): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Promote a viewer to a full bidirectional participant in a broadcast room.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to promote.
+     */
+    promotePeer(roomId: string, peerId: string): void;
+    /**
+     * Demote a participant to a receive-only viewer in a broadcast room.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to demote.
+     */
+    demotePeer(roomId: string, peerId: string): void;
+    /**
+     * Set the screen share simulcast strategy for a peer.
+     *
+     * @param roomId - Room containing the screensharing peer.
+     * @param peerId - Peer sharing their screen.
+     * @param mode - `"static"` (prioritize resolution) or `"motion"` (prioritize framerate).
+     */
+    setScreenShareMode(roomId: string, peerId: string, mode: ScreenShareMode): void;
+    /**
+     * Request historical chat messages for a room.
+     * Chat is also bridged to pub/sub topic `room:{roomId}:chat` with replay buffer.
+     *
+     * @param roomId - Room to get chat history for.
+     * @param lastN - Maximum number of recent messages to return (default: all stored).
+     */
+    getChatHistory(roomId: string, lastN?: number): void;
+}
+/** Event map for pub/sub events on the server-side Hall connection. */
+export interface HallPubsubEvents {
+    topicSubscribed: TopicSubscribedEvent;
+    topicUnsubscribed: TopicUnsubscribedEvent;
+    topicMessage: TopicMessageEvent;
+    presenceUpdate: PresenceUpdateEvent;
+    presenceSnapshot: PresenceSnapshotEvent;
 }
 /**
  * A handle for a live Hall room, returned by `sdk.hall.createRoom()`.
@@ -408,10 +832,14 @@ export interface HallModule {
  *
  * @example
  * ```typescript
- * const room = await hall.createRoom('cohort-123', { enableTranscription: true })
+ * const room = await hall.createRoom('cohort-123', {
+ *   enableTranscription: true,
+ *   allowBroadcast: true,
+ * })
  * room.on('transcript', (t) => console.log(`${t.peerId}: ${t.text}`))
  * room.on('conceptMention', (c) => brain.relate({ from: c.peerId, to: c.nodeId }))
  * room.on('peerJoined', (p) => updatePresence(p.peerId, 'joined'))
+ * room.on('viewerCount', (v) => updateDashboard(v.participants, v.whepViewers + v.hlsViewers))
  * ```
  */
 export interface HallRoom {
@@ -462,6 +890,8 @@ export interface HallRoomHandleEvents {
         peerId: string;
         track: MediaStreamTrack;
     };
+    /** Role changed (promoted or demoted in a broadcast room). */
+    roleChanged: RoleChangedEvent;
     /** The Hall server closed the room. */
     closed: {
         roomId: string;
@@ -478,6 +908,9 @@ export interface HallRoomHandleEvents {
  * (transcript, conceptMention, relationProposed) alongside media track events
  * so kit apps have a single event surface for the full session experience.
  *
+ * In broadcast rooms, the `roleChanged` event fires when the peer is promoted
+ * or demoted. The SDK handles transport upgrade/downgrade transparently.
+ *
  * @example
  * ```typescript
  * const room = await joinHallRoom({ token, hallUrl: 'wss://hall.soulcraft.com' })
@@ -489,7 +922,7 @@ export interface HallRoomHandleEvents {
  * room.on('transcript', ({ peerId, text, isFinal }) => {
  *   if (isFinal) appendTranscript(peerId, text)
  * })
- * room.on('conceptMention', ({ nodeId, confidence }) => pulseGraphNode(nodeId, confidence))
+ * room.on('roleChanged', ({ role, canPublish }) => updateUI(role, canPublish))
  * ```
  */
 export interface HallRoomHandle {
@@ -497,6 +930,10 @@ export interface HallRoomHandle {
     readonly roomId: string;
     /** The peer ID for this connection (decoded from the session token). */
     readonly peerId: string;
+    /** The assigned role in the room. Updated when `roleChanged` fires. */
+    readonly role: HallPeerRole;
+    /** Whether this peer can publish media tracks. Updated when `roleChanged` fires. */
+    readonly canPublish: boolean;
     /**
      * Register a listener for a room event.
      *
@@ -524,4 +961,90 @@ export interface HallRoomHandle {
      */
     close(): void;
 }
+/** Events emitted by a `HallPubsubHandle` in the browser. */
+export interface HallPubsubHandleEvents {
+    /** Topic subscription confirmed. */
+    topicSubscribed: TopicSubscribedEvent;
+    /** Topic unsubscription confirmed. */
+    topicUnsubscribed: TopicUnsubscribedEvent;
+    /** Message received on a subscribed topic. */
+    topicMessage: TopicMessageEvent;
+    /** A subscriber joined or left a topic. */
+    presenceUpdate: PresenceUpdateEvent;
+    /** Full presence snapshot for a topic. */
+    presenceSnapshot: PresenceSnapshotEvent;
+    /** A connection or protocol error occurred. */
+    error: {
+        code: string;
+        message: string;
+    };
+    /** The pub/sub connection was closed. */
+    closed: void;
+}
+/**
+ * An active pub/sub connection to Hall, returned by `joinHallPubsub()`.
+ *
+ * Wraps a WebSocket connection to `wss://hall.soulcraft.com/ws/pubsub/{token}`.
+ * Uses msgpack wire format, same as the product WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { joinHallPubsub } from '@soulcraft/sdk/client'
+ *
+ * const pubsub = await joinHallPubsub({ token, hallUrl: 'wss://hall.soulcraft.com' })
+ * pubsub.subscribe('room:abc:chat', { username: 'Alice' })
+ * pubsub.on('topicMessage', ({ topic, senderId, payload }) => showMessage(senderId, payload))
+ * pubsub.on('presenceUpdate', ({ peerId, action }) => updatePresence(peerId, action))
+ *
+ * pubsub.broadcast('room:abc:chat', { text: 'Hello!' })
+ * // On leave:
+ * pubsub.close()
+ * ```
+ */
+export interface HallPubsubHandle {
+    /** The peer ID for this connection (decoded from the pubsub token). */
+    readonly peerId: string;
+    /**
+     * Subscribe to a pub/sub topic.
+     *
+     * @param topic - Topic name to subscribe to.
+     * @param metadata - Optional presence metadata visible to other subscribers.
+     */
+    subscribe(topic: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Unsubscribe from a pub/sub topic.
+     *
+     * @param topic - Topic name to unsubscribe from.
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Broadcast a message to all subscribers of a topic.
+     *
+     * @param topic - Topic to broadcast to.
+     * @param payload - Arbitrary JSON payload delivered to all subscribers.
+     */
+    broadcast(topic: string, payload: unknown): void;
+    /**
+     * Request a presence snapshot for a topic.
+     *
+     * @param topic - Topic to query presence for.
+     */
+    getPresence(topic: string): void;
+    /**
+     * Register a listener for a pub/sub event.
+     *
+     * @param event - The event name.
+     * @param listener - Callback invoked with the typed event payload.
+     */
+    on<K extends keyof HallPubsubHandleEvents>(event: K, listener: (data: HallPubsubHandleEvents[K]) => void): this;
+    /**
+     * Remove a previously registered listener.
+     *
+     * @param event - The event name.
+     * @param listener - The exact function reference passed to `on`.
+     */
+    off<K extends keyof HallPubsubHandleEvents>(event: K, listener: (data: HallPubsubHandleEvents[K]) => void): this;
+    /** Disconnect the pub/sub WebSocket. */
+    close(): void;
+}
 //# sourceMappingURL=types.d.ts.map