@wix/media 1.0.1 → 1.0.3

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

@@ -20,12 +20,18 @@ export interface FileDescriptor {
      * @readonly
      */
     private?: boolean;
-    /** Media file type. */
+    /**
+     * Media file type.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaType?: MediaType;
     /** Media file content. */
     media?: FileMedia;
     /**
      * Status of the file that was uploaded.
+     *
+     * Supported values: `"FAILED"`, `"READY"`, `"PENDING"`
      * * `FAILED`: The file failed to upload, for example, during media post processing.
      * * `READY`: The file uploaded, finished all processing, and is ready for use.
      * * `PENDING`: The file is processing and the URLs are not yet available. This response is returned when importing a file.
@@ -43,7 +49,11 @@ export interface FileDescriptor {
     _updatedDate?: Date;
     /** The Wix site ID where the media file is stored. */
     siteId?: string;
-    /** State of the file. */
+    /**
+     * State of the file.
+     *
+     * Supported values: `"OK"`, `"DELETED"`
+     */
     state?: State;
 }
 export declare enum MediaType {
@@ -240,6 +250,14 @@ export interface GetFileDescriptorResponse {
     /** Information about the file. */
     file?: FileDescriptor;
 }
+export interface GetFileDescriptorsRequest {
+    /** File IDs. */
+    fileIds: string[];
+}
+export interface GetFileDescriptorsResponse {
+    /** Information about the requested files. */
+    files?: FileDescriptor[];
+}
 export interface UpdateFileRequest {
     /** ID of the file to update. */
     fileId: string;
@@ -310,7 +328,11 @@ export declare enum UploadProtocol {
     TUS = "TUS"
 }
 export interface GenerateFileResumableUploadUrlResponse {
-    /** The upload protocol to use for implementing the resumable upload. */
+    /**
+     * The upload protocol to use for implementing the resumable upload.
+     *
+     * Supported values: `"TUS"`
+     */
     uploadProtocol?: UploadProtocol;
     /** The URL for uploading a file to the Media Manager. */
     uploadUrl?: string;
@@ -318,9 +340,13 @@ export interface GenerateFileResumableUploadUrlResponse {
     uploadToken?: string;
 }
 export interface ImportFileRequest {
-    /** Publicly accessible external file url. */
+    /** Publicly accessible external file URL. */
     url: string;
-    /** Media type of the file to import. */
+    /**
+     * Media type of the file to import.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaType?: MediaType;
     /** File name that appears in the Media Manager. */
     displayName?: string | null;
@@ -337,6 +363,10 @@ export interface ImportFileRequest {
     mimeType?: string;
     /** A place to map an external entity to an imported file in the Wix Media Manager. */
     externalInfo?: ExternalInfo;
+    /** Optional parameters that should be sent with the external URL. */
+    urlParams?: Record<string, any> | null;
+    /** Optional headers that should be sent with the external URL. */
+    urlHeaders?: Record<string, any> | null;
 }
 export interface ImportFileResponse {
     /** Information about the imported file. */
@@ -373,7 +403,11 @@ export interface ListFilesRequest {
 export interface Sorting {
     /** Name of the field to sort by. */
     fieldName?: string;
-    /** Sort order. */
+    /**
+     * Sort order
+     *
+     * Supported values: `"ASC"`, `"DESC"`
+     */
     order?: SortOrder;
 }
 export declare enum SortOrder {
@@ -511,9 +545,11 @@ export interface ListDeletedFilesResponse {
     nextCursor?: PagingMetadataV2;
 }
 /**
- * Generates a URL for downloading a compressed file containing specific files in the Media Manager. <br/>
+ * Generates a URL for downloading a compressed file containing specific files in the Media Manager.
  *
  * The compressed file can contain up to 1000 files.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileIds - IDs of the files to download.
  * @public
  * @documentationMaturity preview
@@ -527,10 +563,13 @@ export declare function generateFilesDownloadUrl(fileIds: string[]): Promise<Gen
  * If no `assetKey` 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.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileId - File ID.
  * @public
  * @documentationMaturity preview
  * @requiredField fileId
+ * @param options - Options to use when generating a file's download URL.
  */
 export declare function generateFileDownloadUrl(fileId: string, options?: GenerateFileDownloadUrlOptions): Promise<GenerateFileDownloadUrlResponse>;
 export interface GenerateFileDownloadUrlOptions {
@@ -559,6 +598,8 @@ export interface GenerateFileDownloadUrlOptions {
 }
 /**
  * Gets information about a specific file in the Media Manager.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileId - File ID.
  * @public
  * @documentationMaturity preview
@@ -566,13 +607,24 @@ export interface GenerateFileDownloadUrlOptions {
  */
 export declare function getFileDescriptor(fileId: string): Promise<GetFileDescriptorResponse>;
 /**
- * Updates a file. <br />
+ * Gets information about a specific files in the Media Manager.
+ * @param fileIds - File IDs.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField fileIds
+ */
+export declare function getFileDescriptors(fileIds: string[]): Promise<GetFileDescriptorsResponse>;
+/**
+ * Updates a file by the specified ID.
  *
  * You can use the `parentFolderId` parameter to move a file from its current folder to a different folder.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileId - ID of the file to update.
  * @public
  * @documentationMaturity preview
  * @requiredField fileId
+ * @param options - Options to use when updating a file.
  */
 export declare function updateFile(fileId: string, options?: UpdateFileOptions): Promise<UpdateFileResponse>;
 export interface UpdateFileOptions {
@@ -587,14 +639,17 @@ export interface UpdateFileOptions {
     labels?: string[] | null;
 }
 /**
- * Generates an upload URL to allow external clients to upload a file to the Media Manager. <br/>
+ * Generates an upload URL to allow external clients to upload a file to the Media Manager.
  *
  * 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](https://dev.wix.com/api/rest/media/media-manager/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 [Generate File Resumable Upload Url](https://dev.wix.com/api/rest/media/media-manager/files/generate-file-resumable-upload-url) 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.
+ * > **Notes:**
+ * > - This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
+ * > - Any interruption in the upload process stops the file upload. For files larger than 10MB, or when network connection is poor, use the [Generate File Resumable Upload Url](https://www.wix.com/velo/reference/wix-media-v2/files/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
  * @requiredField mimeType
+ * @param options - Options to use when generating a file's upload URL.
  */
 export declare function generateFileUploadUrl(mimeType: string | null, options?: GenerateFileUploadUrlOptions): Promise<GenerateFileUploadUrlResponse>;
 export interface GenerateFileUploadUrlOptions {
@@ -618,14 +673,18 @@ 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. <br/>
+ * Generates a resumable upload URL to allow external clients to easily upload large files over 10MB to the Media Manager.
  *
  * 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.
+ *
  * 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](https://dev.wix.com/api/rest/media/media-manager/resumable-upload-api) article.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param mimeType - File mime type.
  * @public
  * @documentationMaturity preview
  * @requiredField mimeType
+ * @param options - Options to use when generating a resumable upload URL.
  */
 export declare function generateFileResumableUploadUrl(mimeType: string | null, options?: GenerateFileResumableUploadUrlOptions): Promise<GenerateFileResumableUploadUrlResponse>;
 export interface GenerateFileResumableUploadUrlOptions {
@@ -645,30 +704,42 @@ export interface GenerateFileResumableUploadUrlOptions {
     private?: boolean | null;
     /** Labels assigned to media files that describe and categorize them. Provided by the user, or generated by [Google Vision API](https://cloud.google.com/vision/docs/drag-and-drop) for images. */
     labels?: string[] | null;
-    /** The upload protocol to use for implementing the resumable upload. */
+    /**
+     * The upload protocol to use for implementing the resumable upload.
+     *
+     * Supported values: `"TUS"`
+     */
     uploadProtocol?: UploadProtocol;
 }
 /**
  * Imports a file to the Media Manager using an external url.
  *
- * Returns information about the imported file.
+ * This function returns information about the imported file.
  * 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 extenstion. For example, 'my-image.png'.
- * 3. If you don't know the 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.
+ * 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 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.
+ *
+ * >**Notes:**
+ * > - This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
+ * > - The `media` property isn't returned in the `files` response object.
  *
- * >**Note:** The `media` property isn't returned in the `files` response object.
- * @param url - Publicly accessible external file url.
+ * @param url - Publicly accessible external file URL.
  * @public
  * @documentationMaturity preview
  * @requiredField url
+ * @param options - Options to use when importing a single file.
  */
 export declare function importFile(url: string, options?: ImportFileOptions): Promise<ImportFileResponse>;
 export interface ImportFileOptions {
-    /** Media type of the file to import. */
+    /**
+     * Media type of the file to import.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaType?: MediaType;
     /** File name that appears in the Media Manager. */
     displayName?: string | null;
@@ -685,22 +756,29 @@ export interface ImportFileOptions {
     mimeType?: string;
     /** A place to map an external entity to an imported file in the Wix Media Manager. */
     externalInfo?: ExternalInfo;
+    /** Optional parameters that should be sent with the external URL. */
+    urlParams?: Record<string, any> | null;
+    /** Optional headers that should be sent with the external URL. */
+    urlHeaders?: Record<string, any> | null;
 }
 /**
- * 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.
  *
  * 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 extenstion. 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.
+ * 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.
  *
- * >**Note:** The `media` property isn't returned in the `files` response object.
+ * >**Notes:**
+ * > - This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
+ * > - The `media` property isn't returned in the `files` response object.
  * @public
  * @documentationMaturity preview
  * @requiredField options.importFileRequests.url
+ * @param options - Options to use when uploading multiple files.
  */
 export declare function bulkImportFiles(options?: BulkImportFilesOptions): Promise<BulkImportFilesResponse>;
 export interface BulkImportFilesOptions {
@@ -711,8 +789,11 @@ export interface BulkImportFilesOptions {
  * Retrieves a list of files in the Media Manager.
  *
  * 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 the list of files in the root folder of the Media Manager.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @public
  * @documentationMaturity preview
+ * @param options - Options to use when listing media files.
  */
 export declare function listFiles(options?: ListFilesOptions): Promise<ListFilesResponse>;
 export interface ListFilesOptions {
@@ -721,7 +802,11 @@ export interface ListFilesOptions {
      * Default:`media-root`.
      */
     parentFolderId?: string | null;
-    /** File media type. */
+    /**
+     * Media file type.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaTypes?: MediaType[];
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
@@ -736,11 +821,14 @@ export interface ListFilesOptions {
     paging?: CursorPaging;
 }
 /**
- * Searches all folders in the Media Manager and returns a list of files that match the terms specified in the parameters. <br/>
+ * 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.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @public
  * @documentationMaturity preview
+ * @param options - Options to specify which folders to search.
  */
 export declare function searchFiles(options?: SearchFilesOptions): Promise<SearchFilesResponse>;
 export interface SearchFilesOptions {
@@ -755,7 +843,11 @@ export interface SearchFilesOptions {
      * Default: `MEDIA_ROOT`.
      */
     rootFolder?: RootFolder;
-    /** File media type. */
+    /**
+     * Media file type.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaTypes?: MediaType[];
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;
@@ -770,21 +862,31 @@ export interface SearchFilesOptions {
     paging?: CursorPaging;
 }
 /**
- * Generates a URL for streaming a specific video file in the Media Manager. <br/>
+ * Generates a URL for streaming a specific video file in the Media Manager.
  *
  * To stream different assets of the file, use the `assetKeys` parameter which generates a video streaming URL for each asset. If no assetKey is specified, it defaults to `src`, which generates one video streaming URL in the original file's format and quality.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileId - File ID.
  * @public
  * @documentationMaturity preview
  * @requiredField fileId
+ * @param options - Options to use when generating a video file's streaming URL.
  */
 export declare function generateVideoStreamingUrl(fileId: string, options?: GenerateVideoStreamingUrlOptions): Promise<GenerateVideoStreamingUrlResponse>;
 export interface GenerateVideoStreamingUrlOptions {
-    /** Video stream format. */
+    /**
+     * Video stream format.
+     *
+     * Supported values: `"UNKNOWN"`, `"HLS"`, `"DASH"`
+     *
+     *
+     */
     format?: StreamFormat;
 }
 /**
- * Deletes the specified files from the Media Manager. <br/>
+ * 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.
  *
@@ -793,9 +895,13 @@ export interface GenerateVideoStreamingUrlOptions {
  * * Moving multiple files at once is an asynchronous action, and may take time for the changes to appear in the Media Manager.
  * * Attempting to delete files that are already in the trash bin doesn't result in an error.
  * * If your site contains deleted media files, the deleted media files still appear on your site as the files are still in the Media Manager (in the trash bin).
- * * You can use the [Bulk Restore Files From Trash Bin](https://dev.wix.com/api/rest/media/media-manager/files/bulk-restore-files-from-trash-bin) endpoint to restore files from the Media Manager's trash bin.
+ * * You can use the [Bulk Restore Files From Trash Bin](https://www.wix.com/velo/reference/wix-media-v2/files/bulkrestorefilesfromtrashbin) endpoint to restore files from the Media Manager's trash bin.
+ *
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @public
  * @documentationMaturity preview
+ * @param options - Options to use when deleting files.
  */
 export declare function bulkDeleteFiles(options?: BulkDeleteFilesOptions): Promise<void>;
 export interface BulkDeleteFilesOptions {
@@ -809,6 +915,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.
+ *
+ * >**Note:** This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
  * @param fileIds - IDs of the files to restore from the Media Manager's trash bin.
  * @public
  * @documentationMaturity preview
@@ -816,11 +924,14 @@ export interface BulkDeleteFilesOptions {
  */
 export declare function bulkRestoreFilesFromTrashBin(fileIds: string[]): Promise<void>;
 /**
- * Retrieves a list of files in the Media Manager's trash bin. <br/>
+ * 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.
+ * >**Notes:**
+ * > - This function is restricted and only runs if you elevate permissions using the [`wix-auth.elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function.
+ * > - The Media Manager's trash bin (`TRASH-ROOT` folder) only contains temporarily deleted files, not permanently deleted files.
  * @public
  * @documentationMaturity preview
+ * @param options - Options to use when listing deleted files from the trash bin.
  */
 export declare function listDeletedFiles(options?: ListDeletedFilesOptions): Promise<ListDeletedFilesResponse>;
 export interface ListDeletedFilesOptions {
@@ -829,7 +940,11 @@ export interface ListDeletedFilesOptions {
      * Default: `media-root`.
      */
     parentFolderId?: string | null;
-    /** File media type. */
+    /**
+     * Media file type.
+     *
+     * Supported values: `"IMAGE"`, `"VIDEO"`, `"AUDIO"`, `"DOCUMENT"`, `"VECTOR"`
+     */
     mediaTypes?: MediaType[];
     /** Whether the link to the imported file is public or private. */
     private?: boolean | null;