@repzo/widget-react-native 1.3.1 → 1.4.0

package/src/state/widget-store.ts

@@ -10,13 +10,22 @@
 
 import { AppState, type AppStateStatus, Platform } from 'react-native';
 
-import { isTerminalErrorCode, RepzoWidgetError, WidgetApiClient } from '../api/client';
+import { isTerminalErrorCode, RepzoWidgetError, WidgetApiClient, type UploadedFile } from '../api/client';
 import { WidgetRealtime } from '../api/realtime';
 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 {
+  CONFIG_KEY,
+  LAST_MESSAGE_KEY,
+  LEGACY_CONFIG_KEY,
+  SecureStorage,
+  Storage,
+  UNREAD_KEY,
+  USER_KEY,
+} from '../storage';
+import { clearLocalPreviews, rememberLocalPreview } from '../attachments/local-previews';
+import { guessContentType, isImageAttachment, setAttachmentOptions } from '../attachments/pickers';
 import { DEFAULT_BASE_URL } from '../types';
 import type {
   AgentUiAction,
@@ -37,11 +46,13 @@ import type {
   WidgetUser,
   WidgetView,
 } from '../types';
+import { clearRetainedState } from '../ui/hooks/use-retained-state';
 import { canRetryMessage, isLocalMessage } from '../ui/utils/conversations';
+import { stripHtml } from '../ui/utils/html';
 import { setOpenUrlHandler } from '../ui/utils/safe-url';
 
 /** Sent on every init; must match `package.json` (tests/version.test.js checks). */
-const SDK_VERSION = '@repzo/widget-react-native@1.3.1';
+const SDK_VERSION = '@repzo/widget-react-native@1.4.0';
 
 /** The platform this session reports — mobile sessions get the Mobile SDKs overrides. */
 function sessionPlatform(): 'ios' | 'android' | 'web' {
@@ -62,6 +73,12 @@ const TYPING_SETTLE_MS = 3_000;
 const TYPING_PING_INTERVAL_MS = 4_000;
 /** Guards against the SSE stream replaying messages after a reconnect. */
 const SEEN_MESSAGE_LIMIT = 100;
+/** Threads whose newest message is remembered across launches. */
+const LAST_MESSAGE_LIMIT = 50;
+/** How far the phone's clock may be from Workstation's for a sent message to still match the list. */
+const SAME_MESSAGE_DRIFT_MS = 120_000;
+/** How far the list's `lastMessageAt` may trail the message's own `createdAt` (7 ms seen live). */
+const LIST_LAG_MS = 1_000;
 /** Logout's server calls are best-effort — a dead network must not block sign-out. */
 const LOGOUT_REQUEST_TIMEOUT_MS = 5_000;
 /** A server that 401s every fresh stream must not spin init (10/min limit). */
@@ -174,6 +191,10 @@ export class WidgetStore {
 
   /** `boot({ posts })` — Send posts over the app. */
   private postsEnabled = true;
+  /** `boot({ photoAlbums })` — a message's photos share one album in the thread. */
+  private photoAlbumsEnabled = true;
+  /** `boot({ youPrefix })` — "You:" before the visitor's own newest message in the lists. */
+  private youPrefixEnabled = true;
 
   /** Posts whose view was reported this session (the server also dedupes per day). */
   private viewedPostIds = new Set<string>();
@@ -236,6 +257,11 @@ export class WidgetStore {
   private visitorTypingActive = false;
 
   private seenMessageIds: string[] = [];
+
+  /** Who sent each thread's newest message and what it carried; see `withLastMessage`. */
+  private lastMessages: Record<string, LastMessageHint> = {};
+
+  private lastMessagesLoaded = false;
   /** Statuses (e.g. "read") that arrived for an id before a send response revealed it. */
   private earlyStatuses = new Map<string, string>();
   /** The agent UI action behind a failed bubble, so Retry runs it again too. */
@@ -321,6 +347,10 @@ export class WidgetStore {
   /** Composer identity: explicit opens reset it; a draft receiving its server ID does not. */
   getThreadGeneration = (): number => this.threadGeneration;
 
+  showsPhotoAlbums = (): boolean => this.photoAlbumsEnabled;
+
+  showsYouPrefix = (): boolean => this.youPrefixEnabled;
+
   private setState(patch: Partial<WidgetState> | ((current: WidgetState) => Partial<WidgetState>)) {
     const previous = this.state;
     const resolved = typeof patch === 'function' ? patch(previous) : patch;
@@ -394,6 +424,8 @@ export class WidgetStore {
     if (options.inAppNotifications !== undefined) {
       this.inAppNotificationsEnabled = options.inAppNotifications !== false;
     }
+    if (options.photoAlbums !== undefined) this.photoAlbumsEnabled = options.photoAlbums !== false;
+    if (options.youPrefix !== undefined) this.youPrefixEnabled = options.youPrefix !== false;
     if (options.posts !== undefined) {
       const wasEnabled = this.postsEnabled;
       this.postsEnabled = options.posts !== false;
@@ -555,15 +587,15 @@ export class WidgetStore {
     ]);
     if (this.isStale(epoch)) return;
 
-    const conversations = result.conversations.map((conversation) =>
-      this.hydrateConversation(conversation)
-    );
-
     // Server counts win (they include replies pushed while the app was
     // killed); the locally persisted map only covers older Workstation
     // deployments that don't send unreadCount yet.
-    const storedUnread = await this.loadUnread();
+    const [, storedUnread] = await Promise.all([this.loadLastMessages(epoch), this.loadUnread()]);
     if (this.isStale(epoch)) return;
+    const conversations = result.conversations.map((conversation) =>
+      this.hydrateConversation(conversation)
+    );
+
     const unreadByConversation: Record<string, number> = {};
     for (const conversation of conversations) {
       const count =
@@ -851,11 +883,15 @@ export class WidgetStore {
     this.userKeyLoaded = true;
     this.pendingAgentByConversation = {};
     this.seenMessageIds = [];
+    this.lastMessages = {};
+    this.lastMessagesLoaded = false;
     this.earlyStatuses.clear();
     this.visitorTypingActive = false;
     this.lastTypingPingAt = 0;
     this.launchCardOffered = false;
     this.resetPost();
+    clearLocalPreviews();
+    clearRetainedState();
     this.setState({ ...USER_SCOPED_STATE });
 
     const token = await this.client.getToken();
@@ -863,6 +899,7 @@ export class WidgetStore {
       this.client.clearToken(),
       SecureStorage.removeItem(USER_KEY),
       Storage.removeItem(UNREAD_KEY),
+      Storage.removeItem(LAST_MESSAGE_KEY),
       // A new anonymous visitor on this device gets a new tracking identity.
       rotateDeviceId(),
     ]);
@@ -1284,6 +1321,7 @@ export class WidgetStore {
 
     // Set inside the updater, read after: `setState` runs synchronously.
     let countedAsUnread = false;
+    const rowFields = rowFieldsOf(message);
 
     this.setState((current) => {
       const conversations = conversationId
@@ -1291,10 +1329,7 @@ export class WidgetStore {
             conversation.id === conversationId
               ? {
                   ...conversation,
-                  snippet:
-                    message.messageType === 'message'
-                      ? message.bodyPlain || conversation.snippet
-                      : conversation.snippet,
+                  ...rowFields,
                   lastMessageAt: message.createdAt,
                   messageCount: conversation.messageCount + 1,
                 }
@@ -1336,12 +1371,14 @@ export class WidgetStore {
           messageId,
           senderName: message.senderName || conversation?.agentName || null,
           senderAvatar: conversation?.agentAvatar ?? null,
-          preview: (message.bodyPlain ?? '').trim(),
+          preview: plainTextOf(message),
           hasAttachments: (message.attachments?.length ?? 0) > 0,
         },
       };
     });
 
+    if (conversationId && rowFields) this.rememberLastMessage(conversationId, message.createdAt, rowFields, 'stream');
+
     // The visitor is reading it live — move the server cursor too, or the
     // next list/init would badge a reply they already saw.
     if ((onScreen || readInPost) && isTeamReply && conversationId) this.scheduleMarkRead(conversationId);
@@ -1438,10 +1475,116 @@ export class WidgetStore {
   }
 
   private hydrateConversation(conversation: Conversation): Conversation {
-    return this.applyConversationAgent({
+    return this.applyConversationAgent(
+      this.withLastMessage({
+        ...conversation,
+        agentAvatar: this.client.resolveUrl(conversation.agentAvatar),
+      })
+    );
+  }
+
+  /**
+   * Workstation's list doesn't say who sent the newest message, and calls one
+   * without words "2 attachments". While a row still describes the message
+   * this device saw last, both are filled in from it. `snippet` keeps the
+   * list's words: apps read it, and the lists draw "Photo" or "File" from
+   * `lastMessageAttachment` instead.
+   */
+  private withLastMessage(conversation: Conversation): Conversation {
+    const known = this.lastMessages[conversation.id];
+    if (!known || !describesSameMessage(conversation, known)) return conversation;
+    // A list that says who sent it, or what it carried, is used as is.
+    return {
       ...conversation,
-      agentAvatar: this.client.resolveUrl(conversation.agentAvatar),
+      lastMessageFromVisitor: conversation.lastMessageFromVisitor ?? known.fromVisitor,
+      lastMessageAttachment:
+        conversation.lastMessageAttachment !== undefined ? conversation.lastMessageAttachment : known.attachment,
+    };
+  }
+
+  /**
+   * A send or a streamed message is the newest by arrival, whatever the two
+   * clocks say; a history page only replaces something older. A sent message
+   * is timed by the phone, which may run ahead of Workstation, so instead a
+   * page that has it replaces it: whatever is newest there came after it, and
+   * Workstation's own time then stands in for the phone's.
+   */
+  private rememberLastMessage(
+    conversationId: string,
+    at: string,
+    fields: LastMessageFields,
+    source: 'sent' | 'stream' | 'history',
+    { messageId, pageIds }: { messageId?: string; pageIds?: ReadonlySet<string> } = {}
+  ): void {
+    const known = this.lastMessages[conversationId];
+    if (source === 'history' && known) {
+      const outdated =
+        known.phoneClock && known.messageId
+          ? !pageIds?.has(known.messageId)
+          : Date.parse(known.at) > Date.parse(at);
+      if (outdated) return;
+    }
+    const hint: LastMessageHint = {
+      at,
+      fromVisitor: !!fields.lastMessageFromVisitor,
+      attachment: fields.lastMessageAttachment ?? null,
+      ...(source === 'sent' ? { phoneClock: true, ...(messageId ? { messageId } : {}) } : {}),
+    };
+    this.lastMessages = Object.fromEntries(
+      Object.entries({ ...this.lastMessages, [conversationId]: hint })
+        .sort(([, a], [, b]) => Date.parse(b.at) - Date.parse(a.at))
+        .slice(0, LAST_MESSAGE_LIMIT)
+    );
+    // Until the stored hints are read, saving would overwrite them with these alone.
+    if (this.lastMessagesLoaded) void Storage.setItem(LAST_MESSAGE_KEY, JSON.stringify(this.lastMessages));
+  }
+
+  private async loadLastMessages(epoch: number): Promise<void> {
+    if (this.lastMessagesLoaded) return;
+    let stored: unknown = null;
+    try {
+      stored = JSON.parse((await Storage.getItem(LAST_MESSAGE_KEY)) ?? 'null');
+    } catch {
+      stored = null;
+    }
+    // Left unloaded: the init that replaces this one reads them again.
+    if (this.isStale(epoch) || this.lastMessagesLoaded) return;
+    this.lastMessagesLoaded = true;
+    const learned = Object.keys(this.lastMessages).length > 0;
+    if (stored && typeof stored === 'object') {
+      for (const [conversationId, hint] of Object.entries(stored as Record<string, Partial<LastMessageHint>>)) {
+        if (typeof hint?.at !== 'string' || typeof hint.fromVisitor !== 'boolean') continue;
+        const known = this.lastMessages[conversationId];
+        if (known && Date.parse(known.at) >= Date.parse(hint.at)) continue;
+        this.lastMessages[conversationId] = {
+          at: hint.at,
+          fromVisitor: hint.fromVisitor,
+          attachment: hint.attachment === 'photo' || hint.attachment === 'file' ? hint.attachment : null,
+          ...(hint.phoneClock === true ? { phoneClock: true } : {}),
+          ...(typeof hint.messageId === 'string' ? { messageId: hint.messageId } : {}),
+        };
+      }
+    }
+    // Hints learned while the stored ones were being read are saved with them.
+    if (learned) void Storage.setItem(LAST_MESSAGE_KEY, JSON.stringify(this.lastMessages));
+  }
+
+  /** A thread's newest page shows who sent its newest message, so its row can say too. */
+  private learnLastMessage(conversationId: string, page: Message[]): void {
+    let newest: Message | null = null;
+    for (const message of page) {
+      if (!newest || Date.parse(message.createdAt) > Date.parse(newest.createdAt)) newest = message;
+    }
+    const fields = newest && rowFieldsOf(newest);
+    if (!newest || !fields) return;
+    this.rememberLastMessage(conversationId, newest.createdAt, fields, 'history', {
+      pageIds: new Set(page.map((message) => message.id)),
     });
+    this.setState((current) => ({
+      conversations: current.conversations.map((row) =>
+        row.id === conversationId ? this.withLastMessage(row) : row
+      ),
+    }));
   }
 
   /**
@@ -1452,21 +1595,30 @@ export class WidgetStore {
     if (!Array.isArray(attachments) || attachments.length === 0) return null;
     const hydrated = attachments
       .filter((item): item is Record<string, unknown> => !!item && typeof item === 'object')
-      .map((attachment, index) => ({
-        ...attachment,
-        id:
-          typeof attachment.id === 'string' || typeof attachment.id === 'number'
-            ? String(attachment.id)
-            : `${messageId ?? 'attachment'}-${index}`,
-        name:
-          typeof attachment.name === 'string' && attachment.name ? attachment.name : 'Attachment',
-        contentType: typeof attachment.contentType === 'string' ? attachment.contentType : '',
-        size: typeof attachment.size === 'number' ? attachment.size : 0,
-        // Empty (never the raw value) when the URL isn't http(s) — the preview
-        // then renders the name only, with nothing to open.
-        url:
-          this.client.resolveUrl(typeof attachment.url === 'string' ? attachment.url : null) ?? '',
-      }));
+      .map((attachment, index) => {
+        const name =
+          typeof attachment.name === 'string' && attachment.name ? attachment.name : 'Attachment';
+        const declared = typeof attachment.contentType === 'string' ? attachment.contentType : '';
+        return {
+          ...attachment,
+          id:
+            typeof attachment.id === 'string' || typeof attachment.id === 'number'
+              ? String(attachment.id)
+              : `${messageId ?? 'attachment'}-${index}`,
+          name,
+          // Without a type (or with a generic one) the name says what it is,
+          // so a photo still shows as a photo rather than a file row.
+          contentType:
+            declared && !/^application\/octet-stream$/i.test(declared)
+              ? declared
+              : (guessContentType(name) ?? declared),
+          size: typeof attachment.size === 'number' ? attachment.size : 0,
+          // Empty (never the raw value) when the URL isn't http(s) — the preview
+          // then renders the name only, with nothing to open.
+          url:
+            this.client.resolveUrl(typeof attachment.url === 'string' ? attachment.url : null) ?? '',
+        };
+      });
     return hydrated.length > 0 ? hydrated : null;
   }
 
@@ -1707,10 +1859,10 @@ export class WidgetStore {
       const result = await this.client.listMessages(conversationId);
       // Opening A then B quickly: A's page must never land under B.
       if (this.isStale(epoch) || this.threadGeneration !== generation) return;
+      const page = this.hydrateMessages(result.data);
       this.setState((current) => {
         // Live replies and optimistic sends may have arrived since this page
         // was requested. Keep them, preferring the live copy for shared ids.
-        const page = this.hydrateMessages(result.data);
         const live = adoptOwnServerRows(current.messages, page);
         const liveIds = new Set(live.map((message) => message.id));
         const history = page.filter((message) => !liveIds.has(message.id));
@@ -1721,6 +1873,7 @@ export class WidgetStore {
           messageCursor: result.meta.nextCursor,
         };
       });
+      this.learnLastMessage(conversationId, page);
     } catch {
       if (!this.isStale(epoch) && this.threadGeneration === generation) {
         this.setState({ messagesLoading: false });
@@ -1778,6 +1931,7 @@ export class WidgetStore {
       if (this.state.activeConversationId !== conversationId) return;
 
       const fresh = this.hydrateMessages(result.data);
+      this.learnLastMessage(conversationId, fresh);
       this.setState((current) => {
         const own = adoptOwnServerRows(current.messages, fresh);
         const known = new Set(own.map((message) => message.id));
@@ -1956,6 +2110,18 @@ export class WidgetStore {
     return this.deliverMessage(tempId, trimmed, attachments, agentUiAction);
   }
 
+  /**
+   * Puts a picked file in storage while the visitor is still writing, so
+   * Send goes out at once. Resolves the token `sendMessage` names it by, and
+   * when that token expires.
+   */
+  uploadAttachment(
+    file: { uri: string; name: string; contentType: string; size: number },
+    signal?: AbortSignal
+  ): Promise<UploadedFile> {
+    return this.client.uploadAttachment(file, signal);
+  }
+
   /**
    * Re-sends a text bubble that failed. It moves to the end of the thread,
    * since it now goes out after anything sent meanwhile. Rejects like
@@ -2023,17 +2189,21 @@ export class WidgetStore {
 
     let createdId: string | null = null;
     try {
-      // Local files go up first; the message names each by its upload token.
+      // Local files go up first, unless the composer already put them up; the
+      // message names each by its upload token.
       const sentAttachments = await Promise.all(
-        attachments.map(async ({ name, url, fileUri, contentType, size }) =>
-          fileUri
-            ? {
-                name,
-                contentType,
-                size,
-                uploadToken: await this.client.uploadAttachment({ uri: fileUri, name, contentType, size }),
-              }
-            : { name, url, contentType, size }
+        attachments.map(async ({ name, url, fileUri, uploadToken, contentType, size }) =>
+          uploadToken
+            ? { name, contentType, size, uploadToken }
+            : fileUri
+              ? {
+                  name,
+                  contentType,
+                  size,
+                  uploadToken: (await this.client.uploadAttachment({ uri: fileUri, name, contentType, size }))
+                    .uploadToken,
+                }
+              : { name, url, contentType, size }
         )
       );
       if (this.isStale(epoch)) return;
@@ -2052,6 +2222,10 @@ export class WidgetStore {
       if (this.isStale(epoch)) return;
       if (ownCreation) createdId = result.conversationId;
 
+      // Workstation doesn't stream the visitor's own messages back, so the
+      // list row learns about this one here.
+      const sentAt = new Date().toISOString();
+      const sentRow = rowFieldsFor(trimmed, attachments.map((attachment) => attachment.contentType), true);
       this.setState((current) => {
         // The stream or a catch-up fetch may have delivered this message
         // already — keep one copy, never two bubbles with the same id.
@@ -2064,19 +2238,27 @@ export class WidgetStore {
                 : message
             );
 
-        if (!createdId) return { messages };
+        if (!createdId) {
+          return {
+            messages,
+            conversations: current.conversations.map((row) =>
+              row.id === result.conversationId
+                ? { ...row, ...sentRow, lastMessageAt: sentAt, messageCount: row.messageCount + (delivered ? 0 : 1) }
+                : row
+            ),
+          };
+        }
 
         const known = current.conversations.some((item) => item.id === result.conversationId);
         const conversation: Conversation = {
           id: result.conversationId,
           subject: null,
           status: 'open',
-          snippet: trimmed
-            ? trimmed.slice(0, 100)
-            : `${attachments.length} attachment${attachments.length === 1 ? '' : 's'}`,
+          snippet: null,
+          ...sentRow,
           messageCount: 1,
-          lastMessageAt: new Date().toISOString(),
-          createdAt: new Date().toISOString(),
+          lastMessageAt: sentAt,
+          createdAt: sentAt,
           agentName: null,
           agentAvatar: null,
         };
@@ -2092,6 +2274,7 @@ export class WidgetStore {
             : {}),
         };
       });
+      this.rememberLastMessage(result.conversationId, sentAt, sentRow, 'sent', { messageId: result.messageId });
 
       // New files to fetch the stored copy of: a fresh round of re-reads.
       const sent = this.state.messages.find((message) => message.id === result.messageId);
@@ -2593,6 +2776,77 @@ function asDeletedPlaceholder(message: Message, deletedAt: string): Message {
   return { ...message, body: null, bodyPlain: null, attachments: null, metadata: null, deletedAt };
 }
 
+/** A message's words on one line; replies written in Workstation may only carry HTML. */
+function plainTextOf(message: Message): string {
+  return (message.bodyPlain || stripHtml(message.body ?? '')).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The newest message of a thread as this device saw it. `at` is its
+ * `createdAt`, which Workstation's list repeats as `lastMessageAt`; for a sent
+ * message it's the phone's clock instead.
+ */
+interface LastMessageHint {
+  at: string;
+  fromVisitor: boolean;
+  attachment: 'photo' | 'file' | null;
+  phoneClock?: boolean;
+  /** A sent message's id: a page from Workstation that has it can retime it. */
+  messageId?: string;
+}
+
+/** `snippet` is absent when there's nothing to quote: the row keeps its words. */
+type LastMessageFields = Pick<Conversation, 'lastMessageAttachment' | 'lastMessageFromVisitor'> & {
+  snippet?: string;
+};
+
+/** The list row once `message` is the newest. Null keeps the row as it is: system rows and notes. */
+function rowFieldsOf(message: Message): LastMessageFields | null {
+  if (message.messageType && message.messageType !== 'message') return null;
+  return rowFieldsFor(
+    plainTextOf(message),
+    (message.attachments ?? []).map((attachment) => attachment.contentType),
+    message.senderType === 'visitor' || message.direction === 'inbound',
+    /<img\b/i.test(message.body ?? '')
+  );
+}
+
+/**
+ * Its words, or with none, whether it carried only photos or other files too.
+ * A message with neither (a card) still says who sent it, so a teammate's
+ * card never leaves "You:" on the visitor's earlier message.
+ */
+function rowFieldsFor(
+  text: string,
+  contentTypes: Array<string | null | undefined>,
+  fromVisitor: boolean,
+  inlinePhoto = false
+): LastMessageFields {
+  if (text) return { snippet: text, lastMessageAttachment: null, lastMessageFromVisitor: fromVisitor };
+  const count = contentTypes.length;
+  if (count === 0 && !inlinePhoto) return { lastMessageAttachment: null, lastMessageFromVisitor: fromVisitor };
+  return {
+    // Workstation's list words it this way too, so apps reading `snippet` see the same after a reload.
+    ...(count > 0 ? { snippet: `${count} attachment${count === 1 ? '' : 's'}` } : {}),
+    lastMessageAttachment: contentTypes.every((type) => isImageAttachment(type)) ? 'photo' : 'file',
+    lastMessageFromVisitor: fromVisitor,
+  };
+}
+
+/**
+ * The list stamps a conversation just after storing its message, so its time
+ * trails the message's own by a few milliseconds, never more than `LIST_LAG_MS`.
+ * A sent message is timed by the phone instead: a little drift either way
+ * still matches, but only when the list rules out a team reply the visitor
+ * hasn't read. Older Workstation deployments don't send `unreadCount`, so
+ * there a sent message must match like any other.
+ */
+function describesSameMessage(conversation: Conversation, known: LastMessageHint): boolean {
+  const lag = Date.parse(conversation.lastMessageAt ?? '') - Date.parse(known.at);
+  if (lag >= 0 && lag <= LIST_LAG_MS) return true;
+  return !!known.phoneClock && Math.abs(lag) <= SAME_MESSAGE_DRIFT_MS && conversation.unreadCount === 0;
+}
+
 /** 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(
@@ -2641,13 +2895,31 @@ function mergeAttachments(local: WidgetAttachment[], server: WidgetAttachment[])
   if (local.length !== server.length) {
     return server.every((attachment) => attachment.url) ? server : local;
   }
+  const owns = pairByName(local, server);
   const merged = server.map((attachment, index) => {
-    const own = local[index]!;
-    return isLocalAttachment(own) && attachment.url ? attachment : own;
+    const own = owns[index]!;
+    if (!isLocalAttachment(own) || !attachment.url) return own;
+    rememberLocalPreview(attachment.url, own.url);
+    return attachment;
   });
   return merged.every((attachment, index) => attachment === local[index]) ? local : merged;
 }
 
+/**
+ * The local attachment each server one replaces. By name first: Workstation
+ * may store a message's files in another order than they were sent, and a
+ * photo paired with the wrong file would show it for the rest of the session.
+ * Any it renamed pair up in the order left.
+ */
+function pairByName(local: WidgetAttachment[], server: WidgetAttachment[]): WidgetAttachment[] {
+  const unpaired = [...local];
+  const named = server.map((attachment) => {
+    const index = unpaired.findIndex((own) => own.name === attachment.name);
+    return index < 0 ? null : unpaired.splice(index, 1)[0]!;
+  });
+  return named.map((own) => own ?? unpaired.shift()!);
+}
+
 /**
  * Newer Workstation deployments echo `clientMessageId` on the visitor's own
  * rows. Such a row replaces the pending or failed bubble it came from instead

package/src/storage.ts

@@ -20,6 +20,8 @@ export const TOKEN_KEY = 'repzo_widget_token';
 export const USER_KEY = 'repzo_widget_user_key';
 export const DEVICE_ID_KEY = 'repzo_widget_device_id';
 export const UNREAD_KEY = 'repzo_widget_unread';
+/** Who sent each conversation's newest message; Workstation's list doesn't say. */
+export const LAST_MESSAGE_KEY = 'repzo_widget_last_message';
 /** Last config received — repaints the real theme instantly on relaunch. */
 /**
  * v2 wraps the config with the channel/baseUrl/platform it came from. v1 held a

package/src/types.ts

@@ -104,6 +104,8 @@ export interface OutgoingAttachment {
   url: string;
   /** A local file uploaded before the message is sent (servers with `maxAttachmentBytes`). */
   fileUri?: string;
+  /** `fileUri` is already uploaded under this token, so the send skips uploading it. */
+  uploadToken?: string;
   contentType: string;
   /** Decoded bytes. */
   size: number;
@@ -116,6 +118,21 @@ export interface Conversation {
   subject: string | null;
   status: string;
   snippet: string | null;
+  /**
+   * Set when the newest message had no words, only photos (`'photo'`) or
+   * other files (`'file'`); the lists then say "Photo" or "File", while
+   * `snippet` keeps Workstation's wording ("2 attachments"). `null` when it
+   * had words. Filled in from what this device sent, received or loaded.
+   * @since 1.4.0
+   */
+  lastMessageAttachment?: 'photo' | 'file' | null;
+  /**
+   * The newest message is the visitor's own; the lists put "You:" before it.
+   * A Workstation list that includes it is used as is; otherwise the SDK fills
+   * it in from what this device sent, received or loaded.
+   * @since 1.4.0
+   */
+  lastMessageFromVisitor?: boolean | null;
   messageCount: number;
   lastMessageAt: string | null;
   createdAt: string;
@@ -267,6 +284,22 @@ export interface BootOptions {
    * @since 1.2.0
    */
   posts?: boolean;
+  /**
+   * Show two or more photos in one message together as an album: one square
+   * holding them all, with "+N" on the last tile past four (default true).
+   * False shows each photo on its own, full width, as before 1.4.0. Either
+   * way, tapping a photo opens the message's photos in the viewer.
+   * @since 1.4.0
+   */
+  photoAlbums?: boolean;
+  /**
+   * Put "You: " before a conversation's newest message on Home and in
+   * Messages when the visitor sent it (default true; Arabic "أنت: ", the
+   * `lastMessageYou` translation key). False shows the message alone, as
+   * before 1.4.0. `Conversation.lastMessageFromVisitor` is filled in either way.
+   * @since 1.4.0
+   */
+  youPrefix?: boolean;
 }
 
 /** An option in the composer's attach menu. */
@@ -303,6 +336,14 @@ export interface RepzoWidgetAttachmentOptions {
   pick?: (source: AttachmentSource) => Promise<RepzoPickedFile[] | null>;
   /** Menu options offered with `pick`. Default all three. Ignored without `pick`. */
   sources?: AttachmentSource[];
+  /**
+   * Default true: with a Workstation that takes uploads, a picked file starts
+   * uploading right away, while the visitor writes, so the message goes out
+   * the moment they tap Send. False uploads the files only when they tap
+   * Send, so nothing leaves the phone for a file they remove first.
+   * @since 1.4.0
+   */
+  uploadOnPick?: boolean;
 }
 
 // ─── Agent UI blocks ────────────────────────────────────────────────────────