@vxil/realtime 0.2.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>;

package/package.json

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