opendesk-react-native 0.1.2 → 0.1.3

package/README.md

@@ -1,133 +1,133 @@
-# opendesk-react-native
-
-React Native SDK for [openDesk](https://opendesk.sh) live chat. It uses the same visitor API and realtime gateway as openDesk's web widget (`/widget/v1.js`), with no WebView:
-
-- `OpenDesk`: a headless client for the session, conversations, messages, attachments, AI streaming, handoff and unread counts
-- `OpenDeskProvider` and hooks: `useConversations`, `useConversation`, `useUnreadCount` and `useOpenDeskState`
-- `OpenDeskChat` and `OpenDeskLauncher`: drop-in UI that mirrors the web widget. It reads the brand colour, radius, theme, bot, team and copy from your widget's settings, and is built only from React Native core components.
-
-## Install
-
-```bash
-npm install opendesk-react-native expo-secure-store
-```
-
-## Set up
-
-```tsx
-import * as SecureStore from 'expo-secure-store';
-import { OpenDesk, OpenDeskProvider, secureStoreStorage } from 'opendesk-react-native';
-
-export const support = new OpenDesk({
-  baseUrl: 'https://desk.example.com', // your openDesk origin (https://app.opendesk.sh on cloud)
-  widgetKey: 'wk_…', // Settings → Brands and widgets → Chat widgets
-  storage: secureStoreStorage(SecureStore), // keeps the visitor's conversations across launches
-});
-
-export function App() {
-  const identity = useSupportIdentity(); // see below
-  return (
-    <OpenDeskProvider client={support} identity={identity}>
-      <Navigation />
-    </OpenDeskProvider>
-  );
-}
-```
-
-## Where the visitor token is kept
-
-The SDK stores one value: the visitor token (`od_vis_…`). It is a bearer credential, so anyone holding it can read that visitor's conversations and post as them. Keep it in the iOS Keychain or Android Keystore with one of the two adapters. Each adapter takes the native module as an argument, so the SDK itself depends on neither:
-
-| Your app uses | Install | Pass as `storage` |
-| --- | --- | --- |
-| Expo | `npx expo install expo-secure-store` | `secureStoreStorage(SecureStore)` (`import * as SecureStore from 'expo-secure-store'`) |
-| Bare React Native | `npm install react-native-keychain`, then `pod install` | `keychainStorage(Keychain)` (`import * as Keychain from 'react-native-keychain'`) |
-
-Both adapters store the token as *after first unlock, this device only*. It's readable in the background after the first unlock, and it's left out of iCloud and device-transfer backups.
-
-Leave `storage` out and the token lives in memory only, so every launch starts a new visitor. Any `{ getItem, setItem, removeItem }` object also works. AsyncStorage fits that shape, but it writes plain text, so don't use it for this.
-
-## Identify the signed-in user
-
-To attach chats to a known contact, pass `{ user_id, user_hash, email, name }` as `identity`. `user_hash` is `hex(HMAC-SHA256(widget_secret, user_id))`, as described in [Identity verification](https://docs.opendesk.sh/guides/live-chat/identity-verification/). Compute it on your server, never in the app, and serve it from an authenticated endpoint of your own:
-
-```tsx
-function useSupportIdentity() {
-  const { user } = useAuth();
-  const [identity, setIdentity] = useState<Identity | null>(null);
-
-  useEffect(() => {
-    if (!user) return setIdentity(null);
-    // Your backend returns { user_id, user_hash, email, name } for the signed-in user.
-    fetchMySupportIdentity().then(setIdentity).catch(() => {});
-  }, [user?.id]);
-
-  return identity;
-}
-```
-
-When the user signs out, pass `null` (or call `support.shutdown()`) so the next person on the device never sees their conversations. If a different `user_id` signs in, the SDK drops the previous visitor by itself. Leave `identity` undefined for anonymous chat.
-
-## Show the chat
-
-```tsx
-import * as DocumentPicker from 'expo-document-picker';
-import { OpenDeskChat, OpenDeskLauncher } from 'opendesk-react-native';
-
-<OpenDeskChat
-  onClose={() => navigation.goBack()}
-  keyboardVerticalOffset={headerHeight}
-  pickAttachment={async () => {
-    const result = await DocumentPicker.getDocumentAsync({ type: ['image/*', 'application/pdf'] });
-    const file = result.assets?.[0];
-    return file ? { uri: file.uri, name: file.name, type: file.mimeType ?? 'application/octet-stream', size: file.size } : null;
-  }}
-/>
-
-<OpenDeskLauncher onPress={() => navigation.navigate('Support')} style={{ position: 'absolute', right: 20, bottom: 20 }} />
-```
-
-`OpenDeskChat` also takes these props:
-
-- `theme`: `'light' | 'dark' | 'auto'`, which overrides the widget setting
-- `accentColor`
-- `strings`: replaces any of the built-in English copy (`defaultStrings` lists every key)
-- `initialConversationId`
-
-For an in-app banner while the chat is closed, use `support.onMessage(({ conversationId, from, message }) => …)`.
-
-## Build your own UI
-
-```tsx
-const { conversations } = useConversations();
-const { messages, aiReplies, typing } = useConversation(conversationId); // marks it read while mounted
-const client = useOpenDesk();
-
-await client.startConversation({ body, topic_id });
-await client.sendMessage(conversationId, { body, attachment_ids });
-const attachment = await client.upload({ uri, name, type }); // or a File/Blob on the web
-client.typing(conversationId);
-await client.requestHuman(conversationId); // after an AI answer
-await client.decideAction(conversationId, actionId, 'confirm');
-await client.rateMessage(conversationId, messageId, 'up');
-```
-
-Render messages with `message.client_id ?? message.id` as the key. That keeps a bubble mounted when its optimistic copy or streamed AI answer is replaced by the stored message.
-
-## Preview
-
-```bash
-npm run example
-```
-
-This runs `OpenDeskChat` in the browser on port 8774, through react-native-web, against a mock openDesk (`example/mockDesk.ts`). The mock covers AI streaming, tool checks, an AI action to confirm, agent typing, handoff, attachments and unread badges, and needs no server.
-
-## Notes
-
-- Realtime uses Phoenix Channels (the `phoenix` package) on `<gateway_url>` and the topic `contact:<wid>:<contact_id>`. The 5-minute `ws_token` is refreshed before every reconnect, and missed messages are re-fetched over REST after a drop.
-- If **Allowed sites** is set on the widget, openDesk checks the `Origin` header. Native requests send none, so check that your app can still reach the API.
-- The widget API has no push notifications for replies sent while the app is closed. Use openDesk webhooks (`message.created`) to your backend for those.
-
-## License
-
-MIT
+# opendesk-react-native
+
+React Native SDK for [openDesk](https://opendesk.sh) live chat. It uses the same visitor API and realtime gateway as openDesk's web widget (`/widget/v1.js`), with no WebView:
+
+- `OpenDesk`: a headless client for the session, conversations, messages, attachments, AI streaming, handoff and unread counts
+- `OpenDeskProvider` and hooks: `useConversations`, `useConversation`, `useUnreadCount` and `useOpenDeskState`
+- `OpenDeskChat` and `OpenDeskLauncher`: drop-in UI that mirrors the web widget. It reads the brand colour, radius, theme, bot, team and copy from your widget's settings, and is built only from React Native core components.
+
+## Install
+
+```bash
+npm install opendesk-react-native expo-secure-store
+```
+
+## Set up
+
+```tsx
+import * as SecureStore from 'expo-secure-store';
+import { OpenDesk, OpenDeskProvider, secureStoreStorage } from 'opendesk-react-native';
+
+export const support = new OpenDesk({
+  baseUrl: 'https://desk.example.com', // your openDesk origin (https://app.opendesk.sh on cloud)
+  widgetKey: 'wk_…', // Settings → Brands and widgets → Chat widgets
+  storage: secureStoreStorage(SecureStore), // keeps the visitor's conversations across launches
+});
+
+export function App() {
+  const identity = useSupportIdentity(); // see below
+  return (
+    <OpenDeskProvider client={support} identity={identity}>
+      <Navigation />
+    </OpenDeskProvider>
+  );
+}
+```
+
+## Where the visitor token is kept
+
+The SDK stores one value: the visitor token (`od_vis_…`). It is a bearer credential, so anyone holding it can read that visitor's conversations and post as them. Keep it in the iOS Keychain or Android Keystore with one of the two adapters. Each adapter takes the native module as an argument, so the SDK itself depends on neither:
+
+| Your app uses | Install | Pass as `storage` |
+| --- | --- | --- |
+| Expo | `npx expo install expo-secure-store` | `secureStoreStorage(SecureStore)` (`import * as SecureStore from 'expo-secure-store'`) |
+| Bare React Native | `npm install react-native-keychain`, then `pod install` | `keychainStorage(Keychain)` (`import * as Keychain from 'react-native-keychain'`) |
+
+Both adapters store the token as *after first unlock, this device only*. It's readable in the background after the first unlock, and it's left out of iCloud and device-transfer backups.
+
+Leave `storage` out and the token lives in memory only, so every launch starts a new visitor. Any `{ getItem, setItem, removeItem }` object also works. AsyncStorage fits that shape, but it writes plain text, so don't use it for this.
+
+## Identify the signed-in user
+
+To attach chats to a known contact, pass `{ user_id, user_hash, email, name }` as `identity`. `user_hash` is `hex(HMAC-SHA256(widget_secret, user_id))`, as described in [Identity verification](https://docs.opendesk.sh/guides/live-chat/identity-verification/). Compute it on your server, never in the app, and serve it from an authenticated endpoint of your own:
+
+```tsx
+function useSupportIdentity() {
+  const { user } = useAuth();
+  const [identity, setIdentity] = useState<Identity | null>(null);
+
+  useEffect(() => {
+    if (!user) return setIdentity(null);
+    // Your backend returns { user_id, user_hash, email, name } for the signed-in user.
+    fetchMySupportIdentity().then(setIdentity).catch(() => {});
+  }, [user?.id]);
+
+  return identity;
+}
+```
+
+When the user signs out, pass `null` (or call `support.shutdown()`) so the next person on the device never sees their conversations. If a different `user_id` signs in, the SDK drops the previous visitor by itself. Leave `identity` undefined for anonymous chat.
+
+## Show the chat
+
+```tsx
+import * as DocumentPicker from 'expo-document-picker';
+import { OpenDeskChat, OpenDeskLauncher } from 'opendesk-react-native';
+
+<OpenDeskChat
+  onClose={() => navigation.goBack()}
+  keyboardVerticalOffset={headerHeight}
+  pickAttachment={async () => {
+    const result = await DocumentPicker.getDocumentAsync({ type: ['image/*', 'application/pdf'] });
+    const file = result.assets?.[0];
+    return file ? { uri: file.uri, name: file.name, type: file.mimeType ?? 'application/octet-stream', size: file.size } : null;
+  }}
+/>
+
+<OpenDeskLauncher onPress={() => navigation.navigate('Support')} style={{ position: 'absolute', right: 20, bottom: 20 }} />
+```
+
+`OpenDeskChat` also takes these props:
+
+- `theme`: `'light' | 'dark' | 'auto'`, which overrides the widget setting
+- `accentColor`
+- `strings`: replaces any of the built-in English copy (`defaultStrings` lists every key)
+- `initialConversationId`
+
+For an in-app banner while the chat is closed, use `support.onMessage(({ conversationId, from, message }) => …)`.
+
+## Build your own UI
+
+```tsx
+const { conversations } = useConversations();
+const { messages, aiReplies, typing } = useConversation(conversationId); // marks it read while mounted
+const client = useOpenDesk();
+
+await client.startConversation({ body, topic_id });
+await client.sendMessage(conversationId, { body, attachment_ids });
+const attachment = await client.upload({ uri, name, type }); // or a File/Blob on the web
+client.typing(conversationId);
+await client.requestHuman(conversationId); // after an AI answer
+await client.decideAction(conversationId, actionId, 'confirm');
+await client.rateMessage(conversationId, messageId, 'up');
+```
+
+Render messages with `message.client_id ?? message.id` as the key. That keeps a bubble mounted when its optimistic copy or streamed AI answer is replaced by the stored message.
+
+## Preview
+
+```bash
+npm run example
+```
+
+This runs `OpenDeskChat` in the browser on port 8774, through react-native-web, against a mock openDesk (`example/mockDesk.ts`). The mock covers AI streaming, tool checks, an AI action to confirm, agent typing, handoff, attachments and unread badges, and needs no server.
+
+## Notes
+
+- Realtime uses Phoenix Channels (the `phoenix` package, 1.8+) on `<gateway_url>` and the topic `contact:<wid>:<contact_id>`. The 5-minute `ws_token` goes in Phoenix's `authToken` (the `Sec-WebSocket-Protocol` header; the gateway refuses it in the URL), is refreshed before every reconnect, and missed messages are re-fetched over REST after a drop.
+- If **Allowed sites** is set on the widget, openDesk checks the `Origin` header. Native requests send none, so check that your app can still reach the API.
+- The widget API has no push notifications for replies sent while the app is closed. Use openDesk webhooks (`message.created`) to your backend for those.
+
+## License
+
+MIT

package/lib/realtime.d.ts

@@ -17,6 +17,11 @@ export interface RealtimeSocket {
 export type SocketFactory = (url: string, params: () => {
     token: string;
 }) => RealtimeSocket;
+/**
+ * The gateway reads the token from Phoenix's `authToken` (sent in the `Sec-WebSocket-Protocol`
+ * header) and refuses a connect that carries it in the query string. Phoenix calls the function
+ * on every connect, so a refreshed token is used on the next attempt.
+ */
 export declare const phoenixSocketFactory: SocketFactory;
 export interface RealtimeHandlers {
     onEvent(event: RealtimeEvent): void;

package/lib/realtime.js

@@ -3,7 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenDeskRealtime = exports.phoenixSocketFactory = void 0;
 exports.jwtClaim = jwtClaim;
 const phoenix_1 = require("phoenix");
-const phoenixSocketFactory = (url, params) => new phoenix_1.Socket(url, { params, reconnectAfterMs: (tries) => [1000, 2000, 5000, 10000][tries - 1] ?? 15000 });
+/**
+ * The gateway reads the token from Phoenix's `authToken` (sent in the `Sec-WebSocket-Protocol`
+ * header) and refuses a connect that carries it in the query string. Phoenix calls the function
+ * on every connect, so a refreshed token is used on the next attempt.
+ */
+const phoenixSocketFactory = (url, params) => new phoenix_1.Socket(url, {
+    authToken: () => params().token,
+    reconnectAfterMs: (tries) => [1000, 2000, 5000, 10000][tries - 1] ?? 15000,
+});
 exports.phoenixSocketFactory = phoenixSocketFactory;
 const TYPING_THROTTLE_MS = 3000;
 /**

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "opendesk-react-native",
-  "version": "0.1.2",
-  "description": "React Native SDK for openDesk live chat: headless client, realtime, hooks and a drop-in chat screen.",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib",
-    "src",
-    "!src/**/__tests__"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepare": "npm run build",
-    "example": "vite --config example/vite.config.ts"
-  },
-  "keywords": [
-    "opendesk",
-    "react-native",
-    "live-chat",
-    "support"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "phoenix": "^1.7.21"
-  },
-  "peerDependencies": {
-    "react": ">=18",
-    "react-native": ">=0.72"
-  },
-  "devDependencies": {
-    "@types/phoenix": "^1.6.6",
-    "@types/react": "^19.1.0",
-    "@vitejs/plugin-react": "^5.2.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.3.1",
-    "react-native": "^0.81.0",
-    "react-native-web": "^0.21.4",
-    "typescript": "^5.9.2",
-    "vite": "^7.3.7",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "opendesk-react-native",
+  "version": "0.1.3",
+  "description": "React Native SDK for openDesk live chat: headless client, realtime, hooks and a drop-in chat screen.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "!src/**/__tests__"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepare": "npm run build",
+    "example": "vite --config example/vite.config.ts"
+  },
+  "keywords": [
+    "opendesk",
+    "react-native",
+    "live-chat",
+    "support"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "phoenix": "^1.8.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "devDependencies": {
+    "@types/phoenix": "^1.6.6",
+    "@types/react": "^19.1.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.3.1",
+    "react-native": "^0.81.0",
+    "react-native-web": "^0.21.4",
+    "typescript": "^5.9.2",
+    "vite": "^7.3.7",
+    "vitest": "^3.2.4"
+  }
+}

package/src/realtime.ts

@@ -1,166 +1,174 @@
-import { Socket } from 'phoenix';
-import type { LiveEvent, RealtimeEvent, TypingEvent } from './types';
-
-/** The parts of a Phoenix socket and channel the SDK uses, so tests can swap them. */
-export interface RealtimeChannel {
-  on(event: string, callback: (payload: any) => void): unknown;
-  join(): unknown;
-  leave(): unknown;
-  push(event: string, payload: object): unknown;
-}
-
-export interface RealtimeSocket {
-  onOpen(callback: () => void): unknown;
-  onClose(callback: () => void): unknown;
-  onError(callback: () => void): unknown;
-  connect(): void;
-  disconnect(): void;
-  channel(topic: string, params?: object): RealtimeChannel;
-}
-
-export type SocketFactory = (url: string, params: () => { token: string }) => RealtimeSocket;
-
-export const phoenixSocketFactory: SocketFactory = (url, params) =>
-  new Socket(url, { params, reconnectAfterMs: (tries: number) => [1000, 2000, 5000, 10000][tries - 1] ?? 15000 });
-
-export interface RealtimeHandlers {
-  onEvent(event: RealtimeEvent): void;
-  onLive(event: LiveEvent): void;
-  onTyping(event: TypingEvent): void;
-  onStatus(connected: boolean): void;
-  /** Fired when the socket comes back after a drop, so missed events can be fetched over REST. */
-  onReconnect(): void;
-}
-
-const TYPING_THROTTLE_MS = 3000;
-
-/**
- * Joins `contact:<wid>:<contact_id>` on the widget gateway. The `ws_token` lasts five minutes
- * and is checked only on connect, so every drop fetches a fresh one before the next attempt.
- */
-export class OpenDeskRealtime {
-  private socket: RealtimeSocket | null = null;
-  private channel: RealtimeChannel | null = null;
-  private refreshing = false;
-  private lastTypingAt = 0;
-
-  constructor(
-    private readonly factory: SocketFactory,
-    private readonly gatewayUrl: string,
-    private token: string,
-    private readonly contactId: string,
-    private readonly refreshToken: () => Promise<string>,
-    private readonly handlers: RealtimeHandlers,
-  ) {}
-
-  start(): void {
-    const workspaceId = jwtClaim(this.token, 'wid');
-    if (!workspaceId || !this.gatewayUrl) {
-      return;
-    }
-
-    const socket = this.factory(this.gatewayUrl, () => ({ token: this.token }));
-    let dropped = false;
-
-    socket.onOpen(() => {
-      this.handlers.onStatus(true);
-      if (dropped) {
-        this.handlers.onReconnect();
-      }
-      dropped = false;
-    });
-
-    const onDrop = (): void => {
-      dropped = true;
-      this.handlers.onStatus(false);
-      if (this.refreshing) {
-        return;
-      }
-      this.refreshing = true;
-      this.refreshToken()
-        .then((token) => {
-          this.token = token;
-        })
-        .catch(() => undefined)
-        .finally(() => {
-          this.refreshing = false;
-        });
-    };
-    socket.onError(onDrop);
-    socket.onClose(onDrop);
-    socket.connect();
-
-    const channel = socket.channel(`contact:${workspaceId}:${this.contactId}`, {});
-    channel.on('event', (payload: RealtimeEvent) => this.handlers.onEvent(payload));
-    channel.on('typing', (payload: TypingEvent) => this.handlers.onTyping(payload));
-    channel.on('live', (payload: LiveEvent) => {
-      if (payload && typeof payload.type === 'string' && payload.data) {
-        this.handlers.onLive(payload);
-      }
-    });
-    channel.join();
-
-    this.socket = socket;
-    this.channel = channel;
-  }
-
-  /** Tells agents the visitor is typing in a conversation; throttled to one push per 3s. */
-  typing(conversationId: string): void {
-    const now = Date.now();
-    if (!this.channel || now - this.lastTypingAt < TYPING_THROTTLE_MS) {
-      return;
-    }
-    this.lastTypingAt = now;
-    this.channel.push('typing', { ticket_id: conversationId });
-  }
-
-  typingDone(): void {
-    this.lastTypingAt = 0;
-  }
-
-  stop(): void {
-    this.channel?.leave();
-    this.socket?.disconnect();
-    this.channel = null;
-    this.socket = null;
-  }
-}
-
-export function jwtClaim(token: string, claim: string): string | null {
-  try {
-    const segment = token.split('.')[1];
-    if (!segment) {
-      return null;
-    }
-    const value = JSON.parse(decodeBase64Url(segment))[claim];
-
-    return typeof value === 'string' ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-
-/** Decodes base64url to a UTF-8 string without relying on `atob`, which older Hermes lacks. */
-function decodeBase64Url(input: string): string {
-  const clean = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
-  const bytes: number[] = [];
-  let buffer = 0;
-  let bits = 0;
-
-  for (const char of clean) {
-    const index = BASE64.indexOf(char);
-    if (index < 0) {
-      throw new Error('Invalid base64');
-    }
-    buffer = (buffer << 6) | index;
-    bits += 6;
-    if (bits >= 8) {
-      bits -= 8;
-      bytes.push((buffer >> bits) & 0xff);
-    }
-  }
-
-  return decodeURIComponent(bytes.map((byte) => `%${byte.toString(16).padStart(2, '0')}`).join(''));
-}
+import { Socket } from 'phoenix';
+import type { LiveEvent, RealtimeEvent, TypingEvent } from './types';
+
+/** The parts of a Phoenix socket and channel the SDK uses, so tests can swap them. */
+export interface RealtimeChannel {
+  on(event: string, callback: (payload: any) => void): unknown;
+  join(): unknown;
+  leave(): unknown;
+  push(event: string, payload: object): unknown;
+}
+
+export interface RealtimeSocket {
+  onOpen(callback: () => void): unknown;
+  onClose(callback: () => void): unknown;
+  onError(callback: () => void): unknown;
+  connect(): void;
+  disconnect(): void;
+  channel(topic: string, params?: object): RealtimeChannel;
+}
+
+export type SocketFactory = (url: string, params: () => { token: string }) => RealtimeSocket;
+
+/**
+ * The gateway reads the token from Phoenix's `authToken` (sent in the `Sec-WebSocket-Protocol`
+ * header) and refuses a connect that carries it in the query string. Phoenix calls the function
+ * on every connect, so a refreshed token is used on the next attempt.
+ */
+export const phoenixSocketFactory: SocketFactory = (url, params) =>
+  new Socket(url, {
+    authToken: () => params().token,
+    reconnectAfterMs: (tries: number) => [1000, 2000, 5000, 10000][tries - 1] ?? 15000,
+  });
+
+export interface RealtimeHandlers {
+  onEvent(event: RealtimeEvent): void;
+  onLive(event: LiveEvent): void;
+  onTyping(event: TypingEvent): void;
+  onStatus(connected: boolean): void;
+  /** Fired when the socket comes back after a drop, so missed events can be fetched over REST. */
+  onReconnect(): void;
+}
+
+const TYPING_THROTTLE_MS = 3000;
+
+/**
+ * Joins `contact:<wid>:<contact_id>` on the widget gateway. The `ws_token` lasts five minutes
+ * and is checked only on connect, so every drop fetches a fresh one before the next attempt.
+ */
+export class OpenDeskRealtime {
+  private socket: RealtimeSocket | null = null;
+  private channel: RealtimeChannel | null = null;
+  private refreshing = false;
+  private lastTypingAt = 0;
+
+  constructor(
+    private readonly factory: SocketFactory,
+    private readonly gatewayUrl: string,
+    private token: string,
+    private readonly contactId: string,
+    private readonly refreshToken: () => Promise<string>,
+    private readonly handlers: RealtimeHandlers,
+  ) {}
+
+  start(): void {
+    const workspaceId = jwtClaim(this.token, 'wid');
+    if (!workspaceId || !this.gatewayUrl) {
+      return;
+    }
+
+    const socket = this.factory(this.gatewayUrl, () => ({ token: this.token }));
+    let dropped = false;
+
+    socket.onOpen(() => {
+      this.handlers.onStatus(true);
+      if (dropped) {
+        this.handlers.onReconnect();
+      }
+      dropped = false;
+    });
+
+    const onDrop = (): void => {
+      dropped = true;
+      this.handlers.onStatus(false);
+      if (this.refreshing) {
+        return;
+      }
+      this.refreshing = true;
+      this.refreshToken()
+        .then((token) => {
+          this.token = token;
+        })
+        .catch(() => undefined)
+        .finally(() => {
+          this.refreshing = false;
+        });
+    };
+    socket.onError(onDrop);
+    socket.onClose(onDrop);
+    socket.connect();
+
+    const channel = socket.channel(`contact:${workspaceId}:${this.contactId}`, {});
+    channel.on('event', (payload: RealtimeEvent) => this.handlers.onEvent(payload));
+    channel.on('typing', (payload: TypingEvent) => this.handlers.onTyping(payload));
+    channel.on('live', (payload: LiveEvent) => {
+      if (payload && typeof payload.type === 'string' && payload.data) {
+        this.handlers.onLive(payload);
+      }
+    });
+    channel.join();
+
+    this.socket = socket;
+    this.channel = channel;
+  }
+
+  /** Tells agents the visitor is typing in a conversation; throttled to one push per 3s. */
+  typing(conversationId: string): void {
+    const now = Date.now();
+    if (!this.channel || now - this.lastTypingAt < TYPING_THROTTLE_MS) {
+      return;
+    }
+    this.lastTypingAt = now;
+    this.channel.push('typing', { ticket_id: conversationId });
+  }
+
+  typingDone(): void {
+    this.lastTypingAt = 0;
+  }
+
+  stop(): void {
+    this.channel?.leave();
+    this.socket?.disconnect();
+    this.channel = null;
+    this.socket = null;
+  }
+}
+
+export function jwtClaim(token: string, claim: string): string | null {
+  try {
+    const segment = token.split('.')[1];
+    if (!segment) {
+      return null;
+    }
+    const value = JSON.parse(decodeBase64Url(segment))[claim];
+
+    return typeof value === 'string' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Decodes base64url to a UTF-8 string without relying on `atob`, which older Hermes lacks. */
+function decodeBase64Url(input: string): string {
+  const clean = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+
+  for (const char of clean) {
+    const index = BASE64.indexOf(char);
+    if (index < 0) {
+      throw new Error('Invalid base64');
+    }
+    buffer = (buffer << 6) | index;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 0xff);
+    }
+  }
+
+  return decodeURIComponent(bytes.map((byte) => `%${byte.toString(16).padStart(2, '0')}`).join(''));
+}