@chitchat/sdk-web 0.2.0-dev.2 → 0.3.0-dev.0

package/README.md

@@ -1,5 +1,12 @@
 # ChitChat Web SDK
 
+## 0.3.0-dev.0 source release
+
+Adds createChitChatWebCalls and @chitchat/sdk-web/react (useCallState, CallVideo). Browser signalling remains binary protobuf over WSS; media uses WebRTC.
+
+This version is **not yet published or production-certified**. See the [calling quickstart](../docs/CALLING.md), [all-five SDK audit](../docs/GAP_AUDIT.md), [migration/support targets](../docs/RELEASE.md), and [local tarball installation](../README.md). Existing npm development tags may still resolve to older SDKs.
+
+
 `@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.
 
 This package is currently a **development prerelease**. Pin the version you have tested before shipping an application.
@@ -65,7 +72,10 @@ Use `createRealtimeEnvelopeCodec({ deviceId, platform })`; it produces the hands
 ```js
 const localMessageId = await client.send('chat.message', {
   conversationId: 'conversation_123',
-  body: 'Hello'
+  receiverId: recipientGatewayId,
+  ciphertext: encryptedPayload.ciphertext,
+  iv: encryptedPayload.iv,
+  authTag: encryptedPayload.authTag
 });
 
 client.on('ack', (messageId) => {
@@ -114,4 +124,4 @@ This local exception works only for `localhost`, `127.0.0.1`, or `::1`; never en
 
 ## 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.
+The 0.3 source release includes the calling additions described above. See the [gap audit](../docs/GAP_AUDIT.md) for supported behavior and remaining service requirements. Calling is a foreground small-mesh implementation. Server-authoritative rooms, roles, moderation, recording, signed call webhooks, SFU meetings, background native calling and device/browser production certification remain unimplemented or unverified.

package/index.d.ts

@@ -1,5 +1,7 @@
 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; isAuthenticationAccepted?(frame: RealtimeFrame): boolean; authenticationError?(frame: RealtimeFrame): string | null; openTimeoutMs?: number; }
+export interface ProtobufCodec { encode(frame: RealtimeFrame): ArrayBuffer | ArrayBufferView; decode(binary: ArrayBuffer | ArrayBufferView): RealtimeFrame; encodeAuth?(input: { token: string; protocol: 'chitchat.protobuf.v1' }): ArrayBuffer | ArrayBufferView; isAuthenticationAccepted(frame: RealtimeFrame): boolean; authenticationError?(frame: RealtimeFrame): string | null; openTimeoutMs?: number; maxBufferedAmount?: 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;
+export function createChitChatWebClient(options: Omit<ReliableRealtimeClientOptions, 'runtime' | 'webTransportFactory'> & { protobuf: ProtobufCodec; WebSocketImpl?: typeof WebSocket; allowInsecureWs?: boolean }): ReliableRealtimeClient;
+
+export function createChitChatWebCalls(options: Omit<import('@chitchat/sdk-core').CallsOptions, 'rtc'> & { rtc?: import('@chitchat/sdk-core').WebRtcRuntime }): import('@chitchat/sdk-core').CallsClient;

package/package.json

@@ -1,12 +1,61 @@
 {
   "name": "@chitchat/sdk-web",
-  "version": "0.2.0-dev.2",
+  "version": "0.3.0-dev.0",
+  "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" } },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./src/index.js",
+      "import": "./src/index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "require": "./src/react.js",
+      "import": "./src/react.js"
+    }
+  },
   "types": "index.d.ts",
-  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "dependencies": { "@chitchat/sdk-core": "0.2.0-dev.1" },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "react.d.ts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@chitchat/sdk-core": "0.3.0-dev.0"
+  },
+  "keywords": [
+    "chitchat",
+    "realtime",
+    "websocket",
+    "wss",
+    "protobuf"
+  ],
+  "sideEffects": false,
   "license": "UNLICENSED",
-  "publishConfig": { "access": "public", "tag": "development" }
+  "publishConfig": {
+    "access": "public",
+    "tag": "development"
+  },
+  "peerDependencies": {
+    "react": ">=18 <20"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
 }

package/react.d.ts

@@ -0,0 +1,4 @@
+import type { CallsClient, CallSnapshot } from '@chitchat/sdk-core';
+import type { ForwardRefExoticComponent, RefAttributes, VideoHTMLAttributes } from 'react';
+export function useCallState(client: CallsClient): CallSnapshot;
+export const CallVideo: ForwardRefExoticComponent<VideoHTMLAttributes<HTMLVideoElement> & RefAttributes<HTMLVideoElement> & { stream: MediaStream | null; onPlaybackError?(event: { code: 'PLAYBACK_BLOCKED' }): void }>;

package/src/index.js

@@ -3,11 +3,11 @@
 let ReliableRealtimeClient;
 try { ({ ReliableRealtimeClient } = require('@chitchat/sdk-core')); } catch (_) { ({ ReliableRealtimeClient } = require('../../chitchat-core/src')); }
 
-const isLocalHttpUrl = (url) => ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+const isLocalHttpUrl = (url) => ['localhost', '127.0.0.1', '::1', '[::1]'].includes(url.hostname);
 const toWssEndpoint = (endpoint, { allowInsecureWs = false } = {}) => {
   let url;
   try { url = new URL(endpoint); } catch (_) { throw new Error('A valid HTTPS or WSS endpoint is required'); }
-  if (url.username || url.password) throw new Error('Realtime endpoint must not include credentials');
+  if (url.username || url.password || url.search || url.hash) throw new Error('Realtime endpoint must not include credentials');
   if (url.protocol === 'https:') url.protocol = 'wss:';
   if (url.protocol === 'http:' && allowInsecureWs === true && isLocalHttpUrl(url)) url.protocol = 'ws:';
   if (url.protocol !== 'wss:' && !(url.protocol === 'ws:' && allowInsecureWs === true && isLocalHttpUrl(url))) throw new Error('Web realtime requires WSS (WS is allowed only for explicit localhost development)');
@@ -20,63 +20,77 @@ const binaryFrame = (value, name) => {
   return value;
 };
 
-const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, encodeAuth, isAuthenticationAccepted, authenticationError, allowInsecureWs = false, openTimeoutMs = 15_000 }) => {
+const createWssTransportFactory = ({ WebSocketImpl = globalThis.WebSocket, encode, decode, encodeAuth, isAuthenticationAccepted, authenticationError, allowInsecureWs = false, openTimeoutMs = 15_000, maxBufferedAmount = 1024 * 1024 }) => {
   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');
+  if (typeof isAuthenticationAccepted !== 'function') throw new Error('isAuthenticationAccepted is required so the SDK can verify the realtime handshake');
+  if (!Number.isInteger(openTimeoutMs) || openTimeoutMs < 100 || openTimeoutMs > 120_000) throw new Error('openTimeoutMs must be between 100 and 120000');
+  if (!Number.isInteger(maxBufferedAmount) || maxBufferedAmount < 1 || maxBufferedAmount > 16 * 1024 * 1024) throw new Error('maxBufferedAmount is invalid');
   return async ({ endpoint, token, protocol }) => {
-    let socket; let onMessage = () => {}; let onClose = () => {}; let opened = false; let authenticationPending = typeof isAuthenticationAccepted === 'function';
-    const encodeFrame = (frame) => binaryFrame(encode(frame), 'protobuf.encode');
-    const encodeAuthentication = () => binaryFrame(encodeAuth ? encodeAuth({ token, protocol }) : encode({ type: 'auth', token, protocol }), 'protobuf authentication encoder');
+    let socket; let onMessage = () => {}; let onClose = () => {}; let opened = false; let closed = false; let notified = false; let timer; let rejectOpen;
+    const notifyClose = (reason) => { if (!notified) { notified = true; onClose(reason); } };
+    const shutdown = (error, code = 'TRANSPORT_CLOSED') => {
+      if (closed) return;
+      closed = true; opened = false; clearTimeout(timer);
+      rejectOpen?.(error || new Error('WSS transport closed'));
+      if (socket) { socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null; try { socket.close(); } catch (_) {} }
+      notifyClose({ code });
+    };
     return {
       onMessage: (listener) => { onMessage = listener; },
       onClose: (listener) => { onClose = listener; },
       open: () => new Promise((resolve, reject) => {
-        let timer;
-        let settled = false;
-        const finish = (handler, value) => { if (settled) return; settled = true; clearTimeout(timer); handler(value); };
+        if (closed || socket) { reject(new Error('WSS transport cannot be reopened')); return; }
+        rejectOpen = reject;
         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);
+          timer = setTimeout(() => shutdown(new Error('WSS connection timed out'), 'CONNECTION_TIMEOUT'), openTimeoutMs);
           socket.onopen = () => {
-            try { socket.send(encodeAuthentication()); if (!authenticationPending) { 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 });
+            if (closed) return;
+            try { socket.send(binaryFrame(encodeAuth ? encodeAuth({ token, protocol }) : encode({ type: 'auth', token, protocol }), 'protobuf authentication encoder')); }
+            catch (error) { shutdown(error, 'PROTOCOL_ENCODE_ERROR'); }
           };
+          socket.onerror = () => shutdown(new Error('WSS connection failed'), 'CONNECTION_FAILED');
+          socket.onclose = (event = {}) => shutdown(new Error('WSS connection closed'), event.code || 'CONNECTION_CLOSED');
           socket.onmessage = (event) => {
+            if (closed) return;
             try {
+              binaryFrame(event.data, 'incoming message');
               const frame = decode(event.data);
-              if (authenticationPending) {
+              if (!opened) {
                 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; }
+                if (rejection) { shutdown(new Error(rejection), 'AUTHENTICATION_REJECTED'); return; }
+                if (!isAuthenticationAccepted(frame)) { shutdown(new Error('Unexpected frame before authentication'), 'AUTHENTICATION_REQUIRED'); return; }
+                opened = true; clearTimeout(timer); rejectOpen = null; resolve();
+                // Core transitions to connected in the open() continuation.
+                queueMicrotask(() => { if (!closed) onMessage(frame); });
+                return;
               }
               onMessage(frame);
-            } catch (_) { try { socket.close(); } catch (_) {} onClose({ code: 'PROTOCOL_DECODE_ERROR', reason: 'Invalid Protobuf frame' }); }
+            } catch (_) { shutdown(new Error('Invalid Protobuf frame'), 'PROTOCOL_DECODE_ERROR'); }
           };
-        } catch (error) { finish(reject, error); }
+        } catch (error) { shutdown(error, 'CONNECTION_FAILED'); }
       }),
-      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); }
+      send: async (frame) => {
+        if (!opened || closed || !socket || socket.readyState !== 1) throw new Error('WSS transport is not authenticated');
+        const bytes = binaryFrame(encode(frame), 'protobuf.encode');
+        if ((socket.bufferedAmount || 0) + bytes.byteLength > maxBufferedAmount) throw new Error('WSS backpressure limit exceeded');
+        socket.send(bytes);
       },
-      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(); }
-      })
+      close: async () => shutdown()
     };
   };
 };
 
-const createChitChatWebClient = ({ endpoint, tokenProvider, protobuf, allowInsecureWs = false, ...options }) => {
+const createChitChatWebClient = ({ endpoint, tokenProvider, protobuf, WebSocketImpl, 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 });
+  return new ReliableRealtimeClient({ endpoint, tokenProvider, runtime: 'web', webTransportFactory: createWssTransportFactory({ ...protobuf, WebSocketImpl, allowInsecureWs }), ...options });
+};
+
+const createChitChatWebCalls = ({ rtc, ...options } = {}) => {
+  const { CallsClient } = requireCore();
+  return new CallsClient({ ...options, rtc: rtc || { RTCPeerConnection: globalThis.RTCPeerConnection, MediaStream: globalThis.MediaStream, mediaDevices: globalThis.navigator?.mediaDevices } });
 };
+const requireCore = () => { try { return require('@chitchat/sdk-core'); } catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; return require('../../chitchat-core/src'); } };
 
-module.exports = { createChitChatWebClient, createWssTransportFactory, toWssEndpoint };
+module.exports = { createChitChatWebCalls, createChitChatWebClient, createWssTransportFactory, toWssEndpoint };

package/src/react.js

@@ -0,0 +1,20 @@
+'use strict';
+const React = require('react');
+function useCallState(client) {
+  const subscribe = React.useCallback((changed) => client.on('stateChange', changed), [client]);
+  const snapshot = React.useCallback(() => client.getSnapshot(), [client]);
+  return React.useSyncExternalStore(subscribe, snapshot, snapshot);
+}
+/** Rendering only; acquiring media always requires an explicit user action. */
+const CallVideo = React.forwardRef(function CallVideo({ stream, muted = false, onPlaybackError, ...props }, ref) {
+  const element = React.useRef(null);
+  React.useImperativeHandle(ref, () => element.current);
+  React.useEffect(() => {
+    const video = element.current; if (!video) return;
+    video.srcObject = stream || null;
+    if (stream) video.play().catch(() => onPlaybackError?.({ code: 'PLAYBACK_BLOCKED' }));
+    return () => { if (video.srcObject === stream) video.srcObject = null; };
+  }, [stream, onPlaybackError]);
+  return React.createElement('video', { autoPlay: true, playsInline: true, ...props, muted, ref: element });
+});
+module.exports = { useCallState, CallVideo };