@giovchat/react-native 0.0.0-stage → 0.2.0

package/src/identity.ts

@@ -0,0 +1,54 @@
+import type { GiovWidgetConfig } from "./types";
+
+/**
+ * Who the visitor is talking to, as the web widget shows it (apps/widget-web/src/components/
+ * header-identity.ts): a person once one has taken over (their name and photo), otherwise the AI
+ * assistant while it answers (its own name and avatar), and the team title when neither is set up.
+ */
+export type HeaderIdentityKind = "person" | "bot" | "team";
+export interface HeaderIdentity {
+  kind: HeaderIdentityKind;
+  title: string;
+  avatar: string | null;
+}
+
+export function headerIdentity(
+  config: Pick<GiovWidgetConfig, "title" | "botEnabled" | "botName" | "botAvatarUrl" | "avatarUrl">,
+  currentAgentName?: string | null,
+  currentAgentAvatar?: string | null,
+): HeaderIdentity {
+  if (currentAgentName) return { kind: "person", title: currentAgentName, avatar: safeImageUrl(currentAgentAvatar) };
+  if (config.botEnabled && config.botName) return { kind: "bot", title: config.botName, avatar: safeImageUrl(config.botAvatarUrl) };
+  return { kind: "team", title: config.title, avatar: safeImageUrl(config.avatarUrl) };
+}
+
+/** Only http(s) images are loaded; anything else falls back to the initial. */
+export function safeImageUrl(value: unknown): string | null {
+  return typeof value === "string" && /^https?:\/\//i.test(value.trim()) ? value.trim() : null;
+}
+
+type IdentityInput = { role: string; isBot?: boolean; isAutomated?: boolean; senderName?: string | null };
+
+/** The label above a bubble. AI delivery is also automated internally; the AI identity takes precedence. */
+export function messageSenderLabel(
+  message: IdentityInput,
+  labels: { botName?: string; agentName?: string | null; you: string; automated: string; agent: string },
+): string {
+  if (message.role !== "agent") return labels.you;
+  if (message.isBot === true) return labels.botName?.trim() || "GiovBot";
+  if (message.isAutomated === true) return labels.automated;
+  return message.senderName?.trim() || labels.agentName?.trim() || labels.agent;
+}
+
+export type AgentTypingState = { visible: boolean; isBot?: boolean };
+
+/** Only explicit server AI metadata may brand a typing indicator as the AI (as in the widget). */
+export function reduceAgentTyping(current: AgentTypingState, event: { type?: unknown; role?: unknown; isBot?: unknown }): AgentTypingState {
+  if (event.role !== "agent") return current;
+  if (event.type === "typing") return { visible: true, isBot: typeof event.isBot === "boolean" ? event.isBot : undefined };
+  if (event.type === "typing_end") {
+    if (typeof event.isBot === "boolean" && typeof current.isBot === "boolean" && event.isBot !== current.isBot) return current;
+    return { visible: false };
+  }
+  return current;
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// Public types
+export type {
+  GiovChatContact,
+  GiovChatSession,
+  GiovChatSessionStorage,
+  GiovChatConnectionStatus,
+  GiovMessage,
+  GiovWidgetConfig,
+  MessageHandler,
+  RequestUserInfo,
+  StatusHandler,
+} from "./types";
+
+// Advanced / headless usage
+export {
+  ChatClient,
+  createConversation,
+  DEFAULT_BASE_URL,
+  fetchWidgetConfig,
+  fetchConversationHistory,
+  PUSH_TOKEN_PATH,
+  SDK_VERSION,
+  UPLOAD_TIMEOUT_MS,
+  unregisterPushToken,
+} from "./client";
+export type {
+  ChatClientOptions,
+  GiovConversationHistory,
+  GiovPushOptions,
+  GiovPushPlatform,
+  GiovPushRegistration,
+  GiovStreamEvent,
+  GiovUploadResult,
+} from "./client";
+export { Outbox, ACK_TIMEOUT_MS, MAX_SEND_FAILURES, MAX_MESSAGE_CHARS, clampMessage } from "./outbox";
+export type { OutboxEntry, OutboxState } from "./outbox";
+export { parseChatMarkdown, parseInline, plainText } from "./markdown";
+export type { Block as ChatMarkdownBlock, InlineNode as ChatMarkdownInline } from "./markdown";
+export { headerIdentity, messageSenderLabel, reduceAgentTyping } from "./identity";
+export type { HeaderIdentity, HeaderIdentityKind, AgentTypingState } from "./identity";
+export {
+  DEFAULT_ATTACHMENT_POLICY,
+  MAX_ATTACHED_FILES,
+  SUPPORTED_ATTACHMENT_TYPES,
+  normalizeAttachmentPolicy,
+  validateAttachments,
+} from "./attachments";
+export type {
+  GiovAttachment,
+  GiovAttachmentPolicy,
+  GiovAttachmentPreview,
+  GiovChatAttachmentPicker,
+  GiovChatPickedFile,
+} from "./attachments";
+
+// Main component
+export { GiovChat } from "./GiovChat";
+export type { GiovChatProps, GiovChatHandle } from "./GiovChat";
+export { useGiovChatUnreadCount } from "./unread";
+export { GIOVCHAT_STRINGS, resolveLocale, resolveStrings } from "./i18n";
+export type { GiovChatLocale, GiovChatStrings } from "./i18n";
+export { GiovChatError } from "./errors";
+export type { GiovChatErrorCode } from "./errors";
+export type {
+  GiovChatStyleOverrides,
+  GiovChatTextStyle,
+  GiovChatBackgroundStyle,
+} from "./styleOverrides";

package/src/markdown.ts

@@ -0,0 +1,227 @@
+/**
+ * Chat Markdown for the SDK: the grammar of the web widget's formatMessage (apps/widget-web/src/lib/
+ * formatMessage.ts, shared by the widget, Copilot and the web inbox), parsed into a tree that
+ * components/ChatMarkdown.tsx renders with native Text. The same parser as the Giov agent app.
+ * Paragraphs and line breaks, **bold**, *italic* or _italic_, ~~strike~~, <u>underline</u>, `code`,
+ * fenced code, # headings, - / * / + and 1. lists (one nested level), > quotes, --- rules,
+ * [links](https://…) and bare links. Only http(s)/mailto links get an href. Unfinished markup (while
+ * a reply streams in) stays as text until it is closed. Pure: no React.
+ */
+export type InlineMarks = { bold?: true; italic?: true; strike?: true; underline?: true; code?: true };
+export type InlineNode = { text: string; marks: InlineMarks; href?: string };
+/** One visual line; lines in a paragraph, quote or list item are separated by line breaks. */
+export type InlineLine = InlineNode[];
+
+export type ListItem = { lines: InlineLine[]; children: ListBlock[] };
+export type ListBlock = { type: "list"; ordered: boolean; start: number; items: ListItem[] };
+export type Block =
+  | { type: "paragraph"; lines: InlineLine[] }
+  | { type: "heading"; content: InlineLine }
+  | { type: "code"; text: string }
+  | { type: "rule" }
+  | { type: "quote"; lines: InlineLine[] }
+  | ListBlock;
+
+type MarkName = "bold" | "italic" | "strike" | "underline";
+
+// Placeholders and mark delimiters are control characters that never survive in chat text, and
+// none is a word character, so the italic rules see the same neighbours as in the widget's HTML.
+const CODE = "\u0000";
+const LINK = "\u0001";
+const MARKS: Record<string, readonly [MarkName, 1 | -1]> = {
+  "\u0010": ["bold", 1],
+  "\u0011": ["bold", -1],
+  "\u0012": ["italic", 1],
+  "\u0013": ["italic", -1],
+  "\u0014": ["strike", 1],
+  "\u0015": ["strike", -1],
+  "\u0016": ["underline", 1],
+  "\u0017": ["underline", -1]
+};
+const bold = (text: string) => `\u0010${text}\u0011`;
+const italic = (text: string) => `\u0012${text}\u0013`;
+const strike = (text: string) => `\u0014${text}\u0015`;
+const underline = (text: string) => `\u0016${text}\u0017`;
+
+function sameMarks(left: InlineMarks, right: InlineMarks): boolean {
+  return left.bold === right.bold && left.italic === right.italic && left.strike === right.strike
+    && left.underline === right.underline && left.code === right.code;
+}
+
+/** Inline markup on one line, in the widget's order: code spans and links are cut out first. */
+export function parseInline(text: string): InlineLine {
+  const source = text.replace(/[\u0000\u0001\u0010-\u0017]/g, "");
+  const codes: string[] = [];
+  let out = source.replace(/`([^`\n]+)`/g, (_, code: string) => `${CODE}${codes.push(code) - 1}${CODE}`);
+  const links: Array<{ label: string; href: string }> = [];
+  const keep = (label: string, href: string) => `${LINK}${links.push({ label, href }) - 1}${LINK}`;
+  out = out.replace(/\[([^\]\n]+)\]\(((?:https?:\/\/|mailto:)[^\s)]+)\)/gi, (_, label: string, href: string) => keep(label, href));
+  out = out.replace(/(^|[\s(])((?:https?:\/\/)[^\s<]+[^\s<.,;:!?)'"&])/gi, (_, lead: string, href: string) => lead + keep(href, href));
+  out = out
+    .replace(/\*\*(?=\S)([^*]+?\S)\*\*/g, (_, inner: string) => bold(inner))
+    .replace(/__(?=\S)([^_]+?\S)__/g, (_, inner: string) => bold(inner))
+    .replace(/(^|[^*\w])\*(?=\S)([^*\n]+?\S)\*(?![*\w])/g, (_, lead: string, inner: string) => lead + italic(inner))
+    .replace(/(^|[^_\w])_(?=\S)([^_\n]+?\S)_(?![_\w])/g, (_, lead: string, inner: string) => lead + italic(inner))
+    .replace(/~~(?=\S)([^~]+?\S)~~/g, (_, inner: string) => strike(inner))
+    .replace(/<u>([\s\S]+?)<\/u>/gi, (_, inner: string) => underline(inner));
+
+  const nodes: InlineNode[] = [];
+  const depth: Record<MarkName, number> = { bold: 0, italic: 0, strike: 0, underline: 0 };
+  const currentMarks = (): InlineMarks => {
+    const marks: InlineMarks = {};
+    for (const name of Object.keys(depth) as MarkName[]) if (depth[name] > 0) marks[name] = true;
+    return marks;
+  };
+  const push = (node: InlineNode) => {
+    if (!node.text) return;
+    const last = nodes[nodes.length - 1];
+    if (last && !last.href && !node.href && sameMarks(last.marks, node.marks)) last.text += node.text;
+    else nodes.push(node);
+  };
+
+  let buffer = "";
+  const flush = () => {
+    push({ text: buffer, marks: currentMarks() });
+    buffer = "";
+  };
+  for (let index = 0; index < out.length; index++) {
+    const char = out[index];
+    const mark = MARKS[char];
+    if (mark) {
+      flush();
+      depth[mark[0]] += mark[1];
+    } else if (char === CODE || char === LINK) {
+      const end = out.indexOf(char, index + 1);
+      const slot = Number(out.slice(index + 1, end));
+      flush();
+      if (char === CODE) push({ text: codes[slot], marks: { ...currentMarks(), code: true } });
+      else push({ text: links[slot].label, marks: currentMarks(), href: links[slot].href });
+      index = end;
+    } else {
+      buffer += char;
+    }
+  }
+  flush();
+  return nodes;
+}
+
+export function parseChatMarkdown(content: string): Block[] {
+  if (!content || typeof content !== "string") return [];
+  const lines = content.replace(/\r\n?/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let paragraph: string[] = [];
+  let quote: string[] = [];
+  // Open lists, outermost first; one nested level, as in the widget.
+  const lists: Array<{ list: ListBlock; indent: number }> = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length) blocks.push({ type: "paragraph", lines: paragraph.map(parseInline) });
+    paragraph = [];
+  };
+  const closeLists = (toIndent = -1) => {
+    while (lists.length && lists[lists.length - 1].indent > toIndent) lists.pop();
+  };
+  const flushQuote = () => {
+    if (quote.length) blocks.push({ type: "quote", lines: quote.map(parseInline) });
+    quote = [];
+  };
+  const flushAll = () => {
+    flushParagraph();
+    closeLists();
+    flushQuote();
+  };
+  const lastItem = (list: ListBlock) => list.items[list.items.length - 1];
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    // Fenced code: everything up to the closing fence (or the end, while streaming) is literal.
+    if (/^\s*```/.test(line)) {
+      flushAll();
+      const body: string[] = [];
+      while (++index < lines.length && !/^\s*```/.test(lines[index])) body.push(lines[index]);
+      blocks.push({ type: "code", text: body.join("\n") });
+      continue;
+    }
+    if (!line.trim()) {
+      flushParagraph();
+      flushQuote();
+      // A blank line between list items keeps the list going.
+      if (lists.length && !/^\s*(?:[-*+]|\d+[.)])\s+/.test(lines[index + 1] ?? "")) closeLists();
+      continue;
+    }
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      flushAll();
+      blocks.push({ type: "heading", content: parseInline(heading[2]) });
+      continue;
+    }
+    if (/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/.test(line)) {
+      flushAll();
+      blocks.push({ type: "rule" });
+      continue;
+    }
+    const quoted = /^>\s?(.*)$/.exec(line);
+    if (quoted) {
+      flushParagraph();
+      closeLists();
+      quote.push(quoted[1]);
+      continue;
+    }
+    flushQuote();
+    const item = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(line);
+    if (item) {
+      flushParagraph();
+      const indent = item[1].replace(/\t/g, "  ").length;
+      const ordered = /\d/.test(item[2]);
+      const entry: ListItem = { lines: [parseInline(item[3])], children: [] };
+      closeLists(indent);
+      const top = lists[lists.length - 1];
+      if (top && top.indent === indent && top.list.ordered === ordered) {
+        top.list.items.push(entry);
+      } else {
+        if (top && top.indent === indent) closeLists(indent - 1);
+        const parent = lists[lists.length - 1];
+        // Only one nested level: deeper indentation joins the nested list.
+        const nested = Boolean(parent) && indent > parent.indent;
+        if (lists.length >= 2 && nested) {
+          parent.list.items.push(entry);
+          continue;
+        }
+        const list: ListBlock = { type: "list", ordered, start: ordered ? Number.parseInt(item[2], 10) || 1 : 1, items: [entry] };
+        if (nested) lastItem(parent.list).children.push(list);
+        else blocks.push(list);
+        lists.push({ list, indent });
+      }
+      continue;
+    }
+    // A line indented under a list item continues that item.
+    if (lists.length && /^\s+\S/.test(line)) {
+      lastItem(lists[lists.length - 1].list).lines.push(parseInline(line.trim()));
+      continue;
+    }
+    closeLists();
+    paragraph.push(line);
+  }
+  flushAll();
+  return blocks;
+}
+
+/** Links are opened only for these schemes, whatever the text claims. */
+export function isOpenableHref(href: string | undefined): href is string {
+  return typeof href === "string" && /^(?:https?:\/\/|mailto:)/i.test(href);
+}
+
+/** The words of a message without its markup, for screen-reader announcements. */
+export function plainText(content: string): string {
+  const line = (nodes: InlineLine) => nodes.map((node) => node.text).join("");
+  const list = (block: ListBlock): string[] => block.items.flatMap((item) => [item.lines.map(line).join(" "), ...item.children.flatMap(list)]);
+  return parseChatMarkdown(content).flatMap((block): string[] => {
+    switch (block.type) {
+      case "paragraph": case "quote": return block.lines.map(line);
+      case "heading": return [line(block.content)];
+      case "code": return [block.text];
+      case "list": return list(block);
+      default: return [];
+    }
+  }).filter((text) => text.trim()).join(" ").replace(/\s+/g, " ").trim();
+}

package/src/outbox.ts

@@ -0,0 +1,175 @@
+import { GiovChatError } from "./errors";
+
+/**
+ * Visitor messages the server has not acknowledged yet, in the order they were written. Every
+ * message keeps one client message id for its whole life, so resending after a dropped socket can
+ * never store it twice: the server answers a repeat with the original's ack. Survives reconnects
+ * and the app going to the background (the chat hook owns it, the transport only flushes it).
+ * Pure: no sockets or timers, so the rules are testable on their own.
+ */
+export type OutboxState = "queued" | "sending" | "failed";
+export interface OutboxEntry {
+  clientMessageId: string;
+  content: string;
+  /** Uploaded attachment URLs this message carries. */
+  attachments: string[];
+  createdAt: number;
+  state: OutboxState;
+  /** When it last went out on a socket; 0 while it is waiting for one. */
+  sentAt: number;
+  /** Times the server said it could not save it. */
+  failures: number;
+}
+
+/** A sent message with no ack after this long means a dead socket: reconnect and resend. */
+export const ACK_TIMEOUT_MS = 10_000;
+/** Save failures retried before the visitor is told the message did not send. */
+export const MAX_SEND_FAILURES = 3;
+export const MAX_MESSAGE_CHARS = 2000;
+/** Wait before resending after a save failure: 2 s, 4 s, … */
+export const retryDelay = (failures: number) => 2000 * failures;
+
+/** UUID v4 where crypto is available (Hermes ships getRandomValues with most setups), else a unique fallback. */
+export function randomClientId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string; getRandomValues?: (bytes: Uint8Array) => Uint8Array } }).crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  if (c && typeof c.getRandomValues === "function") {
+    const bytes = c.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  return `rn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+export class Outbox {
+  private entries = new Map<string, OutboxEntry>();
+  private listeners = new Set<() => void>();
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+  private changed(): void {
+    for (const listener of this.listeners) { try { listener(); } catch { /* Listeners cannot break the queue. */ } }
+  }
+
+  /** Copies, oldest first. */
+  list(): OutboxEntry[] { return [...this.entries.values()].map((entry) => ({ ...entry, attachments: [...entry.attachments] })); }
+  get(clientMessageId: string): OutboxEntry | undefined {
+    const entry = this.entries.get(clientMessageId);
+    return entry && { ...entry, attachments: [...entry.attachments] };
+  }
+  get size(): number { return this.entries.size; }
+
+  /** Adds a message at the end. Throws when it could never be accepted (empty or too long). */
+  enqueue(content: string, attachments: readonly string[] = [], now = Date.now(), clientMessageId = randomClientId()): OutboxEntry {
+    if ((!content.trim() && attachments.length === 0) || content.length > MAX_MESSAGE_CHARS) {
+      throw new GiovChatError("send_failed", "Messages must contain 1–2000 characters.");
+    }
+    const entry: OutboxEntry = { clientMessageId, content, attachments: [...attachments], createdAt: now, state: "queued", sentAt: 0, failures: 0 };
+    this.entries.set(clientMessageId, entry);
+    this.changed();
+    return { ...entry, attachments: [...entry.attachments] };
+  }
+
+  /** The wire frame; identical every time it is sent. */
+  static frame(entry: Pick<OutboxEntry, "clientMessageId" | "content" | "attachments">): string {
+    return JSON.stringify({ type: "message", content: entry.content, clientMessageId: entry.clientMessageId,
+      ...(entry.attachments.length ? { attachments: entry.attachments } : {}) });
+  }
+
+  /** Everything waiting for a socket, in order, marked as sent now. Failed messages wait for `retry`. */
+  takeQueued(now = Date.now()): Array<{ clientMessageId: string; frame: string }> {
+    const out: Array<{ clientMessageId: string; frame: string }> = [];
+    for (const entry of this.entries.values()) {
+      if (entry.state !== "queued") continue;
+      entry.state = "sending";
+      entry.sentAt = now;
+      out.push({ clientMessageId: entry.clientMessageId, frame: Outbox.frame(entry) });
+    }
+    if (out.length) this.changed();
+    return out;
+  }
+
+  /** The server saved it: the message leaves the queue. Unknown ids (already acknowledged) return null. */
+  acknowledge(clientMessageId: string): OutboxEntry | null {
+    const entry = this.entries.get(clientMessageId);
+    if (!entry) return null;
+    this.entries.delete(clientMessageId);
+    this.changed();
+    return entry;
+  }
+
+  /** The server could not save it: wait and resend, or give up after MAX_SEND_FAILURES. */
+  rejected(clientMessageId: string): { failed: boolean; retryAfter: number } | null {
+    const entry = this.entries.get(clientMessageId);
+    if (!entry || entry.state === "failed") return null;
+    entry.failures += 1;
+    entry.sentAt = 0;
+    entry.state = entry.failures >= MAX_SEND_FAILURES ? "failed" : "queued";
+    this.changed();
+    return { failed: entry.state === "failed", retryAfter: entry.state === "failed" ? 0 : retryDelay(entry.failures) };
+  }
+
+  /** A message the server refused outright (invalid content or attachment): no retry can fix it. */
+  refuseOldestSending(): OutboxEntry | null {
+    for (const entry of this.entries.values()) {
+      if (entry.state !== "sending") continue;
+      entry.state = "failed";
+      entry.sentAt = 0;
+      this.changed();
+      return { ...entry, attachments: [...entry.attachments] };
+    }
+    return null;
+  }
+
+  /** The socket went away: whatever was on it goes out again on the next one, with the same ids. */
+  socketClosed(): void {
+    let changed = false;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "sending") { entry.state = "queued"; entry.sentAt = 0; changed = true; }
+    }
+    if (changed) this.changed();
+  }
+
+  /** True when a message has waited longer than ACK_TIMEOUT_MS on an open socket. */
+  stale(now = Date.now()): boolean {
+    for (const entry of this.entries.values()) {
+      if (entry.state === "sending" && entry.sentAt > 0 && now - entry.sentAt > ACK_TIMEOUT_MS) return true;
+    }
+    return false;
+  }
+
+  /** The visitor asked to try a failed message again: it rejoins the queue in its original place. */
+  retry(clientMessageId: string): boolean {
+    const entry = this.entries.get(clientMessageId);
+    if (!entry || entry.state !== "failed") return false;
+    entry.state = "queued";
+    entry.failures = 0;
+    entry.sentAt = 0;
+    this.changed();
+    return true;
+  }
+
+  remove(clientMessageId: string): boolean {
+    const removed = this.entries.delete(clientMessageId);
+    if (removed) this.changed();
+    return removed;
+  }
+
+  clear(): void {
+    if (!this.entries.size) return;
+    this.entries.clear();
+    this.changed();
+  }
+}
+
+/** Composer text cut to MAX_MESSAGE_CHARS UTF-16 units (JavaScript string length), never through a surrogate pair. */
+export function clampMessage(text: string, max = MAX_MESSAGE_CHARS): string {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const last = cut.charCodeAt(cut.length - 1);
+  return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}

package/src/protocol.ts

@@ -0,0 +1,31 @@
+import type { GiovMessage } from "./types";
+import { parseAttachments } from "./attachments";
+import { safeImageUrl } from "./identity";
+
+export function object(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+/**
+ * A message from a socket frame (camelCase) or a history row (snake_case). The server stores the
+ * visitor's role as "user". Sender identity is kept for agents only, and the AI identity wins over
+ * "automated" (AI replies carry both flags).
+ */
+export function parseMessage(value: unknown): GiovMessage | null {
+  const m = object(value);
+  const role = m.role === "user" ? "visitor" : m.role;
+  const createdAt = m.createdAt ?? m.created_at;
+  if (typeof m.id !== "string" || !m.id || (role !== "agent" && role !== "visitor") ||
+      typeof m.content !== "string" || typeof createdAt !== "number" || !Number.isFinite(createdAt)) return null;
+  // camelCase first; the snake_case history fields are deprecated aliases (protocol v1).
+  const isBot = role === "agent" && (typeof m.isBot === "boolean" ? m.isBot : m.is_bot === 1);
+  const isAutomated = role === "agent" && (typeof m.isAutomated === "boolean" ? m.isAutomated : m.is_automated === 1);
+  const human = role === "agent" && !isBot && !isAutomated;
+  const attachments = parseAttachments(m.attachmentId ?? m.attachment_id, m.attachmentPreviews ?? m.attachment_previews);
+  return {
+    id: m.id, role, content: m.content, createdAt, isBot, isAutomated,
+    senderName: role === "agent" && typeof m.senderName === "string" ? m.senderName : undefined,
+    ...(human && safeImageUrl(m.senderAvatar) ? { senderAvatar: safeImageUrl(m.senderAvatar) } : {}),
+    ...(attachments.length ? { attachments } : {}),
+  };
+}

package/src/styleOverrides.ts

@@ -0,0 +1,85 @@
+import type { TextStyle, ViewStyle } from "react-native";
+
+/** Typography and colors only; text sizing and layout remain SDK-controlled. */
+export type GiovChatTextStyle = Pick<TextStyle, "fontFamily" | "fontWeight" | "fontStyle"> & {
+  color?: string;
+};
+
+export type GiovChatBackgroundStyle = { backgroundColor?: string };
+
+/** Plain objects only. No arbitrary React Native styles or branding overrides. */
+export interface GiovChatStyleOverrides {
+  /** Default font family for all customizable text. Load the font in your app. */
+  fontFamily?: string;
+  container?: GiovChatBackgroundStyle;
+  header?: GiovChatBackgroundStyle;
+  headerTitle?: GiovChatTextStyle;
+  headerSubtitle?: GiovChatTextStyle;
+  agentBubble?: GiovChatBackgroundStyle;
+  visitorBubble?: GiovChatBackgroundStyle;
+  agentText?: GiovChatTextStyle;
+  visitorText?: GiovChatTextStyle;
+  composer?: GiovChatBackgroundStyle;
+  input?: GiovChatTextStyle & GiovChatBackgroundStyle;
+  button?: GiovChatBackgroundStyle;
+  buttonText?: GiovChatTextStyle;
+  form?: GiovChatBackgroundStyle;
+  formTitle?: GiovChatTextStyle;
+  label?: GiovChatTextStyle;
+  hint?: GiovChatTextStyle;
+  errorText?: GiovChatTextStyle;
+}
+
+const backgroundSlots = [
+  "container", "header", "agentBubble", "visitorBubble", "composer", "button", "form",
+] as const;
+const textSlots = [
+  "headerTitle", "headerSubtitle", "agentText", "visitorText", "input", "buttonText",
+  "formTitle", "label", "hint", "errorText",
+] as const;
+
+export type ResolvedWidgetStyles = Record<(typeof backgroundSlots)[number], ViewStyle> &
+  Record<(typeof textSlots)[number], TextStyle>;
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/** Rebuild every slot from an allowlist, including for untyped JavaScript callers. */
+export function resolveStyleOverrides(value: unknown): ResolvedWidgetStyles {
+  const input = record(value);
+  const result = {} as ResolvedWidgetStyles;
+  for (const slot of backgroundSlots) {
+    const source = record(input[slot]);
+    result[slot] = nonEmptyString(source.backgroundColor)
+      ? { backgroundColor: source.backgroundColor }
+      : {};
+  }
+  for (const slot of textSlots) {
+    const source = record(input[slot]);
+    const style: TextStyle = {};
+    if (nonEmptyString(input.fontFamily)) style.fontFamily = input.fontFamily;
+    if (nonEmptyString(source.fontFamily)) style.fontFamily = source.fontFamily;
+    if (nonEmptyString(source.color)) style.color = source.color;
+    if (source.fontStyle === "normal" || source.fontStyle === "italic") {
+      style.fontStyle = source.fontStyle;
+    }
+    const weight = source.fontWeight;
+    if (weight === "normal" || weight === "bold" ||
+      (typeof weight === "string" && /^[1-9]00$/.test(weight)) ||
+      (typeof weight === "number" && weight >= 100 && weight <= 900 && weight % 100 === 0)) {
+      style.fontWeight = weight as TextStyle["fontWeight"];
+    }
+    if (slot === "input" && nonEmptyString(source.backgroundColor)) {
+      style.backgroundColor = source.backgroundColor;
+    }
+    result[slot] = style;
+  }
+  return result;
+}