@abraca/dabra 1.6.0 → 1.8.1

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/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

@@ -348,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;
+}

package/src/webrtc/DevicePairingChannel.ts

@@ -77,11 +77,15 @@ interface PairRequestMsg {
 
 interface PairApprovedMsg {
 	type: "pair-approved";
+	/** Approver's account-level Ed25519 public key (base64url). */
+	masterPublicKey?: string;
 }
 
 interface PairInviteCodeMsg {
 	type: "pair-invite-code";
 	code: string;
+	/** Approver's account-level Ed25519 public key (base64url). */
+	masterPublicKey?: string;
 }
 
 interface PairRejectedMsg {
@@ -171,8 +175,12 @@ export 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.
 	 */
-	async approve(client: AbracadabraClient): Promise<PairingResult> {
+	async approve(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult> {
 		if (this.role !== "approver") {
 			return { success: false, error: "Only the approver can approve" };
 		}
@@ -192,7 +200,7 @@ export class DevicePairingChannel extends EventEmitter {
 				x25519Key: req.x25519Key,
 			});
 
-			this.sendMessage({ type: "pair-approved" });
+			this.sendMessage({ type: "pair-approved", masterPublicKey });
 			this._pendingRequest = null;
 			this.emit("pairingComplete", { success: true } as PairingResult);
 			return { success: true };
@@ -210,8 +218,12 @@ export class DevicePairingChannel extends EventEmitter {
 	 * 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.
 	 */
-	async approveWithInvite(client: AbracadabraClient): Promise<PairingResult> {
+	async approveWithInvite(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult> {
 		if (this.role !== "approver") {
 			return { success: false, error: "Only the approver can approve" };
 		}
@@ -224,7 +236,7 @@ export class DevicePairingChannel extends EventEmitter {
 
 		try {
 			const { code } = await client.createDeviceInvite();
-			this.sendMessage({ type: "pair-invite-code", code });
+			this.sendMessage({ type: "pair-invite-code", code, masterPublicKey });
 			this._pendingRequest = null;
 			this.emit("pairingComplete", { success: true } as PairingResult);
 			return { success: true };
@@ -462,7 +474,7 @@ export class DevicePairingChannel extends EventEmitter {
 
 			case "pair-approved":
 				if (this.role !== "requester") return;
-				this.emit("approved");
+				this.emit("approved", { masterPublicKey: msg.masterPublicKey });
 				this.emit("pairingComplete", { success: true } as PairingResult);
 				break;
 
@@ -477,7 +489,7 @@ export class DevicePairingChannel extends EventEmitter {
 
 			case "pair-invite-code":
 				if (this.role !== "requester") return;
-				this.emit("inviteCode", msg.code);
+				this.emit("inviteCode", msg.code, msg.masterPublicKey);
 				break;
 		}
 	}