@abraca/dabra 1.8.1 → 1.9.1

package/dist/index.d.ts

@@ -1160,10 +1160,17 @@ type onAwarenessChangeParameters = {
 type onStatelessParameters = {
   payload: string;
 };
+/** Fired by E2EAbracadabraProvider when the server acknowledges an E2E
+ * client-side compaction (via the `snapshot:compacted` stateless broadcast). */
+type onCompactedParameters = {
+  docId: string; /** User id that performed the compaction; undefined if payload was malformed. */
+  by: string | undefined;
+};
 type onServerErrorParameters = {
   source: string;
   code: string;
   message: string;
+  meta?: Record<string, unknown>;
 };
 type StatesArray = {
   clientId: number;
@@ -1804,6 +1811,13 @@ declare class FileBlobStore extends EventEmitter {
    * the object URL reference is stale.
    */
   invalidateUrl(docId: string, uploadId: string): void;
+  /**
+   * Clear the 404 negative-cache entry for (docId, uploadId) so the next
+   * getBlobUrl() re-fetches from the server instead of short-circuiting.
+   * Use on explicit user retry or after reconnect, when the file may have
+   * become available since the last 404.
+   */
+  clearNotFound(docId: string, uploadId: string): void;
   /** Revoke the object URL and remove the blob from cache. */
   evictBlob(docId: string, uploadId: string): Promise<void>;
   /**
@@ -1830,6 +1844,31 @@ interface E2EAbracadabraProviderConfiguration extends AbracadabraProviderConfigu
   docKeyManager: DocKeyManager;
   keystore: CryptoIdentityKeystore;
   client: AbracadabraClient;
+  /**
+   * Enable client-side compaction: after `compactionThreshold` E2E updates,
+   * the provider merges the whole doc, re-encrypts it, and asks the server to
+   * atomically replace its update log via the `snapshot:compact` stateless
+   * protocol. Requires the user to have a role that `can_manage` the doc
+   * (Owner or above); otherwise the server silently rejects.
+   *
+   * Default: true.
+   */
+  compactionEnabled?: boolean;
+  /**
+   * Number of E2E updates applied in this session before compaction fires.
+   * Default: 50. Ignored when `compactionEnabled === false`.
+   */
+  compactionThreshold?: number;
+  /**
+   * Quiescence delay: once the threshold is crossed, wait this many ms with
+   * no further updates before firing compaction. Debounces active editing
+   * and reduces the chance of racing an in-flight remote update that hasn't
+   * reached us yet (the server does not currently validate state-vector
+   * coverage, so a compaction fired mid-flight could drop an update).
+   *
+   * Default: 2000 ms.
+   */
+  compactionQuiescenceMs?: number;
 }
 declare class E2EAbracadabraProvider extends AbracadabraProvider {
   private readonly docKeyManager;
@@ -1840,6 +1879,16 @@ declare class E2EAbracadabraProvider extends AbracadabraProvider {
   /** E2E-encrypted offline store; created after the doc key is available. */
   private e2eStore;
   private readonly e2eServerOrigin;
+  private readonly compactionEnabled;
+  private readonly compactionThreshold;
+  private readonly compactionQuiescenceMs;
+  private updatesSinceCompaction;
+  private compactionInFlight;
+  /** Cleared on `snapshot:compacted` or on 30s timeout. */
+  private compactionInFlightTimeout;
+  /** Quiescence debounce: reset on every update, fires the actual compaction. */
+  private compactionDebounceTimer;
+  private destroyed;
   constructor(configuration: E2EAbracadabraProviderConfiguration);
   /** Fetch the doc key from the server (requires WebAuthn if not cached). */
   private ensureDocKey;
@@ -1850,6 +1899,17 @@ declare class E2EAbracadabraProvider extends AbracadabraProvider {
   /** Encrypt local updates before sending over WebSocket. */
   documentUpdateHandler(update: Uint8Array, origin: unknown): void;
   private _encryptAndSend;
+  /**
+   * Force an immediate compaction attempt, bypassing the threshold and
+   * quiescence debounce. Resolves once the `snapshot:compact` frame has been
+   * sent (or rejected locally for missing prerequisites — destroyed, no
+   * doc key, or already in-flight). The server acknowledges via a
+   * `snapshot:compacted` broadcast, which emits the `"compacted"` event.
+   */
+  compactNow(): Promise<void>;
+  private _noteUpdateApplied;
+  private _performCompaction;
+  private _handleCompactedBroadcast;
   destroy(): void;
 }
 //#endregion
@@ -3097,4 +3157,4 @@ declare function wrapSeed(seed: Uint8Array, wrappingKeyBytes: Uint8Array): Promi
  */
 declare function unwrapSeed(ciphertext: ArrayBuffer, iv: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<Uint8Array>;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, type ChatChannel, ChatClient, type ChatClientTransport, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, type SendChatMessageInput, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, type ChatChannel, ChatClient, type ChatClientTransport, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, type SendChatMessageInput, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

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

package/src/AbracadabraBaseProvider.ts

@@ -375,9 +375,9 @@ export class AbracadabraBaseProvider extends EventEmitter {
     try {
       const parsed = JSON.parse(payload);
       if (parsed?.type === "error" && parsed.source && parsed.code) {
-        const { source, code, message } = parsed;
-        console.warn(`[Abracadabra] Server error: ${source} (${code}) — ${message}`);
-        this.emit("serverError", { source, code, message: message ?? "" });
+        const { source, code, message, meta } = parsed;
+        console.warn(`[Abracadabra] Server error: ${source} (${code}) — ${message}`, meta ?? "");
+        this.emit("serverError", { source, code, message: message ?? "", meta });
         return;
       }
     } catch {

package/src/ContentManager.ts

@@ -0,0 +1,160 @@
+/**
+ * ContentManager — read/write document content via markdown ↔ Y.js conversion.
+ *
+ * Extracted from `mcp/tools/content.ts` and `cli/commands/content.ts`.
+ */
+import * as Y from "yjs";
+import type { PageMeta } from "./DocTypes.ts";
+import { toPlain } from "./DocUtils.ts";
+import {
+	yjsToMarkdown,
+	populateYDocFromMarkdown,
+	parseFrontmatter,
+} from "./DocConverters.ts";
+import type { DocumentManager } from "./DocumentManager.ts";
+
+export interface DocumentContent {
+	label: string;
+	type?: string;
+	meta?: PageMeta;
+	title: string;
+	markdown: string;
+	children: Array<{
+		id: string;
+		label: string;
+		type?: string;
+		meta?: PageMeta;
+	}>;
+}
+
+export class ContentManager {
+	constructor(private dm: DocumentManager) {}
+
+	/**
+	 * Read document content as markdown.
+	 * Returns the title extracted from the TipTap documentHeader, the markdown
+	 * body, tree metadata, and immediate children.
+	 */
+	async read(docId: string): Promise<DocumentContent> {
+		const provider = await this.dm.getChildProvider(docId);
+		const fragment = provider.document.getXmlFragment("default");
+
+		const { title, markdown } = yjsToMarkdown(fragment);
+
+		// Get tree metadata + immediate children
+		const treeMap = this.dm.getTreeMap();
+		let label = title;
+		let type: string | undefined;
+		let meta: PageMeta | undefined;
+		let children: Array<{
+			id: string;
+			label: string;
+			type?: string;
+			meta?: PageMeta;
+		}> = [];
+
+		if (treeMap) {
+			const raw = treeMap.get(docId);
+			if (raw) {
+				const entry = toPlain(raw) as Record<string, unknown>;
+				label = (entry.label as string) || title;
+				type = entry.type as string | undefined;
+				meta = entry.meta as PageMeta | undefined;
+			}
+			// Collect immediate children sorted by order
+			treeMap.forEach((value: any, id: string) => {
+				if (value.parentId === docId) {
+					children.push({
+						id,
+						label: value.label || "Untitled",
+						type: value.type,
+						meta: value.meta,
+					});
+				}
+			});
+			children.sort((a, b) => {
+				const orderA = treeMap.get(a.id)?.order ?? 0;
+				const orderB = treeMap.get(b.id)?.order ?? 0;
+				return orderA - orderB;
+			});
+		}
+
+		return { label, type, meta, title, markdown, children };
+	}
+
+	/**
+	 * Write markdown content to a document.
+	 * Supports optional YAML frontmatter for title and metadata.
+	 *
+	 * @param mode - "replace" clears existing content first (default),
+	 *               "append" adds to the end.
+	 */
+	async write(
+		docId: string,
+		markdown: string,
+		mode: "replace" | "append" = "replace",
+	): Promise<void> {
+		const provider = await this.dm.getChildProvider(docId);
+		const doc = provider.document;
+		const fragment = doc.getXmlFragment("default");
+
+		// Parse optional frontmatter
+		const { title, meta, body } = parseFrontmatter(markdown);
+
+		// Update tree metadata if frontmatter provided title or meta
+		if (title || Object.keys(meta).length > 0) {
+			const treeMap = this.dm.getTreeMap();
+			const rootDoc = this.dm.rootDocument;
+			if (treeMap && rootDoc) {
+				const entry = treeMap.get(docId);
+				if (entry) {
+					rootDoc.transact(() => {
+						const updates: Record<string, unknown> = {
+							...entry,
+							updatedAt: Date.now(),
+						};
+						if (title) updates.label = title;
+						if (Object.keys(meta).length > 0) {
+							updates.meta = {
+								...(entry.meta ?? {}),
+								...meta,
+							};
+						}
+						treeMap.set(docId, updates);
+					});
+				}
+			}
+		}
+
+		if (mode === "replace") {
+			// Clear existing content
+			doc.transact(() => {
+				while (fragment.length > 0) {
+					fragment.delete(0);
+				}
+			});
+		}
+
+		// Write new content
+		const contentToWrite = body || markdown;
+		const fallbackTitle = title || "Untitled";
+		populateYDocFromMarkdown(fragment, contentToWrite, fallbackTitle);
+	}
+
+	/**
+	 * Get the raw Y.XmlFragment for a document (the 'default' fragment
+	 * that TipTap uses for document content).
+	 */
+	async getFragment(docId: string): Promise<Y.XmlFragment> {
+		const provider = await this.dm.getChildProvider(docId);
+		return provider.document.getXmlFragment("default");
+	}
+
+	/**
+	 * Get the raw Y.Doc for a document (synced).
+	 */
+	async getDoc(docId: string): Promise<Y.Doc> {
+		const provider = await this.dm.getChildProvider(docId);
+		return provider.document;
+	}
+}