@giovchat/react-native 0.0.0-stage → 0.2.0

package/src/client.ts

@@ -0,0 +1,758 @@
+import type { GiovChatContact, GiovChatSession, GiovMessage, GiovWidgetConfig, MessageHandler, StatusHandler } from "./types";
+import { GiovChatError, chatError, retryAfterSeconds } from "./errors";
+import { object, parseMessage } from "./protocol";
+import { safeImageUrl } from "./identity";
+import { deviceLocale } from "./i18n";
+import { Outbox } from "./outbox";
+import {
+  buildUploadForm,
+  normalizeAttachmentPolicy,
+  parseAttachmentAccess,
+  sanitizePreview,
+  type AttachmentAccess,
+  type GiovAttachmentPreview,
+  type GiovChatPickedFile,
+} from "./attachments";
+
+export const DEFAULT_BASE_URL = "https://api.giovchat.app";
+
+/** Keep in step with package.json; sent so the dashboard can show where the chat is installed. */
+export const SDK_VERSION = "0.2.0";
+export const CLIENT_HEADER = { "X-Giov-Client": `react-native/${SDK_VERSION}` };
+
+export function normalizeBaseUrl(value: string): string {
+  const url = new URL(value);
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new GiovChatError("invalid_response", "Use an HTTP(S) API URL without credentials, query parameters or fragments.");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+async function request(baseUrl: string, path: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
+  const controller = new AbortController();
+  let timedOut = false;
+  const abort = () => controller.abort();
+  if (init.signal?.aborted) controller.abort();
+  init.signal?.addEventListener("abort", abort);
+  const timeout = setTimeout(() => { timedOut = true; controller.abort(); }, 15000);
+  try {
+    const response = await fetch(normalizeBaseUrl(baseUrl) + path, { ...init, signal: controller.signal });
+    const data = object(await response.json().catch(() => null));
+    if (!response.ok) {
+      // Protocol v1: 401/403 the session is gone; 409 (or the code) the conversation is closed;
+      // 503 workspace_busy the workspace is at its plan's limit of open conversations; 401
+      // invalid_user_hash the workspace requires a signed identity and userHash is wrong or missing.
+      const code = data.error === "invalid_user_hash" ? "identity_rejected"
+        : response.status === 429 ? "rate_limited"
+        : response.status === 401 || response.status === 403 ? "invalid_session"
+        : response.status === 409 || data.error === "conversation_closed" ? "conversation_closed"
+        : response.status === 503 && data.error === "workspace_busy" ? "workspace_busy" : "server";
+      throw new GiovChatError(code, code === "identity_rejected" ? "This workspace requires a signed visitor identity (userId and userHash)."
+        : code === "invalid_session" ? "Chat session expired. Please start a new chat."
+        : code === "conversation_closed" ? "This conversation has ended."
+        : code === "workspace_busy" ? "The team is busy right now. Please try again later."
+        : code === "rate_limited" ? "Too many requests. Please wait a moment."
+        : "Chat is unavailable. Please try again.", response.status, retryAfterSeconds(response.headers?.get?.("Retry-After")));
+    }
+    return data;
+  } catch (error) {
+    if (init.signal?.aborted) throw new GiovChatError("disconnected", "Chat closed.");
+    if (timedOut) throw new GiovChatError("timeout", "Chat request timed out. Please try again.");
+    throw chatError(error);
+  } finally {
+    clearTimeout(timeout);
+    init.signal?.removeEventListener("abort", abort);
+  }
+}
+
+export async function fetchWidgetConfig(baseUrl: string, tenantKey: string, signal?: AbortSignal): Promise<GiovWidgetConfig> {
+  const data = await request(baseUrl, "/widget/config?tenantId=" + encodeURIComponent(tenantKey), { signal, headers: CLIENT_HEADER });
+  if (typeof data.title !== "string" || typeof data.primaryColor !== "string" ||
+      !["light", "dark", "auto"].includes(String(data.theme))) {
+    throw new GiovChatError("invalid_response", "Invalid widget configuration.");
+  }
+  const fields = object(data.requestUserInfo);
+  const attachments = normalizeAttachmentPolicy(data.attachments);
+  return {
+    title: data.title, primaryColor: data.primaryColor, theme: data.theme as GiovWidgetConfig["theme"],
+    greetingText: typeof data.greetingText === "string" ? data.greetingText : "Hi! How can we help?",
+    textArea: typeof data.textArea === "string" ? data.textArea : undefined,
+    botEnabled: data.botEnabled === true,
+    botName: typeof data.botName === "string" ? data.botName : undefined,
+    botAvatarUrl: safeImageUrl(data.botAvatarUrl) ?? undefined,
+    avatarUrl: typeof data.avatarUrl === "string" ? data.avatarUrl : undefined,
+    showBranding: data.showBranding !== false,
+    requestUserInfo: { email: fields.email === true, phone: fields.phone === true,
+      firstName: fields.firstName === true, lastName: fields.lastName === true },
+    ...(attachments ? { attachments } : {}),
+    ...(privacyPolicyUrl(data.privacyPolicyUrl) ? { privacyPolicyUrl: privacyPolicyUrl(data.privacyPolicyUrl) } : {}),
+  };
+}
+
+/** As the web widget reads it: an https URL without credentials, else nothing. */
+function privacyPolicyUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password ? url.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Creates a credential-bearing visitor session. Resuming requires the entire session. */
+export async function createConversation(
+  baseUrl: string, tenantKey: string, contact?: GiovChatContact,
+  existingSession?: GiovChatSession, signal?: AbortSignal,
+): Promise<GiovChatSession> {
+  const data = await request(baseUrl, "/conversations", {
+    method: "POST", signal,
+    headers: { "Content-Type": "application/json",
+      ...(existingSession ? { Authorization: "Bearer " + existingSession.sessionToken } : {}) },
+    body: JSON.stringify({ tenantId: tenantKey, ...contact, conversationId: existingSession?.conversationId }),
+  });
+  if (typeof data.conversationId !== "string" || !data.conversationId ||
+      typeof data.sessionToken !== "string" || !/^[a-f0-9]{64}$/.test(data.sessionToken)) {
+    throw new GiovChatError("invalid_response", "Invalid chat session response.");
+  }
+  return { conversationId: data.conversationId, sessionToken: data.sessionToken };
+}
+
+/** A short-lived visitor token (the API says 15 minutes) and, when sent, the attachment download token. */
+type WidgetToken = { token: string; expiresAt: number; attachmentAccess: AttachmentAccess | null };
+
+async function fetchWidgetToken(baseUrl: string, tenantKey: string, session: GiovChatSession, signal?: AbortSignal): Promise<WidgetToken> {
+  const data = await request(baseUrl, "/auth/widget-token", {
+    method: "POST", signal,
+    headers: { "Content-Type": "application/json", Authorization: "Bearer " + session.sessionToken },
+    body: JSON.stringify({ tenantId: tenantKey, conversationId: session.conversationId }),
+  });
+  if (typeof data.token !== "string" || !data.token) throw new GiovChatError("invalid_response", "Invalid chat token response.");
+  // The API reports the expiry in seconds; assume a little under 15 minutes when it does not.
+  const expiresAt = typeof data.expiresAt === "number" && Number.isFinite(data.expiresAt) ? data.expiresAt * 1000 : Date.now() + 14 * 60_000;
+  return { token: data.token, expiresAt, attachmentAccess: parseAttachmentAccess(data.attachmentAccess) };
+}
+
+export interface GiovConversationHistory {
+  messages: GiovMessage[];
+  closed: boolean;
+  /** The teammate who has the conversation, when one does; the header shows them. */
+  assignedAgentName?: string | null;
+  assignedAgentAvatar?: string | null;
+  attachmentAccess?: AttachmentAccess | null;
+}
+
+export async function fetchConversationHistory(
+  baseUrl: string, tenantKey: string, session: GiovChatSession, signal?: AbortSignal,
+): Promise<GiovConversationHistory> {
+  const load = async () => {
+    const { token } = await fetchWidgetToken(baseUrl, tenantKey, session, signal);
+    return request(baseUrl, "/conversations/" + encodeURIComponent(session.conversationId) + "/history", {
+      signal, headers: { Authorization: "Bearer " + token },
+    }).catch((error: unknown) => { throw Object.assign(chatError(error), { fromHistory: true }); });
+  };
+  // Protocol "Tokens": a 401 from history renews the visitor token once; a second one (or a 401
+  // from the token route) means the session is gone.
+  const data = await load().catch((error: GiovChatError & { fromHistory?: boolean }) => {
+    if (error.fromHistory && error.status === 401) return load();
+    throw error;
+  });
+  if (!Array.isArray(data.messages)) throw new GiovChatError("invalid_response", "Invalid conversation history.");
+  const assignedAgentName = typeof data.assignedAgentName === "string" ? data.assignedAgentName.trim() || null : null;
+  // History rows carry no sender name; a human reply is shown under the assigned teammate, as in the widget.
+  const messages = data.messages.map(parseMessage).filter((m): m is GiovMessage => m !== null).map((message) =>
+    message.role === "agent" && !message.isBot && !message.isAutomated && !message.senderName && assignedAgentName
+      ? { ...message, senderName: assignedAgentName } : message);
+  return {
+    messages, closed: data.status === "closed",
+    assignedAgentName,
+    assignedAgentAvatar: assignedAgentName ? safeImageUrl(data.assignedAgentAvatar) : null,
+    attachmentAccess: parseAttachmentAccess(data.attachmentAccess),
+  };
+}
+
+export interface ChatClientOptions {
+  baseUrl?: string;
+  tenantKey: string;
+  /**
+   * Messages waiting for the server. Pass one that outlives this client (the chat UI does) so
+   * messages typed while reconnecting or in the background are sent once a socket is back.
+   */
+  outbox?: Outbox;
+  /**
+   * Send the outbox as soon as a socket opens (default). The chat UI turns this off and calls
+   * `flush()` after the history catch-up, in the protocol's order: open, history, merge, resend.
+   */
+  flushOnOpen?: boolean;
+}
+
+/** A GiovBot reply arriving word by word: the whole text so far, then `end` once it is saved or dropped. */
+export type GiovStreamEvent = { streamId: string; content: string; end?: false } | { streamId: string; end: true };
+
+export interface GiovUploadResult {
+  url: string;
+  filename: string;
+  preview?: GiovAttachmentPreview;
+}
+
+export type GiovPushPlatform = "ios" | "android";
+/**
+ * `environment`: APNs only; "sandbox" for development builds (Xcode), "production" (the default) for
+ * TestFlight and the App Store. `appId`: the bundle id or package name. `locale`: the language of the
+ * generic notification text when the workspace hides message text (default: the device language).
+ */
+export type GiovPushOptions = { environment?: "sandbox" | "production"; appId?: string; locale?: string };
+export type GiovPushRegistration = { registered: true } | { registered: false; reason: "unsupported" | "no_conversation" | "failed" };
+/**
+ * Visitor push registration (docs/protocol/README.md, "Push notifications"). Feature-detected: a
+ * server without it answers 404/405/501 and registration degrades to a no-op.
+ */
+export const PUSH_TOKEN_PATH = "/push-token";
+/** BCP 47 tags the server stores with a device ("pt-BR", "fr"); anything else is left out. */
+const PUSH_LOCALE = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8}){0,3}$/;
+
+const SEND_FAILED = "Message could not be sent. Please try again.";
+
+/** Connection timings from the visitor protocol (docs/protocol/README.md). */
+export const OPEN_TIMEOUT_MS = 10_000;
+export const PING_INTERVAL_MS = 25_000;
+export const PONG_TIMEOUT_MS = 10_000;
+/** Retry waits: min(1500 × 2^attempt, 15000) ms plus a little jitter; reset after a successful connect. */
+export function reconnectDelay(attempt: number, jitter = Math.random()): number {
+  return Math.min(1500 * 2 ** attempt, 15000) + Math.floor(jitter * 400);
+}
+
+/** Transport only. Session credentials are never derived from contact information. */
+export class ChatClient {
+  private ws: WebSocket | null = null;
+  private messageCbs = new Set<MessageHandler>();
+  private statusCbs = new Set<StatusHandler>();
+  private typingCbs = new Set<(typing: boolean, isBot?: boolean) => void>();
+  private errorCbs = new Set<(error: GiovChatError) => void>();
+  private ackCbs = new Set<(clientMessageId: string, message: GiovMessage) => void>();
+  private streamCbs = new Set<(event: GiovStreamEvent) => void>();
+  private accessCbs = new Set<(access: AttachmentAccess) => void>();
+  private pending = new Map<string, Array<{ resolve: (message: GiovMessage) => void; reject: (error: GiovChatError) => void }>>();
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeat: ReturnType<typeof setInterval> | null = null;
+  private watchdog: ReturnType<typeof setInterval> | null = null;
+  private resendTimers = new Set<ReturnType<typeof setTimeout>>();
+  private controller: AbortController | null = null;
+  private cancelHandshake: (() => void) | null = null;
+  private generation = 0;
+  private desired = false;
+  private attempt = 0;
+  private session: GiovChatSession | null = null;
+  private widgetToken: WidgetToken | null = null;
+  private tokenRequest: Promise<WidgetToken> | null = null;
+  private pushUnsupported = false;
+  private readonly baseUrl: string;
+  readonly outbox: Outbox;
+
+  constructor(private readonly options: ChatClientOptions) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.outbox = options.outbox ?? new Outbox();
+  }
+
+  onMessage(cb: MessageHandler): () => void { this.messageCbs.add(cb); return () => { this.messageCbs.delete(cb); }; }
+  onStatusChange(cb: StatusHandler): () => void { this.statusCbs.add(cb); return () => { this.statusCbs.delete(cb); }; }
+  /** `isBot` is server-reported identity; undefined means an older/unknown sender. */
+  onTyping(cb: (typing: boolean, isBot?: boolean) => void): () => void { this.typingCbs.add(cb); return () => { this.typingCbs.delete(cb); }; }
+  onError(cb: (error: GiovChatError) => void): () => void { this.errorCbs.add(cb); return () => { this.errorCbs.delete(cb); }; }
+  /** The server saved a visitor message: the stored copy replaces the one shown while sending. */
+  onAck(cb: (clientMessageId: string, message: GiovMessage) => void): () => void { this.ackCbs.add(cb); return () => { this.ackCbs.delete(cb); }; }
+  onStream(cb: (event: GiovStreamEvent) => void): () => void { this.streamCbs.add(cb); return () => { this.streamCbs.delete(cb); }; }
+  /** A newer attachment download token arrived (with a visitor token). */
+  onAttachmentAccess(cb: (access: AttachmentAccess) => void): () => void { this.accessCbs.add(cb); return () => { this.accessCbs.delete(cb); }; }
+  private emit<T>(callbacks: Set<(value: T) => void>, value: T): void {
+    for (const cb of callbacks) { try { cb(value); } catch { /* Host callbacks cannot break transport cleanup. */ } }
+  }
+
+  async connect(session: GiovChatSession): Promise<void> {
+    // Messages already waiting (sendMessage before connect) are kept: they go out on this socket.
+    this.teardown();
+    this.desired = true;
+    this.session = session;
+    this.attempt = 0;
+    await this.open(this.generation);
+  }
+
+  private async token(force = false): Promise<WidgetToken> {
+    const session = this.session;
+    if (!session) throw new GiovChatError("disconnected", "Chat closed.");
+    if (!force && this.widgetToken && this.widgetToken.expiresAt - Date.now() > 60_000) return this.widgetToken;
+    // One request at a time. Teardown forgets it, so the next connection never waits on an aborted one.
+    const generation = this.generation;
+    const pending: Promise<WidgetToken> = this.tokenRequest ??= fetchWidgetToken(this.baseUrl, this.options.tenantKey, session, this.controller?.signal)
+      .then((value) => {
+        if (this.session === session && this.generation === generation) {
+          this.widgetToken = value;
+          if (value.attachmentAccess) this.emit(this.accessCbs, value.attachmentAccess);
+        }
+        return value;
+      })
+      .finally(() => { if (this.tokenRequest === pending) this.tokenRequest = null; });
+    return pending;
+  }
+
+  /** The current visitor token, for attachment downloads when no access token is usable. */
+  get visitorToken(): string | null { return this.widgetToken?.token ?? null; }
+  /** When the current visitor token expires (milliseconds); 0 without one. */
+  get visitorTokenExpiresAt(): number { return this.widgetToken?.expiresAt ?? 0; }
+
+  /**
+   * Fetches a new visitor token (and with it, usually, a newer attachment access token), e.g. before
+   * attachment links that use the visitor token expire. Resolves false when it could not; never throws.
+   */
+  async renewVisitorToken(): Promise<boolean> {
+    if (!this.session) return false;
+    try { await this.token(true); return true; } catch { return false; }
+  }
+
+  private async open(generation: number): Promise<void> {
+    if (!this.desired || !this.session || generation !== this.generation) return;
+    this.controller = new AbortController();
+    const { token } = await this.token(true);
+    if (!this.desired || generation !== this.generation) throw new GiovChatError("disconnected", "Chat closed.");
+    const url = new URL(this.baseUrl + "/conversations/" + encodeURIComponent(this.session.conversationId) + "/ws");
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("token", token);
+    url.searchParams.set("role", "user");
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(url.toString());
+      this.ws = ws;
+      let opened = false;
+      let settled = false;
+      let pongDeadline: ReturnType<typeof setTimeout> | null = null;
+      const finish = (error?: GiovChatError) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        this.cancelHandshake = null;
+        if (error) reject(error); else resolve();
+      };
+      const timeout = setTimeout(() => {
+        finish(new GiovChatError("timeout", "Chat connection timed out."));
+        drop();
+      }, OPEN_TIMEOUT_MS);
+      this.cancelHandshake = () => finish(new GiovChatError("disconnected", "Chat closed."));
+      ws.onopen = () => {
+        if (generation !== this.generation || !this.desired || settled) { ws.close(); return; }
+        opened = true;
+        this.attempt = 0;
+        this.emit(this.statusCbs, true);
+        // A ping every 25 s; no pong within 10 s means the socket is dead.
+        this.heartbeat = setInterval(() => {
+          try { ws.send(JSON.stringify({ type: "ping" })); } catch { drop(); return; }
+          if (pongDeadline) clearTimeout(pongDeadline);
+          pongDeadline = setTimeout(drop, PONG_TIMEOUT_MS);
+        }, PING_INTERVAL_MS);
+        // A message on a socket that never answered means the socket is dead: drop it so the
+        // reconnect resends everything still waiting.
+        this.watchdog = setInterval(() => { if (this.outbox.stale()) drop(); }, 3000);
+        finish();
+        if (this.options.flushOnOpen !== false) this.flush();
+      };
+      ws.onerror = () => {
+        finish(new GiovChatError("connection_failed", "Unable to connect to chat."));
+        ws.close();
+      };
+      // A dead socket can take a minute to report its close (Android's OkHttp waits out the close
+      // handshake), so it is treated as closed at once; its late onclose is then ignored.
+      const drop = () => {
+        try { ws.close(); } catch { /* Already closing. */ }
+        closed();
+      };
+      const closed = (event?: { code?: number; reason?: string }) => {
+        if (pongDeadline) clearTimeout(pongDeadline);
+        pongDeadline = null;
+        if (generation !== this.generation || this.ws !== ws) return;
+        this.ws = null;
+        this.outbox.socketClosed();
+        if (this.heartbeat) clearInterval(this.heartbeat);
+        if (this.watchdog) clearInterval(this.watchdog);
+        this.heartbeat = null;
+        this.watchdog = null;
+        this.emit(this.statusCbs, false);
+        finish(new GiovChatError("connection_failed", "Chat connection closed."));
+        if (event?.code === 1000 && event.reason === "Conversation deleted") {
+          // The conversation is gone: no reconnect; the chat forgets the stored session.
+          this.desired = false;
+          this.emit(this.errorCbs, new GiovChatError("conversation_closed", "This conversation has ended."));
+          return;
+        }
+        if (opened) this.reconnect(generation);
+      };
+      ws.onclose = closed;
+      ws.onmessage = (event) => {
+        if (generation !== this.generation || this.ws !== ws) return;
+        let data: Record<string, unknown>;
+        try { data = object(JSON.parse(String(event.data))); } catch { return; }
+        this.receive(data, () => { if (pongDeadline) clearTimeout(pongDeadline); pongDeadline = null; }, ws);
+      };
+    });
+  }
+
+  private receive(data: Record<string, unknown>, pong: () => void, ws: WebSocket): void {
+    if (data.type === "pong") { pong(); return; }
+    if (data.type === "typing" || data.type === "typing_end") {
+      if (data.role === "agent") {
+        const typing = data.type === "typing";
+        // Kept on typing_end too: a stop from the other sender (person or GiovBot) must not hide the indicator.
+        const isBot = typeof data.isBot === "boolean" ? data.isBot : undefined;
+        for (const cb of this.typingCbs) {
+          try { cb(typing, isBot); } catch { /* Host callbacks cannot break transport cleanup. */ }
+        }
+      }
+      return;
+    }
+    if (data.type === "stream" && typeof data.streamId === "string") {
+      this.emit(this.streamCbs, { streamId: data.streamId, content: typeof data.content === "string" ? data.content : "" });
+      return;
+    }
+    if (data.type === "stream_end" && typeof data.streamId === "string") {
+      this.emit(this.streamCbs, { streamId: data.streamId, end: true });
+      return;
+    }
+    if (data.type === "error") { this.serverError(data, ws); return; }
+    if (data.type === "message_ack" && typeof data.clientMessageId === "string") {
+      const message = parseMessage({ ...object(data.message), role: "visitor" });
+      const entry = this.outbox.acknowledge(data.clientMessageId);
+      if (message) {
+        for (const cb of this.ackCbs) { try { cb(data.clientMessageId, message); } catch { /* Host callbacks cannot break transport cleanup. */ } }
+        this.settle(data.clientMessageId, message);
+      } else if (entry) {
+        this.settle(data.clientMessageId, null);
+      }
+      return;
+    }
+    if (data.type && data.type !== "message") return;
+    const message = parseMessage(data);
+    // The saved reply takes the place of its streamed draft, under the draft's key so it is not redrawn.
+    if (message && typeof data.streamId === "string") message.clientMessageId = `stream:${data.streamId}`;
+    if (message) this.emit(this.messageCbs, message);
+    if (message && typeof data.streamId === "string") this.emit(this.streamCbs, { streamId: data.streamId, end: true });
+  }
+
+  /** Error frames: a save failure names its message; refusals and rate limits apply to what is on the socket. */
+  private serverError(data: Record<string, unknown>, ws: WebSocket): void {
+    if (data.error === "message_failed" && typeof data.clientMessageId === "string") {
+      const outcome = this.outbox.rejected(data.clientMessageId);
+      if (!outcome) return;
+      if (outcome.failed) {
+        this.fail(data.clientMessageId);
+        this.emit(this.errorCbs, new GiovChatError("send_failed", SEND_FAILED));
+      } else {
+        this.later(outcome.retryAfter, () => { if (this.ws === ws) this.flush(); });
+      }
+      return;
+    }
+    if (data.error === "rate_limited") {
+      // Too fast: everything on the socket goes again a little later, with the same ids.
+      this.outbox.socketClosed();
+      this.later(3000, () => { if (this.ws === ws) this.flush(); });
+      return;
+    }
+    if (data.error === "message_failed") return;
+    // invalid_message, invalid_attachment and any code this client does not know (the AsyncAPI says
+    // to treat an unknown one as invalid_message). Frames are checked in order, so the refusal is
+    // for the oldest message still waiting.
+    const refused = this.outbox.refuseOldestSending();
+    if (refused) this.fail(refused.clientMessageId);
+    this.emit(this.errorCbs, new GiovChatError("send_failed", SEND_FAILED));
+  }
+
+  private later(delay: number, run: () => void): void {
+    const timer = setTimeout(() => { this.resendTimers.delete(timer); run(); }, delay);
+    this.resendTimers.add(timer);
+  }
+
+  private settle(clientMessageId: string, message: GiovMessage | null): void {
+    const waiters = this.pending.get(clientMessageId);
+    this.pending.delete(clientMessageId);
+    for (const waiter of waiters ?? []) {
+      if (message) waiter.resolve(message);
+      else waiter.reject(new GiovChatError("send_failed", SEND_FAILED));
+    }
+  }
+
+  private fail(clientMessageId: string): void {
+    const waiters = this.pending.get(clientMessageId);
+    this.pending.delete(clientMessageId);
+    for (const waiter of waiters ?? []) waiter.reject(new GiovChatError("send_failed", SEND_FAILED));
+  }
+
+  private reconnect(generation: number): void {
+    if (!this.desired || generation !== this.generation || this.timer) return;
+    const delay = reconnectDelay(this.attempt++);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.open(generation).catch((error: unknown) => {
+        if (!this.desired || generation !== this.generation) return;
+        const failure = chatError(error);
+        if (failure.code === "invalid_session") this.disconnect();
+        else this.reconnect(generation);
+        this.emit(this.errorCbs, failure);
+      });
+    }, delay);
+  }
+
+  /** Reconnect now instead of waiting for the backoff, e.g. when the app returns to the foreground. */
+  reconnectNow(): void {
+    if (!this.desired || this.isConnected || !this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+    this.attempt = 0;
+    const generation = this.generation;
+    void this.open(generation).catch((error: unknown) => {
+      if (!this.desired || generation !== this.generation) return;
+      const failure = chatError(error);
+      if (failure.code === "invalid_session") this.disconnect();
+      else this.reconnect(generation);
+      this.emit(this.errorCbs, failure);
+    });
+  }
+
+  /** Puts everything waiting in the outbox on the socket, oldest first. */
+  flush(): void {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    for (const { frame } of this.outbox.takeQueued()) {
+      try { ws.send(frame); } catch { ws.close(); return; }
+    }
+  }
+
+  /**
+   * Queues a visitor message and sends it as soon as a socket is open; returns its client message id
+   * at once. Delivery is tracked in `outbox` and confirmed through `onAck`.
+   */
+  send(text: string, attachments: readonly string[] = []): string {
+    const entry = this.outbox.enqueue(text, attachments);
+    this.flush();
+    return entry.clientMessageId;
+  }
+
+  /**
+   * Sends one message and resolves with the stored copy once the server confirms it. While the
+   * connection is being restored it waits in the outbox instead of failing. Rejects only when the
+   * server refuses it or `disconnect()` is called first.
+   */
+  async sendMessage(text: string): Promise<GiovMessage> {
+    if (!text.trim() || text.length > 2000) throw new GiovChatError("send_failed", "Messages must contain 1–2000 characters.");
+    const clientMessageId = this.outbox.enqueue(text).clientMessageId;
+    const result = new Promise<GiovMessage>((resolve, reject) => {
+      const waiters = this.pending.get(clientMessageId) ?? [];
+      waiters.push({ resolve, reject });
+      this.pending.set(clientMessageId, waiters);
+    });
+    this.flush();
+    return result;
+  }
+
+  /** Sends a message that failed again, in its original place in the queue. */
+  retryMessage(clientMessageId: string): boolean {
+    const retried = this.outbox.retry(clientMessageId);
+    if (retried) this.flush();
+    return retried;
+  }
+
+  /** The visitor started typing (send once per burst) or stopped. */
+  sendTyping(): void { this.sendFrame({ type: "typing" }); }
+  sendTypingEnd(): void { this.sendFrame({ type: "typing_end" }); }
+  private sendFrame(frame: Record<string, unknown>): void {
+    if (this.ws?.readyState !== WebSocket.OPEN) return;
+    try { this.ws.send(JSON.stringify(frame)); } catch { /* The next reconnect recovers. */ }
+  }
+
+  /**
+   * Uploads one file to this conversation and returns its URL for `send`. Reports progress (0–1)
+   * where XMLHttpRequest is available (React Native has it). Retries once with a new token on 401.
+   */
+  async uploadAttachment(file: GiovChatPickedFile, onProgress?: (fraction: number) => void): Promise<GiovUploadResult> {
+    const session = this.session;
+    if (!session) throw new GiovChatError("disconnected", "Chat closed.");
+    const path = `${this.baseUrl}/conversations/${encodeURIComponent(session.conversationId)}/upload-visitor`;
+    // One bound for the whole upload, the 401 retry included, so a stalled network cannot hold the composer.
+    const deadline = Date.now() + UPLOAD_TIMEOUT_MS;
+    let { token } = await this.token();
+    let response = await upload(path, token, file, deadline, onProgress);
+    if (response.status === 401 && Date.now() < deadline) {
+      token = (await this.token(true)).token;
+      response = await upload(path, token, file, deadline, onProgress);
+    }
+    const data = object(response.body);
+    if (response.status < 200 || response.status >= 300 || typeof data.url !== "string") throw uploadError(response, data);
+    const access = parseAttachmentAccess(data.attachmentAccess);
+    if (access) this.emit(this.accessCbs, access);
+    const preview = sanitizePreview(data.preview);
+    return { url: data.url, filename: typeof data.filename === "string" ? data.filename : file.name, ...(preview ? { preview } : {}) };
+  }
+
+  /**
+   * Registers this device for visitor push notifications about this conversation. Until the server
+   * supports visitor push it resolves `{ registered: false, reason: "unsupported" }` and never throws.
+   */
+  async registerPushToken(token: string, platform: GiovPushPlatform, options: GiovPushOptions = {}): Promise<GiovPushRegistration> {
+    if (this.pushUnsupported) return { registered: false, reason: "unsupported" };
+    const session = this.session;
+    if (!session) return { registered: false, reason: "no_conversation" };
+    if (!token.trim() || token.length > 4096 || (platform !== "ios" && platform !== "android")) return { registered: false, reason: "failed" };
+    const locale = options.locale ?? deviceLocale();
+    try {
+      const response = await this.pushRequest(session, "POST", { token, platform,
+        ...(options.environment ? { environment: options.environment } : {}), ...(options.appId ? { appId: options.appId } : {}),
+        ...(PUSH_LOCALE.test(locale) ? { locale } : {}) });
+      if (response.status === 404 || response.status === 405 || response.status === 501) {
+        this.pushUnsupported = true;
+        return { registered: false, reason: "unsupported" };
+      }
+      return response.ok ? { registered: true } : { registered: false, reason: "failed" };
+    } catch {
+      return { registered: false, reason: "failed" };
+    }
+  }
+
+  /**
+   * Stops push notifications about this conversation on this device (sign-out, notifications turned
+   * off). Resolves true when the server confirmed; never throws. Without a live connection, pass the
+   * stored `session`: a fresh visitor token is fetched for it.
+   */
+  async unregisterPushToken(token: string, session?: GiovChatSession | null): Promise<boolean> {
+    if (this.pushUnsupported || !token.trim() || token.length > 4096) return false;
+    if (this.session) {
+      try { return (await this.pushRequest(this.session, "DELETE", { token })).ok; } catch { return false; }
+    }
+    return session ? unregisterPushToken(this.baseUrl, this.options.tenantKey, session, token) : false;
+  }
+
+  /** One push-token request with the visitor token, renewed once on 401 (protocol "Tokens"). */
+  private async pushRequest(session: GiovChatSession, method: "POST" | "DELETE", body: Record<string, unknown>): Promise<Response> {
+    const send = async (visitorToken: string) => pushFetch(this.baseUrl, session, method, visitorToken, body);
+    const response = await send((await this.token()).token);
+    return response.status === 401 ? send((await this.token(true)).token) : response;
+  }
+
+  private rejectPending(): void {
+    for (const waiters of this.pending.values()) {
+      for (const waiter of waiters) waiter.reject(new GiovChatError("send_failed", "Delivery could not be confirmed. Check the conversation before sending again."));
+    }
+    this.pending.clear();
+  }
+
+  /** Closes the connection. Unsent messages stay in the outbox; promises from sendMessage are rejected. */
+  disconnect(): void {
+    this.rejectPending();
+    this.teardown();
+  }
+
+  private teardown(): void {
+    this.desired = false;
+    this.generation++;
+    this.controller?.abort();
+    this.controller = null;
+    this.cancelHandshake?.();
+    this.cancelHandshake = null;
+    if (this.timer) clearTimeout(this.timer);
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    if (this.watchdog) clearInterval(this.watchdog);
+    for (const timer of this.resendTimers) clearTimeout(timer);
+    this.resendTimers.clear();
+    this.timer = null;
+    this.heartbeat = null;
+    this.watchdog = null;
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      ws.onopen = ws.onclose = ws.onerror = ws.onmessage = null;
+      ws.close();
+    }
+    // Unsent messages stay in the outbox; a later connection sends them.
+    this.outbox.socketClosed();
+    this.session = null;
+    this.widgetToken = null;
+    this.tokenRequest = null;
+    this.emit(this.statusCbs, false);
+  }
+
+  get isConnected(): boolean { return this.ws !== null && this.ws.readyState === WebSocket.OPEN; }
+}
+
+/** A push-token request; it names the SDK so the dashboard can show which app versions receive pushes. */
+function pushFetch(baseUrl: string, session: GiovChatSession, method: "POST" | "DELETE", visitorToken: string, body: Record<string, unknown>): Promise<Response> {
+  return fetch(`${baseUrl}/conversations/${encodeURIComponent(session.conversationId)}${PUSH_TOKEN_PATH}`, {
+    method, headers: { "Content-Type": "application/json", Authorization: `Bearer ${visitorToken}`, ...CLIENT_HEADER }, body: JSON.stringify(body),
+  });
+}
+
+/**
+ * Stops push for a stored conversation without a connection (the chat is closed or hidden): a fresh
+ * visitor token from the session secret, then `DELETE /push-token`. Never throws.
+ */
+export async function unregisterPushToken(baseUrl: string, tenantKey: string, session: GiovChatSession, token: string): Promise<boolean> {
+  if (!token.trim() || token.length > 4096) return false;
+  try {
+    const { token: visitorToken } = await fetchWidgetToken(baseUrl, tenantKey, session);
+    return (await pushFetch(normalizeBaseUrl(baseUrl), session, "DELETE", visitorToken, { token })).ok;
+  } catch {
+    return false;
+  }
+}
+
+/** The whole upload, retry included, gives up after this long. */
+export const UPLOAD_TIMEOUT_MS = 120_000;
+
+type UploadResponse = { status: number; body: unknown; retryAfter?: number; timedOut?: boolean };
+
+/**
+ * An upload refusal by status: 404 the conversation is gone, 401/403 the session is gone, 429 rate
+ * limited (with Retry-After), 5xx the server, any other 4xx the file itself (type, size, policy).
+ */
+function uploadError(response: UploadResponse, data: Record<string, unknown>): GiovChatError {
+  const { status } = response;
+  const message = typeof data.message === "string" ? data.message : "File upload failed.";
+  if (status === 0) return response.timedOut ? new GiovChatError("timeout", "File upload timed out.") : new GiovChatError("network", "Unable to reach chat. Please try again.");
+  if (status === 404 || status === 409) return new GiovChatError("conversation_closed", "This conversation has ended.", status);
+  if (status === 401 || status === 403) return new GiovChatError("invalid_session", "Chat session expired. Please start a new chat.", status);
+  if (status === 429) return new GiovChatError("rate_limited", "Too many requests. Please wait a moment.", status, response.retryAfter);
+  if (status >= 500) return new GiovChatError("server", message, status, response.retryAfter);
+  return new GiovChatError("upload_failed", message, status);
+}
+
+/** One multipart upload, through XMLHttpRequest for progress when it exists, else fetch; abandoned at `deadline`. */
+function upload(url: string, token: string, file: GiovChatPickedFile, deadline: number, onProgress?: (fraction: number) => void): Promise<UploadResponse> {
+  const form = buildUploadForm(file);
+  const headers = { Authorization: `Bearer ${token}` };
+  const remaining = Math.max(0, deadline - Date.now());
+  if (typeof XMLHttpRequest === "undefined") {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, remaining);
+    return fetch(url, { method: "POST", headers, body: form, signal: controller.signal })
+      .then(async (response) => ({ status: response.status, body: await response.json().catch(() => null),
+        retryAfter: retryAfterSeconds(response.headers?.get?.("Retry-After")) }))
+      .catch(() => ({ status: 0, body: null, timedOut }))
+      .finally(() => clearTimeout(timer));
+  }
+  return new Promise((resolve) => {
+    const xhr = new XMLHttpRequest();
+    let timedOut = false;
+    // xhr.timeout alone is not enough: some stacks never fire it while bytes trickle out.
+    const timer = setTimeout(() => { timedOut = true; xhr.abort(); }, remaining);
+    const done = (value: UploadResponse) => { clearTimeout(timer); resolve(value); };
+    xhr.open("POST", url);
+    for (const [name, value] of Object.entries(headers)) xhr.setRequestHeader(name, value);
+    xhr.timeout = remaining;
+    if (onProgress && xhr.upload) {
+      xhr.upload.onprogress = (event) => { if (event.lengthComputable && event.total > 0) onProgress(Math.min(1, event.loaded / event.total)); };
+    }
+    xhr.onload = () => {
+      let body: unknown = null;
+      try { body = JSON.parse(xhr.responseText); } catch { /* Not JSON. */ }
+      if (xhr.status >= 200 && xhr.status < 300) onProgress?.(1);
+      done({ status: xhr.status, body, retryAfter: retryAfterSeconds(xhr.getResponseHeader?.("Retry-After")) });
+    };
+    xhr.ontimeout = () => { timedOut = true; done({ status: 0, body: null, timedOut }); };
+    xhr.onerror = xhr.onabort = () => done({ status: 0, body: null, timedOut });
+    xhr.send(form);
+  });
+}