opendesk-react-native 0.1.2 → 0.1.6

package/README.md

@@ -1,133 +1,157 @@
-# 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.
+
+## Reply sound
+
+The SDK can play the web widget's reply chime when an agent or AI replies in a conversation the visitor doesn't have open. It follows the widget's **Sound** setting in openDesk, the same as on the web. Install `expo-audio` and pass it in:
+
+```tsx
+// npx expo install expo-audio
+import * as ExpoAudio from 'expo-audio';
+import { expoAudioSound } from 'opendesk-react-native';
+
+export const support = new OpenDesk({
+  // …
+  sound: expoAudioSound(ExpoAudio), // or expoAudioSound(ExpoAudio, { volume: 0.5 })
+});
+```
+
+The chime ships with the package (`assets/chime.wav`). The SDK leaves your app's audio mode alone; under expo-audio's default the chime mixes with other audio rather than pausing it. To play something else, pass any function as `sound`. Leave `sound` out for no sound.
+
+## 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()}
+  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`
+- `keyboardVerticalOffset`: extra space between the composer and the keyboard (see below)
+
+The chat keeps its composer above the keyboard by measuring where it sits on screen, so it needs no offset under a navigation header. Two cases it can't measure past:
+
+- **React Native's `<Modal>` on Android** is a separate window that gets no keyboard events, so the composer stays under the keyboard. Show the chat as a screen, or as a full-screen view over your app, instead.
+- **An iOS page sheet** (`presentationStyle="pageSheet"`, or a sheet-style navigation modal) starts below the top of the screen. Pass the sheet's distance from the top as `keyboardVerticalOffset`, or present it full screen.
+
+Tapping an attached image opens it inside the chat. On Android, the back button closes it.
+
+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/api.js

@@ -63,13 +63,14 @@ class OpenDeskApi {
         const form = new FormData();
         if (isBlob(file)) {
             form.append('file', file, 'name' in file && typeof file.name === 'string' ? file.name : 'upload');
+            return this.request('POST', '/v1/widget/attachments', form);
         }
-        else {
-            form.append('file', { uri: file.uri, name: file.name, type: file.type || 'application/octet-stream' });
-        }
-        return this.request('POST', '/v1/widget/attachments', form);
+        form.append('file', { uri: file.uri, name: file.name, type: file.type || 'application/octet-stream' });
+        // Expo replaces `fetch` with expo/fetch, which can't send `{ uri }` parts; React Native's
+        // XMLHttpRequest reads the file from disk itself.
+        return this.request('POST', '/v1/widget/attachments', form, true, typeof XMLHttpRequest === 'undefined' ? this.fetcher : xhrFetch);
     }
-    async request(method, path, body, authenticated = true) {
+    async request(method, path, body, authenticated = true, fetcher = this.fetcher) {
         const headers = { Accept: 'application/json' };
         let payload;
         if (body instanceof FormData) {
@@ -84,10 +85,10 @@ class OpenDeskApi {
         }
         let response;
         try {
-            response = await this.fetcher(this.baseUrl + path, { method, headers, body: payload });
+            response = await fetcher(this.baseUrl + path, { method, headers, body: payload });
         }
-        catch {
-            throw new errors_1.OpenDeskError(0, 'network_error', "Can't reach the server");
+        catch (cause) {
+            throw new errors_1.OpenDeskError(0, 'network_error', "Can't reach the server", cause);
         }
         if (!response.ok) {
             let code = 'error';
@@ -112,3 +113,19 @@ exports.OpenDeskApi = OpenDeskApi;
 function isBlob(file) {
     return typeof Blob !== 'undefined' && file instanceof Blob;
 }
+/** `fetch` over XMLHttpRequest, for the multipart uploads expo/fetch can't send. */
+const xhrFetch = (input, init) => new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open(init?.method ?? 'GET', String(input));
+    Object.entries((init?.headers ?? {})).forEach(([name, value]) => xhr.setRequestHeader(name, value));
+    xhr.onload = () => {
+        const empty = xhr.status === 204 || xhr.status === 205 || xhr.status === 304;
+        resolve(new Response(empty ? null : xhr.responseText, {
+            status: xhr.status,
+            headers: { 'content-type': xhr.getResponseHeader('content-type') ?? '' },
+        }));
+    };
+    xhr.onerror = () => reject(new TypeError('Network request failed'));
+    xhr.ontimeout = xhr.onerror;
+    xhr.send((init?.body ?? null));
+});

package/lib/client.d.ts

@@ -9,8 +9,14 @@ export interface OpenDeskOptions {
     widgetKey: string;
     /** Persists the visitor token so conversations survive restarts. Defaults to memory. */
     storage?: TokenStorage;
+    /** Replaces `fetch`. Native `{ uri }` uploads still go over XMLHttpRequest, which can read the file. */
     fetcher?: Fetcher;
     socketFactory?: SocketFactory;
+    /**
+     * Played when an agent or AI reply arrives in a conversation that isn't open, if the widget
+     * has sound on. `expoAudioSound(ExpoAudio)` plays the web widget's chime.
+     */
+    sound?: () => void;
 }
 /** An AI answer being streamed before it lands as a message. */
 export interface AIReply {
@@ -61,6 +67,7 @@ export declare class OpenDesk {
     private readonly storage;
     private readonly storageKey;
     private readonly socketFactory;
+    private readonly sound;
     private readonly subscribers;
     private readonly messageListeners;
     private readonly typingTimers;
@@ -103,6 +110,8 @@ export declare class OpenDesk {
     private authorized;
     private catchUp;
     private onRealtimeEvent;
+    /** The widget's sound setting decides, as on the web; the app decides what plays. */
+    private playSound;
     private onLiveEvent;
     private onAgentTyping;
     private clearTyping;

package/lib/client.js

@@ -45,6 +45,7 @@ class OpenDesk {
         this.storage = options.storage ?? (0, storage_1.memoryStorage)();
         this.storageKey = `opendesk.visitor.${options.widgetKey}`;
         this.socketFactory = options.socketFactory ?? realtime_1.phoenixSocketFactory;
+        this.sound = options.sound ?? null;
     }
     /** Called for every agent or AI reply, e.g. to show an in-app banner. */
     onMessage(listener) {
@@ -290,6 +291,7 @@ class OpenDesk {
             this.set((state) => ({
                 unread: { ...state.unread, [conversationId]: (state.unread[conversationId] ?? 0) + 1 },
             }));
+            this.playSound();
         }
         const from = message.author.user?.name || message.author.bot?.name || this.state.config?.workspace_name || 'Support';
         this.messageListeners.forEach((listener) => {
@@ -301,6 +303,18 @@ class OpenDesk {
             }
         });
     }
+    /** The widget's sound setting decides, as on the web; the app decides what plays. */
+    playSound() {
+        if (!this.sound || this.state.config?.sound !== true) {
+            return;
+        }
+        try {
+            this.sound();
+        }
+        catch {
+            // A sound that fails must not break the stream.
+        }
+    }
     onLiveEvent(event) {
         const { reply_id: replyId, ticket_id: conversationId } = event.data;
         if (typeof replyId !== 'string' || typeof conversationId !== 'string') {

package/lib/errors.d.ts

@@ -1,8 +1,12 @@
-/** A failed openDesk request; `status` is 0 when the server could not be reached. */
+/**
+ * A failed openDesk request; `status` is 0 when the server could not be reached, and then
+ * `cause` holds what `fetch` threw.
+ */
 export declare class OpenDeskError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    readonly cause?: unknown | undefined;
+    constructor(status: number, code: string, message: string, cause?: unknown | undefined);
     /** The visitor token is unknown or revoked; a fresh session is needed. */
     get isUnauthorized(): boolean;
 }

package/lib/errors.js

@@ -1,12 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenDeskError = void 0;
-/** A failed openDesk request; `status` is 0 when the server could not be reached. */
+/**
+ * A failed openDesk request; `status` is 0 when the server could not be reached, and then
+ * `cause` holds what `fetch` threw.
+ */
 class OpenDeskError extends Error {
-    constructor(status, code, message) {
+    constructor(status, code, message, cause) {
         super(message);
         this.status = status;
         this.code = code;
+        this.cause = cause;
         this.name = 'OpenDeskError';
     }
     /** The visitor token is unknown or revoked; a fresh session is needed. */

package/lib/index.d.ts

@@ -7,6 +7,8 @@ export { OpenDeskRealtime, phoenixSocketFactory } from './realtime';
 export type { RealtimeChannel, RealtimeSocket, SocketFactory } from './realtime';
 export { keychainStorage, memoryStorage, secureStoreStorage } from './storage';
 export type { ExpoSecureStoreModule, KeychainModule, TokenStorage } from './storage';
+export { expoAudioSound } from './sound';
+export type { ExpoAudioModule, ExpoAudioPlayer } from './sound';
 export { OpenDeskProvider, useConversation, useConversations, useOpenDesk, useOpenDeskState, useUnreadCount, } from './react';
 export type { ConversationView, OpenDeskProviderProps } from './react';
 export { OpenDeskChat } from './ui/OpenDeskChat';

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultStrings = exports.OpenDeskLauncher = exports.OpenDeskChat = exports.useUnreadCount = exports.useOpenDeskState = exports.useOpenDesk = exports.useConversations = exports.useConversation = exports.OpenDeskProvider = exports.secureStoreStorage = exports.memoryStorage = exports.keychainStorage = exports.phoenixSocketFactory = exports.OpenDeskRealtime = exports.OpenDeskError = exports.OpenDeskApi = exports.OpenDesk = void 0;
+exports.defaultStrings = exports.OpenDeskLauncher = exports.OpenDeskChat = exports.useUnreadCount = exports.useOpenDeskState = exports.useOpenDesk = exports.useConversations = exports.useConversation = exports.OpenDeskProvider = exports.expoAudioSound = exports.secureStoreStorage = exports.memoryStorage = exports.keychainStorage = exports.phoenixSocketFactory = exports.OpenDeskRealtime = exports.OpenDeskError = exports.OpenDeskApi = exports.OpenDesk = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "OpenDesk", { enumerable: true, get: function () { return client_1.OpenDesk; } });
 var api_1 = require("./api");
@@ -14,6 +14,8 @@ var storage_1 = require("./storage");
 Object.defineProperty(exports, "keychainStorage", { enumerable: true, get: function () { return storage_1.keychainStorage; } });
 Object.defineProperty(exports, "memoryStorage", { enumerable: true, get: function () { return storage_1.memoryStorage; } });
 Object.defineProperty(exports, "secureStoreStorage", { enumerable: true, get: function () { return storage_1.secureStoreStorage; } });
+var sound_1 = require("./sound");
+Object.defineProperty(exports, "expoAudioSound", { enumerable: true, get: function () { return sound_1.expoAudioSound; } });
 var react_1 = require("./react");
 Object.defineProperty(exports, "OpenDeskProvider", { enumerable: true, get: function () { return react_1.OpenDeskProvider; } });
 Object.defineProperty(exports, "useConversation", { enumerable: true, get: function () { return react_1.useConversation; } });

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/lib/sound.d.ts

@@ -0,0 +1,22 @@
+/** The parts of `expo-audio` the adapter uses; pass the module itself. */
+export interface ExpoAudioModule {
+    createAudioPlayer(source: number): ExpoAudioPlayer;
+}
+export interface ExpoAudioPlayer {
+    volume: number;
+    play(): void;
+    seekTo(seconds: number): Promise<void>;
+}
+/**
+ * Plays the web widget's reply chime with `expo-audio`. Takes the module as an argument, so the
+ * SDK has no dependency on Expo:
+ *
+ *     import * as ExpoAudio from 'expo-audio';
+ *     new OpenDesk({ …, sound: expoAudioSound(ExpoAudio) });
+ *
+ * The player is made on the first reply and kept for the next. The app's audio mode is left
+ * alone; under expo-audio's default the chime mixes with other audio instead of pausing it.
+ */
+export declare function expoAudioSound(ExpoAudio: ExpoAudioModule, options?: {
+    volume?: number;
+}): () => void;

package/lib/sound.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expoAudioSound = expoAudioSound;
+const chime_wav_1 = __importDefault(require("../assets/chime.wav"));
+/**
+ * Plays the web widget's reply chime with `expo-audio`. Takes the module as an argument, so the
+ * SDK has no dependency on Expo:
+ *
+ *     import * as ExpoAudio from 'expo-audio';
+ *     new OpenDesk({ …, sound: expoAudioSound(ExpoAudio) });
+ *
+ * The player is made on the first reply and kept for the next. The app's audio mode is left
+ * alone; under expo-audio's default the chime mixes with other audio instead of pausing it.
+ */
+function expoAudioSound(ExpoAudio, options = {}) {
+    let player = null;
+    return () => {
+        if (!player) {
+            player = ExpoAudio.createAudioPlayer(chime_wav_1.default);
+            if (options.volume !== undefined) {
+                player.volume = options.volume;
+            }
+        }
+        const current = player;
+        void current
+            .seekTo(0)
+            .catch(() => undefined)
+            .then(() => current.play());
+    };
+}

package/lib/types.d.ts

@@ -20,6 +20,8 @@ export interface WidgetConfig {
     locale: string;
     language: string;
     open: boolean;
+    /** Whether replies play a sound while the visitor isn't looking at them. */
+    sound: boolean;
     require_email: boolean;
     chat_welcome: boolean;
     help_center_url: string;

package/lib/ui/OpenDeskChat.d.ts

@@ -17,7 +17,11 @@ export interface OpenDeskChatProps {
     theme?: 'light' | 'dark' | 'auto';
     /** Replaces any of the built-in English strings. */
     strings?: Partial<ChatStrings>;
-    /** Height of any navigation header above the chat, so the keyboard never covers the composer on iOS. */
+    /**
+     * Extra space to keep between the composer and the keyboard. The chat measures its own position,
+     * so navigation headers need nothing here; inside an iOS page sheet, which it can't see past,
+     * pass the sheet's distance from the top of the screen.
+     */
     keyboardVerticalOffset?: number;
 }
 /**