@giovchat/react-native 0.0.0-stage → 0.2.0

package/src/useChatSession.ts

@@ -0,0 +1,695 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AppState } from "react-native";
+import {
+  ChatClient, createConversation, fetchConversationHistory, fetchWidgetConfig, reconnectDelay, unregisterPushToken as unregisterStoredPushToken,
+  type GiovPushOptions, type GiovPushPlatform, type GiovPushRegistration,
+} from "./client";
+import { reduceAgentTyping, type AgentTypingState } from "./identity";
+import { chatError, GiovChatError } from "./errors";
+import { Outbox, type OutboxEntry } from "./outbox";
+import {
+  attachmentDisplayUrl,
+  newerAttachmentAccess,
+  usableAttachmentToken,
+  type AttachmentAccess,
+  type GiovAttachment,
+  type GiovAttachmentPreview,
+  type GiovChatPickedFile,
+} from "./attachments";
+import type { GiovChatConnectionStatus, GiovChatContact, GiovChatSession, GiovChatSessionStorage, GiovMessage, GiovWidgetConfig, RequestUserInfo } from "./types";
+
+export function missingContactFields(fields: RequestUserInfo = {}, contact: GiovChatContact = {}): RequestUserInfo {
+  const missing: RequestUserInfo = {};
+  for (const field of ["email", "phone", "firstName", "lastName"] as const) {
+    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.
+ */
+export function sessionScope(baseUrl: string, tenantKey: string, contact?: GiovChatContact, sessionKey?: string | number): string {
+  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. */
+export function legacySessionScope(baseUrl: string, tenantKey: string, contact?: GiovChatContact, sessionKey?: string | number): string {
+  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. */
+export function mergeMessages(current: GiovMessage[], incoming: GiovMessage[]): GiovMessage[] {
+  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. */
+export function displayMessages(
+  saved: GiovMessage[], pending: readonly OutboxEntry[], drafts: Readonly<Record<string, { content: string; createdAt: number }>>,
+  describe: (url: string) => Omit<GiovAttachment, "url"> = () => ({ filename: "" }),
+): GiovMessage[] {
+  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));
+}
+
+type Options = {
+  tenantKey: string; baseUrl: string; visible: boolean; contact?: GiovChatContact;
+  scope: string; sessionStorage?: GiovChatSessionStorage;
+  /** The host's `sessionKey`, for reading a session stored under the 0.2.0 key. */
+  sessionKey?: string | number;
+  /** Stay connected while hidden (app in the foreground) to count unread replies. Never starts a conversation. */
+  keepConnected?: boolean;
+  /** How long the app may be in the background before the socket closes (so the server pushes replies). */
+  backgroundGraceMs?: number;
+  onError?: (error: GiovChatError) => void;
+  onConnectionStatusChange?: (status: GiovChatConnectionStatus) => void;
+  onConversationStart?: (conversationId: string) => void;
+  onUnreadCountChange?: (count: number) => void;
+};
+
+/**
+ * `ready`: the chat can be used but no conversation exists yet. Per the visitor protocol a native
+ * client starts one when the visitor sends the first message (or submits the pre-chat form), so
+ * opening the screen never creates an empty conversation. `idle`: hidden with nothing to resume.
+ */
+export type ChatPhase = "idle" | "loading" | "pre-chat" | "ready" | "connecting" | "active" | "error";
+export type UploadProgress = { name: string; progress: number };
+
+/** 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. */
+export const BACKGROUND_GRACE_MS = 5000;
+const NOT_TYPING: AgentTypingState = { 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"]);
+
+export function useChatSession(options: Options) {
+  const { tenantKey, baseUrl, visible, scope, sessionStorage } = options;
+  const callbacks = useRef(options);
+  callbacks.current = options;
+  const contact = useRef(options.contact);
+  const session = useRef<GiovChatSession | null>(null);
+  const loadedStorage = useRef(false);
+  // Set by the first message or the pre-chat form: the next start creates the conversation.
+  const startNow = useRef(false);
+  const client = useRef<ChatClient | null>(null);
+  const generation = useRef(0);
+  const outboxRef = useRef<Outbox | null>(null);
+  outboxRef.current ??= new Outbox();
+  const outbox = outboxRef.current;
+  const visibleRef = useRef(visible);
+  visibleRef.current = visible;
+  // Files sent from this device: names and types the server's copy does not carry.
+  const localFiles = useRef(new Map<string, Omit<GiovAttachment, "url">>());
+  const pushRequest = useRef<{ token: string; platform: GiovPushPlatform; options?: GiovPushOptions; resolve: (value: GiovPushRegistration) => void } | null>(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 = useRef<{ token: string; platform: GiovPushPlatform; options?: GiovPushOptions } | null>(null);
+  // Failed starts retried with the protocol's backoff; `auto` while such a retry runs.
+  const autoRetry = useRef<{ failures: number; timer: ReturnType<typeof setTimeout> | null; auto: boolean }>({ failures: 0, timer: null, auto: false });
+  const lastTokenRenewal = useRef(0);
+  const sessionEnded = useRef<{ forget: () => Promise<void>; end: (failure: GiovChatError) => Promise<void> } | null>(null);
+  const typing = useRef<{ active: boolean; timer: ReturnType<typeof setTimeout> | null }>({ active: false, timer: null });
+  const configCache = useRef<{ key: string; config: GiovWidgetConfig } | null>(null);
+  // The current connection's history catch-up, for a quick return from the background.
+  const catchUp = useRef<(() => Promise<void>) | null>(null);
+  const [attempt, setAttempt] = useState(0);
+  const [foreground, setForeground] = useState(AppState.currentState !== "background" && AppState.currentState !== "inactive");
+  const [phase, setPhase] = useState<ChatPhase>("loading");
+  const phaseRef = useRef(phase);
+  phaseRef.current = phase;
+  const [config, setConfig] = useState<GiovWidgetConfig | null>(null);
+  const [messages, setMessages] = useState<GiovMessage[]>([]);
+  const [pending, setPending] = useState<OutboxEntry[]>(() => outbox.list());
+  const [drafts, setDrafts] = useState<Record<string, { content: string; createdAt: number }>>({});
+  const [typingState, setTypingState] = useState<AgentTypingState>(NOT_TYPING);
+  const [tokenVersion, setTokenVersion] = useState(0);
+  // The last reply that arrived live on the socket (not from history), for screen-reader announcements.
+  const [lastIncoming, setLastIncoming] = useState<GiovMessage | null>(null);
+  const [currentAgent, setCurrentAgent] = useState<{ name: string | null; avatar: string | null }>({ name: null, avatar: null });
+  const [access, setAccess] = useState<AttachmentAccess | null>(null);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [error, setError] = useState<GiovChatError | null>(null);
+  const [sending, setSending] = useState(false);
+  const [uploads, setUploads] = useState<UploadProgress[]>([]);
+  const [requiredFields, setRequiredFields] = useState<RequestUserInfo>({});
+  const [hasConversation, setHasConversation] = useState(false);
+  const keepConnected = options.keepConnected === true;
+  const wantConnection = foreground && (visible || keepConnected);
+
+  const report = useCallback((failure: GiovChatError) => {
+    try { callbacks.current.onError?.(failure); } catch { /* Host callbacks are isolated. */ }
+  }, []);
+  const status = useCallback((value: GiovChatConnectionStatus) => {
+    try { callbacks.current.onConnectionStatusChange?.(value); } catch { /* Host callbacks are isolated. */ }
+  }, []);
+  const captureAccess = useCallback((incoming: AttachmentAccess | null | undefined) => {
+    if (incoming) setAccess((current) => newerAttachmentAccess(current, incoming));
+  }, []);
+  const stopTyping = useCallback(() => {
+    const state = typing.current;
+    if (state.timer) clearTimeout(state.timer);
+    state.timer = null;
+    if (state.active) client.current?.sendTypingEnd();
+    state.active = false;
+  }, []);
+
+  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 = useRef(contactKey);
+  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.
+  useEffect(() => {
+    const grace = callbacks.current.backgroundGraceMs ?? BACKGROUND_GRACE_MS;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let since: number | null = null;
+    const subscription = 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(() => { /* The next reconnect catches up. */ });
+      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.
+  useEffect(() => {
+    if (!visible) return;
+    setUnreadCount(0);
+    if (keepConnected && phaseRef.current === "idle") setAttempt((value) => value + 1);
+  }, [visible, keepConnected]);
+
+  useEffect(() => {
+    try { callbacks.current.onUnreadCountChange?.(unreadCount); } catch { /* Host callbacks are isolated. */ }
+  }, [unreadCount]);
+
+  useEffect(() => {
+    const currentGeneration = ++generation.current;
+    if (!wantConnection) {
+      setTypingState(NOT_TYPING);
+      setDrafts({});
+      status("disconnected");
+      return;
+    }
+    let cancelled = false;
+    const controller = new AbortController();
+    let connection: ChatClient | null = 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 GiovChatError("storage", "Chat session could not be saved or restored."));
+    const clearSession = async () => {
+      session.current = null;
+      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: GiovChatError) => {
+      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 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 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;
+      if (session.current) {
+        try { session.current = await createConversation(baseUrl, tenantKey, contact.current, session.current, controller.signal); }
+        catch (failure) {
+          if (!alive()) return;
+          const error = chatError(failure);
+          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 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 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 stop from the other sender (person or GiovBot) keeps the indicator that is showing.
+      connection.onTyping((active, isBot) => {
+        if (alive()) setTypingState((current) => 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 fetchConversationHistory(baseUrl, tenantKey, activeSession, controller.signal); }
+        catch (failure) {
+          const error = chatError(failure);
+          if (error.status === 404) { await forgetConversation(); return; }
+          if (error.code === "invalid_session") { await endSession(error); return; }
+          throw failure;
+        }
+        if (!alive()) return;
+        if (history.closed) { await forgetConversation(); return; }
+        captureAccess(history.attachmentAccess);
+        setCurrentAgent({ name: history.assignedAgentName ?? null, avatar: history.assignedAgentAvatar ?? null });
+        setMessages((previous) => mergeMessages(previous, history.messages));
+        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(chatError(failure));
+            setError(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);
+          }
+        }
+      });
+      await connection.connect(activeSession);
+      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 = 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);
+        }, 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 = useCallback(() => {
+    autoRetry.current = { ...autoRetry.current, failures: 0, auto: false };
+    setAttempt((value) => value + 1);
+  }, []);
+  const submitContact = useCallback((info: GiovChatContact) => {
+    contact.current = { ...contact.current, ...info };
+    startNow.current = true;
+    retry();
+  }, [retry]);
+  const reset = 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();
+    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 GiovChatError("storage", "Saved chat session could not be cleared.")); }
+    retry();
+  }, [sessionStorage, scope, report, retry, outbox, 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 = useCallback(async (text: string, files: readonly GiovChatPickedFile[] = []): Promise<boolean> => {
+    const trimmed = text.trim();
+    if (!trimmed && !files.length) return false;
+    const current = phaseRef.current;
+    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: string[] = [];
+    if (files.length) {
+      const activeClient = client.current;
+      if (!activeClient) {
+        setError(new 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: GiovAttachmentPreview | undefined = 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 = 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 GiovChatError(cause.code, "File upload failed.", cause.status, cause.retryAfterSeconds));
+          setError(new 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: [] as string[] }] : []), ...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 = 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 = useCallback((clientMessageId: string) => {
+    if (outbox.retry(clientMessageId)) client.current?.flush();
+  }, [outbox]);
+  const discardMessage = useCallback((clientMessageId: string) => { outbox.remove(clientMessageId); }, [outbox]);
+
+  /** Call on every keystroke: the agent sees "typing" once per burst and it ends after a pause. */
+  const notifyTyping = 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 = useCallback((token: string, platform: GiovPushPlatform, options?: GiovPushOptions): Promise<GiovPushRegistration> => {
+    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 = useCallback(async (token: string): Promise<boolean> => {
+    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 ? unregisterStoredPushToken(baseUrl, tenantKey, stored, token) : false;
+  }, [baseUrl, tenantKey, scope, sessionStorage]);
+
+  useEffect(() => () => {
+    if (typing.current.timer) clearTimeout(typing.current.timer);
+    pushRequest.current?.resolve({ registered: false, reason: "no_conversation" });
+    pushRequest.current = null;
+  }, []);
+
+  const describe = useCallback((url: string) => localFiles.current.get(url) ?? { filename: "" }, []);
+  const shown = useMemo(() => displayMessages(messages, pending, drafts, describe), [messages, pending, drafts, describe]);
+  // 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.
+  useEffect(() => {
+    const activeClient = client.current;
+    const now = Date.now();
+    if (!activeClient || usableAttachmentToken(access, now)) return;
+    if (activeClient.visitorTokenExpiresAt - now > 2 * 60_000 || now - lastTokenRenewal.current < 60_000) return;
+    lastTokenRenewal.current = now;
+    void activeClient.renewVisitorToken().then((renewed) => { if (renewed) setTokenVersion((value) => value + 1); });
+  }, [messages, access]);
+  const attachmentUrl = useCallback(
+    (url: string) => attachmentDisplayUrl(url, usableAttachmentToken(access, Date.now()), client.current?.visitorToken),
+    // tokenVersion: a renewed visitor token changes the URLs.
+    [access, tokenVersion], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  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,
+  };
+}