@abraca/dabra 1.8.2 → 2.0.0

package/src/messageRecord.ts

@@ -0,0 +1,121 @@
+/**
+ * Decode + fold message records from a period doc's `messages` Y.Array
+ * into the flat `ChatMessage[]` shape the dashboard renders.
+ *
+ * The server appends three kinds of records to the array (see
+ * `abracadabra-rs/crates/abracadabra/src/messages.rs`):
+ *
+ *   - `record_kind: "message"`     — a real message (default kind).
+ *   - `record_kind: "edit"`        — an updated version of `target_id`.
+ *   - `record_kind: "tombstone"`   — `target_id` is deleted.
+ *
+ * Folding rules:
+ *   - For each `target_id`, apply edits in `ts` order; the *last* edit's
+ *     content wins. The original message's id, sender_id, and ts stay.
+ *     `editedAt` is the latest edit's ts.
+ *   - Any target_id with a tombstone is dropped from the output entirely.
+ *   - Records without record_kind default to "message" (back-compat).
+ *
+ * Cross-period folding: edits and tombstones can in principle target a
+ * message in a *prior* period (e.g. user edits a message that lived on
+ * the previous period after rollover). Callers that paginate across
+ * periods should fold the joined list, not each period independently.
+ */
+
+export interface MessageRecord {
+  record_kind?: 'message' | 'edit' | 'tombstone'
+  id: string
+  target_id?: string
+  sender_id: string
+  channel_doc_id: string
+  period_id: string
+  ts: number
+  content: string
+  mentions?: string[]
+  reply_to?: string | null
+  sig?: string
+  server_sig?: string
+}
+
+export interface FoldedMessage {
+  id: string
+  channel: string
+  senderId: string
+  senderName?: string
+  content: string
+  createdAt: number
+  /** Set if the message has been edited at least once. */
+  editedAt?: number
+  /** Reply target message id, if any. */
+  replyTo?: string
+}
+
+/**
+ * Fold an ordered list of records (oldest-first) into the visible
+ * messages a UI should render. Records may come from one period or
+ * across multiple periods concatenated in time order.
+ */
+export function foldRecords(records: MessageRecord[]): FoldedMessage[] {
+  const tombstoned = new Set<string>()
+  for (const r of records) {
+    if (r.record_kind === 'tombstone' && r.target_id) tombstoned.add(r.target_id)
+  }
+
+  const base = new Map<string, FoldedMessage>()
+  for (const r of records) {
+    const kind = r.record_kind ?? 'message'
+    if (kind !== 'message') continue
+    if (tombstoned.has(r.id)) continue
+    base.set(r.id, {
+      id: r.id,
+      channel: r.channel_doc_id,
+      senderId: r.sender_id,
+      content: r.content,
+      createdAt: r.ts,
+      ...(r.reply_to ? { replyTo: r.reply_to } : {}),
+    })
+  }
+
+  for (const r of records) {
+    if (r.record_kind !== 'edit' || !r.target_id) continue
+    if (tombstoned.has(r.target_id)) continue
+    const original = base.get(r.target_id)
+    if (!original) continue
+    original.content = r.content
+    original.editedAt = r.ts
+  }
+
+  return [...base.values()].sort((a, b) => a.createdAt - b.createdAt)
+}
+
+/**
+ * Decode whatever the Y.Array stored for an entry into a MessageRecord.
+ * Note: the server stamps `ts` server-side via `Any::BigInt(now_ts_ms())`,
+ * so on the wire it round-trips as a JS BigInt — `typeof` is `'bigint'`,
+ * not `'number'`. Accept both and coerce.
+ */
+export function recordFromYAny(any: unknown): MessageRecord | null {
+  if (!any || typeof any !== 'object') return null
+  const o = any as Record<string, unknown>
+  const tsRaw = o.ts
+  const tsIsValid = typeof tsRaw === 'number' || typeof tsRaw === 'bigint'
+  if (typeof o.id !== 'string' || typeof o.sender_id !== 'string'
+    || typeof o.channel_doc_id !== 'string' || !tsIsValid) {
+    return null
+  }
+  const ts = typeof tsRaw === 'bigint' ? Number(tsRaw) : (tsRaw as number)
+  return {
+    record_kind: typeof o.record_kind === 'string' ? o.record_kind as MessageRecord['record_kind'] : 'message',
+    id: o.id,
+    target_id: typeof o.target_id === 'string' ? o.target_id : undefined,
+    sender_id: o.sender_id,
+    channel_doc_id: o.channel_doc_id,
+    period_id: typeof o.period_id === 'string' ? o.period_id : '',
+    ts,
+    content: typeof o.content === 'string' ? o.content : '',
+    mentions: Array.isArray(o.mentions) ? o.mentions as string[] : [],
+    reply_to: typeof o.reply_to === 'string' ? o.reply_to : null,
+    sig: typeof o.sig === 'string' ? o.sig : undefined,
+    server_sig: typeof o.server_sig === 'string' ? o.server_sig : undefined,
+  }
+}

package/src/types.ts

@@ -124,6 +124,14 @@ export type onStatelessParameters = {
   payload: string;
 };
 
+/** Fired by E2EAbracadabraProvider when the server acknowledges an E2E
+ * client-side compaction (via the `snapshot:compacted` stateless broadcast). */
+export type onCompactedParameters = {
+  docId: string;
+  /** User id that performed the compaction; undefined if payload was malformed. */
+  by: string | undefined;
+};
+
 export type onServerErrorParameters = {
   source: string;
   code: string;
@@ -175,20 +183,68 @@ export interface UserProfile {
   role: string;
   /** Account-level Ed25519 public key (base64url). Canonical user identity. */
   publicKey: string | null;
+  /**
+   * Whether the user has a password set. `false` for key-based soft
+   * identities until they opt in via {@link AbracadabraClient.setPassword}.
+   * Drives the UI's "Set password" vs "Change password" branching.
+   */
+  hasPassword?: boolean;
 }
 
 export interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  /**
+   * Renderer hint — `"kanban"`, `"checklist"`, `"outline"`, `"graph"`,
+   * `"sheet"`, `"mindmap"`, `"doc"`, etc. Drives the dashboard's choice of
+   * Vue component for this doc. Orthogonal to {@link kind}.
+   */
   doc_type?: string | null;
   label?: string | null;
   description?: string | null;
   public_access?: string | null;
   owner_id?: string | null;
-  is_hub?: boolean;
+  /**
+   * Structural role hint — `"server"` for the reserved server-root doc,
+   * `"space"` for top-level workspace containers, `null`/absent otherwise.
+   * Distinct from {@link doc_type}: a Space (`kind: "space"`) can contain
+   * many Kanban boards (each `doc_type: "kanban"`).
+   */
+  kind?: string | null;
   updated_at?: number | null;
 }
 
+/**
+ * Well-known structural roles for the {@link DocumentMeta.kind} field. These
+ * are conventions only — the server treats `kind` as an opaque string. Use
+ * these constants instead of string literals to avoid typos.
+ */
+export const Kind = {
+  /** The reserved server root document. There is exactly one per server. */
+  Server: "server",
+  /** A top-level workspace container — what the dashboard calls a "Space". */
+  Space: "space",
+  /** A regular content page rendered by the editor. */
+  Page: "page",
+  /** A group chat container under a Space. */
+  Channel: "channel",
+  /** A direct-message container at the server root with two-member permissions. */
+  Dm: "dm",
+  /** A child of channel/dm holding the messages Y.Array. */
+  ChannelPeriod: "channel-period",
+  /** A per-user inbox doc holding inbox entries; child of server root. */
+  Inbox: "inbox",
+} as const;
+export type Kind = typeof Kind[keyof typeof Kind];
+
+/**
+ * Hardcoded UUID of the reserved server root document. Every doc in the tree
+ * chains up to this row, so a permission grant on this doc cascades into
+ * every descendant. Mirrors the constant in the Rust crate
+ * (`crate::types::SERVER_ROOT_ID_STR`).
+ */
+export const SERVER_ROOT_ID = "00000000-0000-0000-0000-000000000000";
+
 export interface UploadMeta {
   id: string;
   doc_id: string;
@@ -242,10 +298,30 @@ export interface SnapshotMeta {
   label?: string | null;
   created_by?: string | null;
   created_at: number;
+  /** Number of uploads referenced by this snapshot's CRDT state.
+   *  Always 0 on servers older than the `snapshot_files` migration, or for
+   *  snapshots created before that migration ran (until the operator runs
+   *  `POST /admin/snapshots/backfill-refs`). */
+  file_count?: number;
+  /** Signed byte delta vs. the previous-version snapshot for this doc.
+   *  `null` for the first snapshot of a doc (or when the previous version
+   *  has been pruned). Lets the UI render `+12 KB` / `−3 KB`. */
+  delta_bytes?: number | null;
+}
+
+export interface SnapshotFileEntry {
+  id: string;
+  doc_id: string;
+  filename: string;
+  mime_type?: string | null;
+  size?: number | null;
 }
 
 export interface SnapshotData extends SnapshotMeta {
   data: string;
+  /** Populated only when fetched with `?include=files`. Each entry is an
+   *  upload referenced by this snapshot's CRDT state. */
+  files?: SnapshotFileEntry[];
 }
 
 export interface SnapshotCreateResult {
@@ -277,10 +353,23 @@ export interface ServerInfo {
   version?: string;
   /** Hocuspocus wire protocol version (currently 2). */
   protocol_version?: number;
-  /** Entry-point document ID advertised by the server, if configured. */
-  index_doc_id?: string;
-  /** Default role assigned to users without explicit permissions. */
-  default_role?: string;
+  /**
+   * The reserved server root document id. Every doc in the tree chains up
+   * to this row; granting Admin here cascades to every doc. Hardcoded by
+   * the server — clients can also use {@link SERVER_ROOT_ID} directly.
+   */
+  root_doc_id?: string;
+  /**
+   * Server-wide access policy. Drives client-side decisions like "show the
+   * sign-up CTA?" (anonymous mode) or "warn before publishing?" (anonymous
+   * grants).
+   */
+  access?: {
+    /** `"none"` rejects unauthenticated requests; `"observer"` allows public read. */
+    anonymous?: "none" | "observer";
+    /** Server-wide floor for authed users with no explicit grant. */
+    authenticated?: "none" | "observer" | "viewer" | "editor";
+  };
   /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
   auth_methods?: string[];
   /** Whether open registration is enabled. */
@@ -289,6 +378,13 @@ export interface ServerInfo {
   invite_only?: boolean;
   /** Server encryption configuration. */
   encryption?: { default_mode?: string; minimum_mode?: string };
+  /**
+   * Ed25519 public key (base64url, no padding) the server uses to sign every
+   * accepted `messages:*` record (`server_sig`). Clients can verify message
+   * placement / ordering by checking each record's `server_sig` against this
+   * key over the canonical `{ msg_id, period_id, ts, client_sig }` payload.
+   */
+  messages_signer_pubkey?: string;
 }
 
 // ── Search ───────────────────────────────────────────────────────────────────
@@ -299,21 +395,83 @@ export interface SearchResult {
   score: number;
 }
 
-// ── Spaces ───────────────────────────────────────────────────────────────────
+/**
+ * A single hit returned by the server's full-text search endpoint
+ * (`GET /docs/search`). Distinct from {@link SearchResult}, which is the
+ * client-side trigram index in `SearchIndex.ts`.
+ *
+ * `snippet` is server-rendered HTML with `<mark>` wrappers around the
+ * matched tokens — safe to inject after standard sanitization. `rank` is
+ * a backend-specific score (SQLite bm25 vs Postgres ts_rank); the only
+ * guarantee is that hits arrive in best-first order.
+ */
+export interface DocSearchHit {
+  doc_id: string;
+  parent_id: string | null;
+  label: string | null;
+  kind: string | null;
+  /** HTML-safe snippet with `<mark>` markers around the matched tokens. */
+  snippet: string;
+  rank: number;
+}
+
+// ── Audit log (admin) ────────────────────────────────────────────────────────
 
-export interface SpaceMeta {
+/**
+ * A single row from `GET /admin/audit`. Mirrors the server's audit log
+ * row format (see `audit::AuditLogRow`). `metadata` is the parsed JSON
+ * object the server stored, or `null` if the row had no metadata. Each
+ * row carries an internal `prev_hash` / `row_hash` chain that admins
+ * verify with {@link AuditVerifyResult}.
+ */
+export interface AuditLogEntry {
   id: string;
-  doc_id: string;
-  name: string;
-  description: string | null;
-  visibility: "public" | "private" | "invite";
-  is_hub: boolean;
-  owner_id: string | null;
-  created_at: number;
-  updated_at: number;
-  public_access?: string | null;
+  ts: number;
+  event_type: string;
+  actor_user_id: string | null;
+  actor_ip: string | null;
+  request_id: string | null;
+  target_type: string | null;
+  target_id: string | null;
+  metadata: Record<string, unknown> | null;
+  outcome: string;
+}
+
+/** Filters for `GET /admin/audit`. All optional and AND-combined. */
+export interface AuditQueryOpts {
+  event_type?: string;
+  actor_user_id?: string;
+  target_type?: string;
+  target_id?: string;
+  since_ts?: number;
+  until_ts?: number;
+  limit?: number;
+  offset?: number;
 }
 
+/** Response of `GET /admin/audit/verify`. `status: "broken"` carries `break`. */
+export interface AuditVerifyResult {
+  status: "ok" | "broken";
+  message?: string;
+  break?: { rows_checked: number; row_id: string; reason: string };
+}
+
+// ── Readiness ────────────────────────────────────────────────────────────────
+
+/** Response of `GET /readyz`. HTTP 200 when ready, 503 when not. */
+export interface ReadyzStatus {
+  status: "ready" | "unready";
+  version: string;
+  checks: { database: "ok" | "error" };
+}
+
+// ── Spaces ───────────────────────────────────────────────────────────────────
+//
+// Spaces are documents whose `parent_id` is the server root and whose `kind`
+// is `"space"`. Listing them is `client.listSpaces()`; they come back as
+// regular `DocumentMeta` objects. Visibility is encoded in `public_access`:
+// `null` (or `"none"`) = private, `"observer"` = public read-only.
+
 // ── Invites ──────────────────────────────────────────────────────────────────
 
 export interface InviteRow {

package/src/webrtc/AbracadabraWebRTC.ts

@@ -527,7 +527,7 @@ export class AbracadabraWebRTC extends EventEmitter {
 				pendingKeyExchangeChannel = channel;
 				return;
 			}
-			channel.send(e2ee.getKeyExchangeMessage());
+			channel.send(e2ee.getKeyExchangeMessage() as unknown as ArrayBuffer);
 		});
 
 		this.resolveE2ee().then(async (identity) => {
@@ -541,7 +541,7 @@ export class AbracadabraWebRTC extends EventEmitter {
 
 			// Drain buffered key-exchange channel open
 			if (pendingKeyExchangeChannel) {
-				pendingKeyExchangeChannel.send(e2ee.getKeyExchangeMessage());
+				pendingKeyExchangeChannel.send(e2ee.getKeyExchangeMessage() as unknown as ArrayBuffer);
 			}
 			// Drain buffered messages
 			for (const msg of pendingMessages) {

package/src/webrtc/DataChannelRouter.ts

@@ -100,9 +100,9 @@ export class DataChannelRouter extends EventEmitter {
 
 		if (this.encryptor?.isEstablished && !this.plaintextChannels.has(name)) {
 			const encrypted = await this.encryptor.encrypt(data);
-			channel.send(encrypted);
+			channel.send(encrypted as unknown as ArrayBuffer);
 		} else {
-			channel.send(data);
+			channel.send(data as unknown as ArrayBuffer);
 		}
 		return true;
 	}

package/src/webrtc/E2EEChannel.ts

@@ -98,7 +98,7 @@ export class E2EEChannel extends EventEmitter {
 
 		this.sessionKey = await crypto.subtle.importKey(
 			"raw",
-			keyBytes,
+			keyBytes as BufferSource,
 			{ name: "AES-GCM" },
 			false,
 			["encrypt", "decrypt"],
@@ -130,9 +130,9 @@ export class E2EEChannel extends EventEmitter {
 		const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
 		const ciphertext = new Uint8Array(
 			await crypto.subtle.encrypt(
-				{ name: "AES-GCM", iv: nonce },
+				{ name: "AES-GCM", iv: nonce as BufferSource },
 				this.sessionKey,
-				plaintext,
+				plaintext as BufferSource,
 			),
 		);
 

package/src/webrtc/FileTransferChannel.ts

@@ -45,6 +45,13 @@ export class FileTransferHandle extends EventEmitter {
 	_setStatus(s: FileTransferStatus): void {
 		this.status = s;
 	}
+
+	/** @internal — public alias for the protected emit so the parent
+	 * `FileTransferChannel` (a different class instance) can dispatch events
+	 * on this handle. Protected access is by-class, not by-hierarchy. */
+	_emit(event: string, ...args: unknown[]): void {
+		this.emit(event, ...args);
+	}
 }
 
 interface ReceiveState {
@@ -102,7 +109,7 @@ export class FileTransferChannel extends EventEmitter {
 		const channel = this.router.getChannel(CHANNEL_NAMES.FILE_TRANSFER);
 		if (!channel || channel.readyState !== "open") {
 			handle._setStatus("error");
-			handle.emit("error", new Error("File transfer channel not open"));
+			handle._emit("error", new Error("File transfer channel not open"));
 			return handle;
 		}
 
@@ -174,7 +181,7 @@ export class FileTransferChannel extends EventEmitter {
 		channel.send(completeMsg);
 
 		handle._setStatus("complete");
-		handle.emit("complete");
+		handle._emit("complete");
 
 		return handle;
 	}