@giovchat/react-native 0.2.0 → 0.3.0

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);
+}

package/src/styleOverrides.ts

@@ -1,4 +1,5 @@
 import type { TextStyle, ViewStyle } from "react-native";
+import type { GiovChatBrandingStyle } from "./brandingStyle";
 
 /** Typography and colors only; text sizing and layout remain SDK-controlled. */
 export type GiovChatTextStyle = Pick<TextStyle, "fontFamily" | "fontWeight" | "fontStyle"> & {
@@ -7,7 +8,7 @@ export type GiovChatTextStyle = Pick<TextStyle, "fontFamily" | "fontWeight" | "f
 
 export type GiovChatBackgroundStyle = { backgroundColor?: string };
 
-/** Plain objects only. No arbitrary React Native styles or branding overrides. */
+/** Plain objects only. No arbitrary React Native styles. */
 export interface GiovChatStyleOverrides {
   /** Default font family for all customizable text. Load the font in your app. */
   fontFamily?: string;
@@ -28,6 +29,11 @@ export interface GiovChatStyleOverrides {
   label?: GiovChatTextStyle;
   hint?: GiovChatTextStyle;
   errorText?: GiovChatTextStyle;
+  /**
+   * The "Powered by GiovChat" footer: font family, text colour, link colour and background. It follows
+   * your app, but stays on (only the plan removes it) and keeps 4.5:1 contrast. Layout, size and text are fixed.
+   */
+  branding?: GiovChatBrandingStyle;
 }
 
 const backgroundSlots = [
@@ -39,7 +45,7 @@ const textSlots = [
 ] as const;
 
 export type ResolvedWidgetStyles = Record<(typeof backgroundSlots)[number], ViewStyle> &
-  Record<(typeof textSlots)[number], TextStyle>;
+  Record<(typeof textSlots)[number], TextStyle> & { branding: GiovChatBrandingStyle };
 
 function record(value: unknown): Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -81,5 +87,12 @@ export function resolveStyleOverrides(value: unknown): ResolvedWidgetStyles {
     }
     result[slot] = style;
   }
+  const footer = record(input.branding);
+  const branding: GiovChatBrandingStyle = {};
+  if (nonEmptyString(input.fontFamily)) branding.fontFamily = input.fontFamily;
+  for (const key of ["fontFamily", "color", "brandColor", "backgroundColor"] as const) {
+    if (nonEmptyString(footer[key])) branding[key] = footer[key] as string;
+  }
+  result.branding = branding;
   return result;
 }

package/src/types.ts

@@ -110,6 +110,57 @@ export interface GiovMessage {
   clientMessageId?: string;
   /** Local only: a GiovBot reply still being written. */
   isStreaming?: boolean;
+  /** The conversation rating card this message carries (team or GiovBot "How did we do?" request). */
+  rating?: GiovRatingBlock;
+  /** The visitor's own thumb on this GiovBot answer. */
+  feedback?: "up" | "down";
+}
+
+/** A score from 1 (Very bad) to 5 (Great). */
+export type GiovRatingScore = 1 | 2 | 3 | 4 | 5;
+
+/** The `rating` block of a message (docs/protocol, "Conversation ratings"). */
+export interface GiovRatingBlock {
+  requestId: string;
+  /** When the card stops accepting answers or changes (epoch ms; the server decides). */
+  closesAt: number;
+  /** A hosted rating page, when the API sent one. The SDK always answers with the visitor token instead. */
+  url?: string;
+  score?: GiovRatingScore;
+  comment?: string;
+  /** `"replaced"`: a newer card took its place; draw nothing. */
+  state?: "replaced";
+}
+
+/** The rating card the visitor can answer or change right now (see `useGiovRating`). */
+export interface GiovRatingRequest {
+  requestId: string;
+  /** The message that carries the card. */
+  messageId: string;
+  closesAt: number;
+  url?: string;
+  /** True once the visitor has answered (the answer can still change until `closesAt`). */
+  answered: boolean;
+  score?: GiovRatingScore;
+  comment?: string;
+}
+
+/** The server's answer to a rating. */
+export interface GiovRatingResult {
+  requestId: string;
+  score: GiovRatingScore;
+  comment?: string;
+  closesAt: number;
+  ratedAt?: number;
+}
+
+/** The visitor's vote on a GiovBot answer. */
+export type GiovFeedbackValue = "up" | "down" | "none";
+
+export interface GiovAnswerFeedback {
+  messageId: string;
+  value: GiovFeedbackValue;
+  reason?: string;
 }
 
 /** Callback invoked for every incoming message. */

package/src/useChatSession.ts

@@ -6,6 +6,7 @@ import {
 } from "./client";
 import { reduceAgentTyping, type AgentTypingState } from "./identity";
 import { chatError, GiovChatError } from "./errors";
+import { applyFeedback, markRating, patchRating, pendingRatingRequest, supersedeRatings } from "./rating";
 import { Outbox, type OutboxEntry } from "./outbox";
 import {
   attachmentDisplayUrl,
@@ -16,7 +17,10 @@ import {
   type GiovAttachmentPreview,
   type GiovChatPickedFile,
 } from "./attachments";
-import type { GiovChatConnectionStatus, GiovChatContact, GiovChatSession, GiovChatSessionStorage, GiovMessage, GiovWidgetConfig, RequestUserInfo } from "./types";
+import type {
+  GiovAnswerFeedback, GiovChatConnectionStatus, GiovChatContact, GiovChatSession, GiovChatSessionStorage, GiovFeedbackValue, GiovMessage,
+  GiovRatingRequest, GiovRatingResult, GiovWidgetConfig, RequestUserInfo,
+} from "./types";
 
 export function missingContactFields(fields: RequestUserInfo = {}, contact: GiovChatContact = {}): RequestUserInfo {
   const missing: RequestUserInfo = {};
@@ -91,6 +95,12 @@ type Options = {
   onConnectionStatusChange?: (status: GiovChatConnectionStatus) => void;
   onConversationStart?: (conversationId: string) => void;
   onUnreadCountChange?: (count: number) => void;
+  /** A rating card the visitor has not answered arrived (live or in the history). Fires once per card. */
+  onRatingRequested?: (request: GiovRatingRequest) => void;
+  /** The visitor's rating was stored. */
+  onRatingSubmitted?: (result: GiovRatingResult) => void;
+  /** The visitor's vote on a GiovBot answer was stored. */
+  onAnswerFeedback?: (feedback: GiovAnswerFeedback) => void;
 };
 
 /**
@@ -160,6 +170,16 @@ export function useChatSession(options: Options) {
   const [uploads, setUploads] = useState<UploadProgress[]>([]);
   const [requiredFields, setRequiredFields] = useState<RequestUserInfo>({});
   const [hasConversation, setHasConversation] = useState(false);
+  // False once the server answered a rating route with 404: an older server, so the controls are hidden.
+  const [ratingsSupported, setRatingsSupported] = useState(true);
+  const [clock, setClock] = useState(0);
+  // The team closed the conversation: it stays on screen, read-only, until the visitor starts a new one.
+  const [closed, setClosed] = useState(false);
+  const closedRef = useRef(false);
+  closedRef.current = closed;
+  const messagesRef = useRef(messages);
+  messagesRef.current = messages;
+  const announcedRatings = useRef(new Set<string>());
   const keepConnected = options.keepConnected === true;
   const wantConnection = foreground && (visible || keepConnected);
 
@@ -257,6 +277,7 @@ export function useChatSession(options: Options) {
     const storageFailure = () => report(new GiovChatError("storage", "Chat session could not be saved or restored."));
     const clearSession = async () => {
       session.current = null;
+      setClosed(false);
       setHasConversation(false);
       setMessages([]);
       try { await sessionStorage?.remove(scope); } catch { storageFailure(); }
@@ -330,13 +351,19 @@ export function useChatSession(options: Options) {
         } catch { storageFailure(); }
       }
       if (!alive()) return;
+      // A 409 on resume means the team closed it: its history is shown read-only when the server still
+      // lets this session read it (a rating card can arrive after the close); otherwise it is forgotten.
+      let resumedClosed = false;
       if (session.current) {
         try { session.current = await createConversation(baseUrl, tenantKey, contact.current, session.current, controller.signal); }
         catch (failure) {
           if (!alive()) return;
           const error = chatError(failure);
-          if (error.code !== "invalid_session" && error.code !== "conversation_closed" && error.status !== 404) throw error;
-          await clearSession();
+          if (error.code === "conversation_closed" && error.status === 409) resumedClosed = true;
+          else {
+            if (error.code !== "invalid_session" && error.code !== "conversation_closed" && error.status !== 404) throw error;
+            await clearSession();
+          }
         }
       }
       if (!alive()) return;
@@ -410,6 +437,22 @@ export function useChatSession(options: Options) {
         if (!event.end && event.content) setTypingState(NOT_TYPING);
       });
       connection.onAttachmentAccess((value) => { if (alive()) captureAccess(value); });
+      // A card was answered or changed on another device, or replaced by a newer one.
+      connection.onRating((frame) => { if (alive()) setMessages((previous) => patchRating(previous, frame)); });
+      // The team closed or reopened the conversation: the switch is immediate (older servers send no status).
+      connection.onConversationState((state) => {
+        if (!alive()) return;
+        if (state.status === "closed") {
+          setClosed(true);
+          setTypingState(NOT_TYPING);
+          setDrafts({});
+          setError(null);
+          setPhase("active");
+        } else if (state.status === "open") {
+          if (closedRef.current) setClosed(false);
+          connection?.flush();
+        }
+      });
       // A stop from the other sender (person or GiovBot) keeps the indicator that is showing.
       connection.onTyping((active, isBot) => {
         if (alive()) setTypingState((current) => reduceAgentTyping(current, { type: active ? "typing" : "typing_end", role: "agent", isBot }));
@@ -428,14 +471,25 @@ export function useChatSession(options: Options) {
         catch (failure) {
           const error = chatError(failure);
           if (error.status === 404) { await forgetConversation(); return; }
+          // A closed conversation this server will not let us read any more: forget it, as before.
+          if (resumedClosed && (error.code === "invalid_session" || error.status === 403)) { await forgetConversation(); return; }
           if (error.code === "invalid_session") { await endSession(error); return; }
           throw failure;
         }
         if (!alive()) return;
-        if (history.closed) { await forgetConversation(); return; }
         captureAccess(history.attachmentAccess);
         setCurrentAgent({ name: history.assignedAgentName ?? null, avatar: history.assignedAgentAvatar ?? null });
         setMessages((previous) => mergeMessages(previous, history.messages));
+        if (history.closed) {
+          // Read-only from here on: the history stays visible and a rating card stays answerable.
+          setClosed(true);
+          setTypingState(NOT_TYPING);
+          setDrafts({});
+          setError(null);
+          setPhase("active");
+          return;
+        }
+        if (closedRef.current) setClosed(false);
         connection?.flush();
       };
       catchUp.current = refreshHistory;
@@ -467,7 +521,8 @@ export function useChatSession(options: Options) {
           }
         }
       });
-      await connection.connect(activeSession);
+      try { await connection.connect(activeSession); }
+      catch (failure) { if (!resumedClosed) throw failure; /* The history below decides whether it can be shown. */ }
       if (!alive()) return;
       await refreshHistory();
     }
@@ -526,6 +581,8 @@ export function useChatSession(options: Options) {
     loadedStorage.current = true;
     outbox.clear();
     localFiles.current.clear();
+    announcedRatings.current.clear();
+    setClosed(false);
     startNow.current = false;
     // Sign-out: the next visitor's conversation must not get this device's notifications.
     lastPush.current = null;
@@ -544,6 +601,33 @@ export function useChatSession(options: Options) {
     retry();
   }, [sessionStorage, scope, report, retry, outbox, stopTyping]);
 
+  /**
+   * Leaves the closed conversation: it is cleared (messages, stored session) and the chat is ready for
+   * a new one, which starts with the visitor's next message. Contact details, the outbox and the push
+   * token are kept. Does nothing while the conversation is open.
+   */
+  const startNew = useCallback(async () => {
+    if (!closedRef.current) return;
+    generation.current++;
+    stopTyping();
+    client.current?.disconnect();
+    client.current = null;
+    catchUp.current = null;
+    session.current = null;
+    startNow.current = false;
+    announcedRatings.current.clear();
+    setClosed(false);
+    setHasConversation(false);
+    setMessages([]);
+    setDrafts({});
+    setTypingState(NOT_TYPING);
+    setCurrentAgent({ name: null, avatar: null });
+    setError(null);
+    try { await sessionStorage?.remove(scope); }
+    catch { report(new GiovChatError("storage", "Saved chat session could not be cleared.")); }
+    retry();
+  }, [sessionStorage, scope, report, retry, stopTyping]);
+
   /**
    * Sends text and files. Files upload first (they need the conversation); the message then waits in
    * the outbox until a socket takes it, so text typed while reconnecting is never lost. Several
@@ -554,6 +638,7 @@ export function useChatSession(options: Options) {
     const trimmed = text.trim();
     if (!trimmed && !files.length) return false;
     const current = phaseRef.current;
+    if (closedRef.current) return false;
     if (current !== "active" && current !== "connecting" && current !== "ready") return false;
     // Uploads need a live conversation; the attach button only appears once one exists.
     if (files.length && !session.current) return false;
@@ -667,8 +752,67 @@ export function useChatSession(options: Options) {
     pushRequest.current = null;
   }, []);
 
+  const noteUnsupported = useCallback((failure: GiovChatError) => { if (failure.code === "unsupported") setRatingsSupported(false); }, []);
+
+  /**
+   * Rates the conversation. `requestId` defaults to the open card (the server picks it when none is
+   * known). Rejects with a `GiovChatError` (`rating_closed`, `request_replaced`, `too_many_changes`,
+   * `invalid_rating`, `rate_limited`, `unsupported`, ...). The card on screen is patched on success and
+   * made read-only or hidden when the server says it is closed or replaced.
+   */
+  const submitRating = useCallback(async (score: number, options: { comment?: string; requestId?: string } = {}): Promise<GiovRatingResult> => {
+    const activeClient = client.current;
+    if (!activeClient) throw new GiovChatError("disconnected", "Chat is not connected.");
+    const requestId = options.requestId ?? pendingRatingRequest(messagesRef.current, Date.now())?.requestId;
+    try {
+      const result = await activeClient.submitRating(score, { comment: options.comment, requestId });
+      setMessages((previous) => patchRating(previous, { requestId: result.requestId, closesAt: result.closesAt, score: result.score, comment: result.comment }));
+      try { callbacks.current.onRatingSubmitted?.(result); } catch { /* Host callbacks are isolated. */ }
+      return result;
+    } catch (failure) {
+      const error = chatError(failure);
+      noteUnsupported(error);
+      if (requestId && error.code === "rating_closed") setMessages((previous) => markRating(previous, requestId, "closed"));
+      if (requestId && error.code === "request_replaced") setMessages((previous) => markRating(previous, requestId, "replaced"));
+      throw error;
+    }
+  }, [noteUnsupported]);
+
+  /** Thumbs on a GiovBot answer, shown at once and taken back if the server refuses. `none` removes the vote. */
+  const submitAnswerFeedback = useCallback(async (messageId: string, value: GiovFeedbackValue, options: { reason?: string } = {}): Promise<void> => {
+    const activeClient = client.current;
+    if (!activeClient) throw new GiovChatError("disconnected", "Chat is not connected.");
+    const before = messagesRef.current.find((message) => message.id === messageId)?.feedback ?? "none";
+    setMessages((previous) => applyFeedback(previous, messageId, value));
+    try {
+      await activeClient.submitAnswerFeedback(messageId, value, options);
+    } catch (failure) {
+      const error = chatError(failure);
+      noteUnsupported(error);
+      setMessages((previous) => applyFeedback(previous, messageId, before));
+      throw error;
+    }
+    try { callbacks.current.onAnswerFeedback?.({ messageId, value, ...(value === "down" && options.reason?.trim() ? { reason: options.reason.trim() } : {}) }); } catch { /* Host callbacks are isolated. */ }
+  }, [noteUnsupported]);
+
   const describe = useCallback((url: string) => localFiles.current.get(url) ?? { filename: "" }, []);
-  const shown = useMemo(() => displayMessages(messages, pending, drafts, describe), [messages, pending, drafts, describe]);
+  // An older card the visitor never answered gives way to a newer one at once.
+  const shown = useMemo(() => supersedeRatings(displayMessages(messages, pending, drafts, describe)), [messages, pending, drafts, describe]);
+  const ratingRequest = useMemo(() => pendingRatingRequest(messages, Date.now()), [messages, clock]); // eslint-disable-line react-hooks/exhaustive-deps
+  // The card closes by the clock: look again at `closesAt`.
+  useEffect(() => {
+    if (!ratingRequest) return;
+    const wait = ratingRequest.closesAt - Date.now();
+    if (wait <= 0) return;
+    const timer = setTimeout(() => setClock((value) => value + 1), Math.min(wait + 50, 2 ** 31 - 1));
+    return () => clearTimeout(timer);
+  }, [ratingRequest]);
+  // "Rating requested" once per card the visitor has not answered.
+  useEffect(() => {
+    if (!ratingRequest || ratingRequest.answered || announcedRatings.current.has(ratingRequest.requestId)) return;
+    announcedRatings.current.add(ratingRequest.requestId);
+    try { callbacks.current.onRatingRequested?.(ratingRequest); } catch { /* Host callbacks are isolated. */ }
+  }, [ratingRequest]);
   // A conversation open for a long time: without a usable access token, images fall back to the
   // 15-minute visitor token. Renew it when messages arrive and it is close to expiry, at most once a
   // minute (the web widget's rule); the new URLs make failed images load again.
@@ -691,5 +835,7 @@ export function useChatSession(options: Options) {
     currentAgentName: currentAgent.name, currentAgentAvatar: currentAgent.avatar, unreadCount: visible ? 0 : unreadCount,
     lastIncoming,
     retry, reset, submitContact, send, retryMessage, discardMessage, notifyTyping, attachmentUrl, registerPushToken, unregisterPushToken,
+    ratingRequest, ratingsSupported, submitRating, submitAnswerFeedback,
+    closed, startNew,
   };
 }