@vxil/realtime 0.1.0 → 0.2.1

package/README.md

@@ -16,13 +16,14 @@ Or zero-install in the browser — the same client is served as a self-contained
 
 ## The one rule: connect tokens, not API keys
 
-Your Vxil API key is a **server-side secret — never put it in a browser bundle**. A browser connects with a short-lived, scoped **connect token** instead: your backend (which holds the key) mints one via `POST /v1/realtime/tokens` and hands it to the client. `RealtimeClient` takes that minting step as a `tokenProvider` callback and re-mints automatically whenever the cached token nears expiry.
+A **server** key is a secret — never put it in a browser bundle. A browser connects with a short-lived, scoped **connect token** instead, minted via `POST /v1/realtime/tokens` either by your backend (which holds the server key) or, with no backend of your own, by the browser itself using a **public `end_user_required` key plus the signed-in user's session**: that mint runs in end-user mode and the token subject is forced to the verified user. `RealtimeClient` takes the minting step as a `tokenProvider` callback and re-mints automatically whenever the cached token nears expiry.
 
 ```ts
 import { RealtimeClient } from '@vxil/realtime';
 
 const rt = new RealtimeClient({
-  // Implemented against YOUR backend — the browser never sees the API key.
+  // Here: your backend's endpoint (it holds the server key). With a public
+  // end_user_required key + the user's session, use the @vxil/sdk glue below.
   tokenProvider: async ({ channel }) => {
     const res = await fetch('/api/realtime-token', {
       method: 'POST',
@@ -40,7 +41,7 @@ room.on('message.created', (frame) => console.log(frame.data));
 room.send({ type: 'message', text: 'hello' }); // buffered while offline, flushed on reconnect
 ```
 
-The `tokenProvider` result may be any one of `connect_url` (full URL), `connect_path` (as returned by the tokens endpoint), or a raw `token`; include `expires_at` to enable pre-expiry re-minting. Server-side (Node) callers can use the `vxil.realtime.tokenProvider({ user_id })` glue from `@vxil/sdk` — it returns a function matching this shape.
+The `tokenProvider` result may be any one of `connect_url` (full URL), `connect_path` (as returned by the tokens endpoint), or a raw `token`; include `expires_at` to enable pre-expiry re-minting. The `vxil.realtime.tokenProvider({ user_id })` glue from `@vxil/sdk` returns a function matching this shape — on a server with a server key, or in the browser with a public `end_user_required` key and `endUserToken` set to the user's session (the subject is then the verified user, whatever `user_id` says).
 
 ## What it adds over a raw WebSocket
 

package/dist/index.d.ts

@@ -8,10 +8,14 @@ export type TokenProviderResult = {
     /** ISO timestamp; enables pre-expiry re-mint. Absent ⇒ re-mint every attempt. */
     expires_at?: string;
 };
-/** Your app implements this against YOUR backend (which holds the tenant API
- *  key and calls POST /v1/realtime/tokens). Server-side (Node) callers can use
- *  the `vxil.realtime.tokenProvider({ user_id })` glue from @vxil/sdk — it
- *  returns a function matching this type structurally. */
+/** Returns a connect token minted by POST /v1/realtime/tokens. The
+ *  `vxil.realtime.tokenProvider({ user_id })` glue from @vxil/sdk returns a
+ *  function matching this type structurally, and works in two set-ups: on a
+ *  server with a server key, or in a browser / mobile app with a PUBLIC
+ *  `end_user_required` key plus the signed-in user's session — that mint runs
+ *  in end-user mode and the token subject is forced to the verified user, so
+ *  no backend of your own is needed. Your own backend endpoint works too. The
+ *  one rule: never put a SERVER key in a browser bundle. */
 export type TokenProvider = (ctx: {
     channel: string;
 }) => Promise<TokenProviderResult>;
@@ -62,8 +66,13 @@ export interface PresenceEvent {
 type FrameListener = (frame: RealtimeFrame) => void;
 type StateListener = (state: ChannelState, detail?: {
     attempt?: number;
-    error?: unknown;
+    error?: unknown; /** the server close code on a terminal close */
+    code?: number;
 }) => void;
+/** Server close code: the end-user's auth session was revoked — terminal, the
+ *  client never reconnects on it (a fresh subscribe() after sign-in does). The
+ *  24 h socket-lifetime close (4001) reconnects like any other close. */
+export declare const CLOSE_SESSION_REVOKED = 4002;
 type PresenceListener = (d: PresenceEvent) => void;
 export declare class Channel {
     readonly name: string;

package/dist/index.js

@@ -28,6 +28,10 @@
 // pass a constructor — `import WebSocket from 'ws'; new RealtimeClient({
 // ..., WebSocket })` — instead of failing with a silent `WebSocket is not
 // defined`. (The `ws` package is NOT a dependency of this package.)
+/** Server close code: the end-user's auth session was revoked — terminal, the
+ *  client never reconnects on it (a fresh subscribe() after sign-in does). The
+ *  24 h socket-lifetime close (4001) reconnects like any other close. */
+export const CLOSE_SESSION_REVOKED = 4002;
 const DEFAULT_BASE = 'https://api.vxil.com';
 function resolveCtor(injected) {
     const WS = injected ?? globalThis.WebSocket;
@@ -293,7 +297,17 @@ export class Channel {
                 clearTimeout(this.flushFallback);
                 this.flushFallback = undefined;
             }
-            this.scheduleReconnect(new Error(`websocket closed (code ${ev.code ?? 'unknown'})`));
+            const error = new Error(`websocket closed (code ${ev.code ?? 'unknown'})`);
+            if (ev.code === CLOSE_SESSION_REVOKED) {
+                // The end-user's auth session was revoked server-side (sign-out,
+                // revoke-all, erase). Reconnecting would loop forever against a mint
+                // that now 401s — terminal instead; subscribe() again after sign-in.
+                this.userClosed = true;
+                this.settleOpen(error);
+                this.setState('closed', { code: ev.code, error });
+                return;
+            }
+            this.scheduleReconnect(error);
         });
         // In browsers every 'error' is followed by 'close' — counting both would
         // double-step the backoff, so only 'close' drives the state machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/realtime",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "sideEffects": false,