@giovchat/react-native 0.0.0-stage → 0.3.0

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,36 @@
+import type { GiovMessage } from "./types";
+import { parseRatingBlock } from "./rating";
+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);
+  // Unknown block types are ignored (protocol versioning); only the rating card is drawn.
+  const rating = Array.isArray(m.blocks) ? m.blocks.map(parseRatingBlock).find((block) => block !== null) : undefined;
+  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 } : {}),
+    ...(rating ? { rating } : {}),
+    ...(isBot && (m.feedback === "up" || m.feedback === "down") ? { feedback: m.feedback } : {}),
+  };
+}

package/src/rating.ts

@@ -0,0 +1,169 @@
+import type {
+  GiovFeedbackValue, GiovMessage, GiovRatingBlock, GiovRatingRequest, GiovRatingResult, GiovRatingScore,
+} from "./types";
+import { GiovChatError, retryAfterSeconds } from "./errors";
+
+/** Pure rules for conversation ratings and the thumbs under GiovBot answers (docs/protocol, "Conversation ratings"). */
+
+export const MAX_RATING_COMMENT = 1000;
+export const MAX_FEEDBACK_REASON = 300;
+
+const obj = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+
+const isScore = (value: unknown): value is GiovRatingScore =>
+  typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 5;
+
+/** A `rating` block from a message; null for any other (or malformed) block. */
+export function parseRatingBlock(value: unknown): GiovRatingBlock | null {
+  const b = obj(value);
+  if (b.type !== "rating" || typeof b.requestId !== "string" || !b.requestId ||
+      typeof b.closesAt !== "number" || !Number.isFinite(b.closesAt)) return null;
+  const score = isScore(b.score) ? b.score : undefined;
+  return {
+    requestId: b.requestId, closesAt: b.closesAt,
+    ...(typeof b.url === "string" && /^https:\/\//i.test(b.url) ? { url: b.url } : {}),
+    ...(score ? { score } : {}),
+    ...(score && typeof b.comment === "string" && b.comment ? { comment: b.comment } : {}),
+    ...(b.state === "replaced" ? { state: "replaced" as const } : {}),
+  };
+}
+
+/** The `rating` socket frame: the card changed (answered, changed or replaced). */
+export interface GiovRatingFrame {
+  requestId: string;
+  messageId?: string;
+  closesAt: number;
+  score?: GiovRatingScore;
+  comment?: string;
+  state?: "replaced";
+}
+
+export function parseRatingFrame(value: unknown): GiovRatingFrame | null {
+  const f = obj(value);
+  if (f.type !== "rating" || typeof f.requestId !== "string" || !f.requestId ||
+      typeof f.closesAt !== "number" || !Number.isFinite(f.closesAt)) return null;
+  const score = isScore(f.score) ? f.score : undefined;
+  return {
+    requestId: f.requestId, closesAt: f.closesAt,
+    ...(typeof f.messageId === "string" && f.messageId ? { messageId: f.messageId } : {}),
+    ...(score ? { score } : {}),
+    ...(score && typeof f.comment === "string" && f.comment ? { comment: f.comment } : {}),
+    ...(f.state === "replaced" ? { state: "replaced" as const } : {}),
+  };
+}
+
+/** Sets the answer, deadline and state on the card a frame (or an answer) names; other messages stay as they are. */
+export function patchRating(messages: GiovMessage[], frame: GiovRatingFrame): GiovMessage[] {
+  let changed = false;
+  const next = messages.map((message) => {
+    if ((frame.messageId && message.id !== frame.messageId) || message.rating?.requestId !== frame.requestId) return message;
+    changed = true;
+    const { score: _s, comment: _c, state: _t, ...rest } = message.rating;
+    return {
+      ...message,
+      rating: {
+        ...rest, closesAt: frame.closesAt,
+        ...(frame.score ? { score: frame.score } : {}),
+        ...(frame.score && frame.comment ? { comment: frame.comment } : {}),
+        ...(frame.state ? { state: frame.state } : message.rating.state ? { state: message.rating.state } : {}),
+      },
+    };
+  });
+  return changed ? next : messages;
+}
+
+/**
+ * One open card per conversation: an older card the visitor never answered is replaced by a newer
+ * one (also before the server's own `replaced` mark arrives). Answered cards keep their answer.
+ */
+export function supersedeRatings(messages: GiovMessage[]): GiovMessage[] {
+  let latest = -1;
+  messages.forEach((message, index) => { if (message.rating && message.rating.state !== "replaced") latest = index; });
+  let changed = false;
+  const next = messages.map((message, index) => {
+    const card = message.rating;
+    if (!card || card.state === "replaced" || index === latest || card.score) return message;
+    changed = true;
+    return { ...message, rating: { ...card, state: "replaced" as const } };
+  });
+  return changed ? next : messages;
+}
+
+/** "hidden" (replaced), "open" (can be answered or changed) or "closed" (read-only: the clock reached `closesAt`; the server decides). */
+export function ratingPhase(block: Pick<GiovRatingBlock, "closesAt" | "state">, now: number): "hidden" | "open" | "closed" {
+  return block.state === "replaced" ? "hidden" : now < block.closesAt ? "open" : "closed";
+}
+
+/** The card the visitor can answer or change now, or null. */
+export function pendingRatingRequest(messages: GiovMessage[], now: number): GiovRatingRequest | null {
+  const cards = supersedeRatings(messages).filter((message) => message.rating && ratingPhase(message.rating, now) === "open");
+  const message = cards[cards.length - 1];
+  const card = message?.rating;
+  if (!message || !card) return null;
+  return {
+    requestId: card.requestId, messageId: message.id, closesAt: card.closesAt, answered: !!card.score,
+    ...(card.url ? { url: card.url } : {}),
+    ...(card.score ? { score: card.score } : {}),
+    ...(card.comment ? { comment: card.comment } : {}),
+  };
+}
+
+/** A refusal for one card: `closed` makes it read-only now, `replaced` hides it. */
+export function markRating(messages: GiovMessage[], requestId: string, kind: "closed" | "replaced", now = Date.now()): GiovMessage[] {
+  return messages.map((message) => {
+    const card = message.rating;
+    if (!card || card.requestId !== requestId) return message;
+    return { ...message, rating: kind === "replaced" ? { ...card, state: "replaced" as const } : { ...card, closesAt: Math.min(card.closesAt, now) } };
+  });
+}
+
+/** What a failed answer means for the card: read-only states, or a message to retry. */
+export function ratingFailure(code: string): "closed" | "replaced" | "retry" {
+  return code === "rating_closed" ? "closed" : code === "request_replaced" ? "replaced" : "retry";
+}
+
+/** What tapping a thumb sends: the same thumb again takes the vote back. */
+export const nextFeedback = (current: "up" | "down" | undefined, tapped: "up" | "down"): GiovFeedbackValue => (current === tapped ? "none" : tapped);
+
+export function applyFeedback(messages: GiovMessage[], id: string, value: GiovFeedbackValue): GiovMessage[] {
+  return messages.map((message) => {
+    if (message.id !== id) return message;
+    const { feedback: _f, ...rest } = message;
+    return value === "none" ? rest : { ...rest, feedback: value };
+  });
+}
+
+/** Thumbs go under finished GiovBot answers, never under the rating request itself. */
+export const canVoteOn = (message: GiovMessage): boolean =>
+  message.role === "agent" && message.isBot === true && !message.isStreaming && !message.id.startsWith("stream:") && !message.rating;
+
+const CODES: Record<string, GiovChatError["code"]> = {
+  invalid_rating: "invalid_rating", invalid_feedback: "invalid_feedback", request_not_found: "request_not_found",
+  message_not_found: "message_not_found", request_replaced: "request_replaced", rating_closed: "rating_closed",
+  too_many_changes: "too_many_changes",
+};
+
+/** The documented refusals of the rating and feedback routes, as typed errors. A 404 without a code is a server that lacks the routes. */
+export function ratingError(status: number, body: unknown, retryAfter?: string | null): GiovChatError {
+  const data = obj(body);
+  const server = typeof data.error === "string" ? data.error : "";
+  const known = CODES[server];
+  const wait = retryAfterSeconds(retryAfter);
+  if (known) return new GiovChatError(known, "Rating was refused.", status, wait);
+  if (status === 404 || status === 405 || status === 501) return new GiovChatError("unsupported", "This chat does not take ratings.", 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, wait);
+  return new GiovChatError("server", "Chat is unavailable. Please try again.", status, wait);
+}
+
+export function parseRatingResult(body: unknown, fallbackRequestId?: string): GiovRatingResult | null {
+  const b = obj(body);
+  const requestId = typeof b.requestId === "string" ? b.requestId : fallbackRequestId;
+  if (!requestId || !isScore(b.score) || typeof b.closesAt !== "number" || !Number.isFinite(b.closesAt)) return null;
+  return {
+    requestId, score: b.score, closesAt: b.closesAt,
+    ...(typeof b.comment === "string" && b.comment ? { comment: b.comment } : {}),
+    ...(typeof b.ratedAt === "number" ? { ratedAt: b.ratedAt } : {}),
+  };
+}

package/src/ratingStore.ts

@@ -0,0 +1,65 @@
+import { useSyncExternalStore } from "react";
+import { GiovChatError } from "./errors";
+import type { GiovFeedbackValue, GiovRatingRequest, GiovRatingResult } from "./types";
+
+/**
+ * What `useGiovRating` returns: the rating card the visitor can answer now, and the calls to answer it
+ * or to open the built-in rating sheet. Each mounted `GiovChat` publishes its own entry under its tenant key.
+ */
+export interface GiovRatingController {
+  /** The open rating card (answered or not) or null: nothing to rate right now. */
+  request: GiovRatingRequest | null;
+  /** False once the server turned out not to take ratings (an older server): hide your own controls. */
+  supported: boolean;
+  /** Rates the conversation; see `GiovChatHandle.submitRating`. */
+  submit(score: number, options?: { comment?: string; requestId?: string }): Promise<GiovRatingResult>;
+  /** Thumbs on a GiovBot answer; see `GiovChatHandle.submitAnswerFeedback`. */
+  submitFeedback(messageId: string, value: GiovFeedbackValue, options?: { reason?: string }): Promise<void>;
+  /** Opens the built-in rating sheet for the open card; false when there is none. */
+  show(): boolean;
+}
+
+const unavailable = () => Promise.reject(new GiovChatError("disconnected", "No chat is mounted."));
+const NONE: GiovRatingController = { request: null, supported: true, submit: unavailable, submitFeedback: unavailable, show: () => false };
+
+const entries = new Map<symbol, { tenantKey: string; value: GiovRatingController }>();
+const listeners = new Set<() => void>();
+const notify = () => { for (const listener of listeners) { try { listener(); } catch { /* Isolated. */ } } };
+
+export function publishRating(owner: symbol, tenantKey: string, value: GiovRatingController): void {
+  entries.set(owner, { tenantKey, value });
+  notify();
+}
+
+export function forgetRating(owner: symbol): void {
+  if (entries.delete(owner)) notify();
+}
+
+export function readRating(tenantKey?: string): GiovRatingController {
+  let found: GiovRatingController | null = null;
+  for (const entry of entries.values()) {
+    if (tenantKey && entry.tenantKey !== tenantKey) continue;
+    // The first mounted chat with a card wins; otherwise the first chat.
+    if (entry.value.request) return entry.value;
+    found ??= entry.value;
+  }
+  return found ?? NONE;
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/**
+ * Conversation rating for a host that draws its own prompt (turn the built-in card off with
+ * `ratingCard={false}`), or wants a button that opens the built-in sheet. Needs a mounted `GiovChat`.
+ *
+ * ```tsx
+ * const rating = useGiovRating();
+ * if (rating.request && !rating.request.answered) return <Button title="Rate us" onPress={rating.show} />;
+ * ```
+ */
+export function useGiovRating(tenantKey?: string): GiovRatingController {
+  return useSyncExternalStore(subscribe, () => readRating(tenantKey), () => NONE);
+}