opendesk-react-native 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opendesk-react-native contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# opendesk-react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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

package/lib/api.d.ts

@@ -0,0 +1,43 @@
+import type { Attachment, Conversation, Identity, Message, SendMessageInput, StartConversationInput, UploadFile, WidgetConfig, WidgetSession } from './types';
+export type Fetcher = typeof fetch;
+export interface OpenDeskApiOptions {
+    /** The openDesk origin, e.g. `https://desk.example.com`. `/v1` is added. */
+    baseUrl: string;
+    /** The chat widget's public key (`wk_…`). */
+    widgetKey: string;
+    fetcher?: Fetcher;
+}
+/**
+ * Thin REST client for openDesk's visitor endpoints. Holds the visitor token once a
+ * session exists and sends it as `Authorization: Visitor <token>`.
+ */
+export declare class OpenDeskApi {
+    readonly baseUrl: string;
+    readonly widgetKey: string;
+    visitorToken: string | null;
+    private readonly fetcher;
+    constructor(options: OpenDeskApiOptions);
+    config(): Promise<WidgetConfig>;
+    /** Starts a session, or resumes the current one when a visitor token is held. */
+    session(identity?: Identity): Promise<WidgetSession>;
+    endSession(): Promise<void>;
+    conversations(): Promise<Conversation[]>;
+    startConversation(input: StartConversationInput): Promise<{
+        conversation: Conversation;
+        message: Message;
+    }>;
+    messages(conversationId: string): Promise<Message[]>;
+    sendMessage(conversationId: string, input: SendMessageInput): Promise<Message>;
+    markSeen(conversationId: string): Promise<void>;
+    /** Asks for a person after an AI answer. */
+    handoff(conversationId: string): Promise<void>;
+    /** Confirms or declines an action the AI proposed. */
+    decideAction(conversationId: string, actionId: string, decision: 'confirm' | 'decline'): Promise<void>;
+    rateMessage(conversationId: string, messageId: string, rating: 'up' | 'down'): Promise<void>;
+    /**
+     * Uploads one file as multipart `file`. React Native's FormData takes `{ uri, name, type }`;
+     * a browser needs a real Blob, so web Files are passed through as they are.
+     */
+    upload(file: UploadFile): Promise<Attachment>;
+    private request;
+}

package/lib/api.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenDeskApi = void 0;
+const errors_1 = require("./errors");
+/**
+ * Thin REST client for openDesk's visitor endpoints. Holds the visitor token once a
+ * session exists and sends it as `Authorization: Visitor <token>`.
+ */
+class OpenDeskApi {
+    constructor(options) {
+        this.visitorToken = null;
+        this.baseUrl = options.baseUrl.replace(/\/widget\/v1\.js$/, '').replace(/\/+$/, '').replace(/\/v1$/, '');
+        this.widgetKey = options.widgetKey;
+        this.fetcher = options.fetcher ?? ((input, init) => fetch(input, init));
+    }
+    config() {
+        return this.request('GET', `/v1/widget/config?key=${encodeURIComponent(this.widgetKey)}`, undefined, false);
+    }
+    /** Starts a session, or resumes the current one when a visitor token is held. */
+    async session(identity = {}) {
+        const session = await this.request('POST', '/v1/widget/session', { key: this.widgetKey, ...(this.visitorToken ? { visitor_token: this.visitorToken } : {}), ...identity }, false);
+        this.visitorToken = session.visitor_token;
+        return session;
+    }
+    async endSession() {
+        if (this.visitorToken) {
+            await this.request('DELETE', '/v1/widget/session');
+        }
+    }
+    async conversations() {
+        const response = await this.request('GET', '/v1/widget/conversations');
+        return response.data ?? [];
+    }
+    startConversation(input) {
+        return this.request('POST', '/v1/widget/conversations', input);
+    }
+    async messages(conversationId) {
+        const response = await this.request('GET', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/messages`);
+        return response.data ?? [];
+    }
+    sendMessage(conversationId, input) {
+        return this.request('POST', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/messages`, input);
+    }
+    async markSeen(conversationId) {
+        await this.request('POST', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/seen`, {});
+    }
+    /** Asks for a person after an AI answer. */
+    async handoff(conversationId) {
+        await this.request('POST', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/handoff`, {});
+    }
+    /** Confirms or declines an action the AI proposed. */
+    async decideAction(conversationId, actionId, decision) {
+        await this.request('POST', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/actions/${encodeURIComponent(actionId)}`, { decision });
+    }
+    async rateMessage(conversationId, messageId, rating) {
+        await this.request('POST', `/v1/widget/conversations/${encodeURIComponent(conversationId)}/messages/${encodeURIComponent(messageId)}/rating`, { rating });
+    }
+    /**
+     * Uploads one file as multipart `file`. React Native's FormData takes `{ uri, name, type }`;
+     * a browser needs a real Blob, so web Files are passed through as they are.
+     */
+    upload(file) {
+        const form = new FormData();
+        if (isBlob(file)) {
+            form.append('file', file, 'name' in file && typeof file.name === 'string' ? file.name : 'upload');
+        }
+        else {
+            form.append('file', { uri: file.uri, name: file.name, type: file.type || 'application/octet-stream' });
+        }
+        return this.request('POST', '/v1/widget/attachments', form);
+    }
+    async request(method, path, body, authenticated = true) {
+        const headers = { Accept: 'application/json' };
+        let payload;
+        if (body instanceof FormData) {
+            payload = body;
+        }
+        else if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            payload = JSON.stringify(body);
+        }
+        if (authenticated && this.visitorToken) {
+            headers.Authorization = `Visitor ${this.visitorToken}`;
+        }
+        let response;
+        try {
+            response = await this.fetcher(this.baseUrl + path, { method, headers, body: payload });
+        }
+        catch {
+            throw new errors_1.OpenDeskError(0, 'network_error', "Can't reach the server");
+        }
+        if (!response.ok) {
+            let code = 'error';
+            let message = `Request failed (${response.status})`;
+            try {
+                const problem = (await response.json());
+                code = problem.code ?? code;
+                message = problem.detail || problem.title || message;
+            }
+            catch {
+                // Not a problem+json body.
+            }
+            throw new errors_1.OpenDeskError(response.status, code, message);
+        }
+        if (response.status === 204 || !(response.headers.get('content-type') ?? '').includes('json')) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+}
+exports.OpenDeskApi = OpenDeskApi;
+function isBlob(file) {
+    return typeof Blob !== 'undefined' && file instanceof Blob;
+}

package/lib/client.d.ts

@@ -0,0 +1,120 @@
+import { OpenDeskApi, type Fetcher } from './api';
+import { type SocketFactory } from './realtime';
+import { type TokenStorage } from './storage';
+import type { Attachment, BotRef, Conversation, Identity, Message, SendMessageInput, StartConversationInput, UploadFile, WidgetConfig, WidgetSession } from './types';
+export interface OpenDeskOptions {
+    /** The openDesk origin, e.g. `https://desk.example.com`. */
+    baseUrl: string;
+    /** The chat widget's public key (`wk_…`). */
+    widgetKey: string;
+    /** Persists the visitor token so conversations survive restarts. Defaults to memory. */
+    storage?: TokenStorage;
+    fetcher?: Fetcher;
+    socketFactory?: SocketFactory;
+}
+/** An AI answer being streamed before it lands as a message. */
+export interface AIReply {
+    id: string;
+    conversationId: string;
+    text: string;
+    phase: 'typing' | 'streaming' | 'done';
+    tools: {
+        name: string;
+        status: 'running' | 'done' | 'error';
+    }[];
+    bot: BotRef | null;
+    messageId: string | null;
+    handoff: boolean;
+    actionId: string | null;
+    updatedAt: number;
+}
+export interface OpenDeskState {
+    status: 'idle' | 'booting' | 'ready' | 'error';
+    error: string | null;
+    config: WidgetConfig | null;
+    session: WidgetSession | null;
+    connected: boolean;
+    conversations: Conversation[];
+    messages: Record<string, Message[]>;
+    /** Conversation id → name of the agent currently typing. */
+    typing: Record<string, string>;
+    aiReplies: Record<string, AIReply>;
+    /** Conversation id → agent replies received while that conversation was not open. */
+    unread: Record<string, number>;
+    activeConversationId: string | null;
+}
+export interface IncomingMessage {
+    conversationId: string;
+    message: Message;
+    from: string;
+}
+/**
+ * Headless openDesk chat client: owns the visitor session, the realtime socket and the
+ * conversation state. Subscribe with `subscribe` (or the React hooks) to render it.
+ */
+export declare class OpenDesk {
+    readonly api: OpenDeskApi;
+    private state;
+    private identity;
+    private realtime;
+    private bootPromise;
+    private readonly storage;
+    private readonly storageKey;
+    private readonly socketFactory;
+    private readonly subscribers;
+    private readonly messageListeners;
+    private readonly typingTimers;
+    /** Files uploaded this session, so a message can show its attachments before the server answers. */
+    private readonly uploads;
+    constructor(options: OpenDeskOptions);
+    getState: () => OpenDeskState;
+    subscribe: (listener: () => void) => (() => void);
+    /** Called for every agent or AI reply, e.g. to show an in-app banner. */
+    onMessage(listener: (incoming: IncomingMessage) => void): () => void;
+    get unreadCount(): number;
+    /** Loads the widget config and starts (or resumes) the visitor session. Safe to call repeatedly. */
+    boot(): Promise<void>;
+    /**
+     * Attaches the signed-in user. A different `user_id` from the one before drops the stored
+     * visitor token, so one user never resumes another's conversations on a shared device.
+     */
+    identify(identity: Identity): Promise<void>;
+    /** Ends the session and forgets the visitor. Call it when the user signs out. */
+    shutdown(): Promise<void>;
+    loadConversations(): Promise<Conversation[]>;
+    /** Marks a conversation as on screen: loads its messages and clears its unread count. */
+    openConversation(conversationId: string): Promise<Message[]>;
+    closeConversation(): void;
+    refreshMessages(conversationId: string): Promise<Message[]>;
+    startConversation(input: StartConversationInput): Promise<Conversation>;
+    /** Sends a reply, showing it at once and swapping in the server copy when it returns. */
+    sendMessage(conversationId: string, input: SendMessageInput): Promise<Message>;
+    upload(file: UploadFile): Promise<Attachment>;
+    typing(conversationId: string): void;
+    requestHuman(conversationId: string): Promise<void>;
+    decideAction(conversationId: string, actionId: string, decision: 'confirm' | 'decline'): Promise<void>;
+    rateMessage(conversationId: string, messageId: string, rating: 'up' | 'down'): Promise<void>;
+    private runBoot;
+    private startSession;
+    private fetchConversations;
+    /** Resumes the stored session; a revoked or expired token falls back to a new one. */
+    private openSession;
+    /** Runs a visitor request, re-opening the session once if the token was revoked. */
+    private authorized;
+    private catchUp;
+    private onRealtimeEvent;
+    private onLiveEvent;
+    private onAgentTyping;
+    private clearTyping;
+    /**
+     * Merges messages by id in time order; `replace` makes the list exactly the server's copy.
+     * A stored message takes over the render key of the optimistic copy (`replacesLocalId`, or
+     * a pending copy with the same text) or of the AI stream it finishes, so its row never remounts.
+     */
+    private applyMessages;
+    private touchConversation;
+    private resetConversations;
+    private forgetToken;
+    private set;
+    private emitChange;
+}