docs(js-sdk): add Upload Files documentation

docs.json

@@ -3195,6 +3195,7 @@
                             "group": "Messaging",
                             "pages": [
                               "sdk/javascript/send-message",
+                              "sdk/javascript/upload-files",
                               "sdk/javascript/receive-message",
                               "sdk/javascript/card-messages",
                               "sdk/javascript/message-filtering",

sdk/javascript/error-codes.mdx

@@ -21,7 +21,7 @@
 }
 ```
 
-**Error categories:** Initialization, Login, Calling, Messages, Groups, Users, Conversations, Receipts, AI, Extensions
+**Error categories:** Initialization, Login, Calling, Messages, Media Upload, Groups, Users, Conversations, Receipts, AI, Extensions
 </Accordion>
 
 Every error thrown by the CometChat SDK is a [`CometChatException`](/sdk/reference/auxiliary#cometchatexception) object with four properties:
@@ -83,7 +83,7 @@
 | Code | Message |
 |------|---------|
 | `COMETCHAT_INITIALIZATION_NOT_DONE` | Please initialize CometChat before using the login method. |
 | `USER_NOT_AUTHORISED` | The authToken of the user is not authorised. Please verify again. |
 | `AUTH_ERR_AUTH_TOKEN_NOT_FOUND` | The auth token does not exist. Please make sure you are logged in and have a valid auth token. |
 | `LOGIN_IN_PROGRESS` | Please wait until the previous login request ends. |
 | `WS_CONNECTION_FAIL` | WebSocket connection failed. |
@@ -110,9 +110,24 @@
 |------|---------|
 | `INVALID_RECEIVER_TYPE` | Receiver type can be `user` or `group`. |
 | `REQUEST_IN_PROGRESS` | Request in progress. |
 | `NOT_ENOUGH_PARAMETERS` | Timestamp, MessageId, or updatedAfter is required to use fetchNext(). |
 | `INVALID_REASON_ID` | Invalid reasonId provided. |
 
+## Media Upload Errors
+
+Raised by the [Upload Files](/sdk/javascript/upload-files) flow — delivered through the `UploadFileListener` (`onFileError` / `onFileFailure`) — and by `sendMediaMessage()`. **Rejected** errors (`onFileError`) mean the input must change and are not retryable; **failed** errors (`onFileFailure`) are transient and can be retried with `retryAttachment()`.
+
+| Code | Surfaced via | Retryable | Message |
+|------|--------------|-----------|---------|
+| `ERR_INVALID_FILE_OBJECT` | `onFileError` | No | The provided file is invalid or its size cannot be determined. |
+| `ERR_FILE_SIZE_EXCEEDED` | `onFileError` | No | The file `%s` exceeds the maximum allowed size of `%s` bytes. |
+| `ERR_PERMISSION_DENIED` | `onFileError` | No | The sender does not have permission to upload media to the specified `receiverId` / `receiverType` (role/scope-based access control). |
+| `ERR_BAD_REQUEST` | `onFileError` | No | The server rejected the presign request for this file (e.g. a corrupted or otherwise invalid file). |
+| `ERR_FILE_COUNT_EXCEEDED` | `sendMediaMessage()` | No | The number of attachments exceeds the allowed limit of `%s`. |
+| `ERR_S3_UPLOAD_FAILED` | `onFileFailure`, `onFileError` | Yes / No | Failed to upload the file to storage (`onFileFailure`, retryable); also the fallback when the server declines a file with no specific code (`onFileError`, not retryable). |
+| `ERR_PRESIGNED_URL_EXPIRED` | `onFileFailure` | Yes | The pre-signed upload URL has expired. Please retry the upload. |
+| `ERR_UPLOAD_STALLED` | `onFileFailure` | Yes | The upload stalled with no progress and was aborted. |
+
 ## User Errors
 
 | Code | Message |
@@ -135,7 +150,7 @@
 | Code | Message |
 |------|---------|
 | `INVALID_CONVERSATION_TYPE` | Conversation type can be `user` or `group`. |
 | `CONVERSATION_NOT_FOUND` | Conversation not found. Check the value of conversationWith and conversationType. |
 | `ERR_CONVERSATION_NOT_ACCESSIBLE` | The conversation is not accessible to the requesting user. |
 
 <Note>
@@ -205,9 +220,9 @@
 
 | Code | Message |
 |------|---------|
 | `ERROR_INVALID_SESSIONID` | The provided sessionId cannot be null or empty. |
 | `ERROR_INVALID_TYPE` | The provided type cannot be null or empty. |
 | `ERROR_INVALID_GROUPLIST` | Grouplist cannot be null or empty. |
 
 ## General Errors
 

sdk/javascript/send-message.mdx

@@ -20,12 +20,12 @@
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   messageText: string = "Hello world!",
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   textMessage: CometChat.TextMessage = new CometChat.TextMessage(
     receiverID,
     messageText,
     receiverType
   );
 
 CometChat.sendMessage(textMessage).then(
@@ -66,12 +66,12 @@
 ```javascript
 try {
   const receiverID = "UID";
   const messageText = "Hello world!";
   const receiverType = CometChat.RECEIVER_TYPE.USER;
   const textMessage = new CometChat.TextMessage(
     receiverID,
     messageText,
     receiverType
   );
 
   const message = await CometChat.sendMessage(textMessage);
@@ -114,7 +114,7 @@
 let textMessage = new CometChat.TextMessage(
   receiverID,
   messageText,
   receiverType
 );
 
 CometChat.sendMessage(textMessage).then(
@@ -162,15 +162,15 @@
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   file: File = (document.getElementById("img_file") as HTMLInputElement).files![0];
 
 let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
 receiverID,
 file,
 messageType,
 receiverType
 );
 
 CometChat.sendMediaMessage(mediaMessage).then(
@@ -214,15 +214,15 @@
 <Tab title="TypeScript (Group)">
 ```typescript
 let receiverID: string = "GUID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
   file: File = (document.getElementById("img_file") as HTMLInputElement).files![0];
 
 let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
 receiverID,
 file,
 messageType,
 receiverType
 );
 
 CometChat.sendMediaMessage(mediaMessage).then(
@@ -273,12 +273,12 @@
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
     receiverID,
     "",
     messageType,
     receiverType
   );
 
@@ -341,12 +341,12 @@
 <Tab title="TypeScript (Group)">
 ```typescript
 let receiverID: string = "GUID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
   mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
     receiverID,
     "",
     messageType,
     receiverType
   );
 
@@ -428,7 +428,7 @@
     ```typescript mediaMessage.setCaption("Check out this photo!"); ```
   </Tab>
   <Tab title="JavaScript">
     ```javascript mediaMessage.setCaption("Check out this photo!"); ```
   </Tab>
 </Tabs>
 
@@ -446,9 +446,15 @@
 
 ## Multiple Attachments in a Media Message
 
-Starting version 3.0.9 & above the SDK supports sending multiple attachments in a single media message. As in the case of a single attachment in a media message, there are two ways you can send Media Messages using the CometChat SDK:
+The SDK supports sending multiple attachments in a single media message. A media message can carry up to a configurable maximum number of attachments (default **10**, controlled by the `file.count.max` app setting). `sendMediaMessage()` rejects with [`ERR_FILE_COUNT_EXCEEDED`](/sdk/javascript/error-codes#media-upload-errors) if you exceed it — read the current limit at runtime with `CometChat.getMaxAttachmentCount()`.
 
-1. **By providing an array of files:** You can now share an array of files while creating an object of the MediaMessage class. When the media message is sent using the `sendMediaMessage()` method, the files are uploaded to the CometChat servers & the URL of the files is sent in the success response of the `sendMediaMessage()` method.
+<Tip>
+**Recommended: upload first, then send.** For a real composer — where you want a progress bar per file, and the ability to remove or retry individual files — create an upload request with [`CometChat.createUploadFileRequest()`](/sdk/javascript/upload-files), upload your files through it, then collect the resulting `Attachment`s (`request.getAttachments()`) and attach them here with `setAttachments()`. This decouples the (slow, cancellable) upload from the (instant) send. See [Upload Files & Send Attachments](/sdk/javascript/upload-files) for the full flow.
+</Tip>
+
+There are two ways to send a multi-attachment media message using the CometChat SDK:
+
+1. **By providing an array of files:** You can share an array of files while creating an object of the MediaMessage class. When the media message is sent using the `sendMediaMessage()` method, the files are uploaded to the CometChat servers & the URL of the files is sent in the success response of the `sendMediaMessage()` method. This is the simplest path, but it gives no upload progress and no per-file cancel/retry — for that, [upload first](/sdk/javascript/upload-files).
 
 Getting files:
 
@@ -465,7 +471,7 @@
       const userType = CometChat.RECEIVER_TYPE.USER;
       const mediaMessage = new MediaMessage(UID, files, fileType, userType);
     </script>
   </body>
 </html>
 ```
 
@@ -474,12 +480,12 @@
 </Tabs>
 
 <Tabs>
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   messageType: string = CometChat.MESSAGE_TYPE.FILE,
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   files: FileList = (document.getElementById("img_file") as HTMLInputElement).files!;
 
 let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
 receiverID,
@@ -517,7 +523,7 @@
     console.log("Media message sent successfully", message);
   },
   (error) => {
     console.log("Media message sending failed with error", error);
   }
 );
 ````
@@ -529,7 +535,7 @@
 let receiverID: string = "GUID",
   messageType: string = CometChat.MESSAGE_TYPE.FILE,
   receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
   files: FileList = (document.getElementById("img_file") as HTMLInputElement).files!;
 
 let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
 receiverID,
@@ -580,12 +586,14 @@
 
 ### Send Multiple URLs
 
+Provide an array of [`Attachment`](/sdk/reference/auxiliary#attachment) objects that already point at hosted URLs. This is also the path the [upload-then-send flow](/sdk/javascript/upload-files) uses — the `Attachment`s from an upload request's `getAttachments()` are ready to pass straight to `setAttachments()`.
+
 <Tabs>
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
     receiverID,
     "",
@@ -662,7 +670,7 @@
     console.log("Media message sent successfully", message);
   },
   (error) => {
     console.log("Media message sending failed with error", error);
   }
 );
 ````
@@ -673,7 +681,7 @@
 ```typescript
 let receiverID: string = "GUID",
   messageType: string = CometChat.MESSAGE_TYPE.IMAGE,
   receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
   mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage(
     receiverID,
     "",
@@ -761,19 +769,19 @@
 
 ## Custom Message
 
 Send structured data that doesn't fit text or media categories — like location coordinates, polls, or game moves.
 
 <Tabs>
 <Tab title="TypeScript (User)">
 ```typescript
 let receiverID: string = "UID",
   customData: Object = {
     latitude: "50.6192171633316",
     longitude: "-72.68182268750002",
   },
   customType: string = "location",
   receiverType: string = CometChat.RECEIVER_TYPE.USER,
   customMessage: CometChat.CustomMessage = new CometChat.CustomMessage(
     receiverID,
     receiverType,
     customType,
@@ -814,7 +822,7 @@
     console.log("Custom message sent successfully", message);
   },
   (error) => {
     console.log("Custom message sending failed with error", error);
   }
 );
 ````
@@ -823,14 +831,14 @@
 
 <Tab title="TypeScript (Group)">
 ```typescript
 let receiverID: string = "GUID",
   customData: Object = {
     latitude: "50.6192171633316",
     longitude: "-72.68182268750002",
   },
   customType: string = "location",
   receiverType: string = CometChat.RECEIVER_TYPE.GROUP,
   customMessage: CometChat.CustomMessage = new CometChat.CustomMessage(
     receiverID,
     receiverType,
     customType,