@abraca/dabra 1.0.16 → 1.0.18

package/dist/index.d.ts

@@ -371,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. */
@@ -421,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>;
   /**
@@ -645,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. */
@@ -864,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;
@@ -930,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.
  *
@@ -966,6 +989,8 @@ interface UserProfile {
 interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  doc_type?: string | null;
+  label?: string | null;
 }
 interface UploadMeta {
   id: string;
@@ -986,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";
@@ -1012,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;
@@ -1609,6 +1647,10 @@ interface BackgroundSyncManagerOptions {
   syncTimeout?: number;
   /** Pre-cache file blobs after syncing a doc. Default: true. */
   prefetchFiles?: boolean;
+  /** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+  throttleMs?: number;
+  /** Max retries for failed docs within a single syncAll() run. Default: 2. */
+  maxRetries?: number;
 }
 declare class BackgroundSyncManager extends EventEmitter {
   private readonly rootProvider;
@@ -1654,6 +1696,7 @@ declare class BackgroundSyncManager extends EventEmitter {
    *  3. Errored docs last
    */
   private _buildQueue;
+  /** Returns true on success (or skip), false on error. */
   private _syncWithSemaphore;
   private _doSyncDoc;
   private _syncNonE2EDoc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "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. */
@@ -579,11 +584,25 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	override destroy() {
 		this.document.off("subdocs", this.boundHandleYSubdocsChange);
 
+		// Collect child IDs before destroying — detach() may skip cleanup if
+		// a new provider already overwrote the slot during teardown/re-init races.
+		const childIds = [...this.childProviders.keys()];
+
 		for (const provider of this.childProviders.values()) {
 			provider.destroy();
 		}
 		this.childProviders.clear();
 
+		// Force-clear any stale providerMap entries for our children.
+		// detach() only removes if current === provider, so orphans can remain
+		// when a new provider attached before the old one was destroyed.
+		const wsProviderMap = this.configuration.websocketProvider?.configuration?.providerMap;
+		if (wsProviderMap) {
+			for (const childId of childIds) {
+				wsProviderMap.delete(childId);
+			}
+		}
+
 		this.offlineStore?.destroy();
 		this.offlineStore = null;
 

package/src/BackgroundSyncManager.ts

@@ -38,6 +38,10 @@ export interface BackgroundSyncManagerOptions {
 	syncTimeout?: number;
 	/** Pre-cache file blobs after syncing a doc. Default: true. */
 	prefetchFiles?: boolean;
+	/** Delay (ms) between starting each doc sync to avoid server pressure. Default: 50. */
+	throttleMs?: number;
+	/** Max retries for failed docs within a single syncAll() run. Default: 2. */
+	maxRetries?: number;
 }
 
 /**
@@ -96,6 +100,8 @@ export class BackgroundSyncManager extends EventEmitter {
 			concurrency: opts?.concurrency ?? 2,
 			syncTimeout: opts?.syncTimeout ?? 15_000,
 			prefetchFiles: opts?.prefetchFiles ?? true,
+			throttleMs: opts?.throttleMs ?? 50,
+			maxRetries: opts?.maxRetries ?? 2,
 		};
 
 		// Derive server origin from client URL for IDB namespacing
@@ -155,12 +161,54 @@ export class BackgroundSyncManager extends EventEmitter {
 		// Build the priority queue
 		const queue = this._buildQueue(entries);
 
-		// Sync all docs respecting concurrency limit
-		await Promise.all(
-			queue.map((docId) =>
-				this._syncWithSemaphore(docId, updatedAtMap.get(docId) ?? 0),
-			),
-		);
+		// Sync all docs with throttling: stagger starts to avoid server pressure.
+		// We use a feeding loop instead of Promise.all(queue.map(...)) so that
+		// each new doc start is spaced by throttleMs.
+		const failed: string[] = [];
+		let idx = 0;
+		const next = async (): Promise<void> => {
+			while (idx < queue.length) {
+				if (this._destroyed) return;
+				const docId = queue[idx++]!;
+				const updatedAt = updatedAtMap.get(docId) ?? 0;
+				const ok = await this._syncWithSemaphore(docId, updatedAt);
+				if (!ok) failed.push(docId);
+				// Throttle between starts
+				if (this.opts.throttleMs > 0 && idx < queue.length) {
+					await new Promise((r) => setTimeout(r, this.opts.throttleMs));
+				}
+			}
+		};
+
+		// Launch `concurrency` parallel workers feeding from the shared index.
+		const workers = Array.from({ length: this.opts.concurrency }, () => next());
+		await Promise.all(workers);
+
+		// Retry failed docs with increasing backoff.
+		for (let retry = 0; retry < this.opts.maxRetries && failed.length > 0; retry++) {
+			if (this._destroyed) return;
+			const batch = failed.splice(0, failed.length);
+			// Backoff: 2s, 4s, 8s...
+			const backoff = 2000 * 2 ** retry;
+			await new Promise((r) => setTimeout(r, backoff));
+
+			idx = 0;
+			const retryQueue = batch;
+			const retryNext = async (): Promise<void> => {
+				while (idx < retryQueue.length) {
+					if (this._destroyed) return;
+					const docId = retryQueue[idx++]!;
+					const updatedAt = updatedAtMap.get(docId) ?? 0;
+					const ok = await this._syncWithSemaphore(docId, updatedAt);
+					if (!ok) failed.push(docId);
+					if (this.opts.throttleMs > 0 && idx < retryQueue.length) {
+						await new Promise((r) => setTimeout(r, this.opts.throttleMs));
+					}
+				}
+			};
+			const retryWorkers = Array.from({ length: this.opts.concurrency }, () => retryNext());
+			await Promise.all(retryWorkers);
+		}
 	}
 
 	/** Sync a single document by ID. */
@@ -273,11 +321,12 @@ export class BackgroundSyncManager extends EventEmitter {
 		return items.map((i) => i.docId);
 	}
 
+	/** Returns true on success (or skip), false on error. */
 	private async _syncWithSemaphore(
 		docId: string,
 		updatedAt: number,
-	): Promise<void> {
-		if (this._destroyed) return;
+	): Promise<boolean> {
+		if (this._destroyed) return true;
 
 		// Skip if already synced and doc hasn't changed since last sync
 		const existing = this.syncStates.get(docId);
@@ -288,7 +337,7 @@ export class BackgroundSyncManager extends EventEmitter {
 			existing.lastSynced >= updatedAt
 		) {
 			this.emit("stateChanged", { docId, state: existing });
-			return;
+			return true;
 		}
 
 		await this.semaphore.acquire();
@@ -297,6 +346,7 @@ export class BackgroundSyncManager extends EventEmitter {
 			this.syncStates.set(docId, state);
 			await this.persistence.setState(state).catch(() => null);
 			this.emit("stateChanged", { docId, state });
+			return state.status !== "error";
 		} finally {
 			this.semaphore.release();
 		}

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