@wix/media 1.0.50 → 1.0.52

package/build/cjs/src/media-site-media-v1-file-descriptor.universal.d.ts

@@ -210,7 +210,7 @@ export interface VideoResolution {
     /**
      * Video format
      * Possible values: ['144p.mp4' '144p.webm' '240p.mp4' '240p.webm' '360p.mp4' '360p.webm' '480p.mp4' '480p.webm'
-     * '720p.mp4' '720p.webm' '1080p.mp4' '1080p.webm' ]
+     * '720p.mp4' '720p.webm' '1080p.mp4' '1080p.webm', 'hls' ]
      */
     format?: string;
 }
@@ -356,9 +356,9 @@ export interface FileReady {
     triggeredByUndelete?: boolean;
 }
 export interface ExternalInfo {
-    /** External information to pass in the [File Ready](https://dev.wix.com/api/rest/media/media-manager/files/file-ready-domain-event) or [File Failed](https://dev.wix.com/api/rest/media/media-manager/files/file-failed-domain-event) events. */
+    /** External information to pass in the File Ready or File Failed events. */
     origin?: string;
-    /** External IDs to pass in the [File Ready](https://dev.wix.com/api/rest/media/media-manager/files/file-ready-domain-event) or [File Failed](https://dev.wix.com/api/rest/media/media-manager/files/file-failed-domain-event) events. */
+    /** External IDs to pass in the File Ready or File Failed events. */
     externalIds?: string[];
 }
 export interface FileFailed {
@@ -641,11 +641,13 @@ export interface ListFilesRequest {
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */
@@ -666,13 +668,12 @@ export declare enum SortOrder {
     DESC = "DESC"
 }
 export interface CursorPaging {
-    /** Number of items to load. */
+    /** Maximum number of items to return in the results. */
     limit?: number | null;
     /**
      * Pointer to the next or previous page in the list of results.
      *
-     * You can get the relevant cursor token
-     * from the `pagingMetadata` object in the previous call's response.
+     * Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response.
      * Not relevant for the first request.
      */
     cursor?: string | null;
@@ -684,13 +685,13 @@ export interface ListFilesResponse {
     nextCursor?: PagingMetadataV2;
 }
 export interface PagingMetadataV2 {
-    /** Total number of items that match the query. */
+    /** Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. */
     total?: number | null;
     /** Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. */
     cursors?: Cursors;
 }
 export interface Cursors {
-    /** Cursor pointing to next page in the list of results. */
+    /** Cursor string pointing to the next page in the list of results. */
     next?: string | null;
 }
 export interface SearchFilesRequest {
@@ -713,11 +714,13 @@ export interface SearchFilesRequest {
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */
@@ -789,11 +792,13 @@ export interface ListDeletedFilesRequest {
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */
@@ -1377,6 +1382,8 @@ export interface ListDeletedFilesResponseNonNullableFields {
 /**
  * Generates a URL for downloading a compressed file containing specific files in the Media Manager.
  *
+ * The `generateFilesDownloadUrl()` function returns a Promise that resolves to a download URL.
+ *
  * The compressed file can contain up to 1000 files.
  * @param fileIds - IDs of the files to download.
  * @public
@@ -1390,10 +1397,12 @@ export declare function generateFilesDownloadUrl(fileIds: string[]): Promise<Gen
 /**
  * Generates one or more temporary URLs for downloading a specific file in the Media Manager.
  *
+ * The `generateFileDownloadUrl()` function returns a Promise that resolves to an array containing download URLs for the assets specified in the options parameter.
+ *
  * To download different assets of the file, use the `assetKeys` parameter which generates a download URL for each asset.
- * If no `assetKey` is specified, it defaults to `src`, which generates one download URL in the original file's format and quality.
+ * If no asset key is specified, it defaults to `src`, which generates one download URL in the original file's format and quality.
  *
- * Use this endpoint to grant external clients access to a private media file. Use the `expirationInMinutes` parameter to set the URL expiration time, and the `expirationRedirectUrl` parameter to add a redirect url when the URL expires.
+ * Use this endpoint to grant external clients access to a private media file. Use the `expirationInMinutes` parameter to set the URL expiration time, and the `expirationRedirectUrl` parameter to add a redirect URL when the URL expires.
  * @param fileId - File ID.
  * @public
  * @requiredField fileId
@@ -1438,6 +1447,11 @@ export interface GenerateFileDownloadUrlOptions {
 }
 /**
  * Gets information about the specified file in the Media Manager.
+ *
+ *
+ * The `getFileDescriptor()` function returns a Promise that resolves to the specified file's descriptor.
+ *
+ * Use `getFileDescriptors()` to get multiple file descriptors at once.
  * @param fileId - File ID.
  * @public
  * @documentationMaturity preview
@@ -1451,6 +1465,11 @@ export interface GenerateFileDownloadUrlOptions {
 export declare function getFileDescriptor(fileId: string): Promise<FileDescriptor & NonNullable<GetFileDescriptorResponseNonNullableFields>['file']>;
 /**
  * Gets information about the specified files in the Media Manager.
+ *
+ *
+ * The `getFileDescriptors()` function returns a Promise that resolves to an array containing the specified files' descriptors.
+ *
+ * Use `getFileDescriptor()` to get a single file descriptor.
  * @param fileIds - File IDs.
  * @public
  * @documentationMaturity preview
@@ -1462,7 +1481,10 @@ export declare function getFileDescriptor(fileId: string): Promise<FileDescripto
  */
 export declare function getFileDescriptors(fileIds: string[]): Promise<GetFileDescriptorsResponse & GetFileDescriptorsResponseNonNullableFields>;
 /**
- * Updates a file. <br />
+ * Updates a file.
+ *
+ *
+ * The `updateFileDescriptor()` function returns a Promise that resolves to the updated file's descriptor.
  *
  * You can use the `parentFolderId` parameter to move a file from its current folder to a different folder.
  * @param _id - File ID. Generated when a file is uploaded to the Media Manager.
@@ -1566,9 +1588,11 @@ export interface UpdateFileDescriptorFile {
 /**
  * Generates an upload URL to allow external clients to upload a file to the Media Manager.
  *
+ * The `generateFileUploadUrl()` function returns a Promise that resolves to an upload URL.
+ *
  * To learn how external clients can use the generated upload URL in the response to upload a file to the Media Manager, see the Upload API article.
  *
- * > **Note:** Any interruption in the upload process stops the file upload. For files larger than 10MB, or when network connection is poor, use the generateFileResumableUploadUrl() instead. With the resumable upload URL, any interruption in the upload process pauses the file upload, and resumes the file upload process after the interruption.
+ * > **Note:** Any interruption in the upload process stops the file upload. For files larger than 10MB, or when network connection is poor, use `generateFileResumableUploadUrl()` instead. With the resumable upload URL, any interruption in the upload process pauses the file upload, and resumes the file upload process after the interruption.
  * @param mimeType - File mime type.
  * @public
  * @documentationMaturity preview
@@ -1603,9 +1627,11 @@ export interface GenerateFileUploadUrlOptions {
     externalInfo?: ExternalInfo;
 }
 /**
- * Generates a resumable upload URL to allow external clients to easily upload large files over 10MB to the Media Manager.
+ * Generates a resumable upload URL to allow external clients to upload large files over 10MB to the Media Manager.
+ *
+ * The `generateFileResumableUploadUrl()` function returns a Promise that resolves to an upload URL, token, and protocol.
  *
- * With the resumable upload URL, any interruptions in the upload process pauses the file upload, and resumes the file upload process after the interruption. The resumable upload URL is also helpful when network connection is poor.
+ * When using the resumable upload URL, any interruptions will pause the file upload process, which automatically resumes once the interruption is resolved. The resumable upload URL is also helpful when network connection is poor.
  *
  * To learn how external clients can use the generated upload URL in the response to upload large files to the Media Manager, see the Resumable Upload API article.
  * @param mimeType - File mime type.
@@ -1646,19 +1672,18 @@ export interface GenerateFileResumableUploadUrlOptions {
     uploadProtocol?: UploadProtocol;
 }
 /**
- * Imports a file to the Media Manager using an external url.
+ * Imports a file to the Media Manager using an external URL.
  *
- * This function returns information about the imported file.
+ * The `importFile()` function returns a Promise that resolves to the imported file's descriptor.
+ *
+ * This function returns information about the imported file. Importing a file is the method through which you can add files to the Media Manager.
  * Use the `parentFolderId` parameter to specify which folder you want the file to be imported to.
  * If no folder is specified, the file is imported to the `media-root` folder.
  *
- * To import a file, you need to provide one of the following:
- * 1. Pass the file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request. For example, `'image/png'`.
- * 2. Pass the file's name and extension. For example, `'my-image.png'`.
- * 3. If you don't know the file's extension or MIME type, pass its [media type](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) in the `mediaType` parameter of the request. For example, `'IMAGE'`. Note that this option only works if the server hosting the media allows a 'HEAD' request.
- *
- * >**Note:** The `media` property isn't returned in the `files` response object.
- *
+ * To import a file, you need to pass one of the following:
+ * - The file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request. For example, `'image/png'`.
+ * - The file's name and extension. For example, `'my-image.png'`.
+ * - If you don't know the file's extension or MIME type, its [media type](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) in the `mediaType` parameter of the request. For example, `'IMAGE'`. Note that this option only works if the server hosting the media allows a 'HEAD' request.
  * @param url - Publicly accessible external file URL.
  * @public
  * @documentationMaturity preview
@@ -1701,15 +1726,17 @@ export interface ImportFileOptions {
  * > This function has been replaced with `bulkImportFile()`, and will be removed on March 31, 2024.
  *
  *
+ * The `bulkImportFiles()` function returns a Promise that resolves to an array of the imported files' descriptors.
+ *
  * Imports a bulk of files to the Media Manager using external urls.
  *
  * Returns information about the imported files. Use the `parentFolderId` parameter to specify in which folder you want each file to be imported.
  * If no folder is specified, the file is imported to the `media-root` folder.
  *
- * To import files, you need to provide one of the following:
- * 1. Pass each file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request. For example, `'image/png'`.
- * 2. Pass each file's name and extension. For example, `'my-image.png'`.
- * 3. If you don't know a file's extension or MIME type, pass its [media type](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) in the `mediaType` parameter of the request. For example, `'IMAGE'`. Note that this option only works if the server hosting the media allows a 'HEAD' request.
+ * To import a file, you need to pass one of the following:
+ * - The file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request. For example, `'image/png'`.
+ * - The file's name and extension. For example, `'my-image.png'`.
+ * - If you don't know the file's extension or MIME type, its [media type](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) in the `mediaType` parameter of the request. For example, `'IMAGE'`. Note that this option only works if the server hosting the media allows a 'HEAD' request.
  *
  * >**Note:** The `media` property isn't returned in the `files` response object.
  * @param importFileRequests - Information about the files to import.
@@ -1724,22 +1751,23 @@ export interface ImportFileOptions {
  */
 export declare function bulkImportFiles(importFileRequests: ImportFileRequest[]): Promise<BulkImportFilesResponse & BulkImportFilesResponseNonNullableFields>;
 /**
- * Imports a bulk of files to the Media Manager using external urls. <br/>
+ * Imports a bulk of files to the Media Manager using external urls.
  *
- * Returns information about the imported files. Use the `parentFolderId` parameter to specify in which folder you want each file to be imported to.
- * If no folder is specified, the file is imported to the `media-root` folder.
+ * The `bulkImportFile()` function returns a Promise that resolves to an object containing bulk import metadata and an array of imported files' descriptors and metadata.
  *
- * To import files, you need to provide one of the following:
- * 1. Pass each file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request.  For example, 'image/png'.
- * 2. Pass each file's name and extension. For example, 'my-image.png'.
- * 3. If you don't know a file's extension or MIME type, pass its media type in the `mediaType` parameter of the request. For example, 'IMAGE'. Note that this option only works if the server hosting the media allows a 'HEAD' request.
+ * Returns information about the imported files. Use the `parentFolderId` parameter to specify in which folder you want each file to be imported.
+ * If no folder is specified, the file is imported to the `media-root` folder.
  *
- * >**Note:** The `media` property isn't returned in the `files` response object.
+ * To import a file, you need to pass one of the following:
+ * - The file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) in the `mimeType` parameter of the request. For example, `'image/png'`.
+ * - The file's name and extension. For example, `'my-image.png'`.
+ * - If you don't know the file's extension or MIME type, its [media type](https://support.wix.com/en/article/wix-media-supported-media-file-types-and-file-sizes) in the `mediaType` parameter of the request. For example, `'IMAGE'`. Note that this option only works if the server hosting the media allows a 'HEAD' request.
  * @param importFileRequests - Information about the files to import.
  * @public
  * @documentationMaturity preview
  * @requiredField importFileRequests
  * @requiredField importFileRequests.url
+ * @param options - Options to include the file descriptor in the response.
  * @permissionScope Manage Bookings Services and Settings
  * @permissionScope Manage Media Manager
  * @applicableIdentity APP
@@ -1756,7 +1784,11 @@ export interface BulkImportFileOptions {
 /**
  * Retrieves a list of files in the Media Manager.
  *
+ * The `listFiles()` function returns a Promise that resolves to an array of the specified files' descriptors and cursor information.
+ *
  * To retrieve a list of files within a specific folder in the Media Manager, pass the folder's ID in the `parentFolderId` parameter. If no folder is specified, the endpoint retrieves only the list of files in the root folder of the Media Manager.
+ *
+ * To retrieve a list of (non-permanently) deleted files, use the `listDeletedFiles()` function.
  * @public
  * @documentationMaturity preview
  * @param options - Options to use when listing media files.
@@ -1781,11 +1813,13 @@ export interface ListFilesOptions {
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */
@@ -1794,7 +1828,9 @@ export interface ListFilesOptions {
 /**
  * Searches all folders in the Media Manager and returns a list of files that match the terms specified in the optional parameters.
  *
- * If no parameters are specified, the endpoint returns all files in the `MEDIA_ROOT` folder.
+ * The `searchFiles()` function returns a Promise that resolves to an array of the specified files' descriptors and cursor information.
+ *
+ * If no parameters are specified, the function returns all files in the `MEDIA_ROOT` folder.
  * @public
  * @documentationMaturity preview
  * @param options - Options to specify which folders to search.
@@ -1825,14 +1861,20 @@ export interface SearchFilesOptions {
      * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`, `"ARCHIVE"`, `"MODEL3D"`
      */
     mediaTypes?: MediaType[];
-    /** Whether the link to the imported file is public or private. */
+    /**
+     * Whether the link to the imported file is public or private.
+     *
+     * Default: `false`.
+     */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */
@@ -1840,6 +1882,11 @@ export interface SearchFilesOptions {
 }
 /**
  * Generates a URL for streaming a specific video file in the Media Manager.
+ *
+ *
+ * The `generateVideoStreamingUrl()` function returns a Promise that resolves to a download URL and its asset key.
+ *
+ * To stream different assets of the file, use the `assetKeys` parameter which generates a video streaming URL for each asset. If no asset key is specified, it defaults to `src`, which generates one video streaming URL in the original file's format and quality.
  * @param fileId - File ID.
  * @public
  * @documentationMaturity preview
@@ -1865,7 +1912,9 @@ export interface GenerateVideoStreamingUrlOptions {
  * Deletes the specified files from the Media Manager.
  *
  *
- * The deleted files are moved to the Media Manager's trash bin (`TRASH-ROOT` folder) unless permanently deleted. To permanently delete files, pass the `permanent` parameter with the value `true`. Permanently deleting files isn't reversible, so make sure that these files aren't being used in a site or in any other way as the files will no longer be accessible.
+ * The `bulkDeleteFiles()` function returns a Promise that resolves when the files are deleted.
+ *
+ * The deleted files are moved to the Media Manager's trash bin (`TRASH_ROOT` folder) unless permanently deleted. To permanently delete files, pass the `permanent` parameter with the value `true`. Permanently deleting files isn't reversible, so make sure that these files aren't being used in a site or in any other way as the files will no longer be accessible.
  *
  * >**Notes:**
  * > - The specified files can be from different folders.
@@ -1892,6 +1941,8 @@ export interface BulkDeleteFilesOptions {
 }
 /**
  * Restores the specified files from the Media Manager's trash bin, and moves them to their original locations in the Media Manager.
+ *
+ * The `bulkRestoreFilesFromTrashBin()` function returns a Promise that resolves when the files have been restored.
  * @param fileIds - IDs of the files to restore from the Media Manager's trash bin.
  * @public
  * @documentationMaturity preview
@@ -1904,7 +1955,11 @@ export declare function bulkRestoreFilesFromTrashBin(fileIds: string[]): Promise
 /**
  * Retrieves a list of files in the Media Manager's trash bin.
  *
- * >**Note:** The Media Manager's trash bin (`TRASH-ROOT` folder) only contains temporarily deleted files, not permanently deleted files.
+ * The `listDeletedFiles()` function returns a Promise that resolves to an array of the specified deleted files' descriptors and cursor information.
+ *
+ * >**Note:** The Media Manager's trash bin (`TRASH_ROOT` folder) only contains temporarily deleted files, not permanently deleted files.
+ *
+ * To retrieve a list of non-deleted files, use the `listFiles()` function.
  * @public
  * @documentationMaturity preview
  * @param options - Options to use when listing deleted files from the trash bin.
@@ -1929,11 +1984,13 @@ export interface ListDeletedFilesOptions {
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
     /**
-     * Field name and order to sort by. One of: <br />
-     * * `displayName`
-     * * `updatedDate`
-     * * `sizeInBytes`
-     * Default: `updatedDate` in `desc` order.
+     * Field name and order to sort by. One of:
+     *
+     * - `displayName`
+     * - `_updatedDate`
+     * - `sizeInBytes`
+     *
+     * Default: `_updatedDate` in `"DESC"` order.
      */
     sort?: Sorting;
     /** Cursor and paging information. */