stream-chat 9.51.0 → 9.52.1

package/src/messageComposer/attachmentManager.ts

@@ -27,6 +27,7 @@ import type {
   FileLike,
   FileReference,
   LocalAttachment,
+  LocalAttachmentUploadMetadata,
   LocalNotImageAttachment,
   LocalUploadAttachment,
   UploadPermissionCheckResult,
@@ -34,6 +35,7 @@ import type {
 import type { ChannelResponse, DraftMessage, LocalMessage } from '../types';
 import type { MessageComposer } from './messageComposer';
 import { mergeWithDiff } from '../utils/mergeWith';
+import { isUploadCancellation } from '../uploadManager';
 
 export type FileUploadFilter = (file: Partial<LocalUploadAttachment>) => boolean;
 
@@ -233,6 +235,7 @@ export class AttachmentManager {
       ...attachment,
       localMetadata: {
         ...attachment.localMetadata,
+        uploadConfirmationPending: false,
         uploadProgress: undefined,
         uploadState: 'failed',
       },
@@ -332,9 +335,28 @@ export class AttachmentManager {
     }
   };
 
+  /**
+   * Releases a local preview URL the SDK minted, if it minted one.
+   *
+   * Only `blob:` URLs are ours to revoke: `toLocalUploadAttachment` puts a
+   * `URL.createObjectURL` result in `previewUri` for a `File`, but for a React Native
+   * `FileReference` it stores the caller's own native file URI, which must be left alone.
+   */
+  private revokePreviewUri = (attachment: LocalAttachment) => {
+    const previewUri = (
+      attachment.localMetadata as Partial<LocalAttachmentUploadMetadata>
+    )?.previewUri;
+
+    if (previewUri?.startsWith('blob:')) URL.revokeObjectURL?.(previewUri);
+  };
+
   removeAttachments = (localAttachmentIds: string[]) => {
     if (!localAttachmentIds.length) return;
 
+    const removedAttachments = this.attachments.filter((attachment) =>
+      localAttachmentIds.includes(attachment.localMetadata?.id),
+    );
+
     this.state.partialNext({
       attachments: this.attachments.filter(
         (attachment) => !localAttachmentIds.includes(attachment.localMetadata?.id),
@@ -344,6 +366,18 @@ export class AttachmentManager {
     for (const id of localAttachmentIds) {
       this.client.uploadManager.deleteUploadRecord(id);
     }
+
+    // Removal is the end of the line for these attachments, so the preview blob goes with
+    // them - otherwise every removed (or cancelled mid-upload) attachment leaks one blob URL
+    // until the page unloads. Revoked after the record is deleted, so nothing is still
+    // rendering from it.
+    //
+    // Deliberately not done in `initState`/`restoreSnapshot`: those drop the composer's *view*
+    // of the attachments without ending their life. A finished upload has already had its
+    // `previewUri` revoked and removed by the post-upload middleware, and an unfinished one may
+    // still be rendered by whoever took it over (an optimistic message sent with the upload
+    // still in flight, for instance).
+    removedAttachments.forEach(this.revokePreviewUri);
   };
 
   getUploadConfigCheck = async (
@@ -619,21 +653,30 @@ export class AttachmentManager {
           ...attachment.localMetadata,
           uploadState: 'failed',
           uploadProgress: undefined,
+          // `false`, not `undefined`: these updates go through `updateAttachment`, which merges
+          // via `mergeWith` — and that skips `undefined` source values, so `undefined` would
+          // leave a stale `true` in place.
+          uploadConfirmationPending: false,
         },
       };
 
-      this.client.notifications.addError({
-        message: 'Error uploading attachment',
-        origin: {
-          emitter: 'AttachmentManager',
-          context: { attachment, failedAttachment },
-        },
-        options: {
-          type: 'api:attachment:upload:failed',
-          metadata: { reason },
-          originalError: error instanceof Error ? error : undefined,
-        },
-      });
+      // A cancellation is the user getting what they asked for, so it gets no error
+      // notification. This path predates the post-upload middleware chain and notifies
+      // directly, so it needs the same guard `createUploadErrorHandlerMiddleware` applies.
+      if (!isUploadCancellation(error)) {
+        this.client.notifications.addError({
+          message: 'Error uploading attachment',
+          origin: {
+            emitter: 'AttachmentManager',
+            context: { attachment, failedAttachment },
+          },
+          options: {
+            type: 'api:attachment:upload:failed',
+            metadata: { reason },
+            originalError: error instanceof Error ? error : undefined,
+          },
+        });
+      }
 
       this.updateAttachment(failedAttachment);
       return failedAttachment;
@@ -654,6 +697,8 @@ export class AttachmentManager {
         ...attachment.localMetadata,
         uploadState: 'finished',
         uploadProgress: undefined,
+        // See the note in the failure branch: `undefined` cannot clear through `mergeWith`.
+        uploadConfirmationPending: false,
       },
     };
 
@@ -715,6 +760,8 @@ export class AttachmentManager {
             ...attachment.localMetadata,
             uploadState: error ? 'failed' : 'finished',
             uploadProgress: undefined,
+            // See the note in `uploadAttachment`: `undefined` cannot clear through `mergeWith`.
+            uploadConfirmationPending: false,
           },
         },
         error,
@@ -759,6 +806,7 @@ export class AttachmentManager {
           ...attachment.localMetadata,
           uploadState: 'uploading',
           uploadProgress: this.config.trackUploadProgress ? 0 : undefined,
+          uploadConfirmationPending: false,
         },
       },
     ]);
@@ -773,6 +821,7 @@ export class AttachmentManager {
             ...attachment.localMetadata,
             uploadState: 'uploading',
             uploadProgress: nextUpload.uploadProgress,
+            uploadConfirmationPending: nextUpload.uploadConfirmationPending,
           },
         });
       },

package/src/messageComposer/messageComposer.ts

@@ -1,4 +1,5 @@
 import { AttachmentManager } from './attachmentManager';
+import { isFinishedUpload, isPendingUpload } from './attachmentIdentity';
 import { CustomDataManager } from './CustomDataManager';
 import { LinkPreviewsManager } from './linkPreviewsManager';
 import { LocationComposer } from './LocationComposer';
@@ -432,16 +433,50 @@ export class MessageComposer extends WithSubscriptions {
     return !currentCommand || this.validateCommandSendability(currentCommand).ready;
   }
 
+  /**
+   * Whether the installed composition middleware composes messages whose uploads are still in
+   * flight — see `MessageCompositionMiddleware.allowsPendingUploads`.
+   *
+   * Derived from the chain rather than from config, so there is exactly one switch: the UI SDK
+   * that implements the rest of the flow installs the middleware, and everything that has to
+   * follow from that (starting with {@link hasSendableData}) follows on its own.
+   *
+   * **Temporary API.** In v10 sending with pending uploads becomes part of the composer
+   * configuration (`MessageComposerConfig`, set through `updateConfig`), and this getter,
+   * together with the middleware declaration it reads, is replaced by that config field.
+   */
+  get allowsPendingUploads() {
+    return this.compositionMiddlewareExecutor.installedMiddleware.some(
+      (middleware) => middleware.allowsPendingUploads,
+    );
+  }
+
   get hasSendableData() {
-    return (
-      this.isCommandSendable &&
-      !!(
-        (!this.attachmentManager.uploadsInProgressCount &&
-          (!this.textComposer.textIsEmpty ||
-            this.attachmentManager.successfulUploadsCount > 0)) ||
+    if (!this.isCommandSendable) return false;
+
+    if (this.allowsPendingUploads) {
+      // An upload in flight is no longer a blocker, and a pending attachment counts as content
+      // in its own right — otherwise an attachment-only message could never be sent before its
+      // upload finished, which is the point of the flow. `failed` and `blocked` attachments
+      // still do not count: a message whose only attachment was rejected must not look sendable.
+      const hasSendableAttachment = this.attachmentManager.attachments.some(
+        (attachment) => isFinishedUpload(attachment) || isPendingUpload(attachment),
+      );
+
+      return !!(
+        !this.textComposer.textIsEmpty ||
+        hasSendableAttachment ||
         this.pollId ||
-        !!this.locationComposer.validLocation
-      )
+        this.locationComposer.validLocation
+      );
+    }
+
+    return !!(
+      (!this.attachmentManager.uploadsInProgressCount &&
+        (!this.textComposer.textIsEmpty ||
+          this.attachmentManager.successfulUploadsCount > 0)) ||
+      this.pollId ||
+      !!this.locationComposer.validLocation
     );
   }
 

package/src/messageComposer/middleware/attachmentManager/postUpload/AttachmentPostUploadMiddlewareExecutor.ts

@@ -14,7 +14,7 @@ export class AttachmentPostUploadMiddlewareExecutor extends MiddlewareExecutor<
     super();
     this.use([
       createUploadErrorHandlerMiddleware(composer),
-      createPostUploadAttachmentEnrichmentMiddleware(),
+      createPostUploadAttachmentEnrichmentMiddleware(composer),
     ]);
   }
 }

package/src/messageComposer/middleware/attachmentManager/postUpload/attachmentEnrichment.ts

@@ -4,41 +4,66 @@ import type {
   AttachmentPostUploadMiddlewareState,
 } from '../types';
 import { isLocalImageAttachment } from '../../../attachmentIdentity';
+import type { MessageComposer } from '../../../messageComposer';
 import type { LocalNotImageAttachment } from '../../../types';
 
-export const createPostUploadAttachmentEnrichmentMiddleware =
-  (): AttachmentPostUploadMiddleware => ({
-    id: 'stream-io/attachment-manager-middleware/post-upload-enrichment',
-    handlers: {
-      postProcess: ({
-        state,
-        discard,
-        forward,
-        next,
-      }: MiddlewareHandlerParams<AttachmentPostUploadMiddlewareState>) => {
-        const { attachment, error, response } = state;
-        if (error) return forward();
-        if (!attachment || !response) return discard();
+/**
+ * Writes the uploaded URL onto the attachment and releases its local preview.
+ *
+ * The preview is a blob URL the composer created for the file. Releasing it once the CDN URL is
+ * in is what keeps the browser from holding the file in memory.
+ *
+ * Pass `composer` and the preview is released only while the attachment is still one of the
+ * composer's own — still listed in `attachmentManager.attachments`, i.e. still shown above the
+ * input, waiting to be sent.
+ *
+ * This runs when an upload finishes, which can be after the composer was cleared: `uploadFile`
+ * executes this chain before the (by then no-op) `updateAttachment`. If the attachment is gone
+ * from the composer, a message is rendering from the preview instead, and releasing it would
+ * blank that message out. A message can be sent with uploads still running — see
+ * `createSendWithPendingUploadsAttachmentsMiddleware`.
+ *
+ * Omit `composer` and the preview is always released.
+ */
+export const createPostUploadAttachmentEnrichmentMiddleware = (
+  composer?: MessageComposer,
+): AttachmentPostUploadMiddleware => ({
+  id: 'stream-io/attachment-manager-middleware/post-upload-enrichment',
+  handlers: {
+    postProcess: ({
+      state,
+      discard,
+      forward,
+      next,
+    }: MiddlewareHandlerParams<AttachmentPostUploadMiddlewareState>) => {
+      const { attachment, error, response } = state;
+      if (error) return forward();
+      if (!attachment || !response) return discard();
 
-        const enrichedAttachment = { ...attachment };
-        const previewUri = attachment.localMetadata.previewUri;
-        if (previewUri) {
-          if (previewUri.startsWith('blob:')) URL.revokeObjectURL(previewUri);
-          delete enrichedAttachment.localMetadata.previewUri;
-        }
-        if (isLocalImageAttachment(attachment)) {
-          enrichedAttachment.image_url = response.file;
-        } else {
-          (enrichedAttachment as LocalNotImageAttachment).asset_url = response.file;
-        }
-        if (response.thumb_url) {
-          (enrichedAttachment as LocalNotImageAttachment).thumb_url = response.thumb_url;
-        }
+      const enrichedAttachment = { ...attachment };
+      const { id, previewUri } = attachment.localMetadata;
+      // `attachmentsById` is built from the composer's current attachment state, so a hit means
+      // the attachment is still in the composer and its preview is not in use elsewhere.
+      const attachmentIsStillInComposer =
+        !composer || !!composer.attachmentManager.attachmentsById[id];
 
-        return next({
-          ...state,
-          attachment: enrichedAttachment,
-        });
-      },
+      if (previewUri && attachmentIsStillInComposer) {
+        if (previewUri.startsWith('blob:')) URL.revokeObjectURL?.(previewUri);
+        delete enrichedAttachment.localMetadata.previewUri;
+      }
+      if (isLocalImageAttachment(attachment)) {
+        enrichedAttachment.image_url = response.file;
+      } else {
+        (enrichedAttachment as LocalNotImageAttachment).asset_url = response.file;
+      }
+      if (response.thumb_url) {
+        (enrichedAttachment as LocalNotImageAttachment).thumb_url = response.thumb_url;
+      }
+
+      return next({
+        ...state,
+        attachment: enrichedAttachment,
+      });
     },
-  });
+  },
+});

package/src/messageComposer/middleware/attachmentManager/postUpload/uploadErrorHandler.ts

@@ -4,6 +4,7 @@ import type {
   AttachmentPostUploadMiddleware,
   AttachmentPostUploadMiddlewareState,
 } from '../types';
+import { isUploadCancellation } from '../../../../uploadManager';
 
 export const createUploadErrorHandlerMiddleware = (
   composer: MessageComposer,
@@ -18,6 +19,9 @@ export const createUploadErrorHandlerMiddleware = (
       const { attachment, error } = state;
       if (!error) return forward();
       if (!attachment) return discard();
+      // A cancellation is the user getting what they asked for, so it gets no error
+      // notification. `StreamChat.doAxiosRequest` draws the same line for the same reason.
+      if (isUploadCancellation(error)) return forward();
 
       const reason = error instanceof Error ? error.message : 'unknown error';
       composer.client.notifications.addError({

package/src/messageComposer/middleware/messageComposer/MessageComposerMiddlewareExecutor.ts

@@ -23,6 +23,7 @@ import { createCompositionDataCleanupMiddleware } from './cleanData';
 import type {
   MessageComposerMiddlewareExecutorOptions,
   MessageComposerMiddlewareState,
+  MessageCompositionMiddleware,
   MessageDraftComposerMiddlewareExecutorOptions,
   MessageDraftComposerMiddlewareValueState,
 } from './types';
@@ -55,6 +56,14 @@ export class MessageComposerMiddlewareExecutor extends MiddlewareExecutor<
       createCompositionDataCleanupMiddleware(composer),
     ]);
   }
+
+  /**
+   * Narrows the base accessor to the composition middleware type, so callers can read the
+   * declarations it carries (`allowsPendingUploads`) without casting.
+   */
+  get installedMiddleware(): ReadonlyArray<MessageCompositionMiddleware> {
+    return super.installedMiddleware as ReadonlyArray<MessageCompositionMiddleware>;
+  }
 }
 
 export class MessageDraftComposerMiddlewareExecutor extends MiddlewareExecutor<

package/src/messageComposer/middleware/messageComposer/attachments.ts

@@ -1,3 +1,4 @@
+import { isFinishedUpload, isPendingUpload } from '../../attachmentIdentity';
 import type { MiddlewareHandlerParams } from '../../../middleware';
 import type { Attachment } from '../../../types';
 import type { MessageComposer } from '../../messageComposer';
@@ -15,6 +16,114 @@ const localAttachmentToAttachment = (localAttachment: LocalAttachment) => {
   return attachment as Attachment;
 };
 
+/**
+ * The composition step used by {@link createSendWithPendingUploadsAttachmentsMiddleware}.
+ *
+ * The two payloads part ways here: `localMessage.attachments` keeps `localMetadata` for
+ * anything still uploading - `id` (the `client.uploadManager` key), `file` (the handle needed
+ * to await the upload) and `previewUri` (so the message list can render the user's own file
+ * meanwhile) - while `message.attachments`, which goes to the API, carries only attachments
+ * that already resolved to a URL. Whoever performs the send fills in the rest once the uploads
+ * settle.
+ */
+const composeWithPendingUploads = ({
+  composer,
+  state,
+}: {
+  composer: MessageComposer;
+  state: MessageComposerMiddlewareState;
+}): MessageComposerMiddlewareState => {
+  // `useSubmitHandler` in the UI SDKs deliberately skips `MessageComposer.clear()` when the
+  // composition carries a poll - it keeps the composer's contents as a draft. Handing a
+  // still-uploading attachment to such a message would leave the same `localMetadata.id` owned
+  // by both the sent message and the composer: the user could send it a second time, and the
+  // second `UploadManager.upload` call would restart the request under an id whose in-flight
+  // entry had already been cleaned up. So a pending upload stays in the composer in that case
+  // and rides along with the next message once it finishes.
+  const composerIsKeptAsDraft = !!composer.pollId;
+
+  // Composer order is preserved in both payloads so previews do not reshuffle when an upload
+  // settles.
+  const relevantAttachments = composer.attachmentManager.attachments.filter(
+    (attachment) =>
+      isFinishedUpload(attachment) ||
+      (!composerIsKeptAsDraft && isPendingUpload(attachment)),
+  );
+
+  const localAttachments = (state.localMessage.attachments ?? []).concat(
+    relevantAttachments.map((attachment) =>
+      isPendingUpload(attachment) ? attachment : localAttachmentToAttachment(attachment),
+    ),
+  );
+  const messageAttachments = (state.message.attachments ?? []).concat(
+    relevantAttachments.filter(isFinishedUpload).map(localAttachmentToAttachment),
+  );
+
+  if (!localAttachments.length && !messageAttachments.length) return state;
+
+  // Each payload gets the `attachments` key only when there is something to put in it, matching
+  // the default middleware. An empty array is not "nothing to say": on an edit the API reads it
+  // as "remove every attachment", and a message whose uploads are all still in flight produces
+  // exactly that - no finished upload to put in `message.attachments` yet.
+  return {
+    ...state,
+    localMessage: localAttachments.length
+      ? {
+          ...state.localMessage,
+          attachments: localAttachments,
+        }
+      : state.localMessage,
+    message: messageAttachments.length
+      ? {
+          ...state.message,
+          attachments: messageAttachments,
+        }
+      : state.message,
+  };
+};
+
+/**
+ * Drop-in replacement for {@link createAttachmentsCompositionMiddleware} that lets a message be
+ * composed while its attachments are still uploading.
+ *
+ * Reuses the same middleware id, so installing it with
+ * `compositionMiddlewareExecutor.replace([...])` keeps its position in the chain. The default
+ * refuses instead: it warns "Wait until all attachments have uploaded" and discards the
+ * composition.
+ *
+ * **Installing this is only half of the flow.** The composition it produces is not ready for the
+ * wire — `message.attachments` omits everything that has no URL yet. Whoever performs the send
+ * has to await those uploads (`UploadManager.upload` is idempotent by `localMetadata.id`, so
+ * calling it again returns the in-flight promise), write the resolved URLs in, and send after
+ * that.
+ *
+ * Sendability follows on its own: the `allowsPendingUploads` declaration below is what
+ * {@link MessageComposer.hasSendableData} reads to stop treating an upload in flight as a
+ * blocker, so installing this middleware is the only switch there is.
+ *
+ * This is why there is no config option turning it on: the switch belongs to the UI SDK that
+ * implements the other half. stream-chat-react exposes it as a `Chat` prop;
+ * stream-chat-react-native as `allowSendBeforeAttachmentsUpload` on the message input.
+ */
+export const createSendWithPendingUploadsAttachmentsMiddleware = (
+  composer: MessageComposer,
+): MessageCompositionMiddleware => ({
+  allowsPendingUploads: true,
+  id: 'stream-io/message-composer-middleware/attachments',
+  handlers: {
+    compose: ({
+      state,
+      next,
+      forward,
+    }: MiddlewareHandlerParams<MessageComposerMiddlewareState>) => {
+      const { attachmentManager } = composer;
+      if (!attachmentManager) return forward();
+
+      return next(composeWithPendingUploads({ composer, state }));
+    },
+  },
+});
+
 export const createAttachmentsCompositionMiddleware = (
   composer: MessageComposer,
 ): MessageCompositionMiddleware => ({

package/src/messageComposer/middleware/messageComposer/types.ts

@@ -32,7 +32,28 @@ export type MessageDraftComposerMiddlewareExecutorOptions = {
 export type MessageCompositionMiddleware = Middleware<
   MessageComposerMiddlewareState,
   'compose'
->;
+> & {
+  /**
+   * Declares that this middleware composes messages whose attachment uploads are still in
+   * flight, instead of refusing to compose until they finish.
+   *
+   * {@link MessageComposer.hasSendableData} reads this: an upload in flight must not block the
+   * send while such a middleware is installed, or the send could never be triggered. Any
+   * middleware implementing that contract may set it - the composer keys off the declaration,
+   * not off a middleware id, so a custom implementation is treated the same as the one shipped
+   * here.
+   *
+   * Composing this way is only half of the flow: whoever performs the send has to await those
+   * uploads and write the resolved URLs into the payload. See
+   * {@link createSendWithPendingUploadsAttachmentsMiddleware}.
+   *
+   * **Temporary API.** In v10 sending with pending uploads becomes part of the composer
+   * configuration (`MessageComposerConfig`, set through `updateConfig`), and this declaration,
+   * together with {@link MessageComposer.allowsPendingUploads}, is replaced by that config
+   * field.
+   */
+  allowsPendingUploads?: boolean;
+};
 
 export type MessageDraftCompositionMiddleware = Middleware<
   MessageDraftComposerMiddlewareValueState,

package/src/messageComposer/types.ts

@@ -119,6 +119,11 @@ export type LocalAttachmentUploadMetadata = {
    */
   previewUri?: string;
   uploadState: AttachmentLoadingState;
+  /**
+   * Mirrors {@link UploadRecord.uploadConfirmationPending}: every byte has been sent, but the server has
+   * not confirmed yet - not returned response to the upload request. Render an indeterminate indicator rather than a full bar.
+   */
+  uploadConfirmationPending?: boolean;
   uploadPermissionCheck?: UploadPermissionCheckResult; // added new
   /** 0–100 while uploading when progress tracking is enabled; undefined otherwise or when indeterminate */
   uploadProgress?: number;

package/src/messageDelivery/MessageDeliveryReporter.ts

@@ -10,7 +10,7 @@ import type {
   MarkReadOptions,
 } from '../types';
 import { type APIErrorResponse } from '../types';
-import { throttle, userHasReadReceipts } from '../utils';
+import { throttle } from '../utils';
 import { isAPIError, isErrorRetryable } from '../errors';
 
 const MAX_DELIVERED_MESSAGE_COUNT_IN_PAYLOAD = 100 as const;
@@ -279,8 +279,6 @@ export class MessageDeliveryReporter {
    * @param options
    */
   public markRead = async (collection: Channel | Thread, options?: MarkReadOptions) => {
-    if (!userHasReadReceipts(this.client)) return null;
-
     let result: EventAPIResponse | null = null;
     if (isChannel(collection)) {
       result = await collection.markAsReadRequest(options);
@@ -291,7 +289,10 @@ export class MessageDeliveryReporter {
       });
     }
 
-    this.removeCandidateFor(collection);
+    // A read implies delivery, so the candidate is only dropped once the request actually went
+    // out. `markAsReadRequest` returns null for channels that do not track read state on the
+    // backend, and those candidates must survive for the next delivery report.
+    if (result) this.removeCandidateFor(collection);
     return result;
   };
 

package/src/middleware.ts

@@ -58,6 +58,17 @@ export class MiddlewareExecutor<TValue, THandlers extends string> {
     this.id = generateUUIDv4();
   }
 
+  /**
+   * The middleware currently installed, in execution order.
+   *
+   * Read-only: use `use` / `insert` / `replace` / `setOrder` / `remove` to change the chain. It
+   * exists so components can ask what the chain is capable of - a middleware may declare
+   * behaviour its host has to account for, and the host has no other way to find out.
+   */
+  get installedMiddleware(): ReadonlyArray<Middleware<TValue, THandlers>> {
+    return this.middleware;
+  }
+
   use(middleware: Middleware<TValue, THandlers> | Middleware<TValue, THandlers>[]) {
     this.middleware = this.middleware.concat(middleware);
     return this;

package/src/offline-support/offline_support_api.ts

@@ -1050,6 +1050,10 @@ export abstract class AbstractOfflineDB implements OfflineDBApi {
     }
 
     if (type === 'message.read' || type === 'notification.mark_read') {
+      // We make sure not to update channel reads (which is what's stored in
+      // the offline DB in any case) whenever we receive a read event for a
+      // a thread specifically.
+      if (event.thread) return [];
       return this.handleRead({ event, unreadMessages: 0, execute });
     }
 

package/src/uploadManager.ts

@@ -1,10 +1,44 @@
+import axios from 'axios';
+
 import type { StreamChat } from './client';
 import type { UploadRequestOptions } from './messageComposer/configuration/types';
 import { StateStore } from './store';
 import type { AttachmentManager } from '.';
 
+/**
+ * Whether an upload ended because it was aborted rather than because it failed.
+ *
+ * {@link UploadManager.deleteUploadRecord} and {@link UploadManager.cancelAllUploads} abort the
+ * request through its `AbortController`, which is what happens when an attachment is removed
+ * from the composer mid-upload or the client disconnects. Axios reports that as a
+ * `CanceledError` (`axios.isCancel`); a custom `doUploadRequest` on another transport
+ * conventionally throws a `DOMException` named `AbortError`.
+ *
+ * Callers use this to keep a deliberate cancellation from being reported as an error.
+ */
+export const isUploadCancellation = (error: unknown) =>
+  axios.isCancel(error) || (error instanceof Error && error.name === 'AbortError');
+
 export type UploadRecord = {
   id: string;
+  /**
+   * `true` once every byte has been handed to the transport but the server has not responded
+   * yet.
+   *
+   * Upload progress measures bytes *written to the connection*, not bytes the server
+   * acknowledged, so it reaches 100% the moment the request body is flushed — then the
+   * connection sits idle while the CDN ingests the file and the response travels back. On a
+   * large file over a slow link that window is long, and a UI that renders 100% as "done"
+   * claims the upload is confirmed while it is not.
+   *
+   * Nothing measurable happens during that window, so it is the point at which a determinate
+   * progress bar should hand over to an indeterminate one. Confirmation is the record being
+   * removed, not progress reaching 100.
+   *
+   * Requires `AttachmentManagerConfig.trackUploadProgress`; without progress reporting there is
+   * no way to tell when the flush happened, and this stays `false`.
+   */
+  uploadConfirmationPending?: boolean;
   uploadProgress?: number;
 };
 
@@ -126,6 +160,7 @@ export class UploadManager {
       const trackProgress = attachmentManager.config.trackUploadProgress;
       try {
         this.upsertUpload({
+          uploadConfirmationPending: false,
           id,
           uploadProgress: trackProgress ? 0 : undefined,
         });
@@ -135,6 +170,16 @@ export class UploadManager {
               this.updateUpload({
                 id,
                 uploadProgress: progress,
+                // Only a number says anything about the flush, so a report without one leaves
+                // the flag alone: `undefined` means the transport cannot measure this upload,
+                // not that bytes were un-sent. Lowering it there would drop a UI that had
+                // already gone indeterminate back to a determinate one with nothing to show.
+                //
+                // The record is removed in the `finally` below, so a record that still exists
+                // while reporting 100% can only mean "flushed, awaiting the response".
+                ...(typeof progress === 'number'
+                  ? { uploadConfirmationPending: progress >= 100 }
+                  : {}),
               });
             }
           : undefined;