@chitchat/sdk-web 0.1.0-dev.1 → 0.2.0-dev.0

package/README.md

@@ -1,5 +1,136 @@
 # ChitChat Web SDK
 
-`createChitChatWebClient` always uses WSS. It authenticates through the first binary Protobuf frame, never by placing a session token in a URL. Supply the generated Protobuf codec and a function that fetches a short-lived project-user session token. Plain `ws://` is rejected except for an explicit `allowInsecureWs: true` localhost-only development configuration.
+`@chitchat/sdk-web` connects a browser to ChitChat realtime using secure WebSocket (**WSS**) and binary Protobuf frames. Browsers cannot use raw TCP, so this package never attempts it.
 
-Raw TCP is not available in browsers and is never attempted by this module.
+This package is currently a **development prerelease**. Pin the version you have tested before shipping an application.
+
+## SDK foundation in v0.2
+
+The Web SDK now rejects text or JSON transport frames. `protobuf.encode` and optional `protobuf.encodeAuth` must return binary Protobuf bytes. Connection opening has a bounded timeout and transport failures are isolated from stale sockets.
+
+## What you need first
+
+1. A backend session endpoint created with `@chitchat/sdk-server`. It authenticates the person in your product and returns a short-lived `{ token, expiresAt }` response.
+2. An HTTPS realtime endpoint, for example `https://realtime.example.com`. The SDK converts it to `wss://realtime.example.com`.
+3. A generated Protobuf codec adapter that is compatible with the ChitChat gateway’s current `chitchat.protobuf.v1` envelope and authentication frame.
+4. A durable browser outbox implementation (IndexedDB) if messages must survive page reloads.
+
+```bash
+npm install @chitchat/sdk-core@development @chitchat/sdk-web@development
+```
+
+Do not install `@chitchat/sdk-server` in a browser application and never expose a ChitChat server API key in JavaScript, public environment variables, source maps, or logs.
+
+## Minimal connection setup
+
+```js
+import { createBackendTokenProvider } from '@chitchat/sdk-core';
+import { createChitChatWebClient } from '@chitchat/sdk-web';
+import { chitchatEnvelopeCodec } from './generated/chitchat-envelope-codec.js';
+
+const tokenProvider = createBackendTokenProvider({
+  endpoint: 'https://api.example.com/api/chitchat/session',
+  credentials: 'include',
+  getBody: () => ({ deviceId: getStableInstallationId() })
+});
+
+const client = createChitChatWebClient({
+  endpoint: 'https://realtime.example.com',
+  tokenProvider,
+  // This must encode/decode the deployed Protobuf envelope—not JSON.
+  protobuf: chitchatEnvelopeCodec,
+  storage: indexedDbOutbox
+});
+
+client.on('connected', () => setRealtimeState('connected'));
+client.on('disconnected', () => setRealtimeState('reconnecting'));
+client.on('message', (frame) => handleChitChatFrame(frame));
+client.on('error', (error) => reportNonSensitiveRealtimeError(error));
+
+await client.connect();
+```
+
+When the user signs out or switches accounts, close the old client before creating a new one:
+
+```js
+await client.close();
+tokenProvider.invalidate();
+```
+
+## Protobuf codec requirement
+
+Pass an object with these two functions:
+
+```js
+const chitchatEnvelopeCodec = {
+  encode(frame) {
+    // Convert the SDK frame to the exact generated Protobuf envelope bytes.
+    // The first auth frame must match the gateway handshake schema.
+    return generatedEnvelope.encode(frame).finish();
+  },
+  decode(binary) {
+    // Convert ArrayBuffer / binary data from the gateway into an SDK frame.
+    return generatedEnvelope.decode(new Uint8Array(binary));
+  }
+};
+```
+
+If the gateway has a distinct authentication envelope, add `encodeAuth({ token, protocol })` to the codec. It must also return binary bytes.
+
+Do not use a JSON mock codec in production. This SDK release exposes the adapter boundary; the generated ChitChat envelope codec and the production handshake compatibility test must come from the deployed platform protocol. If that codec is unavailable, do not enable realtime for users yet.
+
+## Sending and receiving
+
+```js
+const localMessageId = await client.send('chat.message', {
+  conversationId: 'conversation_123',
+  body: 'Hello'
+});
+
+client.on('ack', (messageId) => {
+  // The gateway acknowledged a queued outgoing record.
+  markMessageTransportAcknowledged(messageId);
+});
+```
+
+`send()` queues the outgoing record; it is not a peer-delivered or read receipt. Map the platform’s message/receipt frames to your UI separately.
+
+## WSS and local development
+
+- `https://...` endpoints are converted to `wss://...`.
+- `wss://...` endpoints are accepted directly.
+- `http://...` and `ws://...` are rejected by default.
+- For a loopback-only local test, opt in explicitly:
+
+```js
+const client = createChitChatWebClient({
+  endpoint: 'http://127.0.0.1:5222',
+  tokenProvider,
+  protobuf: chitchatEnvelopeCodec,
+  allowInsecureWs: true
+});
+```
+
+This local exception works only for `localhost`, `127.0.0.1`, or `::1`; never enable it for LAN, staging, or production addresses.
+
+## Common errors
+
+| Error | Fix |
+| --- | --- |
+| `Web realtime requires WSS` | Use an HTTPS/WSS realtime endpoint. Do not use TCP or non-local WS from a browser. |
+| `WSS connection failed` | Check DNS, TLS certificate/hostname, gateway availability, session token, and gateway origin policy. |
+| Connection opens then protocol errors | Your codec or first Protobuf auth frame does not match the deployed gateway schema. Regenerate/use the correct protocol adapter. |
+| Messages disappear after reload | Supply an IndexedDB-backed `storage`; the default core store is memory-only. |
+| Browser session endpoint is rejected | Verify CORS/cookie policy and authenticate the user in your own backend before issuing a ChitChat session. |
+
+## Security checklist
+
+- Keep the server API key in your backend only.
+- Use HTTPS for your token endpoint and WSS for realtime.
+- Do not put session tokens in URLs, logs, analytics, or error reports.
+- Restrict the backend CORS policy to your actual web origins and protect the session endpoint against CSRF when using cookies.
+- Call `close()` and invalidate the token provider at logout.
+
+## Current scope
+
+The Web SDK handles a WSS transport and the reliable client lifecycle. Chat UI, conversation APIs, attachments, read receipts, WebRTC media, meetings, streaming, notifications, and agents require their own deployed platform APIs and protocol handlers.

package/index.d.ts

@@ -0,0 +1,5 @@
+import type { ReliableRealtimeClient, ReliableRealtimeClientOptions, RealtimeFrame } from '@chitchat/sdk-core';
+export interface ProtobufCodec { encode(frame: RealtimeFrame): ArrayBuffer | ArrayBufferView; decode(binary: ArrayBuffer | Blob): RealtimeFrame; encodeAuth?(input: { token: string; protocol: 'chitchat.protobuf.v1' }): ArrayBuffer | ArrayBufferView; openTimeoutMs?: number; }
+export function toWssEndpoint(endpoint: string, options?: { allowInsecureWs?: boolean }): string;
+export function createWssTransportFactory(options: ProtobufCodec & { WebSocketImpl?: typeof WebSocket; allowInsecureWs?: boolean }): ReliableRealtimeClientOptions['webTransportFactory'];
+export function createChitChatWebClient(options: Omit<ReliableRealtimeClientOptions, 'runtime' | 'webTransportFactory'> & { protobuf: ProtobufCodec; allowInsecureWs?: boolean }): ReliableRealtimeClient;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@chitchat/sdk-web",
-  "version": "0.1.0-dev.1",
+  "version": "0.2.0-dev.0",
   "main": "src/index.js",
-  "exports": "./src/index.js",
-  "files": ["src", "README.md", "LICENSE"],
+  "exports": { ".": { "types": "./index.d.ts", "require": "./src/index.js" } },
+  "types": "index.d.ts",
+  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
   "engines": { "node": ">=18" },
-  "dependencies": { "@chitchat/sdk-core": "0.1.0-dev.1" },
+  "dependencies": { "@chitchat/sdk-core": "0.2.0-dev.0" },
   "license": "UNLICENSED",
   "publishConfig": { "access": "public", "tag": "development" }
 }

package/src/index.js

@@ -14,27 +14,62 @@ const toWssEndpoint = (endpoint, { allowInsecureWs = false } = {}) => {
   return url.toString();
 };
 
-const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, allowInsecureWs = false }) => {
+const isBinary = (value) => value instanceof ArrayBuffer || ArrayBuffer.isView(value) || (typeof Buffer !== 'undefined' && Buffer.isBuffer(value));
+const binaryFrame = (value, name) => {
+  if (!isBinary(value)) throw new Error(`${name} must return a binary Protobuf frame`);
+  return value;
+};
+
+const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, encodeAuth, allowInsecureWs = false, openTimeoutMs = 15_000 }) => {
   if (!WebSocketImpl || typeof encode !== 'function' || typeof decode !== 'function') throw new Error('WebSocket implementation and protobuf encode/decode functions are required');
+  if (typeof openTimeoutMs !== 'number' || !Number.isFinite(openTimeoutMs) || openTimeoutMs < 100 || openTimeoutMs > 120_000) throw new Error('openTimeoutMs must be between 100 and 120000');
   return async ({ endpoint, token, protocol }) => {
-    let socket; let onMessage = () => {}; let onClose = () => {};
+    let socket; let onMessage = () => {}; let onClose = () => {}; let opened = false;
+    const encodeFrame = (frame) => binaryFrame(encode(frame), 'protobuf.encode');
+    const encodeAuthentication = () => binaryFrame(encodeAuth ? encodeAuth({ token, protocol }) : encode({ type: 'auth', token, protocol }), 'protobuf authentication encoder');
     return {
       onMessage: (listener) => { onMessage = listener; },
       onClose: (listener) => { onClose = listener; },
       open: () => new Promise((resolve, reject) => {
-        socket = new WebSocketImpl(toWssEndpoint(endpoint, { allowInsecureWs }), protocol);
-        socket.binaryType = 'arraybuffer';
-        socket.onopen = () => { socket.send(encode({ type: 'auth', token })); resolve(); };
-        socket.onerror = () => reject(new Error('WSS connection failed'));
-        socket.onclose = (event) => onClose({ code: event.code, reason: event.reason });
-        socket.onmessage = (event) => onMessage(decode(event.data));
+        let timer;
+        let settled = false;
+        const finish = (handler, value) => { if (settled) return; settled = true; clearTimeout(timer); handler(value); };
+        try {
+          socket = new WebSocketImpl(toWssEndpoint(endpoint, { allowInsecureWs }), protocol);
+          socket.binaryType = 'arraybuffer';
+          timer = setTimeout(() => { try { socket.close(); } catch (_) {} finish(reject, new Error('WSS connection timed out')); }, openTimeoutMs);
+          socket.onopen = () => {
+            try { socket.send(encodeAuthentication()); opened = true; finish(resolve); }
+            catch (error) { finish(reject, error); try { socket.close(); } catch (_) {} }
+          };
+          socket.onerror = () => finish(reject, new Error('WSS connection failed'));
+          socket.onclose = (event = {}) => {
+            if (!opened) finish(reject, new Error(event.reason || 'WSS connection closed before opening'));
+            onClose({ code: event.code, reason: event.reason });
+          };
+          socket.onmessage = (event) => {
+            try { onMessage(decode(event.data)); }
+            catch (_) { try { socket.close(); } catch (_) {} onClose({ code: 'PROTOCOL_DECODE_ERROR', reason: 'Invalid Protobuf frame' }); }
+          };
+        } catch (error) { finish(reject, error); }
       }),
-      send: (frame) => socket.send(encode(frame)),
-      close: () => new Promise((resolve) => { if (!socket || socket.readyState === 3) return resolve(); socket.onclose = () => resolve(); socket.close(); })
+      send: (frame) => {
+        if (!socket || socket.readyState !== 1) return Promise.reject(new Error('WSS transport is not open'));
+        try { socket.send(encodeFrame(frame)); return Promise.resolve(); } catch (error) { return Promise.reject(error); }
+      },
+      close: () => new Promise((resolve) => {
+        if (!socket || socket.readyState === 3) return resolve();
+        const current = socket.onclose;
+        socket.onclose = (event) => { if (typeof current === 'function') current(event); resolve(); };
+        try { socket.close(); } catch (_) { resolve(); }
+      })
     };
   };
 };
 
-const createChitChatWebClient = ({ endpoint, tokenProvider, protobuf, allowInsecureWs = false, ...options }) => new ReliableRealtimeClient({ endpoint, tokenProvider, runtime: 'web', webTransportFactory: createWssTransportFactory({ ...protobuf, allowInsecureWs }), ...options });
+const createChitChatWebClient = ({ endpoint, tokenProvider, protobuf, allowInsecureWs = false, ...options }) => {
+  if (!protobuf || typeof protobuf !== 'object') throw new Error('protobuf codec is required');
+  return new ReliableRealtimeClient({ endpoint, tokenProvider, runtime: 'web', webTransportFactory: createWssTransportFactory({ ...protobuf, allowInsecureWs }), ...options });
+};
 
 module.exports = { createChitChatWebClient, createWssTransportFactory, toWssEndpoint };