@abraca/dabra 1.6.0 → 1.8.1

package/dist/index.d.ts

@@ -826,6 +826,13 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    * the offline store is disabled or when no snapshot has been saved yet.
    */
   readonly ready: Promise<void>;
+  /**
+   * True once `_initFromOfflineStore()` has applied a non-empty snapshot or
+   * at least one pending update to the Y.Doc. Lets the UI decide to render
+   * cached content immediately instead of waiting for a server round-trip.
+   * Only meaningful after `await ready`.
+   */
+  hasCachedContent: boolean;
   constructor(configuration: AbracadabraProviderConfiguration);
   /**
    * Extract the server hostname from the provider configuration.
@@ -1344,6 +1351,77 @@ interface DocEncryptionInfo {
   effective_mode: "none" | "cse" | "e2e";
   inherited_from?: string;
 }
+interface ChatMessage {
+  id: string;
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+  content: string;
+  created_at: number;
+}
+interface ChatChannel {
+  channel: string;
+  label?: string | null;
+  last_message: ChatMessage;
+  unread_count: number;
+}
+interface ChatTypingEvent {
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+}
+interface ChatReadReceipt {
+  channel: string;
+  user_id: string;
+  last_read_at: number;
+}
+interface ChatReadCursor {
+  user_id: string;
+  last_read_at: number;
+}
+interface SendChatMessageInput {
+  channel: string;
+  content: string;
+  sender_name?: string;
+}
+interface GetChatHistoryInput {
+  channel: string;
+  before?: number;
+  limit?: number;
+}
+interface NotificationRecord {
+  id: string;
+  recipient_id: string;
+  notification_type: string;
+  title: string;
+  body: string;
+  icon?: string | null;
+  link?: string | null;
+  source_id?: string | null;
+  read: boolean;
+  created_at: number;
+}
+interface NotificationReadUpdate {
+  /** Present when a specific set of notifications was marked read. */
+  ids?: string[];
+  /** Present when mark_all_read was called. */
+  all?: boolean;
+  recipient_id: string;
+}
+interface CreateNotificationInput {
+  recipient_id: string;
+  notification_type?: string;
+  title: string;
+  body?: string;
+  icon?: string;
+  link?: string;
+  source_id?: string;
+}
+interface FetchNotificationsInput {
+  before?: number;
+  limit?: number;
+  unread_only?: boolean;
+}
 //#endregion
 //#region packages/provider/src/AbracadabraWS.d.ts
 type AbracadabraWebSocketConn = WebSocket & {
@@ -1375,7 +1453,14 @@ interface CompleteAbracadabraWSConfiguration {
    */
   WebSocketPolyfill: any;
   /**
-   * Disconnect when no message is received for the defined amount of milliseconds.
+   * Disconnect and reconnect when no message is received for the defined amount
+   * of milliseconds.
+   *
+   * Defaults to 30000 ms to match y-protocols/awareness `Awareness.outdatedTime`
+   * (also 30 s). Awareness heartbeats are what normally keep this timer
+   * resetting, so this value should be ≥ the largest `outdatedTime` of any
+   * awareness instance attached to this socket. If you pass a custom awareness
+   * with a non-default `outdatedTime`, pass the matching value here too.
    */
   messageReconnectTimeout: number;
   /**
@@ -2534,14 +2619,22 @@ declare class DevicePairingChannel extends EventEmitter {
   /**
    * Approve the pending pairing request. Calls `client.addKey()` to
    * register Device B's public key, then notifies Device B.
+   *
+   * @param client Authenticated REST client.
+   * @param masterPublicKey Approver's account-level Ed25519 public key (base64url).
+   *   Sent to Device B so it can adopt the master's identity doc.
    */
-  approve(client: AbracadabraClient): Promise<PairingResult>;
+  approve(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult>;
   /**
    * Approve via server-side device invite. Creates a single-use invite code
    * and sends it to Device B over the E2EE channel. Device B redeems it
    * independently via HTTP — Device A can go offline after this.
+   *
+   * @param client Authenticated REST client.
+   * @param masterPublicKey Approver's account-level Ed25519 public key (base64url).
+   *   Sent to Device B so it can adopt the master's identity doc.
    */
-  approveWithInvite(client: AbracadabraClient): Promise<PairingResult>;
+  approveWithInvite(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult>;
   /**
    * Reject the pending pairing request.
    */
@@ -2761,6 +2854,12 @@ declare class IdentityDocProvider extends EventEmitter {
    * Call this to decide whether to run migration from localStorage.
    */
   isEmpty(): boolean;
+  /**
+   * Enable WebRTC P2P sync at runtime.
+   * Use this for claimed/passkey users where E2EE identity derivation
+   * was deferred to avoid biometric prompts on page load.
+   */
+  enableWebRTC(webrtcConfig: NonNullable<IdentityDocConfiguration["webrtc"]>): void;
   /**
    * Update the sync server URL at runtime (e.g. when user changes their
    * designated sync server in settings).
@@ -2826,6 +2925,111 @@ declare class DeviceRegistrationService {
   }): Promise<void>;
 }
 //#endregion
+//#region packages/provider/src/ChatClient.d.ts
+/**
+ * Minimal provider surface ChatClient needs. Matches `AbracadabraBaseProvider`.
+ * Kept as an interface so consumers can pass any compatible transport.
+ */
+interface ChatClientTransport {
+  sendStateless(payload: string): void;
+  on(event: string, fn: Function): unknown;
+  off(event: string, fn?: Function): unknown;
+}
+/**
+ * Typed client for the Abracadabra chat feature.
+ *
+ * Wraps a connected provider (or base provider) and translates JSON envelopes
+ * on the stateless channel into typed method calls and events.
+ *
+ * Events emitted:
+ *   - `message`      → ChatMessage       (new message broadcast)
+ *   - `typing`       → ChatTypingEvent   (typing indicator broadcast)
+ *   - `readReceipt`  → ChatReadReceipt   (mark_read broadcast)
+ */
+declare class ChatClient extends EventEmitter {
+  private readonly provider;
+  private readonly responseTimeoutMs;
+  private readonly pending;
+  private readonly boundOnStateless;
+  constructor(provider: ChatClientTransport, options?: {
+    responseTimeoutMs?: number;
+  });
+  /** Stop listening for chat messages. Does not disconnect the underlying provider. */
+  destroy(): void;
+  /** Send a chat message on a channel. Fire-and-forget (the server broadcasts). */
+  sendMessage(input: SendChatMessageInput): void;
+  /** Fetch historical messages for a channel. Resolves with the server response. */
+  getHistory(input: GetChatHistoryInput): Promise<{
+    channel: string;
+    messages: ChatMessage[];
+  }>;
+  /** Broadcast a typing indicator on a channel. */
+  sendTyping(channel: string): void;
+  /** List the current user's channels (ordered by last activity). */
+  listChannels(): Promise<{
+    channels: ChatChannel[];
+  }>;
+  /** Mark a channel read up to `timestamp` (unix ms). */
+  markRead(channel: string, timestamp: number): void;
+  /** Fetch per-user read cursors for a channel. */
+  getReadCursors(channel: string): Promise<{
+    channel: string;
+    cursors: ChatReadCursor[];
+  }>;
+  onMessage(fn: (m: ChatMessage) => void): this;
+  onTyping(fn: (e: ChatTypingEvent) => void): this;
+  onReadReceipt(fn: (e: ChatReadReceipt) => void): this;
+  private enqueue;
+  private removePending;
+  private resolveNext;
+  private handleStateless;
+}
+//#endregion
+//#region packages/provider/src/NotificationsClient.d.ts
+/**
+ * Typed client for the Abracadabra notifications feature.
+ *
+ * Emits:
+ *   - `new`        → NotificationRecord      (incoming notify:new broadcast)
+ *   - `readUpdate` → NotificationReadUpdate  (broadcast after mark_read / mark_all_read)
+ */
+declare class NotificationsClient extends EventEmitter {
+  private readonly provider;
+  private readonly responseTimeoutMs;
+  private readonly pending;
+  private readonly boundOnStateless;
+  constructor(provider: ChatClientTransport, options?: {
+    responseTimeoutMs?: number;
+  });
+  destroy(): void;
+  /**
+   * Create a notification targeting a specific recipient. Requires elevated role
+   * (service or admin); a `server:error` event with code `forbidden` is emitted
+   * by the underlying provider if the caller lacks permission.
+   */
+  create(input: CreateNotificationInput): void;
+  /** Fetch notification history for the current user. */
+  fetch(input?: FetchNotificationsInput): Promise<{
+    notifications: NotificationRecord[];
+  }>;
+  /** Mark a single notification, or a batch, as read. */
+  markRead(target: {
+    id: string;
+  } | {
+    ids: string[];
+  }): void;
+  /** Mark every notification for the current user as read. */
+  markAllRead(): void;
+  /** Mark all notifications generated by the given source (e.g. a chat channel) as read. */
+  markReadBySource(sourceId: string): void;
+  onNew(fn: (n: NotificationRecord) => void): this;
+  onReadUpdate(fn: (u: NotificationReadUpdate) => void): this;
+  private enqueue;
+  private removePending;
+  private resolveNext;
+  private handleStateless;
+}
+//#endregion
 //#region node_modules/@scure/bip39/esm/wordlists/english.d.ts
 declare const wordlist: string[];
 //#endregion
@@ -2893,4 +3097,4 @@ declare function wrapSeed(seed: Uint8Array, wrappingKeyBytes: Uint8Array): Promi
  */
 declare function unwrapSeed(ciphertext: ArrayBuffer, iv: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<Uint8Array>;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, type ChatChannel, ChatClient, type ChatClientTransport, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, type SendChatMessageInput, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.6.0",
+  "version": "1.8.1",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraProvider.ts

@@ -129,6 +129,14 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	 */
 	public readonly ready: Promise<void>;
 
+	/**
+	 * True once `_initFromOfflineStore()` has applied a non-empty snapshot or
+	 * at least one pending update to the Y.Doc. Lets the UI decide to render
+	 * cached content immediately instead of waiting for a server round-trip.
+	 * Only meaningful after `await ready`.
+	 */
+	public hasCachedContent = false;
+
 	constructor(configuration: AbracadabraProviderConfiguration) {
 		// Derive URL and token from client when not explicitly set.
 		const resolved = { ...configuration } as AbracadabraBaseProviderConfiguration;
@@ -225,9 +233,11 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 		if (snapshot) {
 			Y.applyUpdate(this.document, snapshot, this.offlineStore);
+			this.hasCachedContent = true;
 		}
 		for (const update of pending) {
 			Y.applyUpdate(this.document, update, this.offlineStore);
+			this.hasCachedContent = true;
 		}
 	}
 

package/src/AbracadabraWS.ts

@@ -55,7 +55,14 @@ export interface CompleteAbracadabraWSConfiguration {
   WebSocketPolyfill: any;
 
   /**
-   * Disconnect when no message is received for the defined amount of milliseconds.
+   * Disconnect and reconnect when no message is received for the defined amount
+   * of milliseconds.
+   *
+   * Defaults to 30000 ms to match y-protocols/awareness `Awareness.outdatedTime`
+   * (also 30 s). Awareness heartbeats are what normally keep this timer
+   * resetting, so this value should be ≥ the largest `outdatedTime` of any
+   * awareness instance attached to this socket. If you pass a custom awareness
+   * with a non-default `outdatedTime`, pass the matching value here too.
    */
   messageReconnectTimeout: number;
   /**
@@ -121,7 +128,8 @@ export class AbracadabraWS extends EventEmitter {
     // @ts-ignore
     document: undefined,
     WebSocketPolyfill: undefined,
-    // TODO: this should depend on awareness.outdatedTime
+    // Matches y-protocols/awareness Awareness.outdatedTime default (30 s).
+    // See the `messageReconnectTimeout` JSDoc on CompleteAbracadabraWSConfiguration.
     messageReconnectTimeout: 30000,
     // 1 second
     delay: 1000,

package/src/ChatClient.ts

@@ -0,0 +1,234 @@
+import EventEmitter from "./EventEmitter.ts";
+import type {
+  ChatChannel,
+  ChatMessage,
+  ChatReadCursor,
+  ChatReadReceipt,
+  ChatTypingEvent,
+  GetChatHistoryInput,
+  SendChatMessageInput,
+} from "./types.ts";
+
+/**
+ * Minimal provider surface ChatClient needs. Matches `AbracadabraBaseProvider`.
+ * Kept as an interface so consumers can pass any compatible transport.
+ */
+export interface ChatClientTransport {
+  sendStateless(payload: string): void;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  on(event: string, fn: Function): unknown;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  off(event: string, fn?: Function): unknown;
+}
+
+type PendingResolver<T> = {
+  resolve: (value: T) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Typed client for the Abracadabra chat feature.
+ *
+ * Wraps a connected provider (or base provider) and translates JSON envelopes
+ * on the stateless channel into typed method calls and events.
+ *
+ * Events emitted:
+ *   - `message`      → ChatMessage       (new message broadcast)
+ *   - `typing`       → ChatTypingEvent   (typing indicator broadcast)
+ *   - `readReceipt`  → ChatReadReceipt   (mark_read broadcast)
+ */
+export class ChatClient extends EventEmitter {
+  private readonly provider: ChatClientTransport;
+  private readonly responseTimeoutMs: number;
+
+  // FIFO of promises waiting on a particular typed server response. The server
+  // replies on the same socket, one-per-request, so a simple queue per type
+  // matches observed behavior.
+  private readonly pending: Map<string, PendingResolver<any>[]> = new Map();
+
+  private readonly boundOnStateless: (data: { payload: string }) => void;
+
+  constructor(provider: ChatClientTransport, options?: { responseTimeoutMs?: number }) {
+    super();
+    this.provider = provider;
+    this.responseTimeoutMs = options?.responseTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.boundOnStateless = (data) => this.handleStateless(data.payload);
+    this.provider.on("stateless", this.boundOnStateless);
+  }
+
+  /** Stop listening for chat messages. Does not disconnect the underlying provider. */
+  destroy(): void {
+    this.provider.off("stateless", this.boundOnStateless);
+    for (const queue of this.pending.values()) {
+      for (const p of queue) {
+        clearTimeout(p.timer);
+        p.reject(new Error("ChatClient destroyed"));
+      }
+    }
+    this.pending.clear();
+    this.removeAllListeners();
+  }
+
+  // ── Outgoing requests ──────────────────────────────────────────────────────
+
+  /** Send a chat message on a channel. Fire-and-forget (the server broadcasts). */
+  sendMessage(input: SendChatMessageInput): void {
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "chat:send",
+        channel: input.channel,
+        content: input.content,
+        ...(input.sender_name !== undefined ? { sender_name: input.sender_name } : {}),
+      }),
+    );
+  }
+
+  /** Fetch historical messages for a channel. Resolves with the server response. */
+  getHistory(input: GetChatHistoryInput): Promise<{ channel: string; messages: ChatMessage[] }> {
+    const promise = this.enqueue<{ channel: string; messages: ChatMessage[] }>("chat:history");
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "chat:history",
+        channel: input.channel,
+        ...(input.before !== undefined ? { before: input.before } : {}),
+        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+      }),
+    );
+    return promise;
+  }
+
+  /** Broadcast a typing indicator on a channel. */
+  sendTyping(channel: string): void {
+    this.provider.sendStateless(JSON.stringify({ type: "chat:typing", channel }));
+  }
+
+  /** List the current user's channels (ordered by last activity). */
+  listChannels(): Promise<{ channels: ChatChannel[] }> {
+    const promise = this.enqueue<{ channels: ChatChannel[] }>("chat:channels");
+    this.provider.sendStateless(JSON.stringify({ type: "chat:channels" }));
+    return promise;
+  }
+
+  /** Mark a channel read up to `timestamp` (unix ms). */
+  markRead(channel: string, timestamp: number): void {
+    this.provider.sendStateless(
+      JSON.stringify({ type: "chat:mark_read", channel, timestamp }),
+    );
+  }
+
+  /** Fetch per-user read cursors for a channel. */
+  getReadCursors(channel: string): Promise<{ channel: string; cursors: ChatReadCursor[] }> {
+    const promise = this.enqueue<{ channel: string; cursors: ChatReadCursor[] }>(
+      "chat:read_cursors",
+    );
+    this.provider.sendStateless(JSON.stringify({ type: "chat:read_cursors", channel }));
+    return promise;
+  }
+
+  // ── Typed event subscription helpers (optional sugar over EventEmitter) ───
+
+  onMessage(fn: (m: ChatMessage) => void): this {
+    return this.on("message", fn) as this;
+  }
+
+  onTyping(fn: (e: ChatTypingEvent) => void): this {
+    return this.on("typing", fn) as this;
+  }
+
+  onReadReceipt(fn: (e: ChatReadReceipt) => void): this {
+    return this.on("readReceipt", fn) as this;
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────────
+
+  private enqueue<T>(type: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.removePending(type, entry);
+        reject(new Error(`ChatClient: timeout waiting for ${type} response`));
+      }, this.responseTimeoutMs);
+      const entry: PendingResolver<T> = { resolve, reject, timer };
+      const queue = this.pending.get(type) ?? [];
+      queue.push(entry);
+      this.pending.set(type, queue);
+    });
+  }
+
+  private removePending(type: string, entry: PendingResolver<any>): void {
+    const queue = this.pending.get(type);
+    if (!queue) return;
+    const idx = queue.indexOf(entry);
+    if (idx >= 0) queue.splice(idx, 1);
+    if (queue.length === 0) this.pending.delete(type);
+  }
+
+  private resolveNext<T>(type: string, value: T): boolean {
+    const queue = this.pending.get(type);
+    if (!queue || queue.length === 0) return false;
+    const next = queue.shift()!;
+    if (queue.length === 0) this.pending.delete(type);
+    clearTimeout(next.timer);
+    next.resolve(value);
+    return true;
+  }
+
+  private handleStateless(payload: string): void {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    const type: unknown = parsed?.type;
+    if (typeof type !== "string" || !type.startsWith("chat:")) return;
+
+    switch (type) {
+      case "chat:message": {
+        // Server flattens the ChatMessage fields at the top level alongside `type`.
+        const { type: _t, ...rest } = parsed;
+        this.emit("message", rest as ChatMessage);
+        break;
+      }
+      case "chat:history": {
+        this.resolveNext("chat:history", {
+          channel: parsed.channel,
+          messages: parsed.messages ?? [],
+        });
+        break;
+      }
+      case "chat:channels": {
+        this.resolveNext("chat:channels", { channels: parsed.channels ?? [] });
+        break;
+      }
+      case "chat:typing": {
+        this.emit("typing", {
+          channel: parsed.channel,
+          sender_id: parsed.sender_id,
+          sender_name: parsed.sender_name ?? null,
+        } as ChatTypingEvent);
+        break;
+      }
+      case "chat:read_receipt": {
+        this.emit("readReceipt", {
+          channel: parsed.channel,
+          user_id: parsed.user_id,
+          last_read_at: parsed.last_read_at,
+        } as ChatReadReceipt);
+        break;
+      }
+      case "chat:read_cursors": {
+        this.resolveNext("chat:read_cursors", {
+          channel: parsed.channel,
+          cursors: parsed.cursors ?? [],
+        });
+        break;
+      }
+      default:
+        // Unknown chat:* subtype — ignore for forward compat.
+        break;
+    }
+  }
+}

package/src/IdentityDoc.ts

@@ -626,6 +626,17 @@ export class IdentityDocProvider extends EventEmitter {
 
 	// ── Lifecycle ────────────────────────────────────────────────────────────
 
+	/**
+	 * Enable WebRTC P2P sync at runtime.
+	 * Use this for claimed/passkey users where E2EE identity derivation
+	 * was deferred to avoid biometric prompts on page load.
+	 */
+	enableWebRTC(webrtcConfig: NonNullable<IdentityDocConfiguration["webrtc"]>): void {
+		if (this._destroyed || this.webrtc) return;
+		this.config = { ...this.config, webrtc: webrtcConfig };
+		this._connectWebRTC();
+	}
+
 	/**
 	 * Update the sync server URL at runtime (e.g. when user changes their
 	 * designated sync server in settings).