@abraca/dabra 0.6.0 → 0.8.0

package/src/AbracadabraClient.ts

@@ -6,7 +6,10 @@ import type {
 	PublicKeyInfo,
 	PermissionEntry,
 	HealthStatus,
+	ServerInfo,
+	InviteRow,
 } from "./types.ts";
+import type { DocumentCache } from "./DocumentCache.ts";
 
 export interface AbracadabraClientConfig {
 	/** Server base URL (http or https). WebSocket URL is derived automatically. */
@@ -19,6 +22,13 @@ export interface AbracadabraClientConfig {
 	storageKey?: string;
 	/** Custom fetch implementation (useful for Node.js or testing). */
 	fetch?: typeof globalThis.fetch;
+	/**
+	 * Optional metadata cache. When provided, read methods (getDoc, listChildren,
+	 * getMe, listPermissions, listUploads) check the cache before hitting the
+	 * network. Write methods (deleteDoc, upload, deleteUpload) invalidate affected
+	 * cache entries automatically.
+	 */
+	cache?: DocumentCache;
 }
 
 export class AbracadabraClient {
@@ -27,12 +37,14 @@ export class AbracadabraClient {
 	private readonly persistAuth: boolean;
 	private readonly storageKey: string;
 	private readonly _fetch: typeof globalThis.fetch;
+	readonly cache: DocumentCache | null;
 
 	constructor(config: AbracadabraClientConfig) {
 		this.baseUrl = config.url.replace(/\/+$/, "");
 		this.persistAuth = config.persistAuth ?? typeof localStorage !== "undefined";
 		this.storageKey = config.storageKey ?? "abracadabra:auth";
 		this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+		this.cache = config.cache ?? null;
 
 		// Load token: explicit > persisted > null
 		this._token = config.token ?? this.loadPersistedToken() ?? null;
@@ -74,6 +86,7 @@ export class AbracadabraClient {
 		password: string;
 		email?: string;
 		displayName?: string;
+		inviteCode?: string;
 	}): Promise<UserProfile> {
 		return this.request<UserProfile>("POST", "/auth/register", {
 			body: opts,
@@ -91,6 +104,7 @@ export class AbracadabraClient {
 		deviceName?: string;
 		displayName?: string;
 		email?: string;
+		inviteCode?: string;
 	}): Promise<UserProfile> {
 		const username = opts.username ?? `user-${opts.publicKey.slice(0, 8)}`;
 		return this.request<UserProfile>("POST", "/auth/register", {
@@ -100,6 +114,7 @@ export class AbracadabraClient {
 				deviceName: opts.deviceName,
 				displayName: opts.displayName,
 				email: opts.email,
+				inviteCode: opts.inviteCode,
 			},
 			auth: false,
 		});
@@ -175,7 +190,15 @@ export class AbracadabraClient {
 
 	/** Get the current user's profile. */
 	async getMe(): Promise<UserProfile> {
-		return this.request<UserProfile>("GET", "/users/me");
+		if (this.cache) {
+			const cached = await this.cache.getCurrentProfile();
+			if (cached) return cached;
+		}
+		const profile = await this.request<UserProfile>("GET", "/users/me");
+		if (this.cache) {
+			await this.cache.setCurrentProfile(profile).catch(() => null);
+		}
+		return profile;
 	}
 
 	/** Update the current user's display name. */
@@ -192,20 +215,38 @@ export class AbracadabraClient {
 
 	/** Get document metadata. */
 	async getDoc(docId: string): Promise<DocumentMeta> {
-		return this.request<DocumentMeta>("GET", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			const cached = await this.cache.getDoc(docId);
+			if (cached) return cached;
+		}
+		const meta = await this.request<DocumentMeta>("GET", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			await this.cache.setDoc(meta).catch(() => null);
+		}
+		return meta;
 	}
 
 	/** Delete a document (requires Owner role). Cascades to children and uploads. */
 	async deleteDoc(docId: string): Promise<void> {
 		await this.request("DELETE", `/docs/${encodeURIComponent(docId)}`);
+		if (this.cache) {
+			await this.cache.invalidateDoc(docId).catch(() => null);
+		}
 	}
 
 	/** List immediate child documents. */
 	async listChildren(docId: string): Promise<string[]> {
+		if (this.cache) {
+			const cached = await this.cache.getChildren(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ children: string[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/children`,
 		);
+		if (this.cache) {
+			await this.cache.setChildren(docId, res.children).catch(() => null);
+		}
 		return res.children;
 	}
 
@@ -222,10 +263,17 @@ export class AbracadabraClient {
 
 	/** List all permissions for a document (requires read access). */
 	async listPermissions(docId: string): Promise<PermissionEntry[]> {
+		if (this.cache) {
+			const cached = await this.cache.getPermissions(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ permissions: PermissionEntry[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/permissions`,
 		);
+		if (this.cache) {
+			await this.cache.setPermissions(docId, res.permissions).catch(() => null);
+		}
 		return res.permissions;
 	}
 
@@ -273,15 +321,26 @@ export class AbracadabraClient {
 		if (!res.ok) {
 			throw await this.toError(res);
 		}
-		return res.json() as Promise<UploadMeta>;
+		const meta = await res.json() as UploadMeta;
+		if (this.cache) {
+			await this.cache.invalidateUploads(docId).catch(() => null);
+		}
+		return meta;
 	}
 
 	/** List all uploads for a document. */
 	async listUploads(docId: string): Promise<UploadInfo[]> {
+		if (this.cache) {
+			const cached = await this.cache.getUploads(docId);
+			if (cached) return cached;
+		}
 		const res = await this.request<{ uploads: UploadInfo[] }>(
 			"GET",
 			`/docs/${encodeURIComponent(docId)}/uploads`,
 		);
+		if (this.cache) {
+			await this.cache.setUploads(docId, res.uploads).catch(() => null);
+		}
 		return res.uploads;
 	}
 
@@ -308,6 +367,32 @@ export class AbracadabraClient {
 			"DELETE",
 			`/docs/${encodeURIComponent(docId)}/uploads/${encodeURIComponent(uploadId)}`,
 		);
+		if (this.cache) {
+			await this.cache.invalidateUploads(docId).catch(() => null);
+		}
+	}
+
+	// ── Invites ──────────────────────────────────────────────────────────────
+
+	/** Create an invite code (requires permission per server config). */
+	async createInvite(opts?: { role?: string; maxUses?: number; expiresIn?: number }): Promise<InviteRow> {
+		return this.request<InviteRow>("POST", "/invites", { body: opts ?? {} });
+	}
+
+	/** List invite codes visible to the current user. */
+	async listInvites(): Promise<InviteRow[]> {
+		const res = await this.request<{ invites: InviteRow[] }>("GET", "/invites");
+		return res.invites;
+	}
+
+	/** Revoke an invite by its code. */
+	async revokeInvite(code: string): Promise<void> {
+		await this.request("DELETE", `/invites/${encodeURIComponent(code)}`);
+	}
+
+	/** Redeem an invite code for the currently authenticated user. */
+	async redeemInvite(code: string): Promise<void> {
+		await this.request("POST", "/invites/redeem", { body: { code } });
 	}
 
 	// ── System ───────────────────────────────────────────────────────────────
@@ -317,6 +402,14 @@ export class AbracadabraClient {
 		return this.request<HealthStatus>("GET", "/health", { auth: false });
 	}
 
+	/**
+	 * Fetch server metadata including the optional `index_doc_id` entry point.
+	 * No auth required.
+	 */
+	async serverInfo(): Promise<ServerInfo> {
+		return this.request<ServerInfo>("GET", "/info", { auth: false });
+	}
+
 	// ── Internals ────────────────────────────────────────────────────────────
 
 	private async request<T = void>(

package/src/AbracadabraProvider.ts

@@ -1,7 +1,7 @@
 import * as Y from "yjs";
-import { HocuspocusProvider } from "./HocuspocusProvider.ts";
-import type { HocuspocusProviderConfiguration } from "./HocuspocusProvider.ts";
-import type { HocuspocusProviderWebsocket } from "./HocuspocusProviderWebsocket.ts";
+import { AbracadabraBaseProvider } from "./AbracadabraBaseProvider.ts";
+import type { AbracadabraBaseProviderConfiguration } from "./AbracadabraBaseProvider.ts";
+import type { AbracadabraWS } from "./AbracadabraWS.ts";
 import { OfflineStore } from "./OfflineStore.ts";
 import { SubdocMessage } from "./OutgoingMessages/SubdocMessage.ts";
 import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
@@ -15,7 +15,7 @@ import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.
 import type { AbracadabraClient } from "./AbracadabraClient.ts";
 
 export interface AbracadabraProviderConfiguration
-	extends Omit<HocuspocusProviderConfiguration, "url" | "websocketProvider"> {
+	extends Omit<AbracadabraBaseProviderConfiguration, "url" | "websocketProvider"> {
 	/**
 	 * Subdocument loading strategy.
 	 * - "lazy"  (default) – child providers are created only when explicitly requested.
@@ -58,7 +58,7 @@ export interface AbracadabraProviderConfiguration
 	url?: string;
 
 	/** Shared WebSocket connection (use when multiplexing multiple root documents). */
-	websocketProvider?: HocuspocusProviderWebsocket;
+	websocketProvider?: AbracadabraWS;
 }
 
 /** Validate that a string is a UUID acceptable by the server's DocId parser. */
@@ -67,7 +67,7 @@ function isValidDocId(id: string): boolean {
 }
 
 /**
- * AbracadabraProvider extends HocuspocusProvider with:
+ * AbracadabraProvider extends AbracadabraBaseProvider with:
  *
  *  1. Subdocument lifecycle – intercepts Y.Doc subdoc events and syncs them
  *     with the server via MSG_SUBDOC (4) frames.  Child documents get their
@@ -87,7 +87,7 @@ function isValidDocId(id: string): boolean {
  *     can gate write operations without a network round-trip.  Role is
  *     refreshed from the server on every reconnect.
  */
-export class AbracadabraProvider extends HocuspocusProvider {
+export class AbracadabraProvider extends AbracadabraBaseProvider {
 	public effectiveRole: EffectiveRole = null;
 
 	private _client: AbracadabraClient | null;
@@ -110,7 +110,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 	constructor(configuration: AbracadabraProviderConfiguration) {
 		// Derive URL and token from client when not explicitly set.
-		const resolved = { ...configuration } as HocuspocusProviderConfiguration;
+		const resolved = { ...configuration } as AbracadabraBaseProviderConfiguration;
 		const client = configuration.client ?? null;
 
 		if (client) {
@@ -165,7 +165,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		try {
 			const url =
 				config.url ??
-				(config.websocketProvider as HocuspocusProviderWebsocket | undefined)?.url ??
+				(config.websocketProvider as AbracadabraWS | undefined)?.url ??
 				client?.wsUrl;
 			if (url) return new URL(url).hostname;
 		} catch {
@@ -429,7 +429,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		this.registerSubdoc(childDoc);
 
 		// Each child gets its own WebSocket connection.  Omitting
-		// websocketProvider lets HocuspocusProvider create one automatically
+		// websocketProvider lets AbracadabraBaseProvider create one automatically
 		// (manageSocket = true), so we do NOT call attach() manually.
 		const childProvider = new AbracadabraProvider({
 			name: childId,
@@ -527,7 +527,7 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 	get isConnected(): boolean {
 		return (
-			(this.configuration.websocketProvider as HocuspocusProviderWebsocket)
+			(this.configuration.websocketProvider as AbracadabraWS)
 				.status === "connected"
 		);
 	}

package/src/{HocuspocusProviderWebsocket.ts → AbracadabraWS.ts}

@@ -1,9 +1,9 @@
-import { WsReadyStates } from "@abraca/dabra-common";
+import { WsReadyStates } from "./types.ts";
 import { retry } from "@lifeomic/attempt";
 import * as time from "lib0/time";
 import type { Event, MessageEvent } from "ws";
 import EventEmitter from "./EventEmitter.ts";
-import type { HocuspocusProvider } from "./HocuspocusProvider.ts";
+import type { AbracadabraBaseProvider } from "./AbracadabraBaseProvider.ts";
 import { IncomingMessage } from "./IncomingMessage.ts";
 import { CloseMessage } from "./OutgoingMessages/CloseMessage.ts";
 import {
@@ -18,15 +18,21 @@ import {
   type onStatusParameters,
 } from "./types.ts";
 
-export type HocuspocusWebSocket = WebSocket & { identifier: string };
-export type HocusPocusWebSocket = HocuspocusWebSocket;
+export type AbracadabraWebSocketConn = WebSocket & { identifier: string };
+/** @deprecated Use AbracadabraWebSocketConn */
+export type HocuspocusWebSocket = AbracadabraWebSocketConn;
+/** @deprecated Use AbracadabraWebSocketConn */
+export type HocusPocusWebSocket = AbracadabraWebSocketConn;
 
-export type HocuspocusProviderWebsocketConfiguration = Required<
-  Pick<CompleteHocuspocusProviderWebsocketConfiguration, "url">
+export type AbracadabraWSConfiguration = Required<
+  Pick<CompleteAbracadabraWSConfiguration, "url">
 > &
-  Partial<CompleteHocuspocusProviderWebsocketConfiguration>;
+  Partial<CompleteAbracadabraWSConfiguration>;
 
-export interface CompleteHocuspocusProviderWebsocketConfiguration {
+/** @deprecated Use AbracadabraWSConfiguration */
+export type HocuspocusProviderWebsocketConfiguration = AbracadabraWSConfiguration;
+
+export interface CompleteAbracadabraWSConfiguration {
   /**
    * Whether to connect automatically when creating the provider instance. Default=true
    */
@@ -99,13 +105,16 @@ export interface CompleteHocuspocusProviderWebsocketConfiguration {
   /**
    * Map of attached providers keyed by documentName.
    */
-  providerMap: Map<string, HocuspocusProvider>;
+  providerMap: Map<string, AbracadabraBaseProvider>;
 }
 
-export class HocuspocusProviderWebsocket extends EventEmitter {
+/** @deprecated Use CompleteAbracadabraWSConfiguration */
+export type CompleteHocuspocusProviderWebsocketConfiguration = CompleteAbracadabraWSConfiguration;
+
+export class AbracadabraWS extends EventEmitter {
   private messageQueue: any[] = [];
 
-  public configuration: CompleteHocuspocusProviderWebsocketConfiguration = {
+  public configuration: CompleteAbracadabraWSConfiguration = {
     url: "",
     autoConnect: true,
     preserveTrailingSlash: false,
@@ -144,7 +153,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     providerMap: new Map(),
   };
 
-  webSocket: HocusPocusWebSocket | null = null;
+  webSocket: AbracadabraWebSocketConn | null = null;
 
   webSocketHandlers: { [key: string]: any } = {};
 
@@ -165,7 +174,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     reject: (reason?: any) => void;
   } | null = null;
 
-  constructor(configuration: HocuspocusProviderWebsocketConfiguration) {
+  constructor(configuration: AbracadabraWSConfiguration) {
     super();
     this.setConfiguration(configuration);
 
@@ -208,7 +217,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     this.receivedOnOpenPayload = event;
   }
 
-  attach(provider: HocuspocusProvider) {
+  attach(provider: AbracadabraBaseProvider) {
     this.configuration.providerMap.set(provider.configuration.name, provider);
 
     if (this.status === WebSocketStatus.Disconnected && this.shouldConnect) {
@@ -220,7 +229,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     }
   }
 
-  detach(provider: HocuspocusProvider) {
+  detach(provider: AbracadabraBaseProvider) {
     if (this.configuration.providerMap.has(provider.configuration.name)) {
       provider.send(CloseMessage, {
         documentName: provider.configuration.name,
@@ -230,7 +239,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   }
 
   public setConfiguration(
-    configuration: Partial<HocuspocusProviderWebsocketConfiguration> = {},
+    configuration: Partial<AbracadabraWSConfiguration> = {},
   ): void {
     this.configuration = { ...this.configuration, ...configuration };
 
@@ -274,7 +283,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
           }
         },
       }).catch((error: any) => {
-        // If we aborted the connection attempt then don’t throw an error
+        // If we aborted the connection attempt then don't throw an error
         // ref: https://github.com/lifeomic/attempt/blob/master/src/index.ts#L136
         if (error && error.code !== "ATTEMPT_ABORTED") {
           throw error;
@@ -296,7 +305,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  attachWebSocketListeners(ws: HocusPocusWebSocket, reject: Function) {
+  attachWebSocketListeners(ws: AbracadabraWebSocketConn, reject: Function) {
     const { identifier } = ws;
     const onMessageHandler = (payload: any) => this.emit("message", payload);
     const onCloseHandler = (payload: any) => this.emit("close", { event: payload });
@@ -410,17 +419,17 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
   closeTries = 0;
 
   checkConnection() {
-    // Don’t check the connection when it’s not even established
+    // Don't check the connection when it's not even established
     if (this.status !== WebSocketStatus.Connected) {
       return;
     }
 
-    // Don’t close the connection while waiting for the first message
+    // Don't close the connection while waiting for the first message
     if (!this.lastMessageReceived) {
       return;
     }
 
-    // Don’t close the connection when a message was received recently
+    // Don't close the connection when a message was received recently
     if (
       this.configuration.messageReconnectTimeout >=
       time.getUnixTime() - this.lastMessageReceived
@@ -497,7 +506,7 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
       this.rejectConnectionAttempt();
     }
 
-    // Let’s update the connection status.
+    // Let's update the connection status.
     this.status = WebSocketStatus.Disconnected;
     this.emit("status", { status: WebSocketStatus.Disconnected });
 
@@ -535,3 +544,8 @@ export class HocuspocusProviderWebsocket extends EventEmitter {
     this.cleanupWebSocket();
   }
 }
+
+/** @deprecated Use AbracadabraWS */
+export const HocuspocusProviderWebsocket = AbracadabraWS;
+/** @deprecated Use AbracadabraWS */
+export type HocuspocusProviderWebsocket = AbracadabraWS;

package/src/CloseEvents.ts

@@ -0,0 +1,49 @@
+export interface CloseEvent {
+	code: number;
+	reason: string;
+}
+
+/**
+ * The server is terminating the connection because a data frame was received
+ * that is too large.
+ * See: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code
+ */
+export const MessageTooBig: CloseEvent = {
+	code: 1009,
+	reason: "Message Too Big",
+};
+
+/**
+ * The server successfully processed the request, asks that the requester reset
+ * its document view, and is not returning any content.
+ */
+export const ResetConnection: CloseEvent = {
+	code: 4205,
+	reason: "Reset Connection",
+};
+
+/**
+ * Similar to Forbidden, but specifically for use when authentication is required and has
+ * failed or has not yet been provided.
+ */
+export const Unauthorized: CloseEvent = {
+	code: 4401,
+	reason: "Unauthorized",
+};
+
+/**
+ * The request contained valid data and was understood by the server, but the server
+ * is refusing action.
+ */
+export const Forbidden: CloseEvent = {
+	code: 4403,
+	reason: "Forbidden",
+};
+
+/**
+ * The server timed out waiting for the request.
+ */
+export const ConnectionTimeout: CloseEvent = {
+	code: 4408,
+	reason: "Connection Timeout",
+};