@abraca/dabra 1.0.14 → 1.0.16

package/dist/index.d.ts

@@ -126,6 +126,7 @@ declare class EventEmitter {
     [key: string]: Function[];
   };
   on(event: string, fn: Function): this;
+  once(event: string, fn: Function): this;
   protected emit(event: string, ...args: any): this;
   off(event: string, fn?: Function): this;
   removeAllListeners(): void;
@@ -186,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
@@ -256,6 +262,8 @@ declare class AbracadabraClient {
   get token(): string | null;
   set token(value: string | null);
   get isAuthenticated(): boolean;
+  /** Check if the current JWT token is present and not expired. */
+  isTokenValid(): boolean;
   /** Derives ws:// or wss:// URL from the http(s) base URL. */
   get wsUrl(): string;
   /** Register a new user with password. */
@@ -427,6 +435,7 @@ declare class AbracadabraClient {
    */
   getIceServers(): Promise<RTCIceServer[]>;
   private request;
+  private requestOrNull;
   private toError;
   private loadPersistedToken;
   private persistToken;
@@ -508,6 +517,7 @@ declare class CryptoIdentityKeystore {
 //#region packages/provider/src/DocKeyManager.d.ts
 declare class DocKeyManager {
   private cache;
+  private static readonly CACHE_TTL;
   /** Generate a new random AES-256-GCM document key. */
   static generateDocKey(): Promise<CryptoKey>;
   /**
@@ -655,6 +665,10 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    * If offline the event is queued in IndexedDB and replayed on reconnect.
    */
   private registerSubdoc;
+  /** Get a loaded child provider by ID, or null if not yet loaded. */
+  getChild(childId: string): AbracadabraProvider | null;
+  /** Check if a child provider is already loaded. */
+  hasChild(childId: string): boolean;
   /**
    * Create (or return cached) a child AbracadabraProvider for a given
    * child document id.  Each child opens its own WebSocket connection because
@@ -1239,10 +1253,14 @@ declare class AbracadabraBaseProvider extends EventEmitter {
   isSynced: boolean;
   unsyncedChanges: number;
   isAuthenticated: boolean;
+  /** Current WebSocket connection status. */
+  get connectionStatus(): WebSocketStatus;
   authorizedScope: AuthorizedScope | undefined;
   manageSocket: boolean;
   private _isAttached;
-  intervals: any;
+  intervals: {
+    forceSync: ReturnType<typeof setInterval> | null;
+  };
   constructor(configuration: AbracadabraBaseProviderConfiguration);
   boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;
   boundAwarenessUpdateHandler: ({
@@ -1375,7 +1393,7 @@ declare class FileBlobStore extends EventEmitter {
   private readonly _notFound;
   private static readonly NOT_FOUND_TTL;
   /** Prevents concurrent flush runs. */
-  private _flushing;
+  private _flushPromise;
   private readonly _onlineHandler;
   constructor(serverOrigin: string, client?: AbracadabraClient | null);
   private getDb;
@@ -1410,6 +1428,13 @@ declare class FileBlobStore extends EventEmitter {
   }>>;
   /** Revoke all object URLs and clear the entire blob cache from IDB. */
   clearAllBlobs(): Promise<void>;
+  /**
+   * Revoke the in-memory object URL without touching the IDB cache.
+   * The next call to getBlobUrl() will re-create a fresh URL from IDB.
+   * Use this when an <img> @error fires — the blob data is fine, only
+   * the object URL reference is stale.
+   */
+  invalidateUrl(docId: string, uploadId: string): void;
   /** Revoke the object URL and remove the blob from cache. */
   evictBlob(docId: string, uploadId: string): Promise<void>;
   /**
@@ -1426,6 +1451,7 @@ declare class FileBlobStore extends EventEmitter {
    * Entries that fail are marked with status "error" and left in the queue.
    */
   flushQueue(): Promise<void>;
+  private _doFlush;
   private _updateQueueEntry;
   destroy(): void;
 }
@@ -1593,7 +1619,14 @@ declare class BackgroundSyncManager extends EventEmitter {
   private readonly semaphore;
   private readonly syncStates;
   private _destroyed;
+  private _initPromise;
   constructor(rootProvider: AbracadabraProvider, client: AbracadabraClient, fileBlobStore?: FileBlobStore | null, opts?: BackgroundSyncManagerOptions);
+  /**
+   * Load persisted sync states from IndexedDB into the in-memory map.
+   * Called automatically by syncAll() / syncDoc(); safe to call concurrently.
+   */
+  init(): Promise<void>;
+  private _loadPersistedStates;
   /** Sync all documents in the root tree. */
   syncAll(): Promise<void>;
   /** Sync a single document by ID. */
@@ -1606,6 +1639,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:
@@ -1720,7 +1760,7 @@ declare class DataChannelRouter extends EventEmitter {
    * Send data on a named channel, encrypting if E2EE is active.
    * Falls back to plaintext if no encryptor is set or for exempt channels.
    */
-  send(name: string, data: Uint8Array): Promise<void>;
+  send(name: string, data: Uint8Array): Promise<boolean>;
   private registerChannel;
   close(): void;
   destroy(): void;
@@ -2008,7 +2048,9 @@ declare class SignalingSocket extends EventEmitter {
   isConnected: boolean;
   constructor(configuration: SignalingSocketConfiguration);
   private getToken;
+  private _connectPromise;
   connect(): Promise<void>;
+  private _doConnect;
   private createConnection;
   private handleMessage;
   private sendRaw;
@@ -2059,6 +2101,7 @@ declare class YjsDataChannel {
   private readonly document;
   private readonly awareness;
   private readonly router;
+  isSynced: boolean;
   private docUpdateHandler;
   private awarenessUpdateHandler;
   private channelOpenHandler;

package/package.json

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

package/src/AbracadabraBaseProvider.ts

@@ -29,6 +29,7 @@ import type {
   onStatusParameters,
   onSyncedParameters,
   onUnsyncedChangesParameters,
+  WebSocketStatus,
 } from "./types.ts";
 
 export type AbracadabraBaseProviderConfiguration = Required<
@@ -137,6 +138,11 @@ export class AbracadabraBaseProvider extends EventEmitter {
 
   isAuthenticated = false;
 
+  /** Current WebSocket connection status. */
+  get connectionStatus(): WebSocketStatus {
+    return this.configuration.websocketProvider.status;
+  }
+
   authorizedScope: AuthorizedScope | undefined = undefined;
 
   // @internal
@@ -144,7 +150,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
 
   private _isAttached = false;
 
-  intervals: any = {
+  intervals: { forceSync: ReturnType<typeof setInterval> | null } = {
     forceSync: null,
   };
 

package/src/AbracadabraClient.ts

@@ -78,6 +78,18 @@ export class AbracadabraClient {
 		return this._token !== null;
 	}
 
+	/** Check if the current JWT token is present and not expired. */
+	isTokenValid(): boolean {
+		if (!this._token) return false;
+		try {
+			const [, payload] = this._token.split(".");
+			const { exp } = JSON.parse(atob(payload));
+			return typeof exp === "number" && exp * 1000 > Date.now();
+		} catch {
+			return false;
+		}
+	}
+
 	/** Derives ws:// or wss:// URL from the http(s) base URL. */
 	get wsUrl(): string {
 		return this.baseUrl
@@ -202,17 +214,10 @@ export class AbracadabraClient {
 
 	/** Get the caller's key envelope for a document (for decrypting the DocKey). */
 	async getMyKeyEnvelope(docId: string): Promise<{ encrypted_key: string; key_epoch: number } | null> {
-		try {
-			return await this.request<{ encrypted_key: string; key_epoch: number }>(
-				"GET",
-				`/docs/${encodeURIComponent(docId)}/key-envelope`,
-			);
-		} catch (e: unknown) {
-			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
-				return null;
-			}
-			throw e;
-		}
+		return this.requestOrNull<{ encrypted_key: string; key_epoch: number }>(
+			"GET",
+			`/docs/${encodeURIComponent(docId)}/key-envelope`,
+		);
 	}
 
 	/** Upload key envelopes for a document (Owner only). */
@@ -225,18 +230,11 @@ export class AbracadabraClient {
 
 	/** Get the X25519 public key for a user. */
 	async getUserX25519Key(userId: string): Promise<string | null> {
-		try {
-			const res = await this.request<{ x25519_key: string }>(
-				"GET",
-				`/users/${encodeURIComponent(userId)}/x25519-key`,
-			);
-			return res.x25519_key;
-		} catch (e: unknown) {
-			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
-				return null;
-			}
-			throw e;
-		}
+		const res = await this.requestOrNull<{ x25519_key: string }>(
+			"GET",
+			`/users/${encodeURIComponent(userId)}/x25519-key`,
+		);
+		return res?.x25519_key ?? null;
 	}
 
 	/** List all non-revoked keys for a user (Owner/Admin or self). */
@@ -365,13 +363,16 @@ export class AbracadabraClient {
 				"GET",
 				`/docs/${encodeURIComponent(docId)}/effective-permissions`,
 			);
-		} catch {
-			// Fallback for older servers that don't support this endpoint
-			const perms = await this.listPermissions(docId);
-			return {
-				permissions: perms.map((p) => ({ ...p, source: "direct" as const })),
-				default_role: "viewer",
-			};
+		} catch (e: unknown) {
+			// Fallback for older servers that don't support this endpoint (404 only)
+			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
+				const perms = await this.listPermissions(docId);
+				return {
+					permissions: perms.map((p) => ({ ...p, source: "direct" as const })),
+					default_role: "viewer",
+				};
+			}
+			throw e;
 		}
 	}
 
@@ -508,14 +509,7 @@ export class AbracadabraClient {
 
 	/** Get the hub space, or null if none is configured. */
 	async getHubSpace(): Promise<SpaceMeta | null> {
-		try {
-			return await this.request<SpaceMeta>("GET", "/spaces/hub", { auth: false });
-		} catch (e: unknown) {
-			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
-				return null;
-			}
-			throw e;
-		}
+		return this.requestOrNull<SpaceMeta>("GET", "/spaces/hub", { auth: false });
 	}
 
 	/** Create a new space (auth required). */
@@ -588,7 +582,7 @@ export class AbracadabraClient {
 			headers["Authorization"] = `Bearer ${this._token}`;
 		}
 
-		const init: RequestInit = { method, headers };
+		const init: RequestInit = { method, headers, signal: AbortSignal.timeout(30_000) };
 
 		if (opts?.body !== undefined) {
 			headers["Content-Type"] = "application/json";
@@ -598,7 +592,7 @@ export class AbracadabraClient {
 		const res = await this._fetch(`${this.baseUrl}${path}`, init);
 
 		if (!res.ok) {
-			throw await this.toError(res);
+			throw await this.toError(res, method, path);
 		}
 
 		// 204 No Content
@@ -609,7 +603,22 @@ export class AbracadabraClient {
 		return res.json() as Promise<T>;
 	}
 
-	private async toError(res: Response): Promise<Error> {
+	private async requestOrNull<T>(
+		method: string,
+		path: string,
+		opts?: { body?: unknown; auth?: boolean },
+	): Promise<T | null> {
+		try {
+			return await this.request<T>(method, path, opts);
+		} catch (e: unknown) {
+			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
+				return null;
+			}
+			throw e;
+		}
+	}
+
+	private async toError(res: Response, method?: string, path?: string): Promise<Error> {
 		let message: string;
 		try {
 			const body = await res.json() as { error?: string };
@@ -617,7 +626,8 @@ export class AbracadabraClient {
 		} catch {
 			message = res.statusText;
 		}
-		const err = new Error(message);
+		const prefix = method && path ? `${method} ${path}: ` : "";
+		const err = new Error(`${prefix}${message} (${res.status})`);
 		(err as any).status = res.status;
 		return err;
 	}

package/src/AbracadabraProvider.ts

@@ -155,7 +155,12 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		this.restorePermissionSnapshot();
 
 		// Pre-populate the Y.Doc from the local snapshot so the UI works offline.
-		this.ready = this._initFromOfflineStore();
+		this.ready = Promise.race([
+			this._initFromOfflineStore(),
+			new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
+		]).catch((err) => {
+			this.emit("error", { message: `Offline store init failed: ${err?.message ?? err}` });
+		});
 	}
 
 	// ── Server origin derivation ──────────────────────────────────────────────
@@ -337,7 +342,9 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 		// Intercept auth_challenge before subdoc handling.
 		if (msg.type === "auth_challenge" && msg.challenge && msg.expiresAt) {
-			this.handleAuthChallenge(msg.challenge, msg.expiresAt).catch(() => null);
+			this.handleAuthChallenge(msg.challenge, msg.expiresAt).catch((err) => {
+				this.emit("authenticationFailed", { reason: `Auth challenge error: ${err?.message ?? err}` });
+			});
 			return;
 		}
 
@@ -407,6 +414,16 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		}
 	}
 
+	/** Get a loaded child provider by ID, or null if not yet loaded. */
+	getChild(childId: string): AbracadabraProvider | null {
+		return this.childProviders.get(childId) ?? null;
+	}
+
+	/** Check if a child provider is already loaded. */
+	hasChild(childId: string): boolean {
+		return this.childProviders.has(childId);
+	}
+
 	/**
 	 * Create (or return cached) a child AbracadabraProvider for a given
 	 * child document id.  Each child opens its own WebSocket connection because

package/src/AbracadabraWS.ts

@@ -409,7 +409,11 @@ export class AbracadabraWS extends EventEmitter {
     const message = new IncomingMessage(event.data);
     const documentName = message.peekVarString();
 
-    this.configuration.providerMap.get(documentName)?.onMessage(event);
+    try {
+      this.configuration.providerMap.get(documentName)?.onMessage(event);
+    } catch (err) {
+      console.error(`[AbracadabraWS] Provider onMessage error for "${documentName}":`, err);
+    }
   }
 
   resolveConnectionAttempt() {

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";
 
@@ -79,6 +80,7 @@ export class BackgroundSyncManager extends EventEmitter {
 	private readonly syncStates = new Map<string, DocSyncState>();
 
 	private _destroyed = false;
+	private _initPromise: Promise<void> | null = null;
 
 	constructor(
 		rootProvider: AbracadabraProvider,
@@ -108,15 +110,45 @@ export class BackgroundSyncManager extends EventEmitter {
 
 	// ── Public API ────────────────────────────────────────────────────────────
 
+	/**
+	 * Load persisted sync states from IndexedDB into the in-memory map.
+	 * Called automatically by syncAll() / syncDoc(); safe to call concurrently.
+	 */
+	async init(): Promise<void> {
+		if (!this._initPromise) {
+			this._initPromise = this._loadPersistedStates();
+		}
+		return this._initPromise;
+	}
+
+	private async _loadPersistedStates(): Promise<void> {
+		try {
+			const states = await this.persistence.getAllStates();
+			for (const state of states) {
+				this.syncStates.set(state.docId, state);
+			}
+		} catch {
+			// IDB unavailable — proceed with empty map (full sync fallback)
+		}
+	}
+
 	/** Sync all documents in the root tree. */
 	async syncAll(): Promise<void> {
 		if (this._destroyed) return;
 
+		await this.init();
+
 		const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
 		const entries = Array.from(treeMap.entries()) as Array<[string, any]>;
 
 		if (entries.length === 0) return;
 
+		// Build updatedAt lookup for skip-unchanged logic
+		const updatedAtMap = new Map<string, number>();
+		for (const [docId, v] of entries) {
+			updatedAtMap.set(docId, v?.updatedAt ?? v?.createdAt ?? 0);
+		}
+
 		// Pre-cache cover images immediately (fire-and-forget)
 		this._prefetchCovers(entries).catch(() => null);
 
@@ -124,11 +156,16 @@ export class BackgroundSyncManager extends EventEmitter {
 		const queue = this._buildQueue(entries);
 
 		// Sync all docs respecting concurrency limit
-		await Promise.all(queue.map((docId) => this._syncWithSemaphore(docId)));
+		await Promise.all(
+			queue.map((docId) =>
+				this._syncWithSemaphore(docId, updatedAtMap.get(docId) ?? 0),
+			),
+		);
 	}
 
 	/** Sync a single document by ID. */
 	async syncDoc(docId: string): Promise<DocSyncState> {
+		await this.init();
 		const state = await this._doSyncDoc(docId);
 		this.syncStates.set(docId, state);
 		await this.persistence.setState(state).catch(() => null);
@@ -155,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();
@@ -194,8 +273,24 @@ export class BackgroundSyncManager extends EventEmitter {
 		return items.map((i) => i.docId);
 	}
 
-	private async _syncWithSemaphore(docId: string): Promise<void> {
+	private async _syncWithSemaphore(
+		docId: string,
+		updatedAt: number,
+	): Promise<void> {
 		if (this._destroyed) return;
+
+		// Skip if already synced and doc hasn't changed since last sync
+		const existing = this.syncStates.get(docId);
+		if (
+			existing &&
+			existing.status === "synced" &&
+			existing.lastSynced !== null &&
+			existing.lastSynced >= updatedAt
+		) {
+			this.emit("stateChanged", { docId, state: existing });
+			return;
+		}
+
 		await this.semaphore.acquire();
 		try {
 			const state = await this._doSyncDoc(docId);
@@ -218,9 +313,9 @@ export class BackgroundSyncManager extends EventEmitter {
 		this.syncStates.set(docId, syncing);
 		this.emit("stateChanged", { docId, state: syncing });
 
+		let isE2E = false;
 		try {
 			// Check encryption type
-			let isE2E = false;
 			try {
 				const enc = await this.client.getDocEncryption(docId);
 				isE2E = enc.mode === "e2e";
@@ -240,7 +335,7 @@ export class BackgroundSyncManager extends EventEmitter {
 				status: "error",
 				lastSynced: this.syncStates.get(docId)?.lastSynced ?? null,
 				error,
-				isE2E: false,
+				isE2E,
 			};
 		}
 	}

package/src/DocKeyManager.ts

@@ -18,7 +18,8 @@ function fromBase64(b64: string): Uint8Array {
 }
 
 export class DocKeyManager {
-	private cache = new Map<string, { key: CryptoKey; epoch: number }>();
+	private cache = new Map<string, { key: CryptoKey; epoch: number; fetchedAt: number }>();
+	private static readonly CACHE_TTL = 10 * 60 * 1000; // 10 minutes
 
 	/** Generate a new random AES-256-GCM document key. */
 	static async generateDocKey(): Promise<CryptoKey> {
@@ -39,7 +40,9 @@ export class DocKeyManager {
 		keystore: CryptoIdentityKeystore,
 	): Promise<CryptoKey | null> {
 		const cached = this.cache.get(docId);
-		if (cached) return cached.key;
+		if (cached && Date.now() - cached.fetchedAt < DocKeyManager.CACHE_TTL) {
+			return cached.key;
+		}
 
 		const envelope = await client.getMyKeyEnvelope(docId);
 		if (!envelope) return null;
@@ -48,7 +51,7 @@ export class DocKeyManager {
 		try {
 			const wrapped = fromBase64(envelope.encrypted_key);
 			const docKey = await this._unwrapKey(wrapped, x25519PrivKey, docId);
-			this.cache.set(docId, { key: docKey, epoch: envelope.key_epoch });
+			this.cache.set(docId, { key: docKey, epoch: envelope.key_epoch, fetchedAt: Date.now() });
 			return docKey;
 		} finally {
 			x25519PrivKey.fill(0);

package/src/EventEmitter.ts

@@ -13,11 +13,26 @@ export default class EventEmitter {
 		return this;
 	}
 
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	public once(event: string, fn: Function): this {
+		const wrapper = (...args: any[]) => {
+			this.off(event, wrapper);
+			fn.apply(this, args);
+		};
+		return this.on(event, wrapper);
+	}
+
 	protected emit(event: string, ...args: any): this {
 		const callbacks = this.callbacks[event];
 
 		if (callbacks) {
-			callbacks.forEach((callback) => callback.apply(this, args));
+			for (const callback of callbacks) {
+				try {
+					callback.apply(this, args);
+				} catch (err) {
+					console.error(`[EventEmitter] Error in "${event}" listener:`, err);
+				}
+			}
 		}
 
 		return this;