@repzo/widget-react-native 1.0.0 → 1.0.4

package/src/state/widget-store.ts

@@ -16,12 +16,14 @@ import { getDeviceId, rotateDeviceId } from '../device-id';
 import { EventEmitter, RepzoWidgetEvents } from '../events';
 import { PushManager } from '../push/push-notifications';
 import { CONFIG_KEY, LEGACY_CONFIG_KEY, SecureStorage, Storage, UNREAD_KEY, USER_KEY } from '../storage';
+import { setAttachmentOptions } from '../attachments/pickers';
 import { DEFAULT_BASE_URL } from '../types';
 import type {
   AgentUiAction,
   BootOptions,
   Conversation,
   Message,
+  OutgoingAttachment,
   RepzoWidgetErrorCode,
   WidgetAttachment,
   WidgetConfig,
@@ -33,7 +35,7 @@ import type {
 } from '../types';
 import { setOpenUrlHandler } from '../ui/utils/safe-url';
 
-const SDK_VERSION = '@repzo/widget-react-native@1.0.0';
+const SDK_VERSION = '@repzo/widget-react-native@1.0.4';
 
 /** The platform this session reports — mobile sessions get the Mobile SDKs overrides. */
 function sessionPlatform(): 'ios' | 'android' | 'web' {
@@ -91,6 +93,7 @@ const INITIAL_STATE: WidgetState = {
   prefillText: '',
   outboundMessage: null,
   visitorProfile: {},
+  inAppNotification: null,
 };
 
 /** Everything in state that belongs to the signed-in visitor. */
@@ -110,6 +113,7 @@ const USER_SCOPED_STATE: Partial<WidgetState> = {
   prefillText: '',
   outboundMessage: null,
   visitorProfile: {},
+  inAppNotification: null,
 };
 
 export class WidgetStore {
@@ -136,6 +140,12 @@ export class WidgetStore {
 
   private bootConfig: { baseUrl: string; channelAccountId: string } | null = null;
 
+  /** `boot({ inAppNotifications })` — the card over the app for new replies. */
+  private inAppNotificationsEnabled = true;
+
+  /** The launch card (see showUnreadOnLaunch) is offered once per visitor session. */
+  private launchCardOffered = false;
+
   private bootPromise: Promise<void> | null = null;
 
   /** Identity key of the in-flight boot — a boot for someone else is not deduped. */
@@ -158,6 +168,8 @@ export class WidgetStore {
   private visitorTypingActive = false;
 
   private seenMessageIds: string[] = [];
+  /** Statuses (e.g. "read") that arrived for an id before a send response revealed it. */
+  private earlyStatuses = new Map<string, string>();
 
   /**
    * Identity generation. Bumped whenever boot/login/logout is requested; every
@@ -232,6 +244,9 @@ export class WidgetStore {
 
   getState = (): WidgetState => this.state;
 
+  /** Composer identity: explicit opens reset it; a draft receiving its server ID does not. */
+  getThreadGeneration = (): number => this.threadGeneration;
+
   private setState(patch: Partial<WidgetState> | ((current: WidgetState) => Partial<WidgetState>)) {
     const previous = this.state;
     const resolved = typeof patch === 'function' ? patch(previous) : patch;
@@ -239,6 +254,13 @@ export class WidgetStore {
     // The total is always derived from the per-thread map, so no surface can
     // zero the badge while threads stay unread.
     next.unreadCount = sumUnread(next.unreadByConversation);
+    // The in-app card only lives while the messenger is closed and its thread
+    // is unread — opening the widget, reading the thread (here or on another
+    // device) or logging out all take it down without each path clearing it.
+    const card = next.inAppNotification;
+    if (card && (next.isOpen || !next.unreadByConversation[card.conversationId])) {
+      next.inAppNotification = null;
+    }
     this.state = next;
 
     if (next.unreadCount !== previous.unreadCount) {
@@ -286,6 +308,10 @@ export class WidgetStore {
     }
     const baseUrl = assertSecureBaseUrl(options.baseUrl?.trim() || DEFAULT_BASE_URL);
     if (options.onOpenUrl !== undefined) setOpenUrlHandler(options.onOpenUrl ?? null);
+    if (options.attachments !== undefined) setAttachmentOptions(options.attachments ?? null);
+    if (options.inAppNotifications !== undefined) {
+      this.inAppNotificationsEnabled = options.inAppNotifications !== false;
+    }
 
     const sameTarget =
       this.bootConfig?.baseUrl === baseUrl &&
@@ -496,8 +522,12 @@ export class WidgetStore {
     if (this.pendingConversationId) {
       const conversationId = this.pendingConversationId;
       this.pendingConversationId = null;
+      // Launched into a thread (push tap): that is this session's launch, so
+      // a later silent re-init must not offer the card either.
+      this.launchCardOffered = true;
       void this.openConversation(conversationId);
     } else {
+      this.showUnreadOnLaunch();
       // A re-init after a 401 means the stream was down: catch the open
       // thread up (a no-op when nothing is on screen).
       void this.refreshOpenThread();
@@ -711,6 +741,7 @@ export class WidgetStore {
     this.seenMessageIds = [];
     this.visitorTypingActive = false;
     this.lastTypingPingAt = 0;
+    this.launchCardOffered = false;
     this.setState({ ...USER_SCOPED_STATE });
 
     const token = await this.client.getToken();
@@ -859,7 +890,7 @@ export class WidgetStore {
 
   private handleRealtimeEvent(event: string, data: any) {
     if (
-      (event === 'message.new' || event === 'conversation.event') &&
+      (event === 'message.new' || event === 'message.deleted' || event === 'message.status' || event === 'conversation.event') &&
       this.shouldHoldForDraft(data?.conversationId)
     ) {
       this.draftEvents.push({ event, data });
@@ -886,6 +917,14 @@ export class WidgetStore {
         this.handleNewMessage(data);
         break;
 
+      case 'message.deleted':
+        this.handleDeletedMessage(data);
+        break;
+
+      case 'message.status':
+        this.handleMessageStatus(data);
+        break;
+
       case 'conversation.updated':
         this.rememberConversationAgent(data);
         this.setState((current) => ({
@@ -898,6 +937,7 @@ export class WidgetStore {
                     data.agentAvatar === undefined
                       ? conversation.agentAvatar
                       : this.client.resolveUrl(data.agentAvatar),
+                  agentOnline: data.agentOnline === undefined ? conversation.agentOnline : data.agentOnline,
                 }
               : conversation
           ),
@@ -1015,6 +1055,50 @@ export class WidgetStore {
     return false;
   }
 
+  /**
+   * A teammate deleted a message: the visitor sees "This message was deleted"
+   * in its place (they can't delete anything themselves), and the list is
+   * refreshed so its preview stops showing the text. The id stays in
+   * `seenMessageIds`, so a replayed `message.new` can't restore the content.
+   */
+  /**
+   * A teammate opened the conversation: the visitor's messages are now Seen.
+   * The ids are also remembered, because the event can arrive before the send
+   * response swaps a pending bubble's temporary id for the server id.
+   */
+  private handleMessageStatus(data: any) {
+    const ids: string[] = Array.isArray(data?.messageIds) ? data.messageIds : [];
+    const status: string | undefined = typeof data?.status === 'string' ? data.status : undefined;
+    if (!status || ids.length === 0) return;
+    for (const id of ids) this.earlyStatuses.set(id, status);
+    if (this.earlyStatuses.size > SEEN_MESSAGE_LIMIT) {
+      this.earlyStatuses.delete(this.earlyStatuses.keys().next().value as string);
+    }
+    if (!this.isThreadOnScreen(data?.conversationId)) return;
+    this.setState((current) => ({
+      messages: current.messages.map((message) =>
+        ids.includes(message.id) ? { ...message, status } : message
+      ),
+    }));
+  }
+
+  private handleDeletedMessage(data: any) {
+    const messageId: string | undefined = data?.messageId;
+    if (!messageId) return;
+    if (!this.seenMessageIds.includes(messageId)) this.isReplayedMessage(messageId);
+    if (this.isThreadOnScreen(data?.conversationId)) {
+      this.setState((current) => ({
+        messages: current.messages.map((message) =>
+          message.id === messageId ? asDeletedPlaceholder(message, new Date().toISOString()) : message
+        ),
+      }));
+    }
+    if (this.state.inAppNotification?.messageId === messageId) {
+      this.setState({ inAppNotification: null });
+    }
+    void this.refreshConversations();
+  }
+
   private handleNewMessage(data: any) {
     if (this.isReplayedMessage(data?.messageId)) return;
 
@@ -1031,7 +1115,7 @@ export class WidgetStore {
       body: data?.body || null,
       bodyPlain: data?.bodyPlain || null,
       attachments: this.hydrateAttachments(data?.attachments, messageId),
-      metadata: data?.metadata || null,
+      metadata: this.hydrateMetadata(data?.metadata || null),
       status: 'delivered',
       createdAt: data?.createdAt || new Date().toISOString(),
     };
@@ -1072,7 +1156,9 @@ export class WidgetStore {
         const alreadyPresent = current.messages.some((existing) => existing.id === message.id);
         return {
           conversations,
-          messages: alreadyPresent ? current.messages : [...current.messages, message],
+          messages: alreadyPresent
+            ? adoptServerAttachments(current.messages, [message])
+            : [...current.messages, message],
           agentTyping: clearsTyping ? false : current.agentTyping,
         };
       }
@@ -1086,7 +1172,23 @@ export class WidgetStore {
       this.persistUnread(unreadByConversation);
 
       countedAsUnread = true;
-      return { conversations, unreadByConversation };
+      if (!this.inAppNotificationsEnabled || current.isOpen) {
+        return { conversations, unreadByConversation };
+      }
+      // Newest reply wins: one card, not a stack, like the launcher badge.
+      const conversation = conversations.find((item) => item.id === conversationId);
+      return {
+        conversations,
+        unreadByConversation,
+        inAppNotification: {
+          conversationId,
+          messageId,
+          senderName: message.senderName || conversation?.agentName || null,
+          senderAvatar: conversation?.agentAvatar ?? null,
+          preview: (message.bodyPlain ?? '').trim(),
+          hasAttachments: (message.attachments?.length ?? 0) > 0,
+        },
+      };
     });
 
     // The visitor is reading it live — move the server cursor too, or the
@@ -1329,6 +1431,42 @@ export class WidgetStore {
     this.setState({ prefillText: prefill });
   }
 
+  /**
+   * Replies that arrived while the app was closed get the same card a live
+   * reply would, once per launch — so a visitor without push (not set up on
+   * the channel, or permission denied) still sees them. Only the newest unread
+   * thread; silent re-inits and foreground returns never re-offer it.
+   */
+  private showUnreadOnLaunch(): void {
+    if (this.launchCardOffered || !this.inAppNotificationsEnabled) return;
+    this.launchCardOffered = true;
+    const { isOpen, inAppNotification, conversations, unreadByConversation } = this.state;
+    if (isOpen || inAppNotification) return;
+
+    const time = (conversation: Conversation) =>
+      Date.parse(conversation.lastMessageAt ?? conversation.createdAt) || 0;
+    const newest = conversations
+      .filter((conversation) => (unreadByConversation[conversation.id] ?? 0) > 0)
+      .sort((a, b) => time(b) - time(a))[0];
+    if (!newest) return;
+
+    this.setState({
+      inAppNotification: {
+        conversationId: newest.id,
+        messageId: `launch-${newest.id}`,
+        senderName: newest.agentName,
+        senderAvatar: newest.agentAvatar,
+        preview: (newest.snippet ?? '').trim(),
+        hasAttachments: false,
+      },
+    });
+  }
+
+  /** The visitor swiped the in-app card away; the thread stays unread. */
+  dismissInAppNotification(): void {
+    if (this.state.inAppNotification) this.setState({ inAppNotification: null });
+  }
+
   dismissOutboundMessage(): void {
     const outbound = this.state.outboundMessage;
     if (outbound?.id) this.track('widget_outbound_dismissed', { outboundId: outbound.id });
@@ -1405,11 +1543,10 @@ export class WidgetStore {
         // Live replies and optimistic sends may have arrived since this page
         // was requested. Keep them, preferring the live copy for shared ids.
         const liveIds = new Set(current.messages.map((message) => message.id));
-        const history = this.hydrateMessages(result.data).filter(
-          (message) => !liveIds.has(message.id)
-        );
+        const page = this.hydrateMessages(result.data);
+        const history = page.filter((message) => !liveIds.has(message.id));
         return {
-          messages: sortByCreatedAt([...history, ...current.messages]),
+          messages: sortByCreatedAt([...history, ...adoptServerAttachments(current.messages, page)]),
           messagesLoading: false,
           hasMoreMessages: result.meta.hasMore,
           messageCursor: result.meta.nextCursor,
@@ -1475,7 +1612,11 @@ export class WidgetStore {
       this.setState((current) => {
         const known = new Set(current.messages.map((message) => message.id));
         const missing = fresh.filter((message) => !known.has(message.id));
-        if (missing.length === 0) return {};
+        const upgraded = adoptServerStatuses(
+          adoptServerDeletions(adoptServerAttachments(current.messages, fresh), fresh),
+          fresh
+        );
+        if (missing.length === 0) return upgraded === current.messages ? {} : { messages: upgraded };
 
         const local = current.messages.filter(isLocalMessage);
         const hasServerMessages = local.length < current.messages.length;
@@ -1488,7 +1629,7 @@ export class WidgetStore {
             messageCursor: result.meta.nextCursor,
           };
         }
-        return { messages: sortByCreatedAt([...current.messages, ...missing]) };
+        return { messages: sortByCreatedAt([...upgraded, ...missing]) };
       });
       // The server just moved the read cursor — mirror it locally.
       if (this.state.unreadByConversation[conversationId]) {
@@ -1505,13 +1646,26 @@ export class WidgetStore {
       .map((message) => ({
         ...message,
         attachments: this.hydrateAttachments(message.attachments, message.id),
+        metadata: this.hydrateMetadata(message.metadata),
       }))
       .reverse();
   }
 
+  /** The "joined" line's avatar can be a server-relative media path. */
+  private hydrateMetadata(metadata: Message['metadata']): Message['metadata'] {
+    if (!metadata || typeof metadata.agentAvatar !== 'string') return metadata ?? null;
+    return { ...metadata, agentAvatar: this.client.resolveUrl(metadata.agentAvatar) };
+  }
+
+  /**
+   * Rejects when the message wasn't sent, so the composer can keep
+   * attachments for a retry. A text-only bubble is marked failed; one with
+   * attachments is removed instead — the composer's chips are the retry, and
+   * keeping both would leave a duplicate after a successful resend.
+   */
   async sendMessage(
     body: string,
-    attachments: WidgetAttachment[] = [],
+    attachments: OutgoingAttachment[] = [],
     agentUiAction?: AgentUiAction
   ): Promise<void> {
     const trimmed = body.trim();
@@ -1528,7 +1682,22 @@ export class WidgetStore {
       senderName: visitorProfile.name || 'You',
       body: trimmed ? `<p>${trimmed}</p>` : '',
       bodyPlain: trimmed,
-      attachments: attachments.length > 0 ? attachments : null,
+      // The local preview, never a data URL: the bubble shows up at once and
+      // state never holds megabytes of base64. Without a local file the
+      // bubble shows the name until the server copy replaces it.
+      attachments:
+        attachments.length > 0
+          ? attachments.map((attachment, index) => ({
+              id: `${tempId}-${index}`,
+              name: attachment.name,
+              url:
+                attachment.previewUrl && !/^data:/i.test(attachment.previewUrl)
+                  ? attachment.previewUrl
+                  : '',
+              contentType: attachment.contentType,
+              size: attachment.size,
+            }))
+          : null,
       metadata: null,
       status: 'pending',
       createdAt: new Date().toISOString(),
@@ -1545,9 +1714,12 @@ export class WidgetStore {
 
     const markFailed = () =>
       this.setState((current) => ({
-        messages: current.messages.map((message) =>
-          message.id === tempId ? { ...message, status: 'failed' } : message
-        ),
+        messages:
+          attachments.length > 0
+            ? current.messages.filter((message) => message.id !== tempId)
+            : current.messages.map((message) =>
+                message.id === tempId ? { ...message, status: 'failed' } : message
+              ),
       }));
 
     const epoch = this.epoch;
@@ -1570,7 +1742,7 @@ export class WidgetStore {
       // don't open a thread nobody is looking at.
       if (!conversationId && this.threadGeneration !== generation) {
         markFailed();
-        return;
+        throw new Error('The conversation this message was queued for was never created');
       }
     }
 
@@ -1580,7 +1752,15 @@ export class WidgetStore {
         conversationId: conversationId || undefined,
         forceNewConversation: !conversationId,
         body: trimmed,
-        attachments: attachments.length > 0 ? attachments : undefined,
+        attachments:
+          attachments.length > 0
+            ? attachments.map(({ name, url, contentType, size }) => ({
+                name,
+                url,
+                contentType,
+                size,
+              }))
+            : undefined,
         visitorName: visitorProfile.name,
         visitorEmail: visitorProfile.email,
         agentUiAction,
@@ -1595,7 +1775,9 @@ export class WidgetStore {
         const messages = delivered
           ? current.messages.filter((message) => message.id !== tempId)
           : current.messages.map((message) =>
-              message.id === tempId ? { ...message, id: result.messageId, status: 'sent' } : message
+              message.id === tempId
+                ? { ...message, id: result.messageId, status: this.earlyStatuses.get(result.messageId) ?? 'sent' }
+                : message
             );
 
         if (!createdId) return { messages };
@@ -1736,6 +1918,61 @@ function isLocalMessage(message: Message): boolean {
   return message.id.startsWith('temp-');
 }
 
+/**
+ * A sent visitor message keeps its local previews (a `file://` URI, or no URL
+ * at all) until the server copy shows up — the stream echo or a history page.
+ * Its attachments, the only ones that can be opened, then replace them.
+ */
+/** A "Seen" missed while the stream was down shows up on the next re-read. */
+function adoptServerStatuses(messages: Message[], server: Message[]): Message[] {
+  const seen = new Set(server.filter((message) => message.status === 'read').map((message) => message.id));
+  if (seen.size === 0) return messages;
+  let changed = false;
+  const next = messages.map((message) => {
+    if (!seen.has(message.id) || message.status === 'read') return message;
+    changed = true;
+    return { ...message, status: 'read' };
+  });
+  return changed ? next : messages;
+}
+
+/** Keeps who/when, drops everything the visitor could read. */
+function asDeletedPlaceholder(message: Message, deletedAt: string): Message {
+  return { ...message, body: null, bodyPlain: null, attachments: null, metadata: null, deletedAt };
+}
+
+/** A deletion missed while the stream was down shows up on the next re-read. */
+function adoptServerDeletions(messages: Message[], server: Message[]): Message[] {
+  const deleted = new Map(
+    server.filter((message) => message.deletedAt).map((message) => [message.id, message.deletedAt!])
+  );
+  if (deleted.size === 0) return messages;
+  let changed = false;
+  const next = messages.map((message) => {
+    const deletedAt = deleted.get(message.id);
+    if (!deletedAt || message.deletedAt) return message;
+    changed = true;
+    return asDeletedPlaceholder(message, deletedAt);
+  });
+  return changed ? next : messages;
+}
+
+function adoptServerAttachments(messages: Message[], server: Message[]): Message[] {
+  const serverCopies = new Map(
+    server.filter((message) => message.attachments?.length).map((message) => [message.id, message])
+  );
+  if (serverCopies.size === 0) return messages;
+  let changed = false;
+  const next = messages.map((message) => {
+    const copy = serverCopies.get(message.id);
+    const hasLocal = message.attachments?.some((attachment) => !/^https?:\/\//i.test(attachment.url));
+    if (!copy || !hasLocal) return message;
+    changed = true;
+    return { ...message, attachments: copy.attachments };
+  });
+  return changed ? next : messages;
+}
+
 /** Stable, so same-instant rows keep their order; bad dates sort as oldest. */
 function sortByCreatedAt(messages: Message[]): Message[] {
   const time = (message: Message) => Date.parse(message.createdAt) || 0;

package/src/types.ts

@@ -21,6 +21,12 @@ export interface PreChatField {
   options?: string[];
 }
 
+/** A teammate's face for the stacked header / "Waiting for a teammate" avatars. */
+export interface TeamAvatar {
+  initials: string;
+  avatarUrl: string | null;
+}
+
 export interface WidgetConfig {
   primaryColor: string;
   homeLogoUrl: string | null;
@@ -66,6 +72,10 @@ export interface WidgetConfig {
   identityVerificationEnabled: boolean;
   hmacMandatory: boolean;
   isOnline: boolean;
+  /** Header title while no teammate has joined (and after the conversation closes). */
+  workspaceName?: string | null;
+  /** Up to three teammates shown stacked beside it. Absent on older servers. */
+  teamAvatars?: TeamAvatar[];
 }
 
 /** Received attachments are normalized: a missing `id`/`size` is filled in. */
@@ -77,6 +87,21 @@ export interface WidgetAttachment {
   size: number;
 }
 
+/**
+ * A visitor attachment on its way to `POST /api/widget/messages`. `url` is a
+ * base64 data URL (`data:<mime>;base64,<…>`); the server stores it and echoes
+ * the message back with a regular media URL.
+ */
+export interface OutgoingAttachment {
+  name: string;
+  url: string;
+  contentType: string;
+  /** Decoded bytes. */
+  size: number;
+  /** Local URI the optimistic bubble renders until the server copy exists. */
+  previewUrl?: string;
+}
+
 export interface Conversation {
   id: string;
   subject: string | null;
@@ -87,6 +112,8 @@ export interface Conversation {
   createdAt: string;
   agentName: string | null;
   agentAvatar: string | null;
+  /** The assigned teammate's own presence ("Active"/"Away"); absent on older servers. */
+  agentOnline?: boolean | null;
   /**
    * Agent replies the visitor hasn't seen, computed server-side from their
    * read cursor. Absent on older Workstation deployments — the SDK then falls
@@ -107,6 +134,8 @@ export interface Message {
   metadata?: Record<string, unknown> | null;
   status: string | null;
   createdAt: string;
+  /** Set when a teammate deleted the message; the content fields are then empty. */
+  deletedAt?: string | null;
 }
 
 export interface OutboundMessage {
@@ -178,6 +207,55 @@ export interface BootOptions {
      */
     bundleId?: string;
   };
+  /**
+   * Visitor attachments (photos and files). Works out of the box with
+   * `expo-image-picker` / `expo-document-picker` installed; see
+   * `RepzoWidgetAttachmentOptions` to disable it or bring your own picker.
+   */
+  attachments?: RepzoWidgetAttachmentOptions;
+  /**
+   * Show a card at the bottom of the app when a team reply arrives while the
+   * messenger is closed (default true). It stays until the visitor taps it
+   * (opens the conversation) or swipes it away. Requires
+   * `<RepzoWidgetProvider>` to be mounted.
+   */
+  inAppNotifications?: boolean;
+}
+
+/** An option in the composer's attach menu. */
+export type AttachmentSource = 'photo' | 'camera' | 'file';
+
+/**
+ * A file returned by a host `attachments.pick`. Give `base64` (raw or as a
+ * data URL) or a `uri` the SDK can read (`file://`; read with
+ * `expo-file-system` when installed, else `fetch`).
+ */
+export interface RepzoPickedFile {
+  name: string;
+  /** MIME type, e.g. `image/jpeg`. Guessed from the name when empty. */
+  type: string;
+  /** Bytes, when known — lets an oversized file be refused before it's read. */
+  size?: number;
+  uri?: string;
+  base64?: string;
+}
+
+export interface RepzoWidgetAttachmentOptions {
+  /**
+   * Default true. False hides the attach button. It is also hidden when the
+   * channel turns attachments off in Workstation, or when no picker exists
+   * (no `pick` below and neither `expo-image-picker` nor
+   * `expo-document-picker` installed).
+   */
+  enabled?: boolean;
+  /**
+   * Your own picker, replacing the Expo ones — e.g. `react-native-image-picker`
+   * or `react-native-document-picker`. Resolve `null` or `[]` on cancel. The
+   * SDK still enforces the limits (5 files, 1.5 MB each, 6 MB together).
+   */
+  pick?: (source: AttachmentSource) => Promise<RepzoPickedFile[] | null>;
+  /** Menu options offered with `pick`. Default all three. Ignored without `pick`. */
+  sources?: AttachmentSource[];
 }
 
 // ─── Agent UI blocks ────────────────────────────────────────────────────────
@@ -374,6 +452,8 @@ export interface AgentProcedureForm {
 export type WidgetRealtimeEvent =
   | 'connected'
   | 'message.new'
+  | 'message.deleted'
+  | 'message.status'
   | 'typing.start'
   | 'typing.stop'
   | 'conversation.updated'
@@ -442,4 +522,19 @@ export interface WidgetState {
   outboundMessage: OutboundMessage | null;
   /** Name/email captured from pre-chat or `loginUserWithUserAttributes`. */
   visitorProfile: { name?: string; email?: string; phone?: string };
+  /**
+   * The newest team reply the visitor hasn't seen, shown as a card over the
+   * app. Only set while the messenger is closed and its thread is unread.
+   */
+  inAppNotification: InAppNotification | null;
+}
+
+export interface InAppNotification {
+  conversationId: string;
+  messageId: string;
+  senderName: string | null;
+  senderAvatar: string | null;
+  /** Plain-text preview; empty when the reply was only attachments. */
+  preview: string;
+  hasAttachments: boolean;
 }