@abraca/dabra 2.3.0 → 2.5.0

package/README.md

@@ -0,0 +1,50 @@
+# @abraca/dabra
+
+The TypeScript/JavaScript client SDK for the [Abracadabra](https://github.com/iojanis/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.
+
+```typescript
+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/`](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
+
+```bash
+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/`](docs/8.reference) for the non-obvious behaviours (deferred `synced`, `serverError` vs `stateless`, the five IndexedDB databases, RPC registry replay).
+
+## License
+
+MIT.