feat: allow tracking file/image upload progress (#1708)

## CLA

- [ ] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required).
- [ ] Code changes are tested

## Description of the changes, What, Why and How?

https://linear.app/stream/issue/REACT-925/upload-progress-tracking 

## Changelog

-

Author: szuperaz

docs/fileUpload.md

@@ -71,3 +71,57 @@ console.log('file url: ', response.file);
   </body>
 </html>
 ```
+
+## `axiosRequestConfig` (channel and client uploads)
+
+Channel uploads use Axios under the hood. Both **`channel.sendFile`** and **`channel.sendImage`** accept an optional **fifth argument** `axiosRequestConfig` (`AxiosRequestConfig` from axios). The same optional argument exists on **`client.uploadFile`** and **`client.uploadImage`**.
+
+The client merges your config **after** its upload defaults (`timeout: 0`, large `maxContentLength` / `maxBodyLength`, and multipart headers from the form data). Any property you set can override or extend those defaults.
+
+Typical uses:
+
+- **`onUploadProgress`** — track bytes sent (see below)
+- **`signal`** — pass `AbortSignal` from an `AbortController` to cancel an in-flight upload
+- Other Axios per-request options your runtime supports
+
+### Upload progress (`onUploadProgress`)
+
+```js
+// client.uploadFile with progress
+const response = await client.uploadFile(file, file.name, file.type, undefined, {
+  onUploadProgress: (progressEvent) => {
+    const percent = progressEvent.total
+      ? Math.round((progressEvent.loaded * 100) / progressEvent.total)
+      : 0;
+    console.log(`Upload: ${percent}%`);
+  },
+});
+
+// channel.sendFile with progress
+const response = await channel.sendFile(file, file.name, file.type, undefined, {
+  onUploadProgress: (progressEvent) => {
+    const percent = progressEvent.total
+      ? Math.round((progressEvent.loaded * 100) / progressEvent.total)
+      : 0;
+    console.log(`Upload: ${percent}%`);
+  },
+});
+
+// channel.sendImage with progress (same fifth argument)
+const imageResponse = await channel.sendImage(file, file.name, file.type, undefined, {
+  onUploadProgress: (progressEvent) => {
+    const percent = progressEvent.total
+      ? Math.round((progressEvent.loaded * 100) / progressEvent.total)
+      : 0;
+    console.log(`Image upload: ${percent}%`);
+  },
+});
+```
+
+## Message composer / attachment manager
+
+When using the message composer’s attachment manager, upload progress is tracked when `config.attachments.trackUploadProgress` is `true` (the default). Progress is stored on each attachment’s `localMetadata.uploadProgress` (0–100 for the default upload path, from the axios progress event; the initial state is 0% when the upload starts).
+
+With a custom `doUploadRequest`, the function receives an optional second argument `options` with `onProgress?: (percent: number | undefined) => void`. Call `onProgress` from your upload implementation to drive the same `localMetadata.uploadProgress` updates. If you do not call it, `uploadProgress` stays at 0 until the upload finishes.
+
+Set `trackUploadProgress` to `false` to skip setting `uploadProgress` (will be `undefined` in this case) and to omit progress callbacks to both the default channel upload and custom `doUploadRequest`.

src/channel.ts

@@ -1,3 +1,4 @@
+import type { AxiosRequestConfig } from 'axios';
 import { ChannelState } from './channel_state';
 import { CooldownTimer } from './CooldownTimer';
 import { MessageComposer } from './messageComposer';
@@ -245,33 +246,57 @@ export class Channel {
     return await this._sendMessage(message, options);
   }
 
+  /**
+   * Upload a file to this channel’s file endpoint (multipart). Forwards to the client’s `sendFile` implementation.
+   *
+   * @param uri File source: URL string, `File`, `Buffer`, or readable stream (Node).
+   * @param name File name sent in the multipart body.
+   * @param contentType MIME type; defaults are applied when omitted.
+   * @param user Optional user payload appended to the form as JSON.
+   * @param axiosRequestConfig Optional Axios per-request config, merged after upload defaults (e.g. `onUploadProgress`, `signal` from `AbortController`).
+   * @return Promise resolving to `{ file: string, ... }` with the CDN URL.
+   */
   sendFile(
     uri: string | NodeJS.ReadableStream | Buffer | File,
     name?: string,
     contentType?: string,
     user?: UserResponse,
+    axiosRequestConfig?: AxiosRequestConfig,
   ) {
     return this.getClient().sendFile(
       `${this._channelURL()}/file`,
       uri,
       name,
       contentType,
       user,
+      axiosRequestConfig,
     );
   }
 
+  /**
+   * Upload an image to this channel’s image endpoint (multipart). Uses the same transport as `sendFile`.
+   *
+   * @param uri Image source: URL string, `File`, or readable stream (Node). For `Buffer` uploads, use `sendFile` toward the channel file endpoint instead.
+   * @param name File name sent in the multipart body.
+   * @param contentType MIME type.
+   * @param user Optional user payload appended to the form as JSON.
+   * @param axiosRequestConfig Optional Axios per-request config, merged after upload defaults (e.g. `onUploadProgress`, `signal`).
+   * @return Promise resolving to `{ file: string, ... }` with the CDN URL.
+   */
   sendImage(
     uri: string | NodeJS.ReadableStream | File,
     name?: string,
     contentType?: string,
     user?: UserResponse,
+    axiosRequestConfig?: AxiosRequestConfig,
   ) {
     return this.getClient().sendFile(
       `${this._channelURL()}/image`,
       uri,
       name,
       contentType,
       user,
+      axiosRequestConfig,
     );
   }
 

src/client.ts

@@ -1311,6 +1311,7 @@ export class StreamChat {
     name?: string,
     contentType?: string,
     user?: UserResponse,
+    axiosRequestConfig?: AxiosRequestConfig,
   ) {
     const data = addFileToFormData(uri, name, contentType || 'multipart/form-data');
     if (user != null) data.append('user', JSON.stringify(user));
@@ -1321,6 +1322,7 @@ export class StreamChat {
         timeout: 0,
         maxContentLength: Infinity,
         maxBodyLength: Infinity,
+        ...axiosRequestConfig,
       },
     });
   }
@@ -4866,6 +4868,7 @@ export class StreamChat {
    * @param {string} [name] The name of the file
    * @param {string} [contentType] The content type of the file
    * @param {UserResponse} [user] Optional user information
+   * @param {AxiosRequestConfig} [axiosRequestConfig] Optional axios config (e.g. onUploadProgress for progress tracking)
    *
    * @return {Promise<SendFileAPIResponse>} Response containing the file URL
    */
@@ -4874,8 +4877,16 @@ export class StreamChat {
     name?: string,
     contentType?: string,
     user?: UserResponse,
+    axiosRequestConfig?: AxiosRequestConfig,
   ) {
-    return this.sendFile(`${this.baseURL}/uploads/file`, uri, name, contentType, user);
+    return this.sendFile(
+      `${this.baseURL}/uploads/file`,
+      uri,
+      name,
+      contentType,
+      user,
+      axiosRequestConfig,
+    );
   }
 
   /**
@@ -4885,6 +4896,7 @@ export class StreamChat {
    * @param {string} [name] The name of the image
    * @param {string} [contentType] The content type of the image
    * @param {UserResponse} [user] Optional user information
+   * @param {AxiosRequestConfig} [axiosRequestConfig] Optional axios config (e.g. onUploadProgress for progress tracking)
    *
    * @return {Promise<SendFileAPIResponse>} Response containing the image URL
    */
@@ -4893,8 +4905,16 @@ export class StreamChat {
     name?: string,
     contentType?: string,
     user?: UserResponse,
+    axiosRequestConfig?: AxiosRequestConfig,
   ) {
-    return this.sendFile(`${this.baseURL}/uploads/image`, uri, name, contentType, user);
+    return this.sendFile(
+      `${this.baseURL}/uploads/image`,
+      uri,
+      name,
+      contentType,
+      user,
+      axiosRequestConfig,
+    );
   }
 
   /**

src/messageComposer/attachmentManager.ts

@@ -2,6 +2,7 @@ import type {
   AttachmentManagerConfig,
   MinimumUploadRequestResult,
   UploadRequestFn,
+  UploadRequestOptions,
 } from './configuration';
 import { isLocalImageAttachment, isUploadedAttachment } from './attachmentIdentity';
 import {
@@ -445,12 +446,31 @@ export class AttachmentManager {
    * Method to perform the default upload behavior without checking for custom upload functions
    * to prevent recursive calls
    */
-  doDefaultUploadRequest = async (fileLike: FileReference | FileLike) => {
+  doDefaultUploadRequest = async (
+    fileLike: FileReference | FileLike,
+    options?: UploadRequestOptions,
+  ) => {
+    const progressHandler = options?.onProgress
+      ? (progressEvent: {
+          loaded: number;
+          total?: number;
+          lengthComputable?: boolean;
+        }) => {
+          const percent =
+            progressEvent.lengthComputable && progressEvent.total
+              ? Math.round((progressEvent.loaded * 100) / progressEvent.total)
+              : undefined;
+          options.onProgress?.(percent);
+        }
+      : undefined;
+
     if (isFileReference(fileLike)) {
       return this.channel[isImageFile(fileLike) ? 'sendImage' : 'sendFile'](
         fileLike.uri,
         fileLike.name,
         fileLike.type,
+        undefined,
+        progressHandler ? { onUploadProgress: progressHandler } : undefined,
       );
     }
 
@@ -463,22 +483,32 @@ export class AttachmentManager {
         });
 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { duration, ...result } =
-      await this.channel[isImageFile(fileLike) ? 'sendImage' : 'sendFile'](file);
+    const { duration, ...result } = await this.channel[
+      isImageFile(fileLike) ? 'sendImage' : 'sendFile'
+    ](
+      file,
+      undefined,
+      undefined,
+      undefined,
+      progressHandler ? { onUploadProgress: progressHandler } : undefined,
+    );
     return result;
   };
 
   /**
    * todo: docs how to customize the image and file upload by overriding do
    */
 
-  doUploadRequest = async (fileLike: FileReference | FileLike) => {
+  doUploadRequest = async (
+    fileLike: FileReference | FileLike,
+    options?: UploadRequestOptions,
+  ) => {
     const customUploadFn = this.config.doUploadRequest;
     if (customUploadFn) {
-      return await customUploadFn(fileLike);
+      return await customUploadFn(fileLike, options);
     }
 
-    return this.doDefaultUploadRequest(fileLike);
+    return this.doDefaultUploadRequest(fileLike, options);
   };
 
   // @deprecated use attachmentManager.uploadFile(file)
@@ -507,26 +537,45 @@ export class AttachmentManager {
       return localAttachment;
     }
 
-    this.upsertAttachments([
-      {
-        ...attachment,
-        localMetadata: {
-          ...attachment.localMetadata,
-          uploadState: 'uploading',
-        },
+    const shouldTrackProgress = this.config.trackUploadProgress;
+    const uploadingAttachment: LocalUploadAttachment = {
+      ...attachment,
+      localMetadata: {
+        ...attachment.localMetadata,
+        uploadState: 'uploading',
+        ...(shouldTrackProgress && { uploadProgress: 0 }),
       },
-    ]);
+    };
+    this.upsertAttachments([uploadingAttachment]);
+
+    const uploadOptions = shouldTrackProgress
+      ? {
+          onProgress: (percent: number | undefined) => {
+            this.updateAttachment({
+              ...uploadingAttachment,
+              localMetadata: {
+                ...uploadingAttachment.localMetadata,
+                uploadProgress: percent,
+              },
+            });
+          },
+        }
+      : undefined;
 
     let response: MinimumUploadRequestResult;
     try {
-      response = await this.doUploadRequest(localAttachment.localMetadata.file);
+      response = await this.doUploadRequest(
+        localAttachment.localMetadata.file,
+        uploadOptions,
+      );
     } catch (error) {
       const reason = error instanceof Error ? error.message : 'unknown error';
       const failedAttachment: LocalUploadAttachment = {
         ...attachment,
         localMetadata: {
           ...attachment.localMetadata,
           uploadState: 'failed',
+          uploadProgress: undefined,
         },
       };
 
@@ -561,6 +610,7 @@ export class AttachmentManager {
       localMetadata: {
         ...attachment.localMetadata,
         uploadState: 'finished',
+        uploadProgress: undefined,
       },
     };
 
@@ -605,19 +655,35 @@ export class AttachmentManager {
       return preUpload.state.attachment;
     }
 
+    const shouldTrackProgress = this.config.trackUploadProgress;
     attachment = {
       ...attachment,
       localMetadata: {
         ...attachment.localMetadata,
         uploadState: 'uploading',
+        ...(shouldTrackProgress && { uploadProgress: 0 }),
       },
     };
     this.upsertAttachments([attachment]);
 
+    const uploadOptions = shouldTrackProgress
+      ? {
+          onProgress: (percent: number | undefined) => {
+            this.updateAttachment({
+              ...attachment,
+              localMetadata: {
+                ...attachment.localMetadata,
+                uploadProgress: percent,
+              },
+            });
+          },
+        }
+      : undefined;
+
     let response: MinimumUploadRequestResult | undefined;
     let error: Error | undefined;
     try {
-      response = await this.doUploadRequest(file);
+      response = await this.doUploadRequest(file, uploadOptions);
     } catch (err) {
       error = err instanceof Error ? err : undefined;
     }
@@ -630,6 +696,7 @@ export class AttachmentManager {
           localMetadata: {
             ...attachment.localMetadata,
             uploadState: error ? 'failed' : 'finished',
+            uploadProgress: undefined,
           },
         },
         error,

src/messageComposer/configuration/configuration.ts

@@ -31,6 +31,7 @@ export const DEFAULT_ATTACHMENT_MANAGER_CONFIG: AttachmentManagerConfig = {
   acceptedFiles: [], // an empty array means all files are accepted
   fileUploadFilter: () => true,
   maxNumberOfFilesPerMessage: API_MAX_FILES_ALLOWED_PER_MESSAGE,
+  trackUploadProgress: true,
 };
 
 export const DEFAULT_TEXT_COMPOSER_CONFIG: TextComposerConfig = {