@abraca/dabra 1.5.0 → 1.8.0

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;
+    }
+  }
+}

package/src/TreeTimestamps.ts

@@ -8,47 +8,78 @@
  * This propagates "last edited" timestamps to all peers via the root CRDT,
  * without requiring any server-side changes.
  *
- * Limitation: at least one client must have the child doc open after an edit
- * for the timestamp to propagate (eventually consistent).
+ * A trailing-edge throttle (default 5 s) limits writes to avoid CRDT bloat
+ * on the root doc during rapid typing.
  */
 
 import * as Y from "yjs";
 import type { OfflineStore } from "./OfflineStore.ts";
 
 /**
- * Attach an observer that writes `updatedAt: Date.now()` to the root
- * doc-tree entry for `childDocId` whenever the child doc receives a
- * non-offline update.
+ * Attach an observer that writes `updatedAt` to the root doc-tree entry for
+ * `childDocId` whenever the child doc receives a non-offline update.
  *
- * @param treeMap     The root doc's "doc-tree" Y.Map.
- * @param childDocId  The child document's UUID (key in treeMap).
- * @param childDoc    The child Y.Doc to observe.
+ * Writes are throttled: the first qualifying update records the timestamp;
+ * a trailing-edge timer flushes it to the tree map after `throttleMs`.
+ *
+ * @param treeMap       The root doc's "doc-tree" Y.Map.
+ * @param childDocId    The child document's UUID (key in treeMap).
+ * @param childDoc      The child Y.Doc to observe.
  * @param offlineStore  The child provider's OfflineStore (used to detect
  *                      offline-replay origins and skip them). Pass null when
  *                      the offline store is disabled.
- * @returns           Cleanup function — call on provider destroy.
+ * @param options       Optional config. `throttleMs` controls the write
+ *                      interval (default 5000).
+ * @returns             Cleanup function — call on provider destroy.  Flushes
+ *                      any pending write before detaching.
  */
 export function attachUpdatedAtObserver(
 	treeMap: Y.Map<any>,
 	childDocId: string,
 	childDoc: Y.Doc,
 	offlineStore: OfflineStore | null,
+	options?: { throttleMs?: number },
 ): () => void {
-	function handler(update: Uint8Array, origin: unknown): void {
-		// Skip updates replayed from the local offline store — they represent
-		// content that was already "seen" and shouldn't advance updatedAt.
-		if (offlineStore !== null && origin === offlineStore) return;
+	const throttleMs = options?.throttleMs ?? 5000;
+
+	let latestTs = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	function flush(): void {
+		if (latestTs === 0) return;
+		const ts = latestTs;
+		latestTs = 0;
+		timer = null;
 
-		// Update the root tree entry (no-op if the entry doesn't exist).
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
 
 		// Guard: if the entry is a nested Y.Map (possible after Yrs
 		// document compaction), convert to plain object so spread works.
 		const entry = raw instanceof Y.Map ? (raw as any).toJSON() : raw;
-		treeMap.set(childDocId, { ...entry, updatedAt: Date.now() });
+		treeMap.set(childDocId, { ...entry, updatedAt: ts });
+	}
+
+	function handler(_update: Uint8Array, origin: unknown): void {
+		// Skip updates replayed from the local offline store — they represent
+		// content that was already "seen" and shouldn't advance updatedAt.
+		if (offlineStore !== null && origin === offlineStore) return;
+
+		latestTs = Date.now();
+
+		// Schedule a trailing-edge flush if none is pending.
+		if (timer === null) {
+			timer = setTimeout(flush, throttleMs);
+		}
 	}
 
 	childDoc.on("update", handler);
-	return () => childDoc.off("update", handler);
+
+	return () => {
+		childDoc.off("update", handler);
+		if (timer !== null) {
+			clearTimeout(timer);
+			flush(); // persist the last pending timestamp
+		}
+	};
 }

package/src/index.ts

@@ -36,6 +36,22 @@ export type {
 	DeviceTier,
 } from "./IdentityDoc.ts";
 export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";
+export { ChatClient } from "./ChatClient.ts";
+export type { ChatClientTransport } from "./ChatClient.ts";
+export { NotificationsClient } from "./NotificationsClient.ts";
+export type {
+	ChatMessage,
+	ChatChannel,
+	ChatTypingEvent,
+	ChatReadReceipt,
+	ChatReadCursor,
+	SendChatMessageInput,
+	GetChatHistoryInput,
+	NotificationRecord,
+	NotificationReadUpdate,
+	CreateNotificationInput,
+	FetchNotificationsInput,
+} from "./types.ts";
 export {
 	generateMnemonic,
 	validateMnemonic,

package/src/types.ts

@@ -124,6 +124,12 @@ export type onStatelessParameters = {
   payload: string;
 };
 
+export type onServerErrorParameters = {
+  source: string;
+  code: string;
+  message: string;
+};
+
 export type StatesArray = { clientId: number; [key: string | number]: any }[];
 
 // ── Abracadabra extensions ────────────────────────────────────────────────────
@@ -342,3 +348,89 @@ export interface DocEncryptionInfo {
   effective_mode: "none" | "cse" | "e2e";
   inherited_from?: string;
 }
+
+// ── Chat (stateless channel) ─────────────────────────────────────────────────
+
+export interface ChatMessage {
+  id: string;
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+  content: string;
+  created_at: number;
+}
+
+export interface ChatChannel {
+  channel: string;
+  label?: string | null;
+  last_message: ChatMessage;
+  unread_count: number;
+}
+
+export interface ChatTypingEvent {
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+}
+
+export interface ChatReadReceipt {
+  channel: string;
+  user_id: string;
+  last_read_at: number;
+}
+
+export interface ChatReadCursor {
+  user_id: string;
+  last_read_at: number;
+}
+
+export interface SendChatMessageInput {
+  channel: string;
+  content: string;
+  sender_name?: string;
+}
+
+export interface GetChatHistoryInput {
+  channel: string;
+  before?: number;
+  limit?: number;
+}
+
+// ── Notifications (stateless channel) ────────────────────────────────────────
+
+export 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;
+}
+
+export 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;
+}
+
+export interface CreateNotificationInput {
+  recipient_id: string;
+  notification_type?: string;
+  title: string;
+  body?: string;
+  icon?: string;
+  link?: string;
+  source_id?: string;
+}
+
+export interface FetchNotificationsInput {
+  before?: number;
+  limit?: number;
+  unread_only?: boolean;
+}