@chitchat/sdk-react-native 0.1.0-dev.0 → 0.1.0-dev.2

package/README.md

@@ -1,5 +1,120 @@
 # ChitChat React Native SDK
 
-`createChitChatNativeClient` uses the official native TLS TCP bridge. The app developer supplies a session-token provider and imports the module; endpoint resolution, reconnects, durable outbox behavior, and TLS transport selection are handled by the SDK.
+`@chitchat/sdk-react-native` connects a React Native application through a native TLS TCP transport and binary Protobuf frames. It is for iOS/Android native builds; it is not a browser SDK.
 
-The native bridge contract is deliberately small: `connect`, `onFrame`, `onClose`, `send`, and `close`. It is the location where Android/iOS certificate pinning and binary Protobuf framing are enforced.
+This package is currently a **development prerelease**. Pin the version you have tested before shipping an application.
+
+## Read this before integrating
+
+This JavaScript package needs a linked native bridge. You pass that bridge as `nativeModule`; the SDK does not secretly create TCP sockets in JavaScript.
+
+For the current ChitChat app implementation, the bridge is exposed as `NativeModules.XMPPNativeModule` (with `NativeModules.XMPPNative` as a compatibility fallback). A third-party application must include the official ChitChat native bridge or implement the same documented bridge contract. The bridge must perform TLS validation, Protobuf framing, and certificate policy on iOS and Android.
+
+**Expo Go cannot load custom native modules.** Use a development build or a prebuilt/bare React Native application, link the bridge, then rebuild iOS/Android.
+
+## 1. Install
+
+```bash
+npm install @chitchat/sdk-core@development @chitchat/sdk-react-native@development
+
+# iOS after installing native dependencies
+npx pod-install ios
+```
+
+You also need a backend session endpoint made with `@chitchat/sdk-server`. It returns a short-lived client token after authenticating the user in your own product. Do not embed a ChitChat API key in the app.
+
+## 2. Create the client
+
+```js
+import { NativeModules } from 'react-native';
+import { createBackendTokenProvider } from '@chitchat/sdk-core';
+import { createChitChatNativeClient } from '@chitchat/sdk-react-native';
+
+const nativeModule = NativeModules.XMPPNativeModule || NativeModules.XMPPNative;
+if (!nativeModule) {
+  throw new Error('ChitChat native bridge is not linked; rebuild a development/native app.');
+}
+
+const tokenProvider = createBackendTokenProvider({
+  endpoint: 'https://api.example.com/api/chitchat/session',
+  getHeaders: () => ({ authorization: `Bearer ${getYourAppAccessToken()}` }),
+  getBody: () => ({ deviceId: getStableInstallationId() })
+});
+
+const client = createChitChatNativeClient({
+  // TLS TCP host and port only. It is not http://, https://, ws://, or wss://.
+  endpoint: 'realtime.example.com:5223',
+  tokenProvider,
+  nativeModule,
+  storage: durableNativeOutbox
+});
+
+client.on('connected', () => setRealtimeState('connected'));
+client.on('message', (frame) => handleChitChatFrame(frame));
+client.on('error', (error) => reportNonSensitiveRealtimeError(error));
+
+await client.connect();
+```
+
+On logout or account switch:
+
+```js
+await client.close();
+tokenProvider.invalidate();
+```
+
+## Native bridge contract
+
+The supplied module must provide `connect`:
+
+```ts
+type NativeBridge = {
+  connect(input: {
+    endpoint: string; // TLS host:port
+    token: string;    // short-lived project-user session token
+    protocol: 'chitchat.protobuf.v1';
+    tls: true;
+  }): Promise<{
+    onFrame(listener: (frame: unknown) => void): void;
+    onClose(listener: (reason?: unknown) => void): void;
+    send(frame: unknown): Promise<void> | void;
+    close(): Promise<void> | void;
+  }>;
+};
+```
+
+The bridge must encode/decode the gateway’s actual generated Protobuf envelope and authenticate with the current protocol. Do not replace it with raw XML, JSON, or an unauthenticated TCP socket.
+
+## Durable outbox
+
+The default core outbox is memory-only. To preserve queued messages when the app is restarted, pass a durable store with async `put(record)`, `remove(id)`, and `list()` methods. Use an encrypted/device-appropriate storage provider and return records sorted by `createdAt`.
+
+## TLS requirements
+
+- Use a production hostname and certificate trusted by the actual iOS/Android device.
+- The certificate subject/SAN must match the hostname passed in `endpoint`.
+- Test on physical devices as well as simulators/emulators.
+- Do not disable certificate validation to work around a development certificate error.
+- For a local gateway, use a stable local hostname and install a trusted development CA in each test device. A changing LAN IP is not a production TLS identity.
+
+## Common problems
+
+| Problem | Fix |
+| --- | --- |
+| `official ChitChat native TCP module is required` | Link/provide the native bridge and rebuild the app. Expo Go is not enough. |
+| `TLS host:port endpoint is required` | Use `realtime.example.com:5223`; do not pass an HTTP or WebSocket URL. |
+| iOS SSL / certificate error | Check the hostname, SAN, trusted CA, device time, and gateway certificate chain. |
+| Repeated reconnects | Check token issuance/expiry, gateway reachability, bridge frame codec, and `error`/`reconnectFailed` events. |
+| Queued messages disappear after restart | Provide durable `storage`; the default is memory-only. |
+
+## Security checklist
+
+- Never put the ChitChat server API key in the mobile app, build configuration, or CI client logs.
+- Fetch a short-lived session only from your authenticated backend over HTTPS.
+- Close the realtime client on logout and account change.
+- Keep the native bridge and generated Protobuf definitions versioned with the gateway protocol.
+- Do not log tokens, message bodies, user identifiers, or raw binary frames.
+
+## Current scope
+
+This package provides the React Native client lifecycle and native transport adapter boundary. Call UI, CallKit/ConnectionService, push wake-up, ringtone, WebRTC media, meetings, streaming, notifications, and agents are separate platform features and must be integrated and tested before release.

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@chitchat/sdk-react-native",
-  "version": "0.1.0-dev.0",
+  "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.0" },
+  "scripts": { "test": "node test/transport.test.js" },
+  "dependencies": { "@chitchat/sdk-core": "0.1.0-dev.2" },
   "license": "UNLICENSED",
   "publishConfig": { "access": "public", "tag": "development" }
 }

package/src/index.js

@@ -3,9 +3,19 @@
 let ReliableRealtimeClient;
 try { ({ ReliableRealtimeClient } = require('@chitchat/sdk-core')); } catch (_) { ({ ReliableRealtimeClient } = require('../../chitchat-core/src')); }
 
+const validateNativeTlsEndpoint = (endpoint) => {
+  if (typeof endpoint !== 'string' || !endpoint.trim() || /\s/.test(endpoint)) throw new Error('A TLS host:port endpoint is required');
+  if (/^(https?|wss?):\/\//i.test(endpoint)) throw new Error('React Native realtime requires a TLS TCP host:port endpoint, not a HTTP/WebSocket URL');
+  let parsed;
+  try { parsed = new URL(`tls://${endpoint}`); } catch (_) { throw new Error('A valid TLS host:port endpoint is required'); }
+  if (!parsed.hostname || !parsed.port || Number(parsed.port) < 1 || Number(parsed.port) > 65535 || parsed.username || parsed.password || (parsed.pathname && parsed.pathname !== '/')) throw new Error('A valid TLS host:port endpoint is required');
+  return endpoint;
+};
+
 const createNativeTcpTransportFactory = ({ nativeModule }) => {
   if (!nativeModule || typeof nativeModule.connect !== 'function') throw new Error('The official ChitChat native TCP module is required');
   return async ({ endpoint, token, protocol }) => {
+    validateNativeTlsEndpoint(endpoint);
     let connection; let onMessage = () => {}; let onClose = () => {};
     return {
       onMessage: (listener) => { onMessage = listener; },
@@ -23,4 +33,4 @@ const createNativeTcpTransportFactory = ({ nativeModule }) => {
 
 const createChitChatNativeClient = ({ endpoint, tokenProvider, nativeModule, ...options }) => new ReliableRealtimeClient({ endpoint, tokenProvider, runtime: 'native', nativeTransportFactory: createNativeTcpTransportFactory({ nativeModule }), ...options });
 
-module.exports = { createChitChatNativeClient, createNativeTcpTransportFactory };
+module.exports = { createChitChatNativeClient, createNativeTcpTransportFactory, validateNativeTlsEndpoint };