@abraca/dabra

@abraca/dabra

The TypeScript/JavaScript client SDK for the Abracadabra collaboration server.

@abraca/dabra pairs a Yjs Y.Doc with a WebSocket CRDT sync provider, a REST client, an offline-first IndexedDB layer, optional end-to-end encryption, RPC v1, live queries, and an optional WebRTC peer-to-peer stack.

import * as Y from "yjs";
import { AbracadabraClient, AbracadabraProvider } from "@abraca/dabra";

const client = new AbracadabraClient({ url: "https://my-server.example.com" });
await client.login("alice", "secret");

const doc = new Y.Doc();
const provider = new AbracadabraProvider({ name: docId, document: doc, client });
await provider.ready;                       // cached state OR first sync (5s cap)

doc.getText("content").insert(0, "Hello!"); // syncs to server + all clients

Documentation

Full, code-derived documentation lives in docs/ — a numbered Nuxt-Content site covering the provider, WebSocket/sync, REST client, offline-first, the document ORM, auth & crypto, end-to-end encryption, messaging/RPC/queries, WebRTC, and a reference of every event, close code, and gotcha. It is the source of truth; this README is the elevator pitch.

Install

pnpm add @abraca/dabra yjs y-protocols

yjs and y-protocols are peer dependencies.

Highlights

• Offline-first — the Y.Doc is hydrated from IndexedDB before any server contact; await provider.ready, then check provider.hasCachedContent.
• One socket, many docs — Hocuspocus V2 binary protocol multiplexed by document name, with exponential-backoff reconnect and cross-tab BroadcastChannel sync.
• Permission-aware — viewer/observer local edits persist locally but are never sent; gate UI on provider.canWrite.
• E2E — E2EAbracadabraProvider, DocKeyManager, EncryptedY, encrypted chat (Ed25519 identity → X25519 ECDH → AES-256-GCM).
• RPC v1 & live queries — provider.rpc and provider.subscribeQuery, lazily wired per document.
• WebRTC (optional) — P2P data channels, per-peer E2EE, and device pairing.

See docs/8.reference/ for the non-obvious behaviours (deferred synced, serverError vs stateless, the five IndexedDB databases, RPC registry replay).

License

MIT.