@repzo/widget-react-native 1.3.1 → 1.5.0

package/src/api/client.ts

@@ -8,6 +8,7 @@
  * The token itself lives in `SecureStorage`.
  */
 
+import { measureFileSize } from '../attachments/file-size';
 import { SecureStorage, TOKEN_KEY } from '../storage';
 import type {
   AgentUiAction,
@@ -40,26 +41,51 @@ export class RepzoWidgetError extends Error {
 
   readonly code: RepzoWidgetErrorCode;
 
-  constructor(message: string, status: number, code: RepzoWidgetErrorCode = 'http') {
+  /**
+   * Seconds Workstation asked to wait before trying again, on a 429
+   * (`Retry-After`). Undefined when it didn't say.
+   * @since 1.5.0
+   */
+  readonly retryAfter?: number;
+
+  constructor(message: string, status: number, code: RepzoWidgetErrorCode = 'http', retryAfter?: number) {
     super(message);
     this.name = 'RepzoWidgetError';
     this.status = status;
     this.code = code;
+    if (retryAfter !== undefined) this.retryAfter = retryAfter;
   }
 
   /** Builds the error for a non-2xx `{ message, code }` body. */
-  static fromResponse(status: number, body: unknown): RepzoWidgetError {
+  static fromResponse(status: number, body: unknown, retryAfterHeader?: string | null): RepzoWidgetError {
     const payload = (body && typeof body === 'object' ? body : {}) as {
       message?: unknown;
       code?: unknown;
+      retryAfter?: unknown;
     };
     const message = typeof payload.message === 'string' && payload.message ? payload.message : null;
     const code =
       status === 403 && typeof payload.code === 'string' && isTerminalErrorCode(payload.code)
         ? (payload.code as RepzoWidgetErrorCode)
         : 'http';
-    return new RepzoWidgetError(message || `HTTP ${status}`, status, code);
+    const retryAfter = status === 429 ? parseRetryAfter(retryAfterHeader, payload.retryAfter) : undefined;
+    return new RepzoWidgetError(message || `HTTP ${status}`, status, code, retryAfter);
+  }
+}
+
+/**
+ * Seconds from a `Retry-After` header (seconds or an HTTP date), falling back
+ * to the `retryAfter` seconds Workstation also puts in the 429 body.
+ */
+function parseRetryAfter(header: string | null | undefined, bodyValue: unknown): number | undefined {
+  const value = header?.trim();
+  if (value) {
+    if (/^\d+(\.\d+)?$/.test(value)) return Number(value);
+    const at = Date.parse(value);
+    if (Number.isFinite(at)) return Math.max(0, (at - Date.now()) / 1000);
   }
+  if (typeof bodyValue === 'number' && Number.isFinite(bodyValue) && bodyValue >= 0) return bodyValue;
+  return undefined;
 }
 
 /** A Send message part asked for on its own, which may share one request with others. */
@@ -84,6 +110,60 @@ interface RequestOptions {
   authToken?: string | null;
 }
 
+/**
+ * Sends a local file as the request body straight from disk and resolves the
+ * HTTP status. React Native streams a `{ uri }` body natively; `fetch` would
+ * stringify it, so this goes through XMLHttpRequest.
+ */
+function sendFileFromDisk(
+  url: string,
+  method: string,
+  headers: Record<string, string>,
+  file: { uri: string; contentType: string },
+  signal?: AbortSignal
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const cancel = () => xhr.abort();
+    const settle = (finish: () => void) => {
+      signal?.removeEventListener('abort', cancel);
+      finish();
+    };
+    xhr.onload = () => settle(() => resolve(xhr.status));
+    xhr.onerror = () => settle(() => reject(new RepzoWidgetError('Network request failed', 0, 'network')));
+    xhr.ontimeout = xhr.onerror;
+    xhr.onabort = () => settle(() => reject(new RepzoWidgetError('Upload cancelled', 0, 'network')));
+    xhr.open(method, url);
+    Object.entries(headers).forEach(([name, value]) => xhr.setRequestHeader(name, value));
+    // Android refuses a `{ uri }` body without one.
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === 'content-type')) {
+      xhr.setRequestHeader('Content-Type', file.contentType);
+    }
+    signal?.addEventListener('abort', cancel);
+    xhr.send({ uri: file.uri } as unknown as XMLHttpRequestBodyInit);
+  });
+}
+
+/**
+ * How long Workstation keeps an upload for a message to name, when its answer
+ * has no usable `expiresAt` (deployments without it, or a phone clock that
+ * reads it as already past).
+ */
+const UPLOAD_LIFETIME_MS = 60 * 60 * 1000;
+
+/** A file in storage, waiting for the message that names it. */
+export interface UploadedFile {
+  uploadToken: string;
+  /** When Workstation stops taking `uploadToken`, on this phone's clock (ms). */
+  expiresAt: number;
+}
+
+function uploadExpiry(expiresAt: unknown, now: number): number {
+  const at =
+    typeof expiresAt === 'string' ? Date.parse(expiresAt) : typeof expiresAt === 'number' ? expiresAt : NaN;
+  return at > now ? at : now + UPLOAD_LIFETIME_MS;
+}
+
 export class WidgetApiClient {
   private baseUrl = '';
 
@@ -187,7 +267,11 @@ export class WidgetApiClient {
 
     if (!response.ok) {
       const body = await response.json().catch(() => null);
-      const error = RepzoWidgetError.fromResponse(response.status, body);
+      const error = RepzoWidgetError.fromResponse(
+        response.status,
+        body,
+        response.headers?.get?.('Retry-After')
+      );
       // skipReauth calls (init, logout-time) are handled by their caller,
       // which knows whether the result is still current.
       if (isTerminalErrorCode(error.code) && !options.skipReauth) this.onTerminalError?.(error);
@@ -360,54 +444,81 @@ export class WidgetApiClient {
   /**
    * Puts a local file in storage ahead of the message, which then names it by
    * the returned upload token. The target is presigned storage, or a path on
-   * the server where its storage can't presign. The file is read as a native
-   * blob, so it never becomes a JS string; its size is the blob's, since the
-   * upload URL is signed for exactly the size asked for.
+   * the server where its storage can't presign. The upload URL is signed for
+   * exactly the size asked for: a `file://` file whose size `expo-file-system`
+   * can read streams from disk, anything else is read as a native blob and
+   * measured. `signal` cancels the transfer (the visitor removed the file, or
+   * left the conversation). Resolves the token and when it expires.
    */
-  async uploadAttachment(file: {
-    uri: string;
-    name: string;
-    contentType: string;
-    size: number;
-  }): Promise<string> {
-    let blob: Blob;
-    try {
-      blob = await (await fetch(file.uri)).blob();
-    } catch (error) {
-      throw new RepzoWidgetError(
-        error instanceof Error ? error.message : 'Could not read the file',
-        0,
-        'network'
-      );
+  async uploadAttachment(
+    file: {
+      uri: string;
+      name: string;
+      contentType: string;
+      size: number;
+    },
+    signal?: AbortSignal
+  ): Promise<UploadedFile> {
+    // A file removed early is never read, nor given a slot in storage.
+    const stopIfCancelled = () => {
+      if (signal?.aborted) throw new RepzoWidgetError('Upload cancelled', 0, 'network');
+    };
+    stopIfCancelled();
+    // Streaming matters on Android: React Native also copies a blob it reads
+    // into a Base64 string for its network inspector, so a file past ~30 MB
+    // runs the app out of memory. Only file:// gives an exact Content-Length.
+    const streamedSize = urlScheme(file.uri) === 'file:' ? await measureFileSize(file.uri) : null;
+    let blob: Blob | null = null;
+    if (streamedSize === null) {
+      try {
+        blob = await (await fetch(file.uri, { signal })).blob();
+      } catch (error) {
+        throw new RepzoWidgetError(
+          error instanceof Error ? error.message : 'Could not read the file',
+          0,
+          'network'
+        );
+      }
     }
+    stopIfCancelled();
     const target = await this.request<{
       uploadUrl: string;
       method?: string;
       headers?: Record<string, string>;
       uploadToken: string;
+      expiresAt?: string | number;
     }>('/api/widget/uploads', {
       method: 'POST',
-      body: { fileName: file.name, contentType: file.contentType, size: blob.size || file.size },
+      body: {
+        fileName: file.name,
+        contentType: file.contentType,
+        size: streamedSize ?? (blob?.size || file.size),
+      },
     });
+    // Counted from when the token was issued, not from when the file is up.
+    const expiresAt = uploadExpiry(target.expiresAt, Date.now());
     const uploadUrl = this.resolveUrl(target.uploadUrl);
     if (!uploadUrl) throw new RepzoWidgetError('Invalid upload target', 0, 'http');
+    stopIfCancelled();
 
-    let response: Response;
-    try {
-      response = await fetch(uploadUrl, {
-        method: target.method ?? 'PUT',
-        headers: target.headers ?? { 'Content-Type': file.contentType },
-        body: blob,
-      });
-    } catch (error) {
-      throw new RepzoWidgetError(
-        error instanceof Error ? error.message : 'Upload failed',
-        0,
-        'network'
-      );
+    const method = target.method ?? 'PUT';
+    const headers = target.headers ?? { 'Content-Type': file.contentType };
+    let status: number;
+    if (blob) {
+      try {
+        status = (await fetch(uploadUrl, { method, headers, body: blob, signal })).status;
+      } catch (error) {
+        throw new RepzoWidgetError(
+          error instanceof Error ? error.message : 'Upload failed',
+          0,
+          'network'
+        );
+      }
+    } else {
+      status = await sendFileFromDisk(uploadUrl, method, headers, file, signal);
     }
-    if (!response.ok) throw new RepzoWidgetError('Upload failed', response.status, 'http');
-    return target.uploadToken;
+    if (status < 200 || status >= 300) throw new RepzoWidgetError('Upload failed', status, 'http');
+    return { uploadToken: target.uploadToken, expiresAt };
   }
 
   listConversations(): Promise<{ data: Conversation[] }> {

package/src/attachments/file-size.ts

@@ -0,0 +1,42 @@
+/**
+ * Local file sizes from the host's `expo-file-system` (optional, like the
+ * pickers): read from the file's metadata, never from its contents. Shared by
+ * the pickers and the upload client, so the client doesn't pull in pickers.
+ *
+ * No `react-native` import on purpose: it stays testable in plain Node.
+ */
+
+let fileSystem: any = null;
+try {
+  fileSystem = require('expo-file-system') ?? null;
+} catch {
+  fileSystem = null;
+}
+
+/** A positive, finite byte count, or null. */
+export function validSize(size: unknown): number | null {
+  return typeof size === 'number' && Number.isFinite(size) && size > 0 ? size : null;
+}
+
+/**
+ * A local file's exact size in bytes, from its metadata without reading it.
+ * Null without `expo-file-system`, or when it can't tell.
+ */
+export async function measureFileSize(uri: string): Promise<number | null> {
+  if (typeof fileSystem?.File === 'function') {
+    try {
+      const size = validSize(new fileSystem.File(uri).size);
+      if (size !== null) return size;
+    } catch {
+      // Fall through to the next reader.
+    }
+  }
+  if (typeof fileSystem?.getInfoAsync === 'function') {
+    try {
+      return validSize((await fileSystem.getInfoAsync(uri, { size: true }))?.size);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/src/attachments/local-previews.ts

@@ -0,0 +1,32 @@
+/**
+ * The phone's copy of each file the visitor sent, by the URL of the stored
+ * copy that replaced it in the thread. Right after a send the stored copy
+ * may not load yet (Workstation can still be storing it), so a photo keeps
+ * showing from the phone instead of turning into a file row. Kept in memory
+ * only: a later session shows the stored copy.
+ */
+
+const MAX_PREVIEWS = 50;
+const previews = new Map<string, string>();
+
+export function rememberLocalPreview(storedUrl: string, localUrl: string): void {
+  if (!storedUrl || !localUrl) return;
+  previews.delete(storedUrl);
+  previews.set(storedUrl, localUrl);
+  // Oldest first: a Map iterates in insertion order.
+  if (previews.size > MAX_PREVIEWS) previews.delete(previews.keys().next().value as string);
+}
+
+export function localPreviewFor(storedUrl: string): string | null {
+  return (storedUrl && previews.get(storedUrl)) || null;
+}
+
+/** One that failed to load (the OS cleared the picker's cache): every view moves to the stored copy. */
+export function forgetLocalPreview(storedUrl: string): void {
+  previews.delete(storedUrl);
+}
+
+/** Signing out forgets them: the next visitor on the phone doesn't inherit the paths. */
+export function clearLocalPreviews(): void {
+  previews.clear();
+}

package/src/attachments/pickers.ts

@@ -2,7 +2,7 @@
  * Visitor attachments: picking photos/files for `POST /api/widget/messages`.
  *
  * A server that takes uploads names its cap (`maxAttachmentBytes`): a picked
- * file then stays a local URI and is uploaded when the message is sent. An
+ * file then stays a local URI, which the composer uploads right away. An
  * older server only takes files inline, as base64 data URLs within the
  * 1.5 MB / 6 MB caps below.
  *
@@ -24,6 +24,7 @@
  */
 
 import type { AttachmentSource, RepzoPickedFile, RepzoWidgetAttachmentOptions } from '../types';
+import { measureFileSize, validSize } from './file-size';
 
 /** The server keeps the first five and silently drops the rest. */
 export const MAX_ATTACHMENTS = 5;
@@ -48,10 +49,19 @@ export interface DraftAttachment {
   size: number;
   /** `data:<mime>;base64,<…>` for an inline file; empty when `fileUri` is uploaded instead. */
   dataUrl: string;
-  /** The local file uploaded when the message is sent. */
+  /** The local file uploaded ahead of the message. */
   fileUri?: string;
   /** What `<Image>` renders locally: the picked file's URI, else the data URL. */
   previewUri: string;
+  /**
+   * Where `fileUri`'s upload stands. The composer starts it as soon as the
+   * file is picked and holds Send until every file is up. Absent for inline files.
+   */
+  uploadStatus?: 'uploading' | 'uploaded' | 'failed';
+  /** What the message names the uploaded file by, once `uploadStatus` is `uploaded`. */
+  uploadToken?: string;
+  /** When `uploadToken` stops working, on this phone's clock (ms). */
+  uploadExpiresAt?: number;
 }
 
 /** Why some (or all) of a pick didn't make it into the composer. */
@@ -119,6 +129,11 @@ export function setAttachmentOptions(options: RepzoWidgetAttachmentOptions | nul
   hostOptions = options;
 }
 
+/** Whether a picked file starts uploading before Send (`attachments.uploadOnPick`). */
+export function uploadsOnPick(): boolean {
+  return hostOptions?.uploadOnPick !== false;
+}
+
 const ALL_SOURCES: AttachmentSource[] = ['photo', 'camera', 'file'];
 
 /**
@@ -356,7 +371,7 @@ async function toDraft(file: RepzoPickedFile): Promise<DraftAttachment> {
   };
 }
 
-/** A file that's uploaded when the message is sent: only its size is read here. */
+/** A file that's uploaded on its own, ahead of the message: only its size is read here. */
 async function toUploadDraft(file: RepzoPickedFile, uploadLimit: number): Promise<DraftAttachment> {
   const uri = file.uri!;
   const size = validSize(file.size) ?? (await readFileSize(uri));
@@ -375,23 +390,9 @@ async function toUploadDraft(file: RepzoPickedFile, uploadLimit: number): Promis
 
 /** A local file's size in bytes, or 0 when nothing can tell. */
 async function readFileSize(uri: string): Promise<number> {
-  if (typeof fileSystem?.File === 'function') {
-    try {
-      const size = validSize(new fileSystem.File(uri).size);
-      if (size !== null) return size;
-    } catch {
-      // Fall through to the next reader.
-    }
-  }
-  if (typeof fileSystem?.getInfoAsync === 'function') {
-    try {
-      const size = validSize((await fileSystem.getInfoAsync(uri, { size: true }))?.size);
-      if (size !== null) return size;
-    } catch {
-      // Fall through to fetch.
-    }
-  }
-  // A native blob: its size is known without reading it into JS.
+  const size = await measureFileSize(uri);
+  if (size !== null) return size;
+  // Last resort: the native blob reads the whole file (on Android, into memory).
   const blob = await (await fetch(uri)).blob();
   return validSize(blob.size) ?? 0;
 }
@@ -524,10 +525,6 @@ export function isImageAttachment(contentType: string | null | undefined): boole
   return !!contentType && contentType.toLowerCase().startsWith('image/');
 }
 
-function validSize(size: unknown): number | null {
-  return typeof size === 'number' && Number.isFinite(size) && size > 0 ? size : null;
-}
-
 function fileNameFromUri(uri: string | undefined): string | null {
   if (!uri) return null;
   const last = uri.split(/[?#]/)[0]?.split('/').pop();
@@ -563,7 +560,8 @@ const CONTENT_TYPES: Record<string, string> = {
   mov: 'video/quicktime',
 };
 
-function guessContentType(nameOrUri: string | null | undefined): string | null {
+/** The type a file name's extension implies, or null for one this table doesn't know. */
+export function guessContentType(nameOrUri: string | null | undefined): string | null {
   const extension = /\.([a-z0-9]+)$/i.exec(nameOrUri?.split(/[?#]/)[0] ?? '')?.[1];
   return extension ? (CONTENT_TYPES[extension.toLowerCase()] ?? null) : null;
 }

package/src/i18n.ts

@@ -59,6 +59,14 @@ export const DEFAULT_LABELS = {
   loadEarlier: 'Load earlier messages',
   emptyConversation: 'Send a message to start the conversation',
   messagePlaceholder: 'Type a message...',
+  // Screen-reader label of the send button beside the message field.
+  sendMessage: 'Send message',
+  // Screen-reader labels of the button that returns to the newest message
+  // after scrolling up; the second when teammates replied in the meantime.
+  jumpToLatest: 'Jump to latest messages',
+  jumpToLatestNew: 'New messages: {count}. Jump to latest',
+  // Screen readers, on the last tile of a photo album showing "+{count}".
+  morePhotos: '{count} more photos',
   attachFile: 'Attach file',
   // Attach menu, composer chips and the notices under them.
   attachPhotoLibrary: 'Photo library',
@@ -70,6 +78,11 @@ export const DEFAULT_LABELS = {
   attachmentsTooLargeTogether:
     'Attachments are too large to send together — send some in another message',
   attachmentFailed: "Couldn't attach that file",
+  // A picked file uploads before Send is enabled. Screen-reader labels for its
+  // chip while it uploads and after it failed, then the notice for a failure.
+  attachmentUploading: 'Uploading {name}',
+  attachmentUploadFailed: "Couldn't upload {name}. Tap to try again",
+  attachmentsUploadFailed: "Couldn't upload a file. Tap it to try again",
   // A file in a message; tapping opens it. `{name}` is the file name.
   openAttachment: 'Open {name}',
   // Voice notes played in the chat (with expo-audio).
@@ -79,6 +92,8 @@ export const DEFAULT_LABELS = {
   // Full-screen image viewer.
   imageLoadFailed: "Couldn't load this image",
   openImageExternally: 'Open image',
+  // Screen readers: which of a message's photos is open.
+  imagePosition: '{current} of {total}',
   cameraPermissionDenied: 'Allow camera access in Settings to take a photo',
   cancel: 'Cancel',
   failedToSend: 'Failed to send',
@@ -93,13 +108,17 @@ export const DEFAULT_LABELS = {
   preChatSubtitle: 'Let us know a bit about you so we can help you better.',
   preChatSkip: 'Skip',
   preChatSubmit: 'Start chat',
-  viewPreviousConversations: 'View previous conversations',
-  homeRecentTitle: 'Recent',
-  homeViewAllCount: 'View all ({count})',
+  // Heading of Home's card that shows the newest conversation.
+  homeRecentMessageTitle: 'Recent message',
   homeNoConversations: 'Your conversations will show up here',
   homeStatusOnline: "We're online",
   homeStatusAway: "We're away",
   unreadBadge: '{count} unread',
+  // A conversation row whose newest message was only photos, or other files.
+  lastMessagePhoto: 'Photo',
+  lastMessageFile: 'File',
+  // Before the visitor's own newest message in a conversation row.
+  lastMessageYou: 'You: {message}',
   team: 'Team',
   home: 'Home',
   close: 'Close',

package/src/index.tsx

@@ -91,6 +91,11 @@ export type RepzoWidgetType = {
   /**
    * Attach custom attributes to the visitor's identity so agents see them on
    * the conversation (max 30 keys, 64-char keys, 512-char values).
+   *
+   * Since 1.5.0 calls are paced (see `BootOptions.throttleUpdateUser`):
+   * values Workstation already has are skipped, and once more than 20 updates
+   * go out in 30 minutes the rest are merged and sent later. Those calls
+   * resolve right away. A call sent straight away still rejects when it fails.
    */
   updateUser(attributes: WidgetCustomAttributes): Promise<void>;
 

package/src/locales.ts

@@ -20,6 +20,10 @@ const ar: LabelMap = {
   loadEarlier: 'تحميل الرسائل السابقة',
   emptyConversation: 'أرسل رسالة لبدء المحادثة',
   messagePlaceholder: 'اكتب رسالة...',
+  sendMessage: 'إرسال الرسالة',
+  jumpToLatest: 'الانتقال إلى أحدث الرسائل',
+  jumpToLatestNew: 'رسائل جديدة: {count}. الانتقال إلى الأحدث',
+  morePhotos: 'صور أخرى: {count}',
   attachFile: 'إرفاق ملف',
   attachPhotoLibrary: 'مكتبة الصور',
   attachTakePhoto: 'التقاط صورة',
@@ -29,12 +33,16 @@ const ar: LabelMap = {
   attachmentTooMany: 'يمكنك إرفاق {count} ملفات كحد أقصى',
   attachmentsTooLargeTogether: 'المرفقات كبيرة جدًا لإرسالها معًا — أرسل بعضها في رسالة أخرى',
   attachmentFailed: 'تعذر إرفاق هذا الملف',
+  attachmentUploading: 'جارٍ رفع {name}',
+  attachmentUploadFailed: 'تعذر رفع {name}. اضغط لإعادة المحاولة',
+  attachmentsUploadFailed: 'تعذر رفع ملف. اضغط عليه لإعادة المحاولة',
   openAttachment: 'فتح {name}',
   voicePlay: 'تشغيل الرسالة الصوتية',
   voicePause: 'إيقاف الرسالة الصوتية مؤقتًا',
   voiceSpeed: 'سرعة التشغيل',
   imageLoadFailed: 'تعذر تحميل هذه الصورة',
   openImageExternally: 'فتح الصورة',
+  imagePosition: '{current} من {total}',
   cameraPermissionDenied: 'اسمح بالوصول إلى الكاميرا من الإعدادات لالتقاط صورة',
   cancel: 'إلغاء',
   failedToSend: 'تعذر الإرسال',
@@ -48,13 +56,14 @@ const ar: LabelMap = {
   preChatSubtitle: 'أخبرنا قليلاً عنك حتى نتمكن من مساعدتك بشكل أفضل.',
   preChatSkip: 'تخطٍ',
   preChatSubmit: 'ابدأ المحادثة',
-  viewPreviousConversations: 'عرض المحادثات السابقة',
-  homeRecentTitle: 'الأحدث',
-  homeViewAllCount: 'عرض الكل ({count})',
+  homeRecentMessageTitle: 'أحدث رسالة',
   homeNoConversations: 'ستظهر محادثاتك هنا',
   homeStatusOnline: 'نحن متصلون',
   homeStatusAway: 'نحن غير متصلين',
   unreadBadge: '{count} غير مقروءة',
+  lastMessagePhoto: 'صورة',
+  lastMessageFile: 'ملف',
+  lastMessageYou: 'أنت: {message}',
   team: 'الفريق',
   home: 'الرئيسية',
   close: 'إغلاق',