@giovchat/react-native 0.0.0-stage → 0.2.0

package/src/types.ts

@@ -0,0 +1,119 @@
+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;
+}
+
+/** 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);
+}