@digo-labs/ws 0.2.0 → 0.2.1

package/README.md

@@ -1,11 +1,54 @@
 # @digo-labs/ws
 
-The low-level websocket client (`WebsocketClient`), server primitives (`@digo-labs/ws/server`), and the `digo-ws-hub` CLI for local development. Most apps use the typed wrapper in [`@digo-labs/services`](https://design.digo-labs.com/docs/guide/package-services) instead.
+The low-level websocket client (`WebsocketClient`), the hub server (`@digo-labs/ws/server`), and the `digo-ws-hub` CLI for running a hub locally. Most apps use the typed `Websockets` wrapper from [`@digo-labs/services`](https://design.digo-labs.com/docs/guide/package-services) instead, which builds a `WebsocketClient` for you and adds the app name and auth token.
 
-**📖 Full documentation:** https://design.digo-labs.com/docs/guide/package-ws
-
-The Digo design-system guide is the single source of truth for this package — its full API, examples, and patterns live there. This README stays thin on purpose and points to it.
+**How to read this.** This guide ships with the package, so it matches the version you have installed; the site describes the latest release. The types in `node_modules/@digo-labs/ws/dist/*.d.ts` are exact and win if they disagree with it. Deeper pages: https://design.digo-labs.com/docs/guide/package-ws.
 
 ```bash
 npm install @digo-labs/ws
 ```
+
+## Client
+
+`new WebsocketClient(config)` connects straight away. Every config field is optional: `url` (default `WS_URL` from `@digo-labs/common`, `wss://ws.digo-labs.com`), `app` (default `'unknown'`), `id` (default a random UUID), `reconnect` (default `true`), `reconnectInterval` / `maxReconnectInterval` (default `1000` / `10000` ms, doubled with jitter) and `getToken` (an async function returning a realtime token; without it the client identifies anonymously).
+
+```ts
+import { WebsocketClient } from '@digo-labs/ws';
+
+const client = new WebsocketClient({ url: 'ws://localhost:9900', app: 'my-app' });
+
+client.subscribe('scores', data => console.log(data));
+client.send('scores', { team: 'red', points: 3 });     // one-off message to subscribers
+client.setState('scores', { red: 3, blue: 1 });        // stored by the hub, sent to anyone who subscribes later
+client.onReady(() => console.log('identified'));
+```
+
+- `send` and `setState` called while the socket is open but before the hub confirms the client are queued and flushed once it does. Subscriptions are re-sent after every reconnect.
+- `isLive(channel)` is `true` once the client is identified, subscribed and not denied on that channel.
+- `unsubscribe(channel, listener?)` removes one listener, or the whole channel when no listener is given.
+- Lifecycle: `onOpen`, `onReady` / `offReady`, `onClose`, `onError`. `close()` stops reconnecting for good.
+
+## Server
+
+`@digo-labs/ws/server` exports `WebsocketHub`, the hub itself (Node only):
+
+```ts
+import { WebsocketHub } from '@digo-labs/ws/server';
+
+const hub = new WebsocketHub({ port: 9900, tokenSecret: process.env.WS_TOKEN_SECRET });
+
+hub.onMessage((channel, data) => console.log(channel, data));
+hub.getState('scores');
+hub.close();
+```
+
+It also answers `GET /health` with `{ ok, clients }`. `tokenSecret` lets it verify the tokens clients send through `getToken`.
+
+## Running the hub locally
+
+```bash
+npx digo-ws-hub          # port 9900
+npx digo-ws-hub 9901     # another port
+```
+
+The CLI reads `WS_TOKEN_SECRET` from the environment and shuts down cleanly on Ctrl+C. Inside the core monorepo, `npm run ws` (or `npm run dev`) starts the same hub from source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digo-labs/ws",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/client.js",
   "module": "./dist/client.js",
@@ -39,7 +39,7 @@
     "lint:fix": "eslint ./src --fix"
   },
   "peerDependencies": {
-    "@digo-labs/common": "^0.2.0"
+    "@digo-labs/common": "^0.2.1"
   },
   "dependencies": {
     "ws": "^8.18.0"