@repzo/widget-react-native 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -12,20 +12,188 @@ All notable changes to `@repzo/widget-react-native`, newest first.
 
 ## Unreleased
 
+## 1.5.0 — 2026-11-06
+
+### Added
+
+- **`updateUser()` is paced, like other messengers' SDKs.** An app that calls
+  it on a timer or on every location fix no longer sends every call. Values
+  Workstation already has aren't sent again. Up to 20 updates go out at once,
+  then one every 90 seconds (20 per 30 minutes). Calls in between are merged,
+  newest value per key, and sent on the next allowed update, so the latest
+  value of every attribute still arrives. If Workstation answers that it's
+  busy (HTTP 429), the SDK waits as long as it asks and sends again; after a
+  failed connection or a server error it tries again a minute later. New
+  `boot({ throttleUpdateUser })` option (default `true`). See **Upgrading**.
+- **`RepzoWidgetError.retryAfter`.** On an HTTP 429, the seconds Workstation
+  asked to wait, when it said.
+
+### Fixed
+
+- **A message goes out once, however many times Send is tapped.** On a slow
+  or busy phone the chat could take a moment to react to Send. Every extra tap
+  in that moment sent the message again, so your team got it several times.
+  Now only the first tap sends it. Nothing to set up.
+
+### Upgrading
+
+- **`updateUser()` calls may be merged and sent later.** A call that's held
+  back resolves right away instead of waiting for, or failing on, the
+  request. A call that's sent straight away still rejects when the request
+  fails, except for a 429, which the SDK now retries itself. If your app
+  calls `updateUser()` often, you can drop your own retry logic. To send
+  every call straight away, as before:
+
+  ```ts
+  await RepzoWidget.boot({ channelAccountId: '<widget id>', throttleUpdateUser: false });
+  ```
+
+## 1.4.0 — 2026-11-02
+
+### Added
+
+- **Several photos in one message show as an album,** like WhatsApp: one
+  square holding them all. Two sit side by side, three as one tall beside two
+  stacked, four in a grid, and with more than four the last tile shows how
+  many more there are ("+3"). Tapping any tile opens the photos at that one.
+  Other files in the message still show below. New `boot({ photoAlbums })`
+  option (default `true`): `false` shows each photo on its own, as before.
+  See **Upgrading**.
+- **Swipe between a message's photos.** When a message has several photos,
+  sent or received, tapping one opens them all in the full-screen viewer.
+  Swipe left or right to move between them (mirrored in Arabic); the header
+  shows which one is open, like "2 / 4", and screen readers move between them
+  with the adjust gesture. The next photo is already drawn as it slides in
+  and stays on screen while its full-size copy loads, so a swipe never shows
+  a black frame. Pinch and double-tap zoom work as before. Nothing to set up.
+- **Photos in the chat show a loader until they've loaded.** A small spinner
+  sits over each photo, and each album tile, while it downloads or waits its
+  turn, instead of an empty box. A photo that loads straight away (from the
+  cache) never shows it. Nothing to set up.
+- **Choose when picked files upload.** New
+  `boot({ attachments: { uploadOnPick } })` option (default `true`). Set it to
+  `false` to upload files only when the visitor taps Send, so nothing leaves
+  the phone for a file they pick and then remove.
+- **"You:" before the visitor's own last message.** On Home and in Messages,
+  a conversation whose newest message is the visitor's shows "You: " before
+  it ("You: Photo" for a photo), so it's clear who spoke last. Arabic:
+  "أنت: ". Workspaces can change it with the `lastMessageYou` translation key,
+  which keeps `{message}`. Workstation's list doesn't say who sent the newest
+  message, so the SDK remembers it from what this device sent, received or
+  loaded, including across launches; a conversation last written in
+  elsewhere shows no "You:". `Conversation` has a new optional
+  `lastMessageFromVisitor` field; a Workstation list that sends it is used
+  as is. New `boot({ youPrefix })` option (default `true`): `false` shows the
+  message without "You:", as before. See **Upgrading**.
+
 ### Changed
 
+- **A conversation opens on its newest message.** The thread starts at the
+  bottom, with the latest messages drawn first, instead of rendering from the
+  top and then jumping down. Older messages load on their own as the visitor
+  scrolls up, without moving what they're reading, so there's no need to tap
+  **Load earlier messages**. That row stays at the top while a page loads, or
+  to try again if one didn't. A reply that arrives while they read further up
+  doesn't move the text either. Once the visitor has scrolled up, a button in
+  the corner takes them back to the newest message and shows how many
+  teammate replies arrived in the meantime. Nothing to set up.
 - **Visitors can attach files up to 50 MB.** With a Workstation server that
-  takes uploads, a picked file is uploaded when the message is sent, instead of
-  being sent inside the message, so the 1.5 MB cap per file (6 MB per message)
-  is gone; the server sets the cap (50 MB a file, up to five files). Large files
-  are read from the device as they upload, never held in memory as text. The
-  "File is too large" notice shows the server's cap. Nothing to set up.
+  takes uploads, a picked file is uploaded on its own instead of being sent
+  inside the message, so the 1.5 MB cap per file (6 MB per message) is gone;
+  the server sets the cap (50 MB a file, up to five files). With
+  `expo-file-system` installed, a file is sent straight from the phone's
+  storage as it uploads, so even a 50 MB file doesn't fill the app's memory.
+  Without it the file is read into memory first, which can fail on Android
+  for files over about 30 MB. The "File is too large" notice shows the
+  server's cap. Nothing else to set up.
+- **Files upload as soon as they're picked.** A spinner shows on each file
+  in the message field while it uploads, and the send button turns on once
+  every file is up, so the message goes out at once. The upload happens while
+  the visitor writes. A file that fails to upload shows **Tap to retry**, and
+  removing a file cancels its upload. If the visitor waits so long to send
+  that Workstation no longer keeps the upload (about an hour), the file
+  uploads again as the message goes out. With an older Workstation that
+  doesn't take uploads, nothing changes. To keep uploading on Send, see
+  **Upgrading**.
+- **Home shows the latest conversation in a "Recent message" card.** The
+  newest conversation now sits in its own card above **Send us a message**:
+  who replied, how long ago and the last thing said, with the unread count
+  when there is one. Tapping it opens the conversation. It replaces the
+  "Recent" list of two conversations and its **View all** link that sat under
+  the start card; every conversation is still one tap away in the Messages
+  tab. The card follows the workspace's "show previous conversations" setting
+  like the list did. Arabic: "أحدث رسالة". Workspaces can change the title
+  with the `homeRecentMessageTitle` translation key. Nothing to set up.
+
+### Fixed
+
+- **Images in a team reply show where the teammate put them.** A reply with
+  text, an image, more text and another image now shows them in that order,
+  like the web Messenger, instead of all the text first and every image after
+  it. Links and formatting in the text between images are kept.
+- **A photo the visitor sends stays a photo.** Right after sending, a photo
+  could turn into a file row until the conversation was opened again. It now
+  keeps showing from the phone until the next time the conversation loads.
+  An attachment that arrives without a file type shows as what its name says,
+  so a photo shows as a photo.
+- **Photos keep showing in long conversations on Android.** A conversation
+  with a few large photos could use up the memory Android sets aside for
+  images. Later photos, in the chat and elsewhere in your app, then showed as
+  file rows or didn't load. Photos in the chat are now decoded at the size
+  they're shown, and photos over 10 MB download two at a time, newest first,
+  so several of them on screen at once all show instead of all failing.
+  Ordinary photos still load straight away. iOS wasn't affected.
+- **Screen readers name the send button.** VoiceOver and TalkBack read
+  "Send message" (Arabic: "إرسال الرسالة") for the button beside the message
+  field, instead of just "button". Workspaces can change the text with the
+  `sendMessage` translation key.
+- **The conversation list shows the reply that just arrived.** On Home and
+  in Messages, a reply that came in while the visitor was on those screens
+  could leave the row showing the visitor's own last message, beside the
+  unread badge. This happened when the reply was only a photo or file, or
+  came from Workstation as formatted text only. The row now shows the
+  reply's words, or "Photo" or "File" (Arabic: "صورة", "ملف") when it had
+  none. Workspaces can change these with the `lastMessagePhoto` and
+  `lastMessageFile` translation keys. A conversation the visitor starts with
+  only attachments shows the same instead of "1 attachment". For apps that
+  read conversations from `MessageDidArrive`, `snippet` stays text: after a
+  reply with only photos or files it now says "2 attachments", the way
+  Workstation's list words it, instead of keeping the previous message's
+  words. A new optional `lastMessageAttachment` field (`'photo'`, `'file'`
+  or `null`) says which it was.
+- **The conversation list shows what the visitor just sent.** After replying
+  in a conversation and going back to Home or Messages, the row still showed
+  the team's last message until the list was pulled to refresh. It now shows
+  the visitor's message, and its time, as soon as it's sent.
 
 ### Older versions
 
 - Apps on earlier versions keep the 1.5 MB cap. With an older server, this
   version keeps it too.
 
+### Upgrading
+
+- **Picked files now upload before Send.** Nothing to do. To upload them only
+  when the visitor taps Send, as before:
+
+  ```ts
+  await RepzoWidget.boot({ channelAccountId: '<widget id>', attachments: { uploadOnPick: false } });
+  ```
+
+- **Several photos in one message show as an album.** Nothing to do. To keep
+  showing each photo on its own, full width:
+
+  ```ts
+  await RepzoWidget.boot({ channelAccountId: '<widget id>', photoAlbums: false });
+  ```
+
+- **"You:" before the visitor's own last message** on Home and in Messages.
+  Nothing to do. To show the message alone, as before:
+
+  ```ts
+  await RepzoWidget.boot({ channelAccountId: '<widget id>', youPrefix: false });
+  ```
+
 ## 1.3.1 — 2026-10-29
 
 ### Added

package/README.md

@@ -25,7 +25,11 @@ in your Repzo Inbox and agent replies arrive live.
 - Sent/Seen receipts, tap to retry a message that didn't send (*1.3.1+*), teammate avatars and presence, deleted-message placeholders
 - Catches up after a dropped connection or a trip to the background — no missed or duplicated replies
 - Agent UI blocks: product cards, slot pickers, lead forms, quotes, receipts
-- **Image viewer** with pinch and double-tap zoom for photos in the conversation
+- **Image viewer** with pinch and double-tap zoom for photos in the conversation; swipe between a message's photos (*1.4.0+*)
+- **Photo albums**: several photos in one message share one square, WhatsApp-style (*1.4.0+*; `photoAlbums: false` turns them off)
+- Conversations open on the newest message, load older ones as the visitor scrolls up, and offer a jump-to-latest button (*1.4.0+*)
+- Team replies keep their images where the teammate put them, between the text (*1.4.0+*)
+- Conversation lists say "You:" before the visitor's own last message, and "Photo" or "File" for one without words (*1.4.0+*; `youPrefix: false` turns "You:" off)
 - **Photo and file attachments** (optional — with `expo-image-picker` / `expo-document-picker`, or your own picker)
 - **Voice messages play in the chat**, with the phone's own audio player — nothing to install in Expo apps
 - **In-app notification cards** for new replies while the messenger is closed
@@ -46,7 +50,7 @@ in your Repzo Inbox and agent replies arrive live.
 | `react-native-safe-area-context` | optional — safe-area insets from the host provider |
 | `expo-image-picker` | optional — "Photo library" and "Take photo" attachments (v16+ / SDK 52+) |
 | `expo-document-picker` | optional — "File" attachments |
-| `expo-file-system` | optional — reads picked files as base64 (falls back to `fetch` without it) |
+| `expo-file-system` | optional — reads picked files as base64 (falls back to `fetch` without it), and (*1.4.0+*) lets large attachments upload straight from storage (recommended) |
 | `expo-image-manipulator` | optional — shrinks photos so camera shots fit the 1.5 MB attachment limit |
 | `expo-audio` | optional (*1.2.2+*) — no longer needed from *1.3.0+* in apps with Expo modules (see "Voice messages"); still used where the SDK's own player isn't built in |
 | `expo-crypto` | optional (*1.1.0+*) — secure random source for the anonymous device id when the runtime has no `crypto` global (see below) |
@@ -320,7 +324,7 @@ npx expo install expo-image-picker expo-document-picker expo-file-system expo-im
 | --- | --- |
 | `expo-image-picker` | Photo library, Take photo |
 | `expo-document-picker` | File |
-| `expo-file-system` | nothing new — reads picked files faster (SDK 53's `readAsStringAsync` and SDK 54+'s `File` both work) |
+| `expo-file-system` | nothing new — reads picked files faster (SDK 53's `readAsStringAsync` and SDK 54+'s `File` both work), and (*1.4.0+*) uploads large files straight from storage. Without it a file is read into memory before it uploads, which can fail on Android for files over about 30 MB (recommended) |
 | `expo-image-manipulator` | nothing new — shrinks photos so camera shots fit the size limit (recommended) |
 
 With none of them (and no `pick` below) the button isn't shown. It is also
@@ -334,15 +338,25 @@ them. Taking photos needs `NSCameraUsageDescription` in `Info.plist` (the
 gets a clear message instead of a silently missing file:
 
 - 5 files per message
-- 1.5 MB per file
-- 6 MB for all files in one message together (they travel base64-encoded in
-  one JSON request)
+- *1.4.0+.* 50 MB per file, the cap Workstation sets. Each file starts uploading as
+  soon as it's picked, with a spinner on its thumbnail, and Send turns on
+  once every file is up, so the message then goes out at once. A file that
+  fails to upload shows **Tap to retry**; removing it cancels its upload.
+  A file picked about an hour before Send uploads again as the message goes
+  out, since Workstation stops keeping an unsent upload by then.
+- Before 1.4.0, or with an older Workstation that doesn't take uploads,
+  files travel base64-encoded inside the message instead: 1.5 MB per file,
+  and 6 MB for all files in one message together.
+
+*1.4.0+.* To upload the files only when the visitor taps Send, so nothing
+leaves the phone for a file they pick and then remove, pass
+`attachments: { uploadOnPick: false }`. Send then stays on while files are
+attached, and the message goes out once its files are up.
 
 With `expo-image-manipulator` installed, photos are scaled to at most 1600 px
-on the longest edge and saved as 70% JPEG — typically 200–500 KB, so camera
-shots fit comfortably. Without it they're only compressed, and a
-full-resolution camera photo can still exceed 1.5 MB and is then refused with
-a message. A message can be attachments only,
+on the longest edge and saved as 70% JPEG — typically 200–500 KB, so they
+upload quickly and fit the 1.5 MB cap of an older Workstation. Without it
+they're only compressed. A message can be attachments only,
 with no text. If a send fails, the attachments stay in the composer so the
 visitor can retry.
 
@@ -351,6 +365,19 @@ full-screen viewer right away, from the copy on the phone. A PDF or other file
 opens in the phone's viewer once Workstation has stored it, usually a moment
 after it's sent.
 
+*1.4.0+.* When a message has several photos, sent or received, they show
+together as an album in one square, WhatsApp-style, with "+N" on the last
+tile when there are more than four. Tapping one opens them all in the
+viewer: swipe sideways to move between them (the direction follows the
+app's language), and the header shows which one is open. To show each photo
+on its own, full width, as before, pass `photoAlbums: false`:
+
+```ts
+await RepzoWidget.boot({ channelAccountId: '…', photoAlbums: false });
+```
+
+Tapping a photo still opens the message's photos in the viewer.
+
 ### Your own picker
 
 Apps that use `react-native-image-picker`, `react-native-document-picker` or
@@ -434,6 +461,63 @@ get a plain message and no Retry.
 Expired or revoked tokens (401) are handled silently: the SDK re-inits once
 (shared by all concurrent requests) and retries.
 
+*1.5.0+.* When Workstation answers that it's busy (HTTP 429), the error's
+`retryAfter` holds the seconds it asked to wait, when it said.
+
+## Custom attributes
+
+`updateUser()` saves attributes on the visitor so agents see them on the
+conversation, for example a plan, a role or which part of your app they're in:
+
+```ts
+await RepzoWidget.updateUser({ plan: 'pro', role: 'manager' });
+```
+
+Up to 30 keys, keys up to 64 characters, values (text, numbers or true/false)
+up to 512 characters. Each call only changes the keys it sends; the others
+keep their saved values.
+
+*1.5.0+.* Calls are paced so an app can't flood Workstation:
+
+- Values Workstation already has aren't sent again.
+- Up to 20 updates go out at once, then one every 90 seconds (20 per 30
+  minutes).
+- Calls in between are merged, newest value per key, and sent on the next
+  allowed update. They resolve right away. The latest value of every
+  attribute still arrives.
+- When Workstation answers that it's busy, the SDK waits as long as it asks
+  and sends again. After a failed connection or a server error it tries again
+  a minute later, and the call that failed still rejects.
+
+Send what agents need to see, not live data. A value that changes every few
+seconds, such as a GPS position, only arrives about every 90 seconds once the
+first 20 updates are used. `boot({ throttleUpdateUser: false })` sends every
+call straight away, as before 1.5.0.
+
+## Conversation list
+
+*1.4.0+.* On Home and in Messages, each conversation shows its newest
+message. When the visitor sent it, "You: " comes first (Arabic "أنت: "), and a
+message with no words shows as "Photo" or "File" (Arabic "صورة", "ملف").
+Workspaces can change these with the `lastMessageYou` (keeps `{message}`),
+`lastMessagePhoto` and `lastMessageFile` translation keys.
+
+Workstation's list doesn't say who sent the newest message, so the SDK
+remembers it from what this device sent, received or loaded, across launches
+too. A conversation last written in on another device shows no "You:". To
+show the message without "You:", as before 1.4.0:
+
+```ts
+await RepzoWidget.boot({ channelAccountId: '…', youPrefix: false });
+```
+
+Conversations in the `MessageDidArrive` payload carry the same information in
+two optional fields: `lastMessageFromVisitor` (`true` when the visitor sent
+the newest message) and `lastMessageAttachment` (`'photo'` or `'file'` when it
+had no words, otherwise `null`). `snippet` stays text, worded the way
+Workstation's list words it ("2 attachments"). Both fields are filled in
+whether or not `youPrefix` is on.
+
 ## In-app notifications
 
 When a team reply arrives while the app is open but the messenger is closed,
@@ -686,7 +770,7 @@ sub.remove();
 | Event | Payload | Use it for |
 | --- | --- | --- |
 | `UnreadCountDidChange` | `{ count }` | Badge on your own chat button. `count` is the number of unread team replies across all conversations; it drops only when the visitor opens a thread (opening the messenger alone doesn't clear it). Counts are server-backed, so replies that arrived while the app was killed are included after a cold start. |
-| `MessageDidArrive` | `{ conversationId, message, conversation }` | Your own in-app banner while the app is foregrounded (no push is sent then). Fires only for team replies that count as unread — never the visitor's echo, never system rows like "agent joined", never the thread already open. |
+| `MessageDidArrive` | `{ conversationId, message, conversation }` | Your own in-app banner while the app is foregrounded (no push is sent then). Fires only for team replies that count as unread — never the visitor's echo, never system rows like "agent joined", never the thread already open. *1.4.0+:* `conversation.lastMessageFromVisitor` and `conversation.lastMessageAttachment` say who sent the newest message and whether it was only photos or files (see "Conversation list"). |
 | `ConversationDidRead` | `{ conversationId }` | Dismissing that conversation's push notification (example above). |
 | `WindowDidShow` / `WindowDidHide` | — | Pause your own UI (tours, toasts) while the messenger is open. |
 
@@ -694,10 +778,10 @@ sub.remove();
 
 | Method | Notes |
 | --- | --- |
-| `boot({ channelAccountId, baseUrl?, user?, push?, onOpenUrl?, attachments?, inAppNotifications?, posts? })` | Mints/resumes the session and connects the live stream. Idempotent; safe to call repeatedly. |
+| `boot({ channelAccountId, baseUrl?, user?, push?, onOpenUrl?, attachments?, inAppNotifications?, posts?, photoAlbums?, youPrefix?, throttleUpdateUser? })` | Mints/resumes the session and connects the live stream. Idempotent; safe to call repeatedly. |
 | `loginUserWithUserAttributes({ userId?, email?, name?, phone?, userHash?, account?, signedUpAt? })` | Identifies the visitor; moves anonymous history over. `account: { id, name?, website? }` links them to a CRM account matched by `id`; `signedUpAt` (Date, unix seconds or ISO) shows as "Signed up". A different stored user is signed out first. |
 | `loginUnidentifiedUser()` | Drops the identity (signing out a stored user), fresh anonymous session. |
-| `updateUser(attributes)` | Custom attributes agents see on the conversation (≤30 keys, 64-char keys, 512-char values). |
+| `updateUser(attributes)` | Custom attributes agents see on the conversation (≤30 keys, 64-char keys, 512-char values). *1.5.0+:* paced, see "Custom attributes". |
 | `logout()` | Revokes the token, removes the push registration, wipes visitor data, rotates the device id, resets the UI. Await it on sign-out. |
 | `present()` / `presentSpace('home' \| 'messages')` / `presentConversation(id)` / `hide()` | UI commands. |
 | `getUnreadConversationCount()` | Number of conversations with at least one unread reply. |
@@ -740,6 +824,8 @@ action from you:
 | 1.0.9 or older | Nothing required. Development builds now warn once if the visitor token isn't in secure storage, or if the device has no secure random source — see "Secure token storage" and "Requirements". |
 | 1.1.0 or older | Posts from Workstation now show over the app by default, once one is set live for Mobile (`posts: false` turns them off). They need `<RepzoWidgetProvider>` mounted at the root. |
 | 1.2.2 or older | Nothing required. In apps with Expo modules, the SDK now includes a small native voice player, so build the app again (development or store build) to get it; `expo-audio` can be removed if nothing else in your app uses it. If your `runtimeVersion` uses the `fingerprint` policy, it changes with this update. |
+| 1.3.1 or older | Nothing required. With a Workstation that takes uploads, a picked file now starts uploading right away, before the visitor taps Send (`attachments: { uploadOnPick: false }` uploads on Send instead). Several photos in one message now show as an album (`photoAlbums: false` shows each on its own, as before). Home and Messages put "You:" before the visitor's own last message (`youPrefix: false` turns it off). |
+| 1.4.0 or older | Nothing required. `updateUser()` is now paced: unchanged values are skipped, and past 20 updates in 30 minutes calls are merged and sent later (`throttleUpdateUser: false` sends every call, as before). See "Custom attributes". |
 
 ## Troubleshooting
 

package/lib/commonjs/api/client.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.WidgetApiClient = exports.RepzoWidgetError = void 0;
 exports.isTerminalErrorCode = isTerminalErrorCode;
+var _fileSize = require("../attachments/file-size.js");
 var _storage = require("../storage.js");
 var _safeUrl = require("../ui/utils/safe-url.js");
 /**
@@ -23,24 +24,91 @@ function isTerminalErrorCode(code) {
   return !!code && TERMINAL_CODES.has(code);
 }
 class RepzoWidgetError extends Error {
-  constructor(message, status, code = 'http') {
+  /**
+   * Seconds Workstation asked to wait before trying again, on a 429
+   * (`Retry-After`). Undefined when it didn't say.
+   * @since 1.5.0
+   */
+
+  constructor(message, status, code = 'http', retryAfter) {
     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, body) {
+  static fromResponse(status, body, retryAfterHeader) {
     const payload = body && typeof body === 'object' ? body : {};
     const message = typeof payload.message === 'string' && payload.message ? payload.message : null;
     const code = status === 403 && typeof payload.code === 'string' && isTerminalErrorCode(payload.code) ? payload.code : '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);
   }
 }
 
-/** A Send message part asked for on its own, which may share one request with others. */
+/**
+ * Seconds from a `Retry-After` header (seconds or an HTTP date), falling back
+ * to the `retryAfter` seconds Workstation also puts in the 429 body.
+ */
 exports.RepzoWidgetError = RepzoWidgetError;
+function parseRetryAfter(header, bodyValue) {
+  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. */
+
+/**
+ * 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, method, headers, file, signal) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const cancel = () => xhr.abort();
+    const settle = finish => {
+      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
+    });
+  });
+}
+
+/**
+ * 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. */
+
+function uploadExpiry(expiresAt, now) {
+  const at = typeof expiresAt === 'string' ? Date.parse(expiresAt) : typeof expiresAt === 'number' ? expiresAt : NaN;
+  return at > now ? at : now + UPLOAD_LIFETIME_MS;
+}
 class WidgetApiClient {
   baseUrl = '';
   channelAccountId = '';
@@ -128,7 +196,7 @@ 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);
@@ -282,41 +350,70 @@ 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) {
-    let 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, signal) {
+    // 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 = (0, _safeUrl.urlScheme)(file.uri) === 'file:' ? await (0, _fileSize.measureFileSize)(file.uri) : null;
+    let blob = 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('/api/widget/uploads', {
       method: 'POST',
       body: {
         fileName: file.name,
         contentType: file.contentType,
-        size: blob.size || file.size
+        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');
-    let 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');
+    stopIfCancelled();
+    const method = target.method ?? 'PUT';
+    const headers = target.headers ?? {
+      'Content-Type': file.contentType
+    };
+    let status;
+    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() {
     return this.request('/api/widget/conversations');