@abraca/dabra 1.0.15 → 1.0.17

package/dist/index.d.ts

@@ -187,6 +187,11 @@ declare class OfflineStore {
   removeSubdocFromQueue(childId: string): Promise<void>;
   getMeta(key: string): Promise<string | null>;
   setMeta(key: string, value: string): Promise<void>;
+  /**
+   * Clear all stored data (updates, snapshots, state vectors, subdoc queue).
+   * The database itself is kept but emptied.
+   */
+  clearAll(): Promise<void>;
   destroy(): void;
 }
 //#endregion
@@ -366,6 +371,8 @@ declare class AbracadabraClient {
     doc_type?: string;
     label?: string;
   }): Promise<DocumentMeta>;
+  /** Broadcast a stateless message to all connected clients on a document (requires manage permission). */
+  broadcast(docId: string, payload: string): Promise<void>;
   /** List all permissions for a document (requires read access). */
   listPermissions(docId: string): Promise<PermissionEntry[]>;
   /** List effective permissions including inherited ones from ancestor documents. */
@@ -416,6 +423,26 @@ declare class AbracadabraClient {
   updateSpace(spaceId: string, opts: Partial<Pick<SpaceMeta, "name" | "description" | "visibility" | "is_hub">>): Promise<SpaceMeta>;
   /** Delete a space and its root document (Owner or admin required). */
   deleteSpace(spaceId: string): Promise<void>;
+  /** List all users (requires elevated role: admin or service). */
+  adminListUsers(): Promise<{
+    users: (UserProfile & {
+      revoked: boolean;
+      deviceKeys: string[];
+    })[];
+  }>;
+  /** Promote a user to admin (requires service role). */
+  adminPromote(userId: string): Promise<void>;
+  /** Demote an admin user back to regular (requires service role). */
+  adminDemote(userId: string): Promise<void>;
+  /** Sweep orphaned file blobs from storage (requires elevated role). */
+  adminStorageSweep(): Promise<{
+    blobsDeleted: number;
+  }>;
+  /** Repair blob ref-counts and sweep orphans (requires elevated role). */
+  adminStorageRepair(): Promise<{
+    refCountsRepaired: number;
+    blobsSwept: number;
+  }>;
   /** Health check — no auth required. */
   health(): Promise<HealthStatus>;
   /**
@@ -640,6 +667,7 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   private handleAuthChallenge;
   private restorePermissionSnapshot;
   get canWrite(): boolean;
+  get canAwareness(): boolean;
   /** The AbracadabraClient instance for REST API access, if configured. */
   get client(): AbracadabraClient | null;
   /** The OfflineStore instance, or null if offline storage is disabled. */
@@ -859,7 +887,7 @@ declare enum WebSocketStatus {
   Connected = "connected",
   Disconnected = "disconnected"
 }
-type AuthorizedScope = "service" | "admin" | "owner" | "editor" | "viewer" | "read-write" | "readonly";
+type AuthorizedScope = "service" | "admin" | "owner" | "editor" | "viewer" | "observer" | "read-write" | "readonly";
 interface OutgoingMessageInterface {
   encoder: Encoder;
   type?: MessageType;
@@ -925,7 +953,7 @@ type StatesArray = {
   clientId: number;
   [key: string | number]: any;
 }[];
-type EffectiveRole = "service" | "admin" | "owner" | "editor" | "viewer" | null;
+type EffectiveRole = "service" | "admin" | "owner" | "editor" | "viewer" | "observer" | null;
 /**
  * Ed25519 identity for passwordless crypto auth.
  *
@@ -961,6 +989,8 @@ interface UserProfile {
 interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  doc_type?: string | null;
+  label?: string | null;
 }
 interface UploadMeta {
   id: string;
@@ -981,13 +1011,13 @@ interface PublicKeyInfo {
 }
 interface PermissionEntry {
   user_id: string;
-  role: "owner" | "editor" | "viewer" | "observer";
+  role: "service" | "admin" | "owner" | "editor" | "viewer" | "observer";
   username: string;
   display_name: string | null;
 }
 interface EffectivePermissionEntry {
   user_id: string;
-  role: "owner" | "editor" | "viewer" | "observer";
+  role: "service" | "admin" | "owner" | "editor" | "viewer" | "observer";
   username: string;
   display_name: string | null;
   source: "direct" | "inherited";
@@ -1007,10 +1037,23 @@ interface ServerInfo {
   name?: string;
   /** Server version string. */
   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;
+  /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
+  auth_methods?: string[];
+  /** Whether open registration is enabled. */
+  registration_allowed?: boolean;
+  /** Whether an invite code is required to register. */
+  invite_only?: boolean;
+  /** Server encryption configuration. */
+  encryption?: {
+    default_mode?: string;
+    minimum_mode?: string;
+  };
 }
 interface SearchResult {
   docId: string;
@@ -1634,6 +1677,13 @@ declare class BackgroundSyncManager extends EventEmitter {
    * @returns Cleanup function to stop the periodic sync.
    */
   startPeriodicSync(intervalMs?: number): () => void;
+  /**
+   * Clear all offline document data and sync state.
+   * Opens each document's OfflineStore and clears its contents, then
+   * resets the background sync persistence. After calling this, all
+   * documents will need to be re-synced.
+   */
+  clearAllSyncedData(): Promise<void>;
   destroy(): void;
   /**
    * Build a priority-sorted list of doc IDs:

package/package.json

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

package/src/AbracadabraClient.ts

@@ -336,6 +336,11 @@ export class AbracadabraClient {
 		);
 	}
 
+	/** Broadcast a stateless message to all connected clients on a document (requires manage permission). */
+	async broadcast(docId: string, payload: string): Promise<void> {
+		await this.request("POST", `/docs/${encodeURIComponent(docId)}/broadcast`, { body: { payload } });
+	}
+
 	// ── Permissions ──────────────────────────────────────────────────────────
 
 	/** List all permissions for a document (requires read access). */
@@ -535,6 +540,33 @@ export class AbracadabraClient {
 		await this.request("DELETE", `/spaces/${encodeURIComponent(spaceId)}`);
 	}
 
+	// ── Admin ───────────────────────────────────────────────────────────────
+
+	/** List all users (requires elevated role: admin or service). */
+	async adminListUsers(): Promise<{ users: (UserProfile & { revoked: boolean; deviceKeys: string[] })[] }> {
+		return this.request("GET", "/admin/users");
+	}
+
+	/** Promote a user to admin (requires service role). */
+	async adminPromote(userId: string): Promise<void> {
+		await this.request("POST", `/admin/users/${encodeURIComponent(userId)}/admin`);
+	}
+
+	/** Demote an admin user back to regular (requires service role). */
+	async adminDemote(userId: string): Promise<void> {
+		await this.request("DELETE", `/admin/users/${encodeURIComponent(userId)}/admin`);
+	}
+
+	/** Sweep orphaned file blobs from storage (requires elevated role). */
+	async adminStorageSweep(): Promise<{ blobsDeleted: number }> {
+		return this.request("POST", "/admin/storage/sweep");
+	}
+
+	/** Repair blob ref-counts and sweep orphans (requires elevated role). */
+	async adminStorageRepair(): Promise<{ refCountsRepaired: number; blobsSwept: number }> {
+		return this.request("POST", "/admin/storage/repair");
+	}
+
 	// ── System ───────────────────────────────────────────────────────────────
 
 	/** Health check — no auth required. */

package/src/AbracadabraProvider.ts

@@ -226,10 +226,11 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			owner: "owner",
 			editor: "editor",
 			viewer: "viewer",
+			observer: "observer",
 			"read-write": "editor",
 			readonly: "viewer",
 		};
-		this.effectiveRole = roleMap[scope] ?? "viewer";
+		this.effectiveRole = roleMap[scope] ?? "observer";
 
 		this.offlineStore?.savePermissionSnapshot(this.effectiveRole);
 	}
@@ -303,7 +304,11 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	}
 
 	get canWrite(): boolean {
-		return this.effectiveRole != null && this.effectiveRole !== "viewer";
+		return this.effectiveRole != null && this.effectiveRole !== "viewer" && this.effectiveRole !== "observer";
+	}
+
+	get canAwareness(): boolean {
+		return this.effectiveRole != null && this.effectiveRole !== "observer";
 	}
 
 	/** The AbracadabraClient instance for REST API access, if configured. */

package/src/BackgroundSyncManager.ts

@@ -27,6 +27,7 @@ import {
 	BackgroundSyncPersistence,
 	type DocSyncState,
 } from "./BackgroundSyncPersistence.ts";
+import { OfflineStore } from "./OfflineStore.ts";
 import EventEmitter from "./EventEmitter.ts";
 import { E2EAbracadabraProvider } from "./E2EAbracadabraProvider.ts";
 
@@ -191,6 +192,48 @@ export class BackgroundSyncManager extends EventEmitter {
 		return () => clearInterval(handle);
 	}
 
+	/**
+	 * Clear all offline document data and sync state.
+	 * Opens each document's OfflineStore and clears its contents, then
+	 * resets the background sync persistence. After calling this, all
+	 * documents will need to be re-synced.
+	 */
+	async clearAllSyncedData(): Promise<void> {
+		// Collect doc IDs from both in-memory state and the tree
+		const docIds = new Set<string>(this.syncStates.keys());
+		const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
+		for (const docId of treeMap.keys()) {
+			docIds.add(docId);
+		}
+
+		// Derive server origin the same way the provider does
+		let serverOrigin: string | undefined;
+		try {
+			serverOrigin = new URL((this.client as any).baseUrl ?? "").hostname;
+		} catch {}
+
+		// Clear each document's offline store contents
+		const clearPromises = Array.from(docIds).map(async (docId) => {
+			try {
+				const store = new OfflineStore(docId, serverOrigin);
+				await store.clearAll();
+				store.destroy();
+			} catch {
+				// Ignore per-doc failures
+			}
+		});
+		await Promise.all(clearPromises);
+
+		// Clear background sync persistence
+		for (const docId of docIds) {
+			await this.persistence.deleteState(docId).catch(() => null);
+		}
+
+		// Reset in-memory state
+		this.syncStates.clear();
+		this._initPromise = null;
+	}
+
 	destroy(): void {
 		this._destroyed = true;
 		this.removeAllListeners();

package/src/OfflineStore.ts

@@ -251,6 +251,28 @@ export class OfflineStore {
 		);
 	}
 
+	/**
+	 * Clear all stored data (updates, snapshots, state vectors, subdoc queue).
+	 * The database itself is kept but emptied.
+	 */
+	async clearAll(): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const storeNames = Array.from(db.objectStoreNames);
+		if (storeNames.length === 0) return;
+		const tx = db.transaction(storeNames, "readwrite");
+		await Promise.all(
+			storeNames.map(
+				(name) =>
+					new Promise<void>((resolve, reject) => {
+						const req = tx.objectStore(name).clear();
+						req.onsuccess = () => resolve();
+						req.onerror = () => reject(req.error);
+					}),
+			),
+		);
+	}
+
 	// ── Lifecycle ─────────────────────────────────────────────────────────────
 
 	destroy() {

package/src/types.ts

@@ -40,7 +40,7 @@ export enum WebSocketStatus {
   Disconnected = "disconnected",
 }
 
-export type AuthorizedScope = "service" | "admin" | "owner" | "editor" | "viewer" | "read-write" | "readonly";
+export type AuthorizedScope = "service" | "admin" | "owner" | "editor" | "viewer" | "observer" | "read-write" | "readonly";
 
 export interface OutgoingMessageInterface {
   encoder: Encoder;
@@ -128,7 +128,7 @@ export type StatesArray = { clientId: number; [key: string | number]: any }[];
 
 // ── Abracadabra extensions ────────────────────────────────────────────────────
 
-export type EffectiveRole = "service" | "admin" | "owner" | "editor" | "viewer" | null;
+export type EffectiveRole = "service" | "admin" | "owner" | "editor" | "viewer" | "observer" | null;
 
 /**
  * Ed25519 identity for passwordless crypto auth.
@@ -173,6 +173,8 @@ export interface UserProfile {
 export interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  doc_type?: string | null;
+  label?: string | null;
 }
 
 export interface UploadMeta {
@@ -197,14 +199,14 @@ export interface PublicKeyInfo {
 
 export interface PermissionEntry {
   user_id: string;
-  role: "owner" | "editor" | "viewer" | "observer";
+  role: "service" | "admin" | "owner" | "editor" | "viewer" | "observer";
   username: string;
   display_name: string | null;
 }
 
 export interface EffectivePermissionEntry {
   user_id: string;
-  role: "owner" | "editor" | "viewer" | "observer";
+  role: "service" | "admin" | "owner" | "editor" | "viewer" | "observer";
   username: string;
   display_name: string | null;
   source: "direct" | "inherited";
@@ -227,10 +229,20 @@ export interface ServerInfo {
   name?: string;
   /** Server version string. */
   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;
+  /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
+  auth_methods?: string[];
+  /** Whether open registration is enabled. */
+  registration_allowed?: boolean;
+  /** Whether an invite code is required to register. */
+  invite_only?: boolean;
+  /** Server encryption configuration. */
+  encryption?: { default_mode?: string; minimum_mode?: string };
 }
 
 // ── Search ───────────────────────────────────────────────────────────────────