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

package/README.md

@@ -4,6 +4,10 @@
 
 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.
@@ -71,6 +75,8 @@ const chitchatEnvelopeCodec = {
 };
 ```
 
+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

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.2",
+  "version": "0.2.0-dev.1",
   "main": "src/index.js",
-  "exports": "./src/index.js",
-  "files": ["src", "README.md", "LICENSE"],
+  "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"],
   "engines": { "node": ">=18" },
-  "dependencies": { "@chitchat/sdk-core": "0.1.0-dev.2" },
+  "dependencies": { "@chitchat/sdk-core": "0.2.0-dev.1" },
   "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 };