# @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.
