@chitchat/sdk-web 0.2.0-dev.1 → 0.2.0-dev.3

package/README.md

@@ -6,17 +6,17 @@ This package is currently a **development prerelease**. Pin the version you have
 
 ## 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.
+The Web SDK now rejects text or JSON transport frames. `protobuf.encode` and optional `protobuf.encodeAuth` must return binary Protobuf bytes. With the official protocol codec, `connect()` resolves only after the gateway accepts the handshake. 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.
+3. `@chitchat/sdk-protocol`, the official codec 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
+npm install @chitchat/sdk-core@development @chitchat/sdk-web@development @chitchat/sdk-protocol@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.
@@ -26,7 +26,7 @@ Do not install `@chitchat/sdk-server` in a browser application and never expose
 ```js
 import { createBackendTokenProvider } from '@chitchat/sdk-core';
 import { createChitChatWebClient } from '@chitchat/sdk-web';
-import { chitchatEnvelopeCodec } from './generated/chitchat-envelope-codec.js';
+import { createRealtimeEnvelopeCodec } from '@chitchat/sdk-protocol';
 
 const tokenProvider = createBackendTokenProvider({
   endpoint: 'https://api.example.com/api/chitchat/session',
@@ -37,8 +37,7 @@ const tokenProvider = createBackendTokenProvider({
 const client = createChitChatWebClient({
   endpoint: 'https://realtime.example.com',
   tokenProvider,
-  // This must encode/decode the deployed Protobuf envelope—not JSON.
-  protobuf: chitchatEnvelopeCodec,
+  protobuf: createRealtimeEnvelopeCodec({ deviceId: getStableInstallationId(), platform: 'web' }),
   storage: indexedDbOutbox
 });
 
@@ -57,27 +56,9 @@ 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.
+## Official Protobuf codec
 
-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.
+Use `createRealtimeEnvelopeCodec({ deviceId, platform })`; it produces the handshake and application envelope bytes, handles ACK translation, and rejects invalid data. Do not use a JSON mock codec in production.
 
 ## Sending and receiving
 

package/index.d.ts

@@ -1,5 +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 interface ProtobufCodec { encode(frame: RealtimeFrame): ArrayBuffer | ArrayBufferView; decode(binary: ArrayBuffer | Blob): RealtimeFrame; encodeAuth?(input: { token: string; protocol: 'chitchat.protobuf.v1' }): ArrayBuffer | ArrayBufferView; isAuthenticationAccepted?(frame: RealtimeFrame): boolean; authenticationError?(frame: RealtimeFrame): string | null; 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,12 +1,18 @@
 {
   "name": "@chitchat/sdk-web",
-  "version": "0.2.0-dev.1",
+  "version": "0.2.0-dev.3",
+  "description": "Browser WSS transport for the ChitChat Developer Platform",
+  "repository": { "type": "git", "url": "git+https://github.com/07Akashh/E2E-Chat.git", "directory": "developer-web/sdk/chitchat-web" },
+  "bugs": { "url": "https://github.com/07Akashh/E2E-Chat/issues" },
+  "homepage": "https://github.com/07Akashh/E2E-Chat/tree/main/docs/developer-platform",
   "main": "src/index.js",
   "exports": { ".": { "types": "./index.d.ts", "require": "./src/index.js", "import": "./src/index.js" } },
   "types": "index.d.ts",
-  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
+  "files": ["src", "index.d.ts", "README.md"],
   "engines": { "node": ">=18" },
-  "dependencies": { "@chitchat/sdk-core": "0.2.0-dev.1" },
+  "dependencies": { "@chitchat/sdk-core": "0.2.0-dev.2" },
+  "keywords": ["chitchat", "realtime", "websocket", "wss", "protobuf"],
+  "sideEffects": false,
   "license": "UNLICENSED",
   "publishConfig": { "access": "public", "tag": "development" }
 }

package/src/index.js

@@ -20,11 +20,12 @@ const binaryFrame = (value, name) => {
   return value;
 };
 
-const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, encodeAuth, allowInsecureWs = false, openTimeoutMs = 15_000 }) => {
+const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, encodeAuth, isAuthenticationAccepted, authenticationError, 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 isAuthenticationAccepted !== 'function') throw new Error('isAuthenticationAccepted is required so the SDK can verify the realtime handshake');
   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 opened = false;
+    let socket; let onMessage = () => {}; let onClose = () => {}; let opened = false; let authenticationPending = true;
     const encodeFrame = (frame) => binaryFrame(encode(frame), 'protobuf.encode');
     const encodeAuthentication = () => binaryFrame(encodeAuth ? encodeAuth({ token, protocol }) : encode({ type: 'auth', token, protocol }), 'protobuf authentication encoder');
     return {
@@ -39,7 +40,7 @@ const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encod
           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); }
+            try { socket.send(encodeAuthentication()); }
             catch (error) { finish(reject, error); try { socket.close(); } catch (_) {} }
           };
           socket.onerror = () => finish(reject, new Error('WSS connection failed'));
@@ -48,8 +49,15 @@ const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encod
             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' }); }
+            try {
+              const frame = decode(event.data);
+              if (authenticationPending) {
+                const rejection = typeof authenticationError === 'function' ? authenticationError(frame) : null;
+                if (rejection) { finish(reject, new Error(rejection)); try { socket.close(); } catch (_) {} return; }
+                if (isAuthenticationAccepted(frame)) { authenticationPending = false; opened = true; finish(resolve); onMessage(frame); return; }
+              }
+              onMessage(frame);
+            } catch (_) { try { socket.close(); } catch (_) {} onClose({ code: 'PROTOCOL_DECODE_ERROR', reason: 'Invalid Protobuf frame' }); }
           };
         } catch (error) { finish(reject, error); }
       }),