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 @@ try {
 }
 ```
 
-**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:
@@ -113,6 +113,21 @@ try {
 | `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_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. |
+| `ERR_UPLOAD_CANCELLED` | — | — | The upload was cancelled. |
+
 ## User Errors
 
 | Code | Message |

sdk/javascript/send-message.mdx

@@ -446,9 +446,15 @@ The `sendMediaMessage()` method returns a [`MediaMessage`](/sdk/reference/messag
 
 ## 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:
 
@@ -580,6 +586,8 @@ CometChat.sendMediaMessage(mediaMessage).then(
 
 ### 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