@chitchat/sdk-web 0.1.0-dev.1 → 0.1.0-dev.2

package/README.md

@@ -1,5 +1,130 @@
 # 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.
+
+## 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));
+  }
+};
+```
+
+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/package.json

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