@abraca/dabra 1.6.0 → 1.8.0

package/dist/index.d.ts

@@ -1344,6 +1344,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 & {
@@ -2534,14 +2605,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 +2840,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 +2911,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 +3083,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.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

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).

package/src/NotificationsClient.ts

@@ -0,0 +1,185 @@
+import EventEmitter from "./EventEmitter.ts";
+import type {
+  CreateNotificationInput,
+  FetchNotificationsInput,
+  NotificationReadUpdate,
+  NotificationRecord,
+} from "./types.ts";
+import type { ChatClientTransport } from "./ChatClient.ts";
+
+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 notifications feature.
+ *
+ * Emits:
+ *   - `new`        → NotificationRecord      (incoming notify:new broadcast)
+ *   - `readUpdate` → NotificationReadUpdate  (broadcast after mark_read / mark_all_read)
+ */
+export class NotificationsClient extends EventEmitter {
+  private readonly provider: ChatClientTransport;
+  private readonly responseTimeoutMs: number;
+  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);
+  }
+
+  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("NotificationsClient destroyed"));
+      }
+    }
+    this.pending.clear();
+    this.removeAllListeners();
+  }
+
+  // ── Outgoing requests ──────────────────────────────────────────────────────
+
+  /**
+   * 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 {
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "notify:create",
+        recipient_id: input.recipient_id,
+        ...(input.notification_type !== undefined ? { notification_type: input.notification_type } : {}),
+        title: input.title,
+        ...(input.body !== undefined ? { body: input.body } : {}),
+        ...(input.icon !== undefined ? { icon: input.icon } : {}),
+        ...(input.link !== undefined ? { link: input.link } : {}),
+        ...(input.source_id !== undefined ? { source_id: input.source_id } : {}),
+      }),
+    );
+  }
+
+  /** Fetch notification history for the current user. */
+  fetch(input: FetchNotificationsInput = {}): Promise<{ notifications: NotificationRecord[] }> {
+    const promise = this.enqueue<{ notifications: NotificationRecord[] }>("notify:history");
+    this.provider.sendStateless(
+      JSON.stringify({
+        type: "notify:fetch",
+        ...(input.before !== undefined ? { before: input.before } : {}),
+        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        ...(input.unread_only !== undefined ? { unread_only: input.unread_only } : {}),
+      }),
+    );
+    return promise;
+  }
+
+  /** Mark a single notification, or a batch, as read. */
+  markRead(target: { id: string } | { ids: string[] }): void {
+    const body: Record<string, unknown> = { type: "notify:mark_read" };
+    if ("id" in target) body.id = target.id;
+    else body.ids = target.ids;
+    this.provider.sendStateless(JSON.stringify(body));
+  }
+
+  /** Mark every notification for the current user as read. */
+  markAllRead(): void {
+    this.provider.sendStateless(JSON.stringify({ type: "notify:mark_all_read" }));
+  }
+
+  /** Mark all notifications generated by the given source (e.g. a chat channel) as read. */
+  markReadBySource(sourceId: string): void {
+    this.provider.sendStateless(
+      JSON.stringify({ type: "notify:mark_read_by_source", source_id: sourceId }),
+    );
+  }
+
+  // ── Event helpers ─────────────────────────────────────────────────────────
+
+  onNew(fn: (n: NotificationRecord) => void): this {
+    return this.on("new", fn) as this;
+  }
+
+  onReadUpdate(fn: (u: NotificationReadUpdate) => void): this {
+    return this.on("readUpdate", 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(`NotificationsClient: 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("notify:")) return;
+
+    switch (type) {
+      case "notify:new": {
+        const { type: _t, ...rest } = parsed;
+        this.emit("new", rest as NotificationRecord);
+        break;
+      }
+      case "notify:history": {
+        this.resolveNext("notify:history", {
+          notifications: parsed.notifications ?? [],
+        });
+        break;
+      }
+      case "notify:read_update": {
+        const update: NotificationReadUpdate = {
+          recipient_id: parsed.recipient_id,
+        };
+        if (parsed.ids !== undefined) update.ids = parsed.ids;
+        if (parsed.all !== undefined) update.all = parsed.all;
+        this.emit("readUpdate", update);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}