@giovchat/react-native 0.2.0 → 0.3.0

package/src/components/RatingCard.tsx

@@ -0,0 +1,219 @@
+import React, { useEffect, useState } from "react";
+import { Text, TextInput, TouchableOpacity, View } from "react-native";
+import type { GiovFeedbackValue, GiovRatingBlock } from "../types";
+import { useGiovChatStrings } from "../i18n";
+import { GiovChatError } from "../errors";
+import { MAX_FEEDBACK_REASON, MAX_RATING_COMMENT, nextFeedback, ratingFailure, ratingPhase } from "../rating";
+import { textOn } from "../color";
+
+/**
+ * The conversation rating card (a `rating` block) and the thumbs under GiovBot answers. The card keeps
+ * the visitor's pick on screen while the answer is on its way and takes it back, with a short message,
+ * when it fails. Faces are emoji, so nothing native is needed (Expo Go included).
+ */
+const FACES = ["😞", "🙁", "😐", "🙂", "😄"];
+
+export type RateFn = (requestId: string, score: number, comment: string) => Promise<void>;
+export type VoteFn = (messageId: string, value: GiovFeedbackValue, reason?: string) => Promise<void>;
+
+export interface RatingCardProps {
+  block: GiovRatingBlock;
+  primaryColor: string;
+  dark: boolean;
+  /** Without it the card is read-only (a hidden or unsupported feature). */
+  onRate?: RateFn;
+  /** Where the card was drawn; sets the test ids. */
+  testIDPrefix?: string;
+}
+
+export function RatingCard({ block, primaryColor, dark, onRate, testIDPrefix = "giov-rating" }: RatingCardProps) {
+  const strings = useGiovChatStrings();
+  const [now, setNow] = useState(() => Date.now());
+  const [pick, setPick] = useState(0);
+  const [comment, setComment] = useState("");
+  const [editing, setEditing] = useState(false);
+  const [pending, setPending] = useState<{ score: number; comment: string } | null>(null);
+  const [error, setError] = useState("");
+  const [lock, setLock] = useState<"" | "closed" | "replaced">("");
+
+  // Read-only from `closesAt` on, without waiting for another render.
+  useEffect(() => {
+    const wait = block.closesAt - Date.now();
+    if (wait <= 0) return;
+    const timer = setTimeout(() => setNow(Date.now()), Math.min(wait, 2 ** 31 - 1));
+    return () => clearTimeout(timer);
+  }, [block.closesAt, now]);
+
+  const ink = dark ? "#f0f0f0" : "#111";
+  const quiet = dark ? "#aaa" : "#555";
+  const border = dark ? "#3a3a3a" : "#d4d4d4";
+  const label = (score: number) => strings.ratingFace(score);
+
+  if (lock === "replaced" || ratingPhase(block, now) === "hidden") return null;
+  const closed = lock === "closed" || ratingPhase(block, now) === "closed";
+  const score = pending?.score ?? block.score;
+  const text = pending ? pending.comment : block.comment;
+
+  if (score && !editing) {
+    return (
+      <View testID={`${testIDPrefix}-done`} accessibilityRole="summary" accessibilityLabel={`${strings.yourRating}: ${label(score)}`} style={{ marginTop: 8, gap: 6 }}>
+        <Text style={{ color: ink, fontSize: 14, fontWeight: "600" }}>
+          <Text accessibilityElementsHidden importantForAccessibility="no-hide-descendants">{FACES[score - 1]} </Text>
+          {strings.ratingThanks} · {label(score)}
+        </Text>
+        {text ? <Text style={{ color: quiet, fontSize: 13 }}>{text}</Text> : null}
+        {!closed && onRate ? (
+          <TouchableOpacity
+            testID={`${testIDPrefix}-change`}
+            accessibilityRole="button"
+            accessibilityLabel={strings.ratingChange}
+            disabled={!!pending}
+            hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
+            onPress={() => { setPick(score); setComment(text ?? ""); setError(""); setEditing(true); }}
+          >
+            <Text style={{ color: primaryColor, fontSize: 13, fontWeight: "600" }}>{strings.ratingChange}</Text>
+          </TouchableOpacity>
+        ) : null}
+      </View>
+    );
+  }
+  if (closed) return <Text testID={`${testIDPrefix}-closed`} style={{ color: quiet, fontSize: 13, marginTop: 8 }}>{strings.ratingClosed}</Text>;
+
+  const submit = async () => {
+    if (!pick || pending || !onRate) return;
+    const next = { score: pick, comment: comment.trim() };
+    setError("");
+    setPending(next);
+    setEditing(false);
+    try {
+      await onRate(block.requestId, next.score, next.comment);
+    } catch (failure) {
+      const code = failure instanceof GiovChatError ? failure.code : "network";
+      const kind = ratingFailure(code);
+      if (kind === "retry") {
+        setEditing(true);
+        setError(code === "too_many_changes" ? strings.ratingTooMany
+          : code === "rate_limited" ? strings.ratingWait(failure instanceof GiovChatError ? failure.retryAfterSeconds ?? 30 : 30)
+          : strings.ratingFailed);
+      } else setLock(kind);
+    } finally {
+      setPending(null);
+    }
+  };
+
+  return (
+    <View testID={`${testIDPrefix}-form`} accessibilityLabel={strings.rateTitle} style={{ marginTop: 8, gap: 8 }}>
+      <View accessibilityRole="radiogroup" accessibilityLabel={strings.yourRating} style={{ flexDirection: "row", gap: 6 }}>
+        {FACES.map((face, index) => {
+          const n = index + 1;
+          return (
+            <TouchableOpacity
+              key={n}
+              testID={`${testIDPrefix}-face-${n}`}
+              accessibilityRole="radio"
+              accessibilityLabel={label(n)}
+              accessibilityState={{ checked: pick === n }}
+              onPress={() => setPick(n)}
+              style={{ width: 44, height: 44, borderRadius: 22, alignItems: "center", justifyContent: "center", borderWidth: pick === n ? 2 : 1, borderColor: pick === n ? primaryColor : border }}
+            >
+              <Text style={{ fontSize: 22 }}>{face}</Text>
+            </TouchableOpacity>
+          );
+        })}
+      </View>
+      <TextInput
+        testID={`${testIDPrefix}-comment`}
+        value={comment}
+        onChangeText={setComment}
+        maxLength={MAX_RATING_COMMENT}
+        multiline
+        placeholder={strings.ratingComment}
+        placeholderTextColor={dark ? "#777" : "#999"}
+        accessibilityLabel={strings.ratingComment}
+        style={{ color: ink, borderWidth: 1, borderColor: border, borderRadius: 10, paddingHorizontal: 10, paddingVertical: 8, fontSize: 14, minHeight: 56, maxHeight: 120 }}
+      />
+      {error ? <Text accessibilityRole="alert" style={{ color: "#dc2626", fontSize: 13 }}>{error}</Text> : null}
+      <View style={{ flexDirection: "row", gap: 12, alignItems: "center" }}>
+        <TouchableOpacity
+          testID={`${testIDPrefix}-send`}
+          accessibilityRole="button"
+          accessibilityLabel={strings.ratingSend}
+          accessibilityState={{ disabled: !pick || !!pending || !onRate }}
+          disabled={!pick || !!pending || !onRate}
+          onPress={submit}
+          style={{ backgroundColor: primaryColor, borderRadius: 8, paddingHorizontal: 18, paddingVertical: 9, opacity: !pick || !onRate ? 0.4 : 1 }}
+        >
+          <Text style={{ color: textOn(primaryColor), fontSize: 14, fontWeight: "600" }}>{strings.ratingSend}</Text>
+        </TouchableOpacity>
+        {block.score ? (
+          <TouchableOpacity testID={`${testIDPrefix}-cancel`} accessibilityRole="button" accessibilityLabel={strings.ratingCancel} onPress={() => setEditing(false)} hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}>
+            <Text style={{ color: quiet, fontSize: 14 }}>{strings.ratingCancel}</Text>
+          </TouchableOpacity>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+/** Thumbs under a GiovBot answer: one vote, changeable; a thumbs-down offers an optional reason. */
+export function AnswerFeedback({ messageId, value, dark, primaryColor, onVote }: {
+  messageId: string; value?: "up" | "down"; dark: boolean; primaryColor: string; onVote: VoteFn;
+}) {
+  const strings = useGiovChatStrings();
+  const [asking, setAsking] = useState(false);
+  const [reason, setReason] = useState("");
+  const [failed, setFailed] = useState(false);
+  const quiet = dark ? "#aaa" : "#555";
+  const tap = async (tapped: "up" | "down") => {
+    const next = nextFeedback(value, tapped);
+    setFailed(false);
+    setReason("");
+    setAsking(next === "down");
+    try { await onVote(messageId, next); } catch { setAsking(false); setFailed(true); }
+  };
+  const sendReason = async () => {
+    setAsking(false);
+    if (reason.trim()) await onVote(messageId, "down", reason.trim()).catch(() => setFailed(true));
+  };
+  return (
+    <View testID={`giov-feedback-${messageId}`} accessibilityRole="toolbar" accessibilityLabel={strings.answerGroup} style={{ marginTop: 2, marginLeft: 52 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+        {(["up", "down"] as const).map((kind) => (
+          <TouchableOpacity
+            key={kind}
+            testID={`giov-feedback-${kind}`}
+            accessibilityRole="button"
+            accessibilityLabel={kind === "up" ? strings.answerGood : strings.answerBad}
+            accessibilityState={{ selected: value === kind }}
+            onPress={() => tap(kind)}
+            hitSlop={{ top: 6, bottom: 6, left: 6, right: 6 }}
+            style={{ width: 36, height: 36, borderRadius: 18, alignItems: "center", justifyContent: "center", backgroundColor: value === kind ? primaryColor : "transparent", opacity: value && value !== kind ? 0.4 : 1 }}
+          >
+            <Text style={{ fontSize: 16 }}>{kind === "up" ? "👍" : "👎"}</Text>
+          </TouchableOpacity>
+        ))}
+        {failed ? <Text accessibilityRole="alert" style={{ color: "#dc2626", fontSize: 12 }}>{strings.answerFailed}</Text> : null}
+      </View>
+      {asking ? (
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8, marginTop: 4 }}>
+          <TextInput
+            testID="giov-feedback-reason"
+            value={reason}
+            onChangeText={setReason}
+            maxLength={MAX_FEEDBACK_REASON}
+            placeholder={strings.answerReason}
+            placeholderTextColor={dark ? "#777" : "#999"}
+            accessibilityLabel={strings.answerReason}
+            style={{ flex: 1, color: dark ? "#f0f0f0" : "#111", borderWidth: 1, borderColor: dark ? "#3a3a3a" : "#d4d4d4", borderRadius: 10, paddingHorizontal: 10, paddingVertical: 6, fontSize: 13 }}
+          />
+          <TouchableOpacity testID="giov-feedback-send" accessibilityRole="button" accessibilityLabel={strings.ratingSend} onPress={sendReason} hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}>
+            <Text style={{ color: primaryColor, fontSize: 13, fontWeight: "600" }}>{strings.ratingSend}</Text>
+          </TouchableOpacity>
+          <TouchableOpacity testID="giov-feedback-skip" accessibilityRole="button" accessibilityLabel={strings.answerSkip} onPress={() => setAsking(false)} hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}>
+            <Text style={{ color: quiet, fontSize: 13 }}>{strings.answerSkip}</Text>
+          </TouchableOpacity>
+        </View>
+      ) : null}
+    </View>
+  );
+}

package/src/errors.ts

@@ -4,7 +4,10 @@ export type GiovChatErrorCode =
   /** `401 invalid_user_hash`: the workspace requires a signed identity and `userHash` is wrong or missing. */
   | "identity_rejected"
   /** `429 rate_limited`: wait `retryAfterSeconds` before trying again. */
-  | "rate_limited";
+  | "rate_limited"
+  /** Ratings and answer feedback (docs/protocol, "Conversation ratings"). `unsupported`: the server has no such routes. */
+  | "unsupported" | "invalid_rating" | "invalid_feedback" | "request_not_found" | "message_not_found"
+  | "request_replaced" | "rating_closed" | "too_many_changes";
 
 export class GiovChatError extends Error {
   constructor(

package/src/i18n.ts

@@ -61,6 +61,29 @@ export interface GiovChatStrings {
   phone: string;
   required: (label: string) => string;
   startChat: string;
+  /** Conversation ratings (the card, the thumbs under GiovBot answers): visible text and screen-reader labels. */
+  rateTitle: string;
+  yourRating: string;
+  /** The five faces, from 1 (Very bad) to 5 (Great). */
+  ratingFace: (score: number) => string;
+  ratingComment: string;
+  ratingSend: string;
+  ratingThanks: string;
+  ratingChange: string;
+  ratingCancel: string;
+  ratingClosed: string;
+  ratingFailed: string;
+  ratingTooMany: string;
+  ratingWait: (seconds: number) => string;
+  answerGroup: string;
+  answerGood: string;
+  answerBad: string;
+  answerReason: string;
+  answerSkip: string;
+  answerFailed: string;
+  closeRating: string;
+  /** Replaces the composer once the team closed the conversation. */
+  startNewConversation: string;
 }
 
 export type GiovChatLocale = "en" | "fr" | "es" | "pt" | "de";
@@ -114,6 +137,26 @@ const en: GiovChatStrings = {
   phone: "Phone",
   required: (label) => `${label} *`,
   startChat: "Start chat",
+  rateTitle: "Rate this conversation",
+  yourRating: "Your rating",
+  ratingFace: (score) => ["Very bad", "Bad", "Okay", "Good", "Great"][score - 1] ?? String(score),
+  ratingComment: "Add a comment (optional)",
+  ratingSend: "Send",
+  ratingThanks: "Thanks",
+  ratingChange: "Change",
+  ratingCancel: "Cancel",
+  ratingClosed: "This rating request has closed.",
+  ratingFailed: "Couldn't send. Please try again.",
+  ratingTooMany: "You have changed this rating too many times.",
+  ratingWait: (seconds) => `Too many requests. Please wait ${seconds} s and try again.`,
+  answerGroup: "Rate this answer",
+  answerGood: "Good answer",
+  answerBad: "Bad answer",
+  answerReason: "What went wrong? (optional)",
+  answerSkip: "Skip",
+  answerFailed: "Couldn't save",
+  closeRating: "Close",
+  startNewConversation: "Start a new conversation",
 };
 
 const fr: GiovChatStrings = {
@@ -165,6 +208,26 @@ const fr: GiovChatStrings = {
   phone: "Téléphone",
   required: (label) => `${label} *`,
   startChat: "Démarrer le chat",
+  rateTitle: "Évaluer cette conversation",
+  yourRating: "Votre note",
+  ratingFace: (score) => ["Très mauvais", "Mauvais", "Moyen", "Bon", "Excellent"][score - 1] ?? String(score),
+  ratingComment: "Ajouter un commentaire (facultatif)",
+  ratingSend: "Envoyer",
+  ratingThanks: "Merci",
+  ratingChange: "Modifier",
+  ratingCancel: "Annuler",
+  ratingClosed: "Cette demande d'évaluation est terminée.",
+  ratingFailed: "Envoi impossible. Réessayez.",
+  ratingTooMany: "Vous avez trop souvent modifié cette note.",
+  ratingWait: (seconds) => `Trop de demandes. Patientez ${seconds} s puis réessayez.`,
+  answerGroup: "Évaluer cette réponse",
+  answerGood: "Bonne réponse",
+  answerBad: "Mauvaise réponse",
+  answerReason: "Qu'est-ce qui n'allait pas ? (facultatif)",
+  answerSkip: "Passer",
+  answerFailed: "Enregistrement impossible",
+  closeRating: "Fermer",
+  startNewConversation: "Démarrer une nouvelle conversation",
 };
 
 const es: GiovChatStrings = {
@@ -216,6 +279,26 @@ const es: GiovChatStrings = {
   phone: "Teléfono",
   required: (label) => `${label} *`,
   startChat: "Iniciar chat",
+  rateTitle: "Valora esta conversación",
+  yourRating: "Tu valoración",
+  ratingFace: (score) => ["Muy mala", "Mala", "Regular", "Buena", "Excelente"][score - 1] ?? String(score),
+  ratingComment: "Añade un comentario (opcional)",
+  ratingSend: "Enviar",
+  ratingThanks: "Gracias",
+  ratingChange: "Cambiar",
+  ratingCancel: "Cancelar",
+  ratingClosed: "Esta solicitud de valoración ha terminado.",
+  ratingFailed: "No se pudo enviar. Inténtalo de nuevo.",
+  ratingTooMany: "Has cambiado esta valoración demasiadas veces.",
+  ratingWait: (seconds) => `Demasiadas solicitudes. Espera ${seconds} s e inténtalo de nuevo.`,
+  answerGroup: "Valora esta respuesta",
+  answerGood: "Buena respuesta",
+  answerBad: "Mala respuesta",
+  answerReason: "¿Qué salió mal? (opcional)",
+  answerSkip: "Omitir",
+  answerFailed: "No se pudo guardar",
+  closeRating: "Cerrar",
+  startNewConversation: "Iniciar una conversación nueva",
 };
 
 const pt: GiovChatStrings = {
@@ -267,6 +350,26 @@ const pt: GiovChatStrings = {
   phone: "Telefone",
   required: (label) => `${label} *`,
   startChat: "Iniciar chat",
+  rateTitle: "Avalie esta conversa",
+  yourRating: "Sua avaliação",
+  ratingFace: (score) => ["Muito ruim", "Ruim", "Regular", "Boa", "Ótima"][score - 1] ?? String(score),
+  ratingComment: "Adicione um comentário (opcional)",
+  ratingSend: "Enviar",
+  ratingThanks: "Obrigado",
+  ratingChange: "Alterar",
+  ratingCancel: "Cancelar",
+  ratingClosed: "Este pedido de avaliação foi encerrado.",
+  ratingFailed: "Não foi possível enviar. Tente novamente.",
+  ratingTooMany: "Você alterou esta avaliação vezes demais.",
+  ratingWait: (seconds) => `Muitas solicitações. Aguarde ${seconds} s e tente novamente.`,
+  answerGroup: "Avalie esta resposta",
+  answerGood: "Boa resposta",
+  answerBad: "Resposta ruim",
+  answerReason: "O que deu errado? (opcional)",
+  answerSkip: "Pular",
+  answerFailed: "Não foi possível salvar",
+  closeRating: "Fechar",
+  startNewConversation: "Iniciar uma nova conversa",
 };
 
 const de: GiovChatStrings = {
@@ -318,6 +421,26 @@ const de: GiovChatStrings = {
   phone: "Telefon",
   required: (label) => `${label} *`,
   startChat: "Chat starten",
+  rateTitle: "Bewerte diese Unterhaltung",
+  yourRating: "Deine Bewertung",
+  ratingFace: (score) => ["Sehr schlecht", "Schlecht", "Okay", "Gut", "Sehr gut"][score - 1] ?? String(score),
+  ratingComment: "Kommentar hinzufügen (optional)",
+  ratingSend: "Senden",
+  ratingThanks: "Danke",
+  ratingChange: "Ändern",
+  ratingCancel: "Abbrechen",
+  ratingClosed: "Diese Bewertungsanfrage ist beendet.",
+  ratingFailed: "Senden fehlgeschlagen. Bitte versuche es erneut.",
+  ratingTooMany: "Du hast diese Bewertung zu oft geändert.",
+  ratingWait: (seconds) => `Zu viele Anfragen. Warte ${seconds} s und versuche es erneut.`,
+  answerGroup: "Bewerte diese Antwort",
+  answerGood: "Gute Antwort",
+  answerBad: "Schlechte Antwort",
+  answerReason: "Was ist schiefgelaufen? (optional)",
+  answerSkip: "Überspringen",
+  answerFailed: "Speichern fehlgeschlagen",
+  closeRating: "Schließen",
+  startNewConversation: "Neue Unterhaltung starten",
 };
 
 export const GIOVCHAT_STRINGS: Readonly<Record<GiovChatLocale, GiovChatStrings>> = { en, fr, es, pt, de };

package/src/index.ts

@@ -4,7 +4,13 @@ export type {
   GiovChatSession,
   GiovChatSessionStorage,
   GiovChatConnectionStatus,
+  GiovAnswerFeedback,
+  GiovFeedbackValue,
   GiovMessage,
+  GiovRatingBlock,
+  GiovRatingRequest,
+  GiovRatingResult,
+  GiovRatingScore,
   GiovWidgetConfig,
   MessageHandler,
   RequestUserInfo,
@@ -26,6 +32,7 @@ export {
 export type {
   ChatClientOptions,
   GiovConversationHistory,
+  GiovConversationState,
   GiovPushOptions,
   GiovPushPlatform,
   GiovPushRegistration,
@@ -59,8 +66,18 @@ export type { GiovChatProps, GiovChatHandle } from "./GiovChat";
 export { useGiovChatUnreadCount } from "./unread";
 export { GIOVCHAT_STRINGS, resolveLocale, resolveStrings } from "./i18n";
 export type { GiovChatLocale, GiovChatStrings } from "./i18n";
+export { useGiovRating } from "./ratingStore";
+export type { GiovRatingController } from "./ratingStore";
+export { MAX_FEEDBACK_REASON, MAX_RATING_COMMENT, nextFeedback, parseRatingFrame, patchRating, pendingRatingRequest, ratingPhase, supersedeRatings } from "./rating";
+export type { GiovRatingFrame } from "./rating";
+export { RatingCard, AnswerFeedback } from "./components/RatingCard";
+export type { RatingCardProps, RateFn, VoteFn } from "./components/RatingCard";
 export { GiovChatError } from "./errors";
 export type { GiovChatErrorCode } from "./errors";
+export { GiovBranding } from "./components/Branding";
+export type { GiovBrandingProps } from "./components/Branding";
+export { FOOTER_MIN_CONTRAST } from "./brandingStyle";
+export type { GiovChatBrandingStyle } from "./brandingStyle";
 export type {
   GiovChatStyleOverrides,
   GiovChatTextStyle,

package/src/protocol.ts

@@ -1,4 +1,5 @@
 import type { GiovMessage } from "./types";
+import { parseRatingBlock } from "./rating";
 import { parseAttachments } from "./attachments";
 import { safeImageUrl } from "./identity";
 
@@ -22,10 +23,14 @@ export function parseMessage(value: unknown): GiovMessage | null {
   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 } : {}),
+  };
+}