@giovchat/react-native 0.0.0-stage → 0.3.0

package/src/styleOverrides.ts

@@ -0,0 +1,98 @@
+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"> & {
+  color?: string;
+};
+
+export type GiovChatBackgroundStyle = { backgroundColor?: string };
+
+/** 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;
+  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;
+  /**
+   * 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 = [
+  "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> & { branding: GiovChatBrandingStyle };
+
+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;
+  }
+  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

@@ -0,0 +1,170 @@
+import type { GiovAttachment, GiovAttachmentPolicy } from "./attachments";
+
+/**
+ * Fields the agent has configured as required in the pre-chat form.
+ * Mirrors the dashboard "Pre-chat form" settings.
+ */
+export interface RequestUserInfo {
+  email?: boolean;
+  phone?: boolean;
+  firstName?: boolean;
+  lastName?: boolean;
+}
+
+/**
+ * Contact information for the current user.
+ *
+ * Pass this to `GiovChat` via the `contact` prop to automatically identify
+ * the visitor and skip (or pre-fill) any required pre-chat fields.
+ */
+export interface GiovChatContact {
+  /**
+   * Your stable user id. On its own it is only a claim: the API stores it for
+   * agents but does not link the chat to an existing contact. Pass `userHash`
+   * as well to have it verified.
+   */
+  userId?: string;
+  /**
+   * HMAC-SHA256 of `userId` (hex) using the workspace's visitor identity
+   * secret from Settings → Chat widget → Visitor details. Compute it on YOUR backend;
+   * never ship the secret in the app.
+   */
+  userHash?: string;
+  email?: string;
+  phone?: string;
+  firstName?: string;
+  lastName?: string;
+}
+
+/** Private visitor credential. Never log it or share it across users. */
+export interface GiovChatSession {
+  conversationId: string;
+  sessionToken: string;
+}
+
+/** Optional host-owned secure persistence. The scope separates API, tenant, identity and reset key. */
+export interface GiovChatSessionStorage {
+  load(scope: string): Promise<GiovChatSession | null>;
+  save(scope: string, session: GiovChatSession): Promise<void>;
+  remove(scope: string): Promise<void>;
+}
+
+export type GiovChatConnectionStatus = "connecting" | "connected" | "disconnected";
+
+/**
+ * Widget configuration returned by `GET /widget/config`.
+ * All values are set by the agent in their dashboard.
+ */
+export interface GiovWidgetConfig {
+  /** Primary brand color (hex or CSS color). */
+  primaryColor: string;
+  /** Display name shown in the chat header. */
+  title: string;
+  /** Greeting message shown at the top of the conversation. */
+  greetingText: string;
+  /** Placeholder text for the message composer. */
+  textArea?: string;
+  /** Display name for the AI bot, when the GiovBot add-on is enabled. */
+  botName?: string;
+  /** True when GiovBot is turned on and included in the tenant's plan. */
+  botEnabled?: boolean;
+  /** The published GiovBot agent's avatar; the header shows the bot while it answers. */
+  botAvatarUrl?: string;
+  /** What visitors may attach, from the published agent's settings. Absent: images only. */
+  attachments?: GiovAttachmentPolicy;
+  /** URL of the agent/team avatar image. */
+  avatarUrl?: string;
+  /** Color theme. `"auto"` follows the device system setting. */
+  theme: "light" | "dark" | "auto";
+  /** Server-resolved plan policy. Only an explicit false removes GiovChat branding. */
+  showBranding?: boolean;
+  /** The workspace's privacy policy (https only); the header menu links to it, else to Giov's. */
+  privacyPolicyUrl?: string;
+  /** Which contact fields the agent requires before starting a chat. */
+  requestUserInfo?: RequestUserInfo;
+}
+
+/** A single message in a conversation. */
+export interface GiovMessage {
+  /** Unique message identifier. */
+  id: string;
+  /** Who sent the message. */
+  role: "visitor" | "agent";
+  /** Message body: Chat Markdown, as the web widget renders it. */
+  content: string;
+  /** Unix timestamp in milliseconds. */
+  createdAt: number;
+  /** `true` when this message was sent by the AI bot. */
+  isBot?: boolean;
+  /** System-generated delivery. AI replies may set both this flag and `isBot`. */
+  isAutomated?: boolean;
+  /** Display name of the human agent, when available. */
+  senderName?: string | null;
+  /** Photo of the human agent (http(s) only), when available. */
+  senderAvatar?: string | null;
+  /** Files sent with the message. */
+  attachments?: GiovAttachment[];
+  /** Local only: "sending" until the server confirms it, "failed" when it could not be delivered. */
+  status?: "sending" | "failed";
+  /** Local only: the id it was shown under before the server confirmed it (keeps list keys stable). */
+  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. */
+export type MessageHandler = (message: GiovMessage) => void;
+
+/** Callback invoked when the WebSocket connection status changes. */
+export type StatusHandler = (connected: boolean) => void;

package/src/unread.ts

@@ -0,0 +1,39 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Unread agent replies per mounted chat, so any screen can show a badge without a provider. Each
+ * `GiovChat` publishes its own count under its tenant key; the hook sums them (normally one).
+ */
+const counts = new Map<symbol, { tenantKey: string; count: number }>();
+const listeners = new Set<() => void>();
+const notify = () => { for (const listener of listeners) { try { listener(); } catch { /* Isolated. */ } } };
+
+export function publishUnreadCount(owner: symbol, tenantKey: string, count: number): void {
+  const current = counts.get(owner);
+  if (current && current.tenantKey === tenantKey && current.count === count) return;
+  counts.set(owner, { tenantKey, count });
+  notify();
+}
+
+export function forgetUnreadCount(owner: symbol): void {
+  if (counts.delete(owner)) notify();
+}
+
+export function readUnreadCount(tenantKey?: string): number {
+  let total = 0;
+  for (const entry of counts.values()) if (!tenantKey || entry.tenantKey === tenantKey) total += entry.count;
+  return total;
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+/**
+ * Agent replies the visitor has not seen because the chat was closed. Counts only while a mounted
+ * `GiovChat` stays connected when hidden (`keepConnected`); opening the chat clears it.
+ */
+export function useGiovChatUnreadCount(tenantKey?: string): number {
+  return useSyncExternalStore(subscribe, () => readUnreadCount(tenantKey), () => 0);
+}