opendesk-react-native 0.0.0-stage → 0.1.1

package/lib/client.js

@@ -0,0 +1,505 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenDesk = void 0;
+const api_1 = require("./api");
+const errors_1 = require("./errors");
+const realtime_1 = require("./realtime");
+const storage_1 = require("./storage");
+const TYPING_TTL_MS = 6000;
+const AI_REPLY_TTL_MS = 60000;
+const initialState = {
+    status: 'idle',
+    error: null,
+    config: null,
+    session: null,
+    connected: false,
+    conversations: [],
+    messages: {},
+    typing: {},
+    aiReplies: {},
+    unread: {},
+    activeConversationId: null,
+};
+let localIds = 0;
+/**
+ * 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.
+ */
+class OpenDesk {
+    constructor(options) {
+        this.state = initialState;
+        this.identity = {};
+        this.realtime = null;
+        this.bootPromise = null;
+        this.subscribers = new Set();
+        this.messageListeners = new Set();
+        this.typingTimers = {};
+        /** Files uploaded this session, so a message can show its attachments before the server answers. */
+        this.uploads = new Map();
+        this.getState = () => this.state;
+        this.subscribe = (listener) => {
+            this.subscribers.add(listener);
+            return () => this.subscribers.delete(listener);
+        };
+        this.api = new api_1.OpenDeskApi(options);
+        this.storage = options.storage ?? (0, storage_1.memoryStorage)();
+        this.storageKey = `opendesk.visitor.${options.widgetKey}`;
+        this.socketFactory = options.socketFactory ?? realtime_1.phoenixSocketFactory;
+    }
+    /** Called for every agent or AI reply, e.g. to show an in-app banner. */
+    onMessage(listener) {
+        this.messageListeners.add(listener);
+        return () => this.messageListeners.delete(listener);
+    }
+    get unreadCount() {
+        return Object.values(this.state.unread).reduce((total, count) => total + count, 0);
+    }
+    /** Loads the widget config and starts (or resumes) the visitor session. Safe to call repeatedly. */
+    boot() {
+        if (!this.bootPromise) {
+            this.bootPromise = this.runBoot().catch((error) => {
+                this.bootPromise = null;
+                this.set({ status: 'error', error: errorMessage(error) });
+                throw error;
+            });
+        }
+        return this.bootPromise;
+    }
+    /**
+     * 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.
+     */
+    async identify(identity) {
+        const switchedUser = Boolean(this.identity.user_id) && this.identity.user_id !== identity.user_id;
+        this.identity = { ...(switchedUser ? {} : this.identity), ...identity };
+        if (switchedUser) {
+            this.resetConversations();
+            await this.forgetToken();
+        }
+        if (this.bootPromise) {
+            await this.bootPromise.catch(() => undefined);
+            if (this.state.status === 'ready') {
+                await this.startSession();
+            }
+        }
+    }
+    /** Ends the session and forgets the visitor. Call it when the user signs out. */
+    async shutdown() {
+        this.realtime?.stop();
+        this.realtime = null;
+        Object.values(this.typingTimers).forEach(clearTimeout);
+        await this.api.endSession().catch(() => undefined);
+        await this.forgetToken();
+        this.identity = {};
+        this.bootPromise = null;
+        this.state = { ...initialState, config: this.state.config };
+        this.emitChange();
+    }
+    loadConversations() {
+        return this.authorized(() => this.fetchConversations());
+    }
+    /** Marks a conversation as on screen: loads its messages and clears its unread count. */
+    async openConversation(conversationId) {
+        this.set((state) => ({
+            activeConversationId: conversationId,
+            unread: withoutKey(state.unread, conversationId),
+        }));
+        const messages = await this.refreshMessages(conversationId);
+        this.api.markSeen(conversationId).catch(() => undefined);
+        return messages;
+    }
+    closeConversation() {
+        this.realtime?.typingDone();
+        this.set({ activeConversationId: null });
+    }
+    async refreshMessages(conversationId) {
+        const messages = await this.authorized(() => this.api.messages(conversationId));
+        this.applyMessages(conversationId, messages, true);
+        return this.state.messages[conversationId] ?? [];
+    }
+    async startConversation(input) {
+        const { conversation, message } = await this.authorized(() => this.api.startConversation(input));
+        this.set((state) => ({
+            conversations: [conversation, ...state.conversations.filter((c) => c.id !== conversation.id)],
+            activeConversationId: conversation.id,
+        }));
+        if (message) {
+            this.applyMessages(conversation.id, [message], false);
+        }
+        return conversation;
+    }
+    /** Sends a reply, showing it at once and swapping in the server copy when it returns. */
+    async sendMessage(conversationId, input) {
+        const localId = `local-${++localIds}`;
+        const local = {
+            id: localId,
+            ticket_id: conversationId,
+            kind: 'reply',
+            direction: 'inbound',
+            author: { type: 'contact', contact: this.state.session?.contact ?? null },
+            body_text: input.body ?? '',
+            body_html: '',
+            attachments: (input.attachment_ids ?? []).flatMap((id) => this.uploads.get(id) ?? []),
+            created_at: new Date().toISOString(),
+        };
+        this.applyMessages(conversationId, [local], false);
+        this.realtime?.typingDone();
+        try {
+            const message = await this.authorized(() => this.api.sendMessage(conversationId, input));
+            this.applyMessages(conversationId, [message], false, localId);
+            this.touchConversation(conversationId, message);
+            return message;
+        }
+        catch (error) {
+            this.set((state) => ({
+                messages: {
+                    ...state.messages,
+                    [conversationId]: (state.messages[conversationId] ?? []).filter((m) => m.id !== localId),
+                },
+            }));
+            throw error;
+        }
+    }
+    async upload(file) {
+        const attachment = await this.authorized(() => this.api.upload(file));
+        this.uploads.set(attachment.id, attachment);
+        return attachment;
+    }
+    typing(conversationId) {
+        this.realtime?.typing(conversationId);
+    }
+    async requestHuman(conversationId) {
+        await this.authorized(() => this.api.handoff(conversationId));
+        this.set((state) => ({
+            conversations: state.conversations.map((c) => (c.id === conversationId ? { ...c, ai_handoff: true } : c)),
+        }));
+    }
+    decideAction(conversationId, actionId, decision) {
+        return this.authorized(() => this.api.decideAction(conversationId, actionId, decision));
+    }
+    rateMessage(conversationId, messageId, rating) {
+        return this.authorized(() => this.api.rateMessage(conversationId, messageId, rating));
+    }
+    async runBoot() {
+        this.set({ status: 'booting', error: null });
+        if (!this.api.visitorToken) {
+            this.api.visitorToken = await this.storage.getItem(this.storageKey).catch(() => null);
+        }
+        const config = await this.api.config();
+        this.set({ config });
+        await this.startSession();
+        this.set({ status: 'ready' });
+    }
+    async startSession() {
+        const session = await this.openSession();
+        this.set({ session, error: null });
+        this.realtime?.stop();
+        this.realtime = new realtime_1.OpenDeskRealtime(this.socketFactory, session.gateway_url, session.ws_token, session.contact.id, async () => (await this.openSession()).ws_token, {
+            onEvent: (event) => this.onRealtimeEvent(event),
+            onLive: (event) => this.onLiveEvent(event),
+            onTyping: (event) => this.onAgentTyping(event.ticket_id, event.user?.name || 'Support'),
+            onStatus: (connected) => this.set({ connected }),
+            onReconnect: () => void this.catchUp(),
+        });
+        this.realtime.start();
+        await this.fetchConversations();
+    }
+    async fetchConversations() {
+        const conversations = await this.api.conversations();
+        conversations.sort((a, b) => Date.parse(b.last_message_at) - Date.parse(a.last_message_at));
+        this.set({ conversations });
+        return conversations;
+    }
+    /** Resumes the stored session; a revoked or expired token falls back to a new one. */
+    async openSession() {
+        let session;
+        try {
+            session = await this.api.session(this.identity);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.OpenDeskError) || !this.api.visitorToken || error.status < 400 || error.status >= 500) {
+                throw error;
+            }
+            this.api.visitorToken = null;
+            session = await this.api.session(this.identity);
+        }
+        await this.storage.setItem(this.storageKey, session.visitor_token).catch(() => undefined);
+        return session;
+    }
+    /** Runs a visitor request, re-opening the session once if the token was revoked. */
+    async authorized(request) {
+        await this.boot();
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.OpenDeskError) || !error.isUnauthorized) {
+                throw error;
+            }
+            this.api.visitorToken = null;
+            await this.startSession();
+            return request();
+        }
+    }
+    async catchUp() {
+        await this.loadConversations().catch(() => undefined);
+        const active = this.state.activeConversationId;
+        if (active) {
+            await this.refreshMessages(active).catch(() => undefined);
+        }
+    }
+    onRealtimeEvent(event) {
+        const conversationId = event.data.ticket_id ?? event.data.message?.ticket_id;
+        if (event.type === 'message.withdrawn') {
+            const messageId = event.data.message_id;
+            if (conversationId && messageId) {
+                this.set((state) => ({
+                    messages: {
+                        ...state.messages,
+                        [conversationId]: (state.messages[conversationId] ?? []).filter((m) => m.id !== messageId),
+                    },
+                }));
+            }
+            return;
+        }
+        if (event.type !== 'message.created' && event.type !== 'message.updated') {
+            return;
+        }
+        const message = event.data.message;
+        if (!message || !conversationId || message.kind === 'note') {
+            return;
+        }
+        this.applyMessages(conversationId, [message], false);
+        if (event.type === 'message.updated') {
+            return;
+        }
+        if (this.state.conversations.some((c) => c.id === conversationId)) {
+            this.touchConversation(conversationId, message);
+        }
+        else {
+            void this.loadConversations().catch(() => undefined);
+        }
+        if (message.direction !== 'outbound') {
+            return;
+        }
+        this.clearTyping(conversationId);
+        if (this.state.activeConversationId === conversationId) {
+            this.api.markSeen(conversationId).catch(() => undefined);
+        }
+        else {
+            this.set((state) => ({
+                unread: { ...state.unread, [conversationId]: (state.unread[conversationId] ?? 0) + 1 },
+            }));
+        }
+        const from = message.author.user?.name || message.author.bot?.name || this.state.config?.workspace_name || 'Support';
+        this.messageListeners.forEach((listener) => {
+            try {
+                listener({ conversationId, message, from });
+            }
+            catch {
+                // A listener's failure must not break the stream.
+            }
+        });
+    }
+    onLiveEvent(event) {
+        const { reply_id: replyId, ticket_id: conversationId } = event.data;
+        if (typeof replyId !== 'string' || typeof conversationId !== 'string') {
+            return;
+        }
+        const now = Date.now();
+        this.set((state) => {
+            const replies = pruneReplies(state.aiReplies, now);
+            const current = replies[replyId] ?? {
+                id: replyId,
+                conversationId,
+                text: '',
+                phase: 'typing',
+                tools: [],
+                bot: null,
+                messageId: null,
+                handoff: false,
+                actionId: null,
+                updatedAt: now,
+            };
+            switch (event.type) {
+                case 'ai.reply.started':
+                    return { aiReplies: { ...replies, [replyId]: { ...current, bot: event.data.bot ?? current.bot, updatedAt: now } } };
+                case 'ai.reply.delta':
+                    if (!event.data.text) {
+                        return {};
+                    }
+                    return {
+                        aiReplies: {
+                            ...replies,
+                            [replyId]: { ...current, text: current.text + event.data.text, phase: 'streaming', updatedAt: now },
+                        },
+                    };
+                case 'ai.reply.tool': {
+                    const name = event.data.tool;
+                    if (!name) {
+                        return {};
+                    }
+                    const status = event.data.status === 'done' || event.data.status === 'error' ? event.data.status : 'running';
+                    const tools = [...current.tools];
+                    const running = tools.map((t) => t.name === name && t.status === 'running').lastIndexOf(true);
+                    if (running >= 0) {
+                        tools[running] = { name, status };
+                    }
+                    else {
+                        tools.push({ name, status });
+                    }
+                    return { aiReplies: { ...replies, [replyId]: { ...current, tools, updatedAt: now } } };
+                }
+                case 'ai.reply.ended': {
+                    const messageId = event.data.message_id || null;
+                    const landed = !messageId || (state.messages[conversationId] ?? []).some((m) => m.id === messageId);
+                    if (landed) {
+                        return { aiReplies: withoutKey(replies, replyId) };
+                    }
+                    return {
+                        aiReplies: {
+                            ...replies,
+                            [replyId]: {
+                                ...current,
+                                phase: 'done',
+                                tools: current.tools.map((t) => (t.status === 'running' ? { ...t, status: 'done' } : t)),
+                                messageId,
+                                handoff: event.data.handoff === true,
+                                actionId: event.data.action_id ?? null,
+                                updatedAt: now,
+                            },
+                        },
+                    };
+                }
+                default:
+                    return {};
+            }
+        });
+    }
+    onAgentTyping(conversationId, name) {
+        this.set((state) => ({ typing: { ...state.typing, [conversationId]: name } }));
+        clearTimeout(this.typingTimers[conversationId]);
+        this.typingTimers[conversationId] = setTimeout(() => this.clearTyping(conversationId), TYPING_TTL_MS);
+    }
+    clearTyping(conversationId) {
+        clearTimeout(this.typingTimers[conversationId]);
+        delete this.typingTimers[conversationId];
+        if (conversationId in this.state.typing) {
+            this.set((state) => ({ typing: withoutKey(state.typing, conversationId) }));
+        }
+    }
+    /**
+     * 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.
+     */
+    applyMessages(conversationId, incoming, replace, replacesLocalId) {
+        this.set((state) => {
+            const existing = state.messages[conversationId] ?? [];
+            const existingById = new Map(existing.map((m) => [m.id, m]));
+            const pending = existing.filter((m) => m.id.startsWith('local-'));
+            const usedLocalIds = new Set();
+            const finishedReplyIds = new Set();
+            const keyed = incoming.map((message) => {
+                if (message.client_id) {
+                    return message;
+                }
+                const previous = existingById.get(message.id);
+                if (previous?.client_id) {
+                    return { ...message, client_id: previous.client_id };
+                }
+                if (message.direction === 'inbound' && !message.id.startsWith('local-')) {
+                    const local = pending.find((m) => m.id === replacesLocalId) ??
+                        pending.find((m) => !usedLocalIds.has(m.id) && (m.body_text ?? '') === (message.body_text ?? ''));
+                    if (local) {
+                        usedLocalIds.add(local.id);
+                        return { ...message, client_id: local.client_id ?? local.id };
+                    }
+                }
+                if (message.ai && message.direction === 'outbound') {
+                    const reply = Object.values(state.aiReplies).find((r) => !finishedReplyIds.has(r.id) &&
+                        (r.messageId === message.id || (r.conversationId === conversationId && r.phase !== 'done')));
+                    if (reply) {
+                        finishedReplyIds.add(reply.id);
+                        return { ...message, client_id: `ai-${reply.id}` };
+                    }
+                }
+                return message;
+            });
+            const base = (replace ? pending : existing).filter((m) => !usedLocalIds.has(m.id));
+            const byId = new Map(base.map((m) => [m.id, m]));
+            keyed.forEach((m) => byId.set(m.id, m));
+            const merged = [...byId.values()].sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+            const landedIds = new Set(incoming.map((m) => m.id));
+            const aiReplies = Object.fromEntries(Object.entries(state.aiReplies).filter(([id, reply]) => !finishedReplyIds.has(id) && !(reply.messageId && landedIds.has(reply.messageId))));
+            return { messages: { ...state.messages, [conversationId]: merged }, aiReplies };
+        });
+    }
+    touchConversation(conversationId, message) {
+        this.set((state) => {
+            const conversation = state.conversations.find((c) => c.id === conversationId);
+            if (!conversation) {
+                return {};
+            }
+            return {
+                conversations: [
+                    {
+                        ...conversation,
+                        last_message_at: message.created_at,
+                        last_message_preview: previewOf(message),
+                    },
+                    ...state.conversations.filter((c) => c.id !== conversationId),
+                ],
+            };
+        });
+    }
+    resetConversations() {
+        this.realtime?.stop();
+        this.realtime = null;
+        this.set({
+            session: null,
+            connected: false,
+            conversations: [],
+            messages: {},
+            typing: {},
+            aiReplies: {},
+            unread: {},
+            activeConversationId: null,
+        });
+    }
+    async forgetToken() {
+        this.api.visitorToken = null;
+        await this.storage.removeItem(this.storageKey).catch(() => undefined);
+    }
+    set(patch) {
+        const next = typeof patch === 'function' ? patch(this.state) : patch;
+        if (Object.keys(next).length === 0) {
+            return;
+        }
+        this.state = { ...this.state, ...next };
+        this.emitChange();
+    }
+    emitChange() {
+        this.subscribers.forEach((listener) => listener());
+    }
+}
+exports.OpenDesk = OpenDesk;
+function withoutKey(record, key) {
+    if (!(key in record)) {
+        return record;
+    }
+    const copy = { ...record };
+    delete copy[key];
+    return copy;
+}
+function pruneReplies(replies, now) {
+    return Object.fromEntries(Object.entries(replies).filter(([, reply]) => now - reply.updatedAt < AI_REPLY_TTL_MS));
+}
+/** A list preview for a message; an attachment-only message shows its file names. */
+function previewOf(message) {
+    const text = (message.body_text ?? '').trim();
+    return (text || (message.attachments ?? []).map((a) => a.filename).join(', ')).slice(0, 140);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'Support is unavailable right now';
+}

package/lib/errors.d.ts

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

package/lib/errors.js

@@ -0,0 +1,17 @@
+"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. */
+class OpenDeskError extends Error {
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'OpenDeskError';
+    }
+    /** The visitor token is unknown or revoked; a fresh session is needed. */
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+}
+exports.OpenDeskError = OpenDeskError;

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+export { OpenDesk } from './client';
+export type { AIReply, IncomingMessage, OpenDeskOptions, OpenDeskState } from './client';
+export { OpenDeskApi } from './api';
+export type { Fetcher, OpenDeskApiOptions } from './api';
+export { OpenDeskError } from './errors';
+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 { OpenDeskProvider, useConversation, useConversations, useOpenDesk, useOpenDeskState, useUnreadCount, } from './react';
+export type { ConversationView, OpenDeskProviderProps } from './react';
+export { OpenDeskChat } from './ui/OpenDeskChat';
+export type { OpenDeskChatProps } from './ui/OpenDeskChat';
+export { OpenDeskLauncher } from './ui/OpenDeskLauncher';
+export type { OpenDeskLauncherProps } from './ui/OpenDeskLauncher';
+export { defaultStrings } from './ui/strings';
+export type { ChatStrings } from './ui/strings';
+export type * from './types';

package/lib/index.js

@@ -0,0 +1,29 @@
+"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;
+var client_1 = require("./client");
+Object.defineProperty(exports, "OpenDesk", { enumerable: true, get: function () { return client_1.OpenDesk; } });
+var api_1 = require("./api");
+Object.defineProperty(exports, "OpenDeskApi", { enumerable: true, get: function () { return api_1.OpenDeskApi; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "OpenDeskError", { enumerable: true, get: function () { return errors_1.OpenDeskError; } });
+var realtime_1 = require("./realtime");
+Object.defineProperty(exports, "OpenDeskRealtime", { enumerable: true, get: function () { return realtime_1.OpenDeskRealtime; } });
+Object.defineProperty(exports, "phoenixSocketFactory", { enumerable: true, get: function () { return realtime_1.phoenixSocketFactory; } });
+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 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; } });
+Object.defineProperty(exports, "useConversations", { enumerable: true, get: function () { return react_1.useConversations; } });
+Object.defineProperty(exports, "useOpenDesk", { enumerable: true, get: function () { return react_1.useOpenDesk; } });
+Object.defineProperty(exports, "useOpenDeskState", { enumerable: true, get: function () { return react_1.useOpenDeskState; } });
+Object.defineProperty(exports, "useUnreadCount", { enumerable: true, get: function () { return react_1.useUnreadCount; } });
+var OpenDeskChat_1 = require("./ui/OpenDeskChat");
+Object.defineProperty(exports, "OpenDeskChat", { enumerable: true, get: function () { return OpenDeskChat_1.OpenDeskChat; } });
+var OpenDeskLauncher_1 = require("./ui/OpenDeskLauncher");
+Object.defineProperty(exports, "OpenDeskLauncher", { enumerable: true, get: function () { return OpenDeskLauncher_1.OpenDeskLauncher; } });
+var strings_1 = require("./ui/strings");
+Object.defineProperty(exports, "defaultStrings", { enumerable: true, get: function () { return strings_1.defaultStrings; } });

package/lib/react.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from 'react';
+import { OpenDesk, type AIReply, type OpenDeskState } from './client';
+import type { Conversation, Identity, Message } from './types';
+export interface OpenDeskProviderProps {
+    client: OpenDesk;
+    /**
+     * The signed-in user, fetched from your backend (it holds the widget secret). Pass `null`
+     * after sign-out to end the session; leave it undefined for anonymous chat.
+     */
+    identity?: Identity | null;
+    /** Starts the session on mount; turn off to boot lazily when the chat is first opened. */
+    autoBoot?: boolean;
+    children: ReactNode;
+}
+export declare function OpenDeskProvider({ client, identity, autoBoot, children }: OpenDeskProviderProps): import("react").JSX.Element;
+export declare function useOpenDesk(): OpenDesk;
+export declare function useOpenDeskState<T>(selector: (state: OpenDeskState) => T): T;
+export declare function useUnreadCount(): number;
+export declare function useConversations(): {
+    conversations: Conversation[];
+    ready: boolean;
+    error: string | null;
+};
+export interface ConversationView {
+    messages: Message[];
+    /** AI answers still streaming in this conversation. */
+    aiReplies: AIReply[];
+    /** Name of the agent typing, if any. */
+    typing: string | null;
+    conversation: Conversation | null;
+}
+/** Opens a conversation while mounted: loads its messages, keeps it read, and closes it on unmount. */
+export declare function useConversation(conversationId: string | null): ConversationView;