@giovchat/react-native 0.0.0-stage → 0.3.0

package/dist/useChatSession.js

@@ -0,0 +1,965 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BACKGROUND_GRACE_MS = void 0;
+exports.missingContactFields = missingContactFields;
+exports.sessionScope = sessionScope;
+exports.legacySessionScope = legacySessionScope;
+exports.mergeMessages = mergeMessages;
+exports.displayMessages = displayMessages;
+exports.useChatSession = useChatSession;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const client_1 = require("./client");
+const identity_1 = require("./identity");
+const errors_1 = require("./errors");
+const rating_1 = require("./rating");
+const outbox_1 = require("./outbox");
+const attachments_1 = require("./attachments");
+function missingContactFields(fields = {}, contact = {}) {
+    const missing = {};
+    for (const field of ["email", "phone", "firstName", "lastName"]) {
+        const value = contact[field]?.trim() ?? "";
+        if (fields[field] && (!value || (field === "email" && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))))
+            missing[field] = true;
+    }
+    return missing;
+}
+/**
+ * The storage key of a visitor's session: the API, the workspace, the host's `sessionKey` and the
+ * signed-in `userId`. Contact details are not part of it, so a profile edit keeps the conversation.
+ */
+function sessionScope(baseUrl, tenantKey, contact, sessionKey) {
+    return JSON.stringify([baseUrl.replace(/\/$/, ""), tenantKey, sessionKey ?? null, contact?.userId ?? null]);
+}
+/** The 0.2.0 key, which also held the contact details; read once so an upgrade keeps the conversation. */
+function legacySessionScope(baseUrl, tenantKey, contact, sessionKey) {
+    return JSON.stringify([baseUrl.replace(/\/$/, ""), tenantKey, sessionKey ?? null,
+        contact?.userId ?? null, contact?.email ?? null, contact?.phone ?? null,
+        contact?.firstName ?? null, contact?.lastName ?? null]);
+}
+/** By server id; a copy without a local key keeps the one it was shown under, so the bubble is not redrawn. */
+function mergeMessages(current, incoming) {
+    const messages = new Map(current.map((message) => [message.id, message]));
+    for (const message of incoming) {
+        const existing = messages.get(message.id);
+        messages.set(message.id, existing?.clientMessageId && !message.clientMessageId
+            ? { ...message, clientMessageId: existing.clientMessageId } : message);
+    }
+    return [...messages.values()].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+/** What the visitor sees: saved messages, then what is still sending, then replies being written. */
+function displayMessages(saved, pending, drafts, describe = () => ({ filename: "" })) {
+    const shown = new Set(saved.map((message) => message.clientMessageId).filter(Boolean));
+    const list = saved.map((message) => message.attachments?.length
+        ? { ...message, attachments: message.attachments.map((attachment) => ({ ...describe(attachment.url), ...attachment, filename: attachment.filename || describe(attachment.url).filename })) }
+        : message);
+    for (const entry of pending) {
+        if (shown.has(entry.clientMessageId))
+            continue;
+        list.push({
+            id: entry.clientMessageId, clientMessageId: entry.clientMessageId, role: "visitor", content: entry.content,
+            createdAt: entry.createdAt, status: entry.state === "failed" ? "failed" : "sending",
+            ...(entry.attachments.length ? { attachments: entry.attachments.map((url) => ({ url, ...describe(url) })) } : {}),
+        });
+    }
+    for (const [streamId, draft] of Object.entries(drafts)) {
+        const key = `stream:${streamId}`;
+        if (shown.has(key) || !draft.content)
+            continue;
+        list.push({ id: key, clientMessageId: key, role: "agent", content: draft.content, createdAt: draft.createdAt, isBot: true, isAutomated: true, isStreaming: true });
+    }
+    return list.sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+/** How long after the last keystroke the agent stops seeing "typing" (the widget's value). */
+const TYPING_IDLE_MS = 2500;
+/** A short trip to the background (a file picker, the app switcher) keeps the socket, as in the Android SDK. */
+exports.BACKGROUND_GRACE_MS = 5000;
+const NOT_TYPING = { visible: false };
+/** A failed start that cannot succeed by itself waits for the visitor instead of retrying. */
+const NO_AUTO_RETRY = new Set(["identity_rejected", "invalid_session"]);
+function useChatSession(options) {
+    const { tenantKey, baseUrl, visible, scope, sessionStorage } = options;
+    const callbacks = (0, react_1.useRef)(options);
+    callbacks.current = options;
+    const contact = (0, react_1.useRef)(options.contact);
+    const session = (0, react_1.useRef)(null);
+    const loadedStorage = (0, react_1.useRef)(false);
+    // Set by the first message or the pre-chat form: the next start creates the conversation.
+    const startNow = (0, react_1.useRef)(false);
+    const client = (0, react_1.useRef)(null);
+    const generation = (0, react_1.useRef)(0);
+    const outboxRef = (0, react_1.useRef)(null);
+    outboxRef.current ?? (outboxRef.current = new outbox_1.Outbox());
+    const outbox = outboxRef.current;
+    const visibleRef = (0, react_1.useRef)(visible);
+    visibleRef.current = visible;
+    // Files sent from this device: names and types the server's copy does not carry.
+    const localFiles = (0, react_1.useRef)(new Map());
+    const pushRequest = (0, react_1.useRef)(null);
+    // The last token the host registered: a conversation started after the team closed the previous
+    // one gets it again. Forgotten by reset() (sign-out) and unregisterPushToken().
+    const lastPush = (0, react_1.useRef)(null);
+    // Failed starts retried with the protocol's backoff; `auto` while such a retry runs.
+    const autoRetry = (0, react_1.useRef)({ failures: 0, timer: null, auto: false });
+    const lastTokenRenewal = (0, react_1.useRef)(0);
+    const sessionEnded = (0, react_1.useRef)(null);
+    const typing = (0, react_1.useRef)({ active: false, timer: null });
+    const configCache = (0, react_1.useRef)(null);
+    // The current connection's history catch-up, for a quick return from the background.
+    const catchUp = (0, react_1.useRef)(null);
+    const [attempt, setAttempt] = (0, react_1.useState)(0);
+    const [foreground, setForeground] = (0, react_1.useState)(react_native_1.AppState.currentState !== "background" && react_native_1.AppState.currentState !== "inactive");
+    const [phase, setPhase] = (0, react_1.useState)("loading");
+    const phaseRef = (0, react_1.useRef)(phase);
+    phaseRef.current = phase;
+    const [config, setConfig] = (0, react_1.useState)(null);
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [pending, setPending] = (0, react_1.useState)(() => outbox.list());
+    const [drafts, setDrafts] = (0, react_1.useState)({});
+    const [typingState, setTypingState] = (0, react_1.useState)(NOT_TYPING);
+    const [tokenVersion, setTokenVersion] = (0, react_1.useState)(0);
+    // The last reply that arrived live on the socket (not from history), for screen-reader announcements.
+    const [lastIncoming, setLastIncoming] = (0, react_1.useState)(null);
+    const [currentAgent, setCurrentAgent] = (0, react_1.useState)({ name: null, avatar: null });
+    const [access, setAccess] = (0, react_1.useState)(null);
+    const [unreadCount, setUnreadCount] = (0, react_1.useState)(0);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [sending, setSending] = (0, react_1.useState)(false);
+    const [uploads, setUploads] = (0, react_1.useState)([]);
+    const [requiredFields, setRequiredFields] = (0, react_1.useState)({});
+    const [hasConversation, setHasConversation] = (0, react_1.useState)(false);
+    // False once the server answered a rating route with 404: an older server, so the controls are hidden.
+    const [ratingsSupported, setRatingsSupported] = (0, react_1.useState)(true);
+    const [clock, setClock] = (0, react_1.useState)(0);
+    // The team closed the conversation: it stays on screen, read-only, until the visitor starts a new one.
+    const [closed, setClosed] = (0, react_1.useState)(false);
+    const closedRef = (0, react_1.useRef)(false);
+    closedRef.current = closed;
+    const messagesRef = (0, react_1.useRef)(messages);
+    messagesRef.current = messages;
+    const announcedRatings = (0, react_1.useRef)(new Set());
+    const keepConnected = options.keepConnected === true;
+    const wantConnection = foreground && (visible || keepConnected);
+    const report = (0, react_1.useCallback)((failure) => {
+        try {
+            callbacks.current.onError?.(failure);
+        }
+        catch { /* Host callbacks are isolated. */ }
+    }, []);
+    const status = (0, react_1.useCallback)((value) => {
+        try {
+            callbacks.current.onConnectionStatusChange?.(value);
+        }
+        catch { /* Host callbacks are isolated. */ }
+    }, []);
+    const captureAccess = (0, react_1.useCallback)((incoming) => {
+        if (incoming)
+            setAccess((current) => (0, attachments_1.newerAttachmentAccess)(current, incoming));
+    }, []);
+    const stopTyping = (0, react_1.useCallback)(() => {
+        const state = typing.current;
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = null;
+        if (state.active)
+            client.current?.sendTypingEnd();
+        state.active = false;
+    }, []);
+    (0, react_1.useEffect)(() => outbox.subscribe(() => setPending(outbox.list())), [outbox]);
+    // A profile edit (name, email, phone) keeps the conversation; the new details go with the next start.
+    const contactKey = JSON.stringify(options.contact ?? null);
+    const firstContact = (0, react_1.useRef)(contactKey);
+    (0, react_1.useEffect)(() => {
+        if (contactKey === firstContact.current)
+            return;
+        firstContact.current = contactKey;
+        contact.current = { ...contact.current, ...callbacks.current.contact };
+    }, [contactKey]);
+    // The socket closes only after a while in the background, so a picker or a glance at the app
+    // switcher does not reload the chat; iOS "inactive" (Control Centre, a system prompt) is ignored.
+    (0, react_1.useEffect)(() => {
+        const grace = callbacks.current.backgroundGraceMs ?? exports.BACKGROUND_GRACE_MS;
+        let timer = null;
+        let since = null;
+        const subscription = react_native_1.AppState.addEventListener("change", (state) => {
+            if (state === "background") {
+                if (since !== null)
+                    return;
+                since = Date.now();
+                timer = setTimeout(() => { timer = null; setForeground(false); }, grace);
+                return;
+            }
+            if (state !== "active")
+                return;
+            // Timers stop while the OS suspends the app, so the time away decides, not whether the timer ran.
+            const away = since === null ? 0 : Date.now() - since;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            since = null;
+            setForeground(true);
+            if (away >= grace) {
+                setAttempt((value) => value + 1);
+                return;
+            }
+            // Back quickly: the socket was kept. Catch up on anything missed, or reconnect now if it dropped.
+            const activeClient = client.current;
+            if (activeClient?.isConnected)
+                void catchUp.current?.().catch(() => { });
+            else
+                activeClient?.reconnectNow();
+        });
+        return () => { subscription.remove(); if (timer)
+            clearTimeout(timer); };
+    }, []);
+    // Opening a chat that stayed connected while hidden shows what arrived; one with no session starts it.
+    (0, react_1.useEffect)(() => {
+        if (!visible)
+            return;
+        setUnreadCount(0);
+        if (keepConnected && phaseRef.current === "idle")
+            setAttempt((value) => value + 1);
+    }, [visible, keepConnected]);
+    (0, react_1.useEffect)(() => {
+        try {
+            callbacks.current.onUnreadCountChange?.(unreadCount);
+        }
+        catch { /* Host callbacks are isolated. */ }
+    }, [unreadCount]);
+    (0, react_1.useEffect)(() => {
+        const currentGeneration = ++generation.current;
+        if (!wantConnection) {
+            setTypingState(NOT_TYPING);
+            setDrafts({});
+            status("disconnected");
+            return;
+        }
+        let cancelled = false;
+        const controller = new AbortController();
+        let connection = null;
+        const alive = () => !cancelled && currentGeneration === generation.current;
+        const abort = () => {
+            cancelled = true;
+            if (generation.current === currentGeneration)
+                generation.current++;
+            controller.abort();
+            if (typing.current.active)
+                connection?.sendTypingEnd();
+            if (typing.current.timer)
+                clearTimeout(typing.current.timer);
+            typing.current = { active: false, timer: null };
+            connection?.disconnect();
+            if (client.current === connection)
+                client.current = null;
+            catchUp.current = null;
+        };
+        const storageFailure = () => report(new errors_1.GiovChatError("storage", "Chat session could not be saved or restored."));
+        const clearSession = async () => {
+            session.current = null;
+            setClosed(false);
+            setHasConversation(false);
+            setMessages([]);
+            try {
+                await sessionStorage?.remove(scope);
+            }
+            catch {
+                storageFailure();
+            }
+        };
+        // The session is gone (401/403 after one token renewal): end the chat and forget the stored pair;
+        // "Try again" then waits for the visitor's next message.
+        const endSession = async (failure) => {
+            if (!alive())
+                return;
+            connection?.disconnect();
+            if (client.current === connection)
+                client.current = null;
+            connection = null;
+            catchUp.current = null;
+            await clearSession();
+            if (!alive())
+                return;
+            setCurrentAgent({ name: null, avatar: null });
+            setDrafts({});
+            setTypingState(NOT_TYPING);
+            setError(failure);
+            setPhase("error");
+            status("disconnected");
+        };
+        // The conversation was closed or deleted: forget it; the visitor's next message starts a new one.
+        const forgetConversation = async () => {
+            if (!alive())
+                return;
+            connection?.disconnect();
+            if (client.current === connection)
+                client.current = null;
+            connection = null;
+            catchUp.current = null;
+            await clearSession();
+            if (!alive())
+                return;
+            setCurrentAgent({ name: null, avatar: null });
+            setDrafts({});
+            setTypingState(NOT_TYPING);
+            setPhase("ready");
+            status("disconnected");
+            setError(new errors_1.GiovChatError("conversation_closed", "This conversation has ended."));
+        };
+        sessionEnded.current = { forget: forgetConversation, end: endSession };
+        async function start() {
+            // The configuration is loaded once: a restart (the first message, the pre-chat form, coming
+            // back from the background) keeps the conversation on screen instead of a loading spinner.
+            const cacheKey = `${baseUrl} ${tenantKey}`;
+            const cached = configCache.current?.key === cacheKey ? configCache.current.config : null;
+            // An automatic retry after a failed start keeps the error on screen until it succeeds.
+            const quiet = autoRetry.current.auto && phaseRef.current === "error";
+            if (!cached) {
+                if (!quiet)
+                    setPhase("loading");
+                setConfig(null);
+            }
+            else if (quiet) { /* Unchanged. */ }
+            else if (session.current)
+                setPhase("connecting");
+            else if (phaseRef.current === "error" || phaseRef.current === "idle")
+                setPhase("loading");
+            if (!quiet)
+                setError(null);
+            setTypingState(NOT_TYPING);
+            setSending(false);
+            status("connecting");
+            const cfg = cached ?? await (0, client_1.fetchWidgetConfig)(baseUrl, tenantKey, controller.signal);
+            if (!alive())
+                return;
+            configCache.current = { key: cacheKey, config: cfg };
+            setConfig(cfg);
+            if (!loadedStorage.current) {
+                loadedStorage.current = true;
+                try {
+                    let stored = await sessionStorage?.load(scope);
+                    // Stored by 0.2.0 under a key that held the contact details: move it to the current key.
+                    const legacy = legacySessionScope(baseUrl, tenantKey, contact.current, callbacks.current.sessionKey);
+                    if (!stored && sessionStorage && legacy !== scope) {
+                        stored = await sessionStorage.load(legacy);
+                        if (stored) {
+                            await sessionStorage.save(scope, stored);
+                            await sessionStorage.remove(legacy);
+                        }
+                    }
+                    if (!alive())
+                        return;
+                    if (stored && typeof stored.conversationId === "string" && typeof stored.sessionToken === "string" &&
+                        /^[a-f0-9]{64}$/.test(stored.sessionToken))
+                        session.current = stored;
+                }
+                catch {
+                    storageFailure();
+                }
+            }
+            if (!alive())
+                return;
+            // A 409 on resume means the team closed it: its history is shown read-only when the server still
+            // lets this session read it (a rating card can arrive after the close); otherwise it is forgotten.
+            let resumedClosed = false;
+            if (session.current) {
+                try {
+                    session.current = await (0, client_1.createConversation)(baseUrl, tenantKey, contact.current, session.current, controller.signal);
+                }
+                catch (failure) {
+                    if (!alive())
+                        return;
+                    const error = (0, errors_1.chatError)(failure);
+                    if (error.code === "conversation_closed" && error.status === 409)
+                        resumedClosed = true;
+                    else {
+                        if (error.code !== "invalid_session" && error.code !== "conversation_closed" && error.status !== 404)
+                            throw error;
+                        await clearSession();
+                    }
+                }
+            }
+            if (!alive())
+                return;
+            // Hidden and nothing to resume: wait until the chat is opened instead of starting a conversation.
+            if (!visibleRef.current && !session.current) {
+                settled();
+                setPhase("idle");
+                status("disconnected");
+                return;
+            }
+            const missing = missingContactFields(cfg.requestUserInfo, contact.current);
+            setRequiredFields(missing);
+            if (!session.current && Object.keys(missing).length) {
+                settled();
+                setPhase("pre-chat");
+                status("disconnected");
+                return;
+            }
+            if (!session.current && !startNow.current) {
+                settled();
+                setPhase("ready");
+                status("disconnected");
+                return;
+            }
+            if (!autoRetry.current.auto || phaseRef.current !== "error")
+                setPhase("connecting");
+            if (!session.current) {
+                const created = await (0, client_1.createConversation)(baseUrl, tenantKey, contact.current, undefined, controller.signal);
+                if (!alive())
+                    return;
+                startNow.current = false;
+                session.current = created;
+                try {
+                    await sessionStorage?.save(scope, created);
+                }
+                catch {
+                    storageFailure();
+                }
+                if (!alive())
+                    return;
+                try {
+                    callbacks.current.onConversationStart?.(created.conversationId);
+                }
+                catch { /* Host callback. */ }
+                // A new conversation for the same visitor (the team closed the last one): the device is registered again.
+                if (lastPush.current && !pushRequest.current)
+                    pushRequest.current = { ...lastPush.current, resolve: () => { } };
+            }
+            if (!alive() || !session.current)
+                return;
+            const activeSession = session.current;
+            setHasConversation(true);
+            // The outbox goes out after the history catch-up, in the protocol's order.
+            connection = new client_1.ChatClient({ baseUrl, tenantKey, outbox, flushOnOpen: false });
+            client.current = connection;
+            let openedOnce = false;
+            connection.onMessage((message) => {
+                if (!alive())
+                    return;
+                setMessages((previous) => mergeMessages(previous, [message]));
+                if (message.role === "agent") {
+                    setTypingState(NOT_TYPING);
+                    if (!message.isBot && !message.isAutomated && message.senderName?.trim()) {
+                        setCurrentAgent({ name: message.senderName.trim(), avatar: message.senderAvatar ?? null });
+                    }
+                    if (!visibleRef.current)
+                        setUnreadCount((count) => count + 1);
+                    setLastIncoming(message);
+                }
+            });
+            connection.onAck((clientMessageId, message) => {
+                if (!alive())
+                    return;
+                setMessages((previous) => mergeMessages(previous, [{ ...message, clientMessageId }]));
+            });
+            connection.onStream((event) => {
+                if (!alive())
+                    return;
+                setDrafts((current) => {
+                    if (event.end) {
+                        if (!(event.streamId in current))
+                            return current;
+                        const next = { ...current };
+                        delete next[event.streamId];
+                        return next;
+                    }
+                    return { ...current, [event.streamId]: { content: event.content, createdAt: current[event.streamId]?.createdAt ?? Date.now() } };
+                });
+                if (!event.end && event.content)
+                    setTypingState(NOT_TYPING);
+            });
+            connection.onAttachmentAccess((value) => { if (alive())
+                captureAccess(value); });
+            // A card was answered or changed on another device, or replaced by a newer one.
+            connection.onRating((frame) => { if (alive())
+                setMessages((previous) => (0, rating_1.patchRating)(previous, frame)); });
+            // The team closed or reopened the conversation: the switch is immediate (older servers send no status).
+            connection.onConversationState((state) => {
+                if (!alive())
+                    return;
+                if (state.status === "closed") {
+                    setClosed(true);
+                    setTypingState(NOT_TYPING);
+                    setDrafts({});
+                    setError(null);
+                    setPhase("active");
+                }
+                else if (state.status === "open") {
+                    if (closedRef.current)
+                        setClosed(false);
+                    connection?.flush();
+                }
+            });
+            // A stop from the other sender (person or GiovBot) keeps the indicator that is showing.
+            connection.onTyping((active, isBot) => {
+                if (alive())
+                    setTypingState((current) => (0, identity_1.reduceAgentTyping)(current, { type: active ? "typing" : "typing_end", role: "agent", isBot }));
+            });
+            connection.onError((failure) => {
+                if (!alive())
+                    return;
+                report(failure);
+                if (failure.code === "conversation_closed") {
+                    void forgetConversation();
+                    return;
+                }
+                if (failure.code === "invalid_session") {
+                    void endSession(failure);
+                    return;
+                }
+                setError(failure);
+            });
+            // Catch-up: history merged by id with what arrived meanwhile, then the outbox is resent.
+            const refreshHistory = async () => {
+                let history;
+                try {
+                    history = await (0, client_1.fetchConversationHistory)(baseUrl, tenantKey, activeSession, controller.signal);
+                }
+                catch (failure) {
+                    const error = (0, errors_1.chatError)(failure);
+                    if (error.status === 404) {
+                        await forgetConversation();
+                        return;
+                    }
+                    // A closed conversation this server will not let us read any more: forget it, as before.
+                    if (resumedClosed && (error.code === "invalid_session" || error.status === 403)) {
+                        await forgetConversation();
+                        return;
+                    }
+                    if (error.code === "invalid_session") {
+                        await endSession(error);
+                        return;
+                    }
+                    throw failure;
+                }
+                if (!alive())
+                    return;
+                captureAccess(history.attachmentAccess);
+                setCurrentAgent({ name: history.assignedAgentName ?? null, avatar: history.assignedAgentAvatar ?? null });
+                setMessages((previous) => mergeMessages(previous, history.messages));
+                if (history.closed) {
+                    // Read-only from here on: the history stays visible and a rating card stays answerable.
+                    setClosed(true);
+                    setTypingState(NOT_TYPING);
+                    setDrafts({});
+                    setError(null);
+                    setPhase("active");
+                    return;
+                }
+                if (closedRef.current)
+                    setClosed(false);
+                connection?.flush();
+            };
+            catchUp.current = refreshHistory;
+            connection.onStatusChange((connected) => {
+                if (!alive())
+                    return;
+                if (!connected) {
+                    setTypingState(NOT_TYPING);
+                    // A reply being written is lost with the socket; the saved copy arrives with the catch-up.
+                    setDrafts({});
+                }
+                status(connected ? "connected" : "disconnected");
+                if (connected)
+                    settled();
+                if (connected || phaseRef.current !== "error")
+                    setPhase(connected ? "active" : "connecting");
+                if (connected) {
+                    setError(null);
+                    // Catch up on whatever arrived while the socket was down.
+                    if (openedOnce)
+                        void refreshHistory().catch((failure) => {
+                            if (!alive())
+                                return;
+                            report((0, errors_1.chatError)(failure));
+                            setError((0, errors_1.chatError)(failure));
+                            // Without the catch-up the outbox still goes out on this socket, rather than waiting for the next one.
+                            connection?.flush();
+                        });
+                    openedOnce = true;
+                    const push = pushRequest.current;
+                    if (push && connection) {
+                        pushRequest.current = null;
+                        void connection.registerPushToken(push.token, push.platform, push.options).then(push.resolve);
+                    }
+                }
+            });
+            try {
+                await connection.connect(activeSession);
+            }
+            catch (failure) {
+                if (!resumedClosed)
+                    throw failure; /* The history below decides whether it can be shown. */
+            }
+            if (!alive())
+                return;
+            await refreshHistory();
+        }
+        // Started for good: later failures retry from the first backoff step.
+        function settled() { autoRetry.current.failures = 0; autoRetry.current.auto = false; }
+        void start().catch((failure) => {
+            if (!alive())
+                return;
+            abort();
+            const error = (0, errors_1.chatError)(failure);
+            if (error.code === "invalid_session")
+                void clearSession();
+            if (error.code === "identity_rejected") {
+                // No conversation can start for this identity: a registration waiting for one ends here.
+                pushRequest.current?.resolve({ registered: false, reason: "no_conversation" });
+                pushRequest.current = null;
+            }
+            setError(error);
+            setPhase("error");
+            status("disconnected");
+            report(error);
+            // A first connection that fails retries with the protocol's backoff while the error shows, as the web widget does.
+            if (!NO_AUTO_RETRY.has(error.code)) {
+                const retrying = autoRetry.current;
+                if (retrying.timer)
+                    clearTimeout(retrying.timer);
+                retrying.timer = setTimeout(() => {
+                    retrying.timer = null;
+                    retrying.auto = true;
+                    setAttempt((value) => value + 1);
+                }, (0, client_1.reconnectDelay)(retrying.failures++));
+            }
+        });
+        return () => {
+            abort();
+            status("disconnected");
+            if (autoRetry.current.timer)
+                clearTimeout(autoRetry.current.timer);
+            autoRetry.current.timer = null;
+        };
+    }, [tenantKey, baseUrl, wantConnection, attempt, scope, sessionStorage, outbox, report, status, captureAccess]);
+    const retry = (0, react_1.useCallback)(() => {
+        autoRetry.current = { ...autoRetry.current, failures: 0, auto: false };
+        setAttempt((value) => value + 1);
+    }, []);
+    const submitContact = (0, react_1.useCallback)((info) => {
+        contact.current = { ...contact.current, ...info };
+        startNow.current = true;
+        retry();
+    }, [retry]);
+    const reset = (0, react_1.useCallback)(async () => {
+        generation.current++;
+        stopTyping();
+        client.current?.disconnect();
+        client.current = null;
+        catchUp.current = null;
+        session.current = null;
+        contact.current = callbacks.current.contact;
+        loadedStorage.current = true;
+        outbox.clear();
+        localFiles.current.clear();
+        announcedRatings.current.clear();
+        setClosed(false);
+        startNow.current = false;
+        // Sign-out: the next visitor's conversation must not get this device's notifications.
+        lastPush.current = null;
+        pushRequest.current?.resolve({ registered: false, reason: "no_conversation" });
+        pushRequest.current = null;
+        setHasConversation(false);
+        setMessages([]);
+        setDrafts({});
+        setTypingState(NOT_TYPING);
+        setCurrentAgent({ name: null, avatar: null });
+        setAccess(null);
+        setUnreadCount(0);
+        setError(null);
+        try {
+            await sessionStorage?.remove(scope);
+        }
+        catch {
+            report(new errors_1.GiovChatError("storage", "Saved chat session could not be cleared."));
+        }
+        retry();
+    }, [sessionStorage, scope, report, retry, outbox, stopTyping]);
+    /**
+     * Leaves the closed conversation: it is cleared (messages, stored session) and the chat is ready for
+     * a new one, which starts with the visitor's next message. Contact details, the outbox and the push
+     * token are kept. Does nothing while the conversation is open.
+     */
+    const startNew = (0, react_1.useCallback)(async () => {
+        if (!closedRef.current)
+            return;
+        generation.current++;
+        stopTyping();
+        client.current?.disconnect();
+        client.current = null;
+        catchUp.current = null;
+        session.current = null;
+        startNow.current = false;
+        announcedRatings.current.clear();
+        setClosed(false);
+        setHasConversation(false);
+        setMessages([]);
+        setDrafts({});
+        setTypingState(NOT_TYPING);
+        setCurrentAgent({ name: null, avatar: null });
+        setError(null);
+        try {
+            await sessionStorage?.remove(scope);
+        }
+        catch {
+            report(new errors_1.GiovChatError("storage", "Saved chat session could not be cleared."));
+        }
+        retry();
+    }, [sessionStorage, scope, report, retry, stopTyping]);
+    /**
+     * Sends text and files. Files upload first (they need the conversation); the message then waits in
+     * the outbox until a socket takes it, so text typed while reconnecting is never lost. Several
+     * files go as one message each after the text, as in the widget. Resolves false when nothing was
+     * queued (empty, or an upload failed).
+     */
+    const send = (0, react_1.useCallback)(async (text, files = []) => {
+        const trimmed = text.trim();
+        if (!trimmed && !files.length)
+            return false;
+        const current = phaseRef.current;
+        if (closedRef.current)
+            return false;
+        if (current !== "active" && current !== "connecting" && current !== "ready")
+            return false;
+        // Uploads need a live conversation; the attach button only appears once one exists.
+        if (files.length && !session.current)
+            return false;
+        const currentGeneration = generation.current;
+        stopTyping();
+        setError(null);
+        const urls = [];
+        if (files.length) {
+            const activeClient = client.current;
+            if (!activeClient) {
+                setError(new errors_1.GiovChatError("disconnected", "Chat is reconnecting. Please try again."));
+                return false;
+            }
+            setSending(true);
+            setUploads(files.map((file) => ({ name: file.name, progress: 0 })));
+            try {
+                for (const [index, file] of files.entries()) {
+                    const result = await activeClient.uploadAttachment(file, (progress) => {
+                        if (generation.current === currentGeneration)
+                            setUploads((current) => current.map((item, i) => i === index ? { ...item, progress } : item));
+                    });
+                    const preview = result.preview ?? (file.width && file.height ? { width: file.width, height: file.height } : undefined);
+                    localFiles.current.set(result.url, { filename: result.filename || file.name, contentType: file.type, ...(preview ? { preview } : {}) });
+                    urls.push(result.url);
+                }
+            }
+            catch (failure) {
+                if (generation.current === currentGeneration) {
+                    const cause = (0, errors_1.chatError)(failure);
+                    // The conversation or the session is gone: the same handling as on the socket.
+                    if (cause.code === "conversation_closed") {
+                        report(cause);
+                        void sessionEnded.current?.forget();
+                        return false;
+                    }
+                    if (cause.code === "invalid_session") {
+                        report(cause);
+                        void sessionEnded.current?.end(cause);
+                        return false;
+                    }
+                    // Rate limits, server and network failures keep their code (and Retry-After) for the host;
+                    // the visitor reads that the upload failed.
+                    report(cause.code === "upload_failed" ? cause : new errors_1.GiovChatError(cause.code, "File upload failed.", cause.status, cause.retryAfterSeconds));
+                    setError(new errors_1.GiovChatError("upload_failed", "File upload failed.", cause.status, cause.retryAfterSeconds));
+                }
+                return false;
+            }
+            finally {
+                if (generation.current === currentGeneration) {
+                    setSending(false);
+                    setUploads([]);
+                }
+            }
+            if (generation.current !== currentGeneration)
+                return false;
+        }
+        const parts = urls.length > 1
+            ? [...(trimmed ? [{ content: trimmed, attachments: [] }] : []), ...urls.map((url) => ({ content: "", attachments: [url] }))]
+            : [{ content: trimmed, attachments: urls }];
+        try {
+            for (const part of parts)
+                outbox.enqueue(part.content, part.attachments);
+        }
+        catch (failure) {
+            const failed = (0, errors_1.chatError)(failure);
+            report(failed);
+            setError(failed);
+            return false;
+        }
+        if (session.current)
+            client.current?.flush();
+        else if (!startNow.current) {
+            // The first message starts the conversation; it goes out once the socket is open.
+            startNow.current = true;
+            setAttempt((value) => value + 1);
+        }
+        return true;
+    }, [outbox, report, stopTyping]);
+    /** Tries a failed message again; it is sent in its original place in the queue. */
+    const retryMessage = (0, react_1.useCallback)((clientMessageId) => {
+        if (outbox.retry(clientMessageId))
+            client.current?.flush();
+    }, [outbox]);
+    const discardMessage = (0, react_1.useCallback)((clientMessageId) => { outbox.remove(clientMessageId); }, [outbox]);
+    /** Call on every keystroke: the agent sees "typing" once per burst and it ends after a pause. */
+    const notifyTyping = (0, react_1.useCallback)(() => {
+        const activeClient = client.current;
+        if (!activeClient?.isConnected)
+            return;
+        const state = typing.current;
+        if (!state.active) {
+            activeClient.sendTyping();
+            state.active = true;
+        }
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = setTimeout(() => { state.timer = null; state.active = false; client.current?.sendTypingEnd(); }, TYPING_IDLE_MS);
+    }, []);
+    /** Registers now when connected, or once the conversation connects. Never throws. */
+    const registerPushToken = (0, react_1.useCallback)((token, platform, options) => {
+        lastPush.current = { token, platform, options };
+        const activeClient = client.current;
+        if (activeClient?.isConnected)
+            return activeClient.registerPushToken(token, platform, options);
+        return new Promise((resolve) => {
+            pushRequest.current?.resolve({ registered: false, reason: "failed" });
+            pushRequest.current = { token, platform, options, resolve };
+        });
+    }, []);
+    /** Stops push for this device; a registration still waiting for the connection is dropped. Never throws. */
+    const unregisterPushToken = (0, react_1.useCallback)(async (token) => {
+        if (pushRequest.current?.token === token) {
+            pushRequest.current.resolve({ registered: false, reason: "failed" });
+            pushRequest.current = null;
+        }
+        if (lastPush.current?.token === token)
+            lastPush.current = null;
+        // While the chat is closed or hidden there is no connection: the stored session is enough.
+        let stored = session.current;
+        if (!stored && !loadedStorage.current) {
+            try {
+                const loaded = await sessionStorage?.load(scope);
+                if (loaded && typeof loaded.conversationId === "string" && /^[a-f0-9]{64}$/.test(String(loaded.sessionToken)))
+                    stored = loaded;
+            }
+            catch { /* Nothing stored that can be used. */ }
+        }
+        if (client.current)
+            return client.current.unregisterPushToken(token, stored);
+        return stored ? (0, client_1.unregisterPushToken)(baseUrl, tenantKey, stored, token) : false;
+    }, [baseUrl, tenantKey, scope, sessionStorage]);
+    (0, react_1.useEffect)(() => () => {
+        if (typing.current.timer)
+            clearTimeout(typing.current.timer);
+        pushRequest.current?.resolve({ registered: false, reason: "no_conversation" });
+        pushRequest.current = null;
+    }, []);
+    const noteUnsupported = (0, react_1.useCallback)((failure) => { if (failure.code === "unsupported")
+        setRatingsSupported(false); }, []);
+    /**
+     * Rates the conversation. `requestId` defaults to the open card (the server picks it when none is
+     * known). Rejects with a `GiovChatError` (`rating_closed`, `request_replaced`, `too_many_changes`,
+     * `invalid_rating`, `rate_limited`, `unsupported`, ...). The card on screen is patched on success and
+     * made read-only or hidden when the server says it is closed or replaced.
+     */
+    const submitRating = (0, react_1.useCallback)(async (score, options = {}) => {
+        const activeClient = client.current;
+        if (!activeClient)
+            throw new errors_1.GiovChatError("disconnected", "Chat is not connected.");
+        const requestId = options.requestId ?? (0, rating_1.pendingRatingRequest)(messagesRef.current, Date.now())?.requestId;
+        try {
+            const result = await activeClient.submitRating(score, { comment: options.comment, requestId });
+            setMessages((previous) => (0, rating_1.patchRating)(previous, { requestId: result.requestId, closesAt: result.closesAt, score: result.score, comment: result.comment }));
+            try {
+                callbacks.current.onRatingSubmitted?.(result);
+            }
+            catch { /* Host callbacks are isolated. */ }
+            return result;
+        }
+        catch (failure) {
+            const error = (0, errors_1.chatError)(failure);
+            noteUnsupported(error);
+            if (requestId && error.code === "rating_closed")
+                setMessages((previous) => (0, rating_1.markRating)(previous, requestId, "closed"));
+            if (requestId && error.code === "request_replaced")
+                setMessages((previous) => (0, rating_1.markRating)(previous, requestId, "replaced"));
+            throw error;
+        }
+    }, [noteUnsupported]);
+    /** Thumbs on a GiovBot answer, shown at once and taken back if the server refuses. `none` removes the vote. */
+    const submitAnswerFeedback = (0, react_1.useCallback)(async (messageId, value, options = {}) => {
+        const activeClient = client.current;
+        if (!activeClient)
+            throw new errors_1.GiovChatError("disconnected", "Chat is not connected.");
+        const before = messagesRef.current.find((message) => message.id === messageId)?.feedback ?? "none";
+        setMessages((previous) => (0, rating_1.applyFeedback)(previous, messageId, value));
+        try {
+            await activeClient.submitAnswerFeedback(messageId, value, options);
+        }
+        catch (failure) {
+            const error = (0, errors_1.chatError)(failure);
+            noteUnsupported(error);
+            setMessages((previous) => (0, rating_1.applyFeedback)(previous, messageId, before));
+            throw error;
+        }
+        try {
+            callbacks.current.onAnswerFeedback?.({ messageId, value, ...(value === "down" && options.reason?.trim() ? { reason: options.reason.trim() } : {}) });
+        }
+        catch { /* Host callbacks are isolated. */ }
+    }, [noteUnsupported]);
+    const describe = (0, react_1.useCallback)((url) => localFiles.current.get(url) ?? { filename: "" }, []);
+    // An older card the visitor never answered gives way to a newer one at once.
+    const shown = (0, react_1.useMemo)(() => (0, rating_1.supersedeRatings)(displayMessages(messages, pending, drafts, describe)), [messages, pending, drafts, describe]);
+    const ratingRequest = (0, react_1.useMemo)(() => (0, rating_1.pendingRatingRequest)(messages, Date.now()), [messages, clock]); // eslint-disable-line react-hooks/exhaustive-deps
+    // The card closes by the clock: look again at `closesAt`.
+    (0, react_1.useEffect)(() => {
+        if (!ratingRequest)
+            return;
+        const wait = ratingRequest.closesAt - Date.now();
+        if (wait <= 0)
+            return;
+        const timer = setTimeout(() => setClock((value) => value + 1), Math.min(wait + 50, 2 ** 31 - 1));
+        return () => clearTimeout(timer);
+    }, [ratingRequest]);
+    // "Rating requested" once per card the visitor has not answered.
+    (0, react_1.useEffect)(() => {
+        if (!ratingRequest || ratingRequest.answered || announcedRatings.current.has(ratingRequest.requestId))
+            return;
+        announcedRatings.current.add(ratingRequest.requestId);
+        try {
+            callbacks.current.onRatingRequested?.(ratingRequest);
+        }
+        catch { /* Host callbacks are isolated. */ }
+    }, [ratingRequest]);
+    // A conversation open for a long time: without a usable access token, images fall back to the
+    // 15-minute visitor token. Renew it when messages arrive and it is close to expiry, at most once a
+    // minute (the web widget's rule); the new URLs make failed images load again.
+    (0, react_1.useEffect)(() => {
+        const activeClient = client.current;
+        const now = Date.now();
+        if (!activeClient || (0, attachments_1.usableAttachmentToken)(access, now))
+            return;
+        if (activeClient.visitorTokenExpiresAt - now > 2 * 60000 || now - lastTokenRenewal.current < 60000)
+            return;
+        lastTokenRenewal.current = now;
+        void activeClient.renewVisitorToken().then((renewed) => { if (renewed)
+            setTokenVersion((value) => value + 1); });
+    }, [messages, access]);
+    const attachmentUrl = (0, react_1.useCallback)((url) => (0, attachments_1.attachmentDisplayUrl)(url, (0, attachments_1.usableAttachmentToken)(access, Date.now()), client.current?.visitorToken), 
+    // tokenVersion: a renewed visitor token changes the URLs.
+    [access, tokenVersion]);
+    return {
+        phase, config, messages: shown, agentTyping: typingState.visible, agentTypingIsBot: typingState.visible ? typingState.isBot : undefined, error, sending, uploads, requiredFields, hasConversation,
+        currentAgentName: currentAgent.name, currentAgentAvatar: currentAgent.avatar, unreadCount: visible ? 0 : unreadCount,
+        lastIncoming,
+        retry, reset, submitContact, send, retryMessage, discardMessage, notifyTyping, attachmentUrl, registerPushToken, unregisterPushToken,
+        ratingRequest, ratingsSupported, submitRating, submitAnswerFeedback,
+        closed, startNew,
+    };
+}
+//# sourceMappingURL=useChatSession.js.map