rooms-kit / README.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
# ardegazu-rooms-kit

Headless Node clients for the [ardegazu.ro](https://ardegazu.ro) suite's
replicated-log rooms: **sueta chat** and the **board**. The same encrypted
OrbitDB log the browsers replicate, the same sealed live channels, the same
suite identity in authorship — from any Node ≥ 22 process.

Written in **ClojureScript** (v2.0.0); TypeScript and JavaScript consumers get
committed compiled ESM plus hand-authored `.d.ts`, so nothing changes for them.

- **`lib/`** — the chat/board shared core: the room crypto (HKDF key ladder,
  per-sender sealers, at-rest ciphers), the libp2p Net (presence beacons,
  two-stage dialing, directed sealed streams), and the RoomLog (OrbitDB events
  DB with entry+payload encryption, the hardened access controller, the suite
  identity provider) on filesystem stores.
- **`chat/`** — `ChatClient`: history replay from local storage, live
  replication, send/react/rename, verified identity badges per peer.
- **`board/`** — `BoardClient` (link-mode boards): the element fold
  (add/edit/del), and `drawStroke()` — a throttled live preview followed by
  the committed op, exactly what the pen tool produces.

The suite identity comes from **`ardegazu-id-kit`**, a sha-pinned dependency.
`Identity` is that kit's own class: its ClojureScript sources are on this
build's classpath, so it is compiled here rather than imported from its dist —
one compile per build, and the same implementation everywhere. (Up to v1.0.0
this repo carried a hand-maintained TypeScript copy of it under `src/vendor/id`
— that vendoring is retired; a pinned upstream is not a copy.)

## Consuming

```jsonc
// package.json
"dependencies": { "ardegazu-rooms-kit": "git+https://git.ardegazu.ro/rooms-kit.git#v2.0.0" }
```

The package ships the ClojureScript source (`src/`), the committed compiled
output (`dist/`, what the `exports` map serves) and the declarations
(`types/`) — plain `node` works with no build step.

```ts
import { ChatClient } from "ardegazu-rooms-kit/chat";
import { Identity } from "ardegazu-rooms-kit";

const identity = await Identity.fromSeed("<43-char suite seed>");
const chat = await ChatClient.join({
  roomSecret: "<invite-link fragment>",
  name: "my-bot",
  dataDir: "./state/room-1",
  identity,
});
chat.on("message", (m) => console.log(`${m.name}: ${m.text}`));
await chat.send("hello from Node");
```

Direct WebRTC upgrades need the native `@ipshipyard/node-datachannel`
prebuild. With npm's `ignore-scripts` on, fetch it once after install:

```sh
(cd node_modules/@ipshipyard/node-datachannel && npx prebuild-install -r napi)
```

WebRTC here is not optional: the browsers replicate the log only over direct
connections. And do not load this package and `ardegazu-peer-kit`'s WebRTC in
one process — their transports carry two different builds of the same native
library, which cannot coexist; run rooms in a worker process (the suite's bot
does exactly that). `deploy/check-dist.sh` enforces the split from this side.

## Develop

Needs Node ≥ 22, plus a JVM ≥ 17 and the `clojure` CLI for the build.

```sh
npm install
npm run check     # shadow-cljs compile + tsc --noEmit of the consumer smoke
npm run build     # dist/ (committed, deterministic)
npm test          # golden vectors + transcripts, against dist/
```

Tests run against `dist/` only. `ROOMS_KIT_TS=1 npm test` re-runs them against
the v1.0.0 TypeScript build instead — how the assertions were validated before
the port landed.

Public mirror (git dumb-HTTP — no git server):

```sh
git clone https://git.ardegazu.ro/rooms-kit.git
```

static mirror of HEAD · about · clone: git clone https://git.ardegazu.ro/rooms-kit.git