@imagekit/javascript 5.1.0 → 5.2.0

package/dist/interfaces/UploadOptions.d.ts

@@ -1,37 +1,4 @@
-interface TransformationObject {
-    type: "transformation";
-    value: string;
-}
-interface GifToVideoOrThumbnailObject {
-    type: "gif-to-video" | "thumbnail";
-    value?: string;
-}
-interface AbsObject {
-    type: "abs";
-    value: string;
-    protocol: "hls" | "dash";
-}
-type PostTransformation = TransformationObject | GifToVideoOrThumbnailObject | AbsObject;
-interface Transformation {
-    /**
-     * Specifies pre-transformations to be applied. Must be a valid string of transformations like "w-300,h-300".
-     * Refer to the docs for more details on transformations.
-     *
-     * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#pre-transformation}
-     */
-    pre?: string;
-    /**
-     * Specifies post-transformations to be applied. This is an array of transformation objects, each with:
-     *  - type: One of "transformation", "gif-to-video", "thumbnail", or "abs".
-     *  - value: A valid transformation string required if "type" is "transformation" or "abs". Optional if "type" is "gif-to-video" or "thumbnail".
-     *  - protocol: Used only when type is "abs". Can be "hls" or "dash".
-     *
-     * Refer to the docs for more details on transformations and usage in post.
-     *
-     * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#post-transformation}
-     */
-    post?: PostTransformation[];
-}
+import * as Shared from './shared';
 /**
  * Options used when uploading a file using the V1 API.
  * Check out the official documentation:
@@ -39,122 +6,182 @@ interface Transformation {
  */
 export interface UploadOptions {
     /**
-     * This field accepts three main input formats for the file content:
-     * - "binary": Directly pass the binary data. Typically used when uploading via the browser using a File or Blob.
-     * - "base64": A base64-encoded string of the file content.
-     * - "url": A direct URL from which ImageKit server will download the file and upload.
+     * The API accepts any of the following:
+     *
+     * - **Binary data** – send the raw bytes as `multipart/form-data`.
+     * - **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can
+     *   fetch.
+     * - **Base64 string** – the file encoded as a Base64 data URI or plain Base64.
+     *
+     * When supplying a URL, the server must receive the response headers within 8
+     * seconds; otherwise the request fails with 400 Bad Request.
      */
     file: string | Blob | File;
     /**
-     * The name with which the file should be uploaded.
-     * - Valid characters: alphanumeric (a-z, A-Z, 0-9, including Unicode letters and numerals) and the special chars ". _ -"
-     * - Any other character (including space) is replaced with "_"
+     * The name with which the file has to be uploaded. The file name can contain:
+     *
+     * - Alphanumeric Characters: `a-z`, `A-Z`, `0-9`.
+     * - Special Characters: `.`, `-`
      *
-     * Example: "company_logo.png"
+     * Any other character including space will be replaced by `_`
      */
     fileName: string;
     /**
-     * The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key.
-     * Required for client-side authentication. Must be computed on the server side.
-     * Calculate this signature in your secure server and pass it to the client.
+     * A unique value that the ImageKit.io server will use to recognize and prevent
+     * subsequent retries for the same request. We suggest using V4 UUIDs, or another
+     * random string with enough entropy to avoid collisions.
+     *
+     * **Note**: Sending a value that has been used in the past will result in a
+     * validation error. Even if your previous request resulted in an error, you should
+     * always send a new value for this field.
      */
-    signature: string;
+    token: string;
     /**
-     * A unique value to identify and prevent replays. Typically a UUID (e.g., version 4).
-     * Each request must carry a fresh token. The server rejects reused tokens, even if the original request failed.
+     * Server-side checks to run on the asset. Read more about
+     * [Upload API checks](/docs/api-reference/upload-file/upload-file#upload-api-checks).
      */
-    token: string;
+    checks?: string;
     /**
-     * A Unix timestamp in seconds, less than 1 hour in the future.
+     * Define an important area in the image. This is only relevant for image type
+     * files.
+     *
+     * - To be passed as a string with the x and y coordinates of the top-left corner,
+     *   and width and height of the area of interest in the format `x,y,width,height`.
+     *   For example - `10,10,100,100`
+     * - Can be used with fo-customtransformation.
+     * - If this field is not specified and the file is overwritten, then
+     *   customCoordinates will be removed.
      */
-    expire: number;
+    customCoordinates?: string;
     /**
-     * The public API key of your ImageKit account. You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
+     * JSON key-value pairs to associate with the asset. Create the custom metadata
+     * fields before setting these values.
      */
-    publicKey: string;
+    customMetadata?: {
+        [key: string]: unknown;
+    };
     /**
-     * Whether to use a unique filename for this file or not.
-     * - Accepts true or false.
-     * - If set true, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename.
-     * - If set false, then the image is uploaded with the provided filename parameter and any existing file with the same name is replaced.
-     * Default value - true
+     * Optional text to describe the contents of the file.
      */
-    useUniqueFileName?: boolean;
+    description?: string;
     /**
-     * Optionally set tags on the uploaded file.
-     * If passing an array, the SDK automatically joins them into a comma-separated string when sending to the server.
-     * Example: ["t-shirt", "round-neck", "men"] => "t-shirt,round-neck,men"
+     * The time until your signature is valid. It must be a
+     * [Unix time](https://en.wikipedia.org/wiki/Unix_time) in less than 1 hour into
+     * the future. It should be in seconds.
      */
-    tags?: string | string[];
+    expire: number;
     /**
-     * The folder path where the file will be stored, e.g., "/images/folder/".
-     * - If the path doesn't exist, it is created on-the-fly.
-     * - Nested folders are supported by using multiple "/".
-     * - Default: "/"
+     * Array of extensions to be applied to the asset. Each extension can be configured
+     * with specific parameters based on the extension type.
+     */
+    extensions?: Shared.Extensions;
+    /**
+     * The folder path in which the image has to be uploaded. If the folder(s) didn't
+     * exist before, a new folder(s) is created.
+     *
+     * The folder name can contain:
+     *
+     * - Alphanumeric Characters: `a-z` , `A-Z` , `0-9`
+     * - Special Characters: `/` , `_` , `-`
+     *
+     * Using multiple `/` creates a nested folder.
      */
     folder?: string;
     /**
-     * Whether to mark the file as private (only relevant for image uploads).
-     * A private file requires signed URLs or named transformations for access.
-     * Default: false
+     * Whether to mark the file as private or not.
+     *
+     * If `true`, the file is marked as private and is accessible only using named
+     * transformation or signed URL.
      */
     isPrivateFile?: boolean;
     /**
-     * A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size).
-     * Example: "10,10,100,100".
+     * Whether to upload file as published or not.
+     *
+     * If `false`, the file is marked as unpublished, which restricts access to the
+     * file only via the media library. Files in draft or unpublished state can only be
+     * publicly accessed after being published.
+     *
+     * The option to upload in draft state is only available in custom enterprise
+     * pricing plans.
      */
-    customCoordinates?: string;
+    isPublished?: boolean;
     /**
-     * A comma-separated or array-based set of fields to return in the upload response.
-     * Example: "tags,customCoordinates,isPrivateFile,metadata"
+     * If set to `true` and a file already exists at the exact location, its AITags
+     * will be removed. Set `overwriteAITags` to `false` to preserve AITags.
      */
-    responseFields?: string | string[];
+    overwriteAITags?: boolean;
     /**
-     * An array of extension objects to apply to the image, e.g. background removal, auto-tagging, etc.
-     * The SDK will JSON-stringify this array automatically before sending.
+     * If the request does not have `customMetadata`, and a file already exists at the
+     * exact location, existing customMetadata will be removed.
      */
-    extensions?: object[];
+    overwriteCustomMetadata?: boolean;
     /**
-     * A webhook URL to receive the final status of any pending extensions once they've completed processing.
+     * If `false` and `useUniqueFileName` is also `false`, and a file already exists at
+     * the exact location, upload API will return an error immediately.
      */
-    webhookUrl?: string;
+    overwriteFile?: boolean;
     /**
-     * Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists.
+     * If the request does not have `tags`, and a file already exists at the exact
+     * location, existing tags will be removed.
      */
-    overwriteFile?: boolean;
+    overwriteTags?: boolean;
     /**
-     * Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags.
+     * The public API key of your ImageKit account.
+     * You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
      */
-    overwriteAITags?: boolean;
+    publicKey: string;
     /**
-     * Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags.
+     * Array of response field keys to include in the API response body.
      */
-    overwriteTags?: boolean;
+    responseFields?: Array<'tags' | 'customCoordinates' | 'isPrivateFile' | 'embeddedMetadata' | 'isPublished' | 'customMetadata' | 'metadata' | 'selectedFieldsSchema'>;
     /**
-     * Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata.
+     * The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key.
+     * Calculate this signature in your secure server and pass it to the client.
      */
-    overwriteCustomMetadata?: boolean;
+    signature: string;
     /**
-     * A stringified JSON or an object containing custom metadata fields to store with the file.
-     * Custom metadata fields must be pre-defined in your ImageKit configuration.
+     * Set the tags while uploading the file. Provide an array of tag strings (e.g.
+     * `["tag1", "tag2", "tag3"]`). The combined length of all tag characters must not
+     * exceed 500, and the `%` character is not allowed. If this field is not specified
+     * and the file is overwritten, the existing tags will be removed.
      */
-    customMetadata?: string | Record<string, string | number | boolean | Array<string | number | boolean>>;
+    tags?: Array<string>;
     /**
-     * Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations.
-     * For details, see:
-     * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload}
+     * Configure pre-processing (`pre`) and post-processing (`post`) transformations.
+     *
+     * - `pre` — applied before the file is uploaded to the Media Library.
+     *   Useful for reducing file size or applying basic optimizations upfront (e.g.,
+     *   resize, compress).
+     *
+     * - `post` — applied immediately after upload.
+     *   Ideal for generating transformed versions (like video encodes or thumbnails)
+     *   in advance, so they're ready for delivery without delay.
+     *
+     * You can mix and match any combination of post-processing types.
      */
-    transformation?: Transformation;
+    transformation?: FileUploadParams.Transformation;
+    /**
+     * Whether to use a unique filename for this file or not.
+     *
+     * If `true`, ImageKit.io will add a unique suffix to the filename parameter to get
+     * a unique filename.
+     *
+     * If `false`, then the image is uploaded with the provided filename parameter, and
+     * any existing file with the same name is replaced.
+     */
+    useUniqueFileName?: boolean;
+    /**
+     * The final status of extensions after they have completed execution will be
+     * delivered to this endpoint as a POST request.
+     * [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure)
+     * about the webhook payload structure.
+     */
+    webhookUrl?: string;
     /**
      * An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc.
      * You can listen to `progress` or other events on this object for custom logic.
      */
     xhr?: XMLHttpRequest;
-    /**
-     * A string specifying the checks to be performed server-side before uploading to the media library, e.g. size or mime type checks.
-     * For format details, see: {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#upload-api-checks}
-     */
-    checks?: string;
     /**
      * Optional callback function that will be called with the progress event when the file is being uploaded.
      */
@@ -165,4 +192,80 @@ export interface UploadOptions {
      */
     abortSignal?: AbortSignal;
 }
-export {};
+export declare namespace FileUploadParams {
+    /**
+     * Configure pre-processing (`pre`) and post-processing (`post`) transformations.
+     *
+     * - `pre` — applied before the file is uploaded to the Media Library.
+     *   Useful for reducing file size or applying basic optimizations upfront (e.g.,
+     *   resize, compress).
+     *
+     * - `post` — applied immediately after upload.
+     *   Ideal for generating transformed versions (like video encodes or thumbnails)
+     *   in advance, so they're ready for delivery without delay.
+     *
+     * You can mix and match any combination of post-processing types.
+     */
+    interface Transformation {
+        /**
+         * List of transformations to apply _after_ the file is uploaded.
+         * Each item must match one of the following types: `transformation`,
+         * `gif-to-video`, `thumbnail`, `abs`.
+         */
+        post?: Array<Transformation.Transformation | Transformation.GifToVideo | Transformation.Thumbnail | Transformation.Abs>;
+        /**
+         * Transformation string to apply before uploading the file to the Media Library.
+         * Useful for optimizing files at ingestion.
+         */
+        pre?: string;
+    }
+    namespace Transformation {
+        interface Transformation {
+            /**
+             * Transformation type.
+             */
+            type: 'transformation';
+            /**
+             * Transformation string (e.g. `w-200,h-200`).
+             * Same syntax as ImageKit URL-based transformations.
+             */
+            value: string;
+        }
+        interface GifToVideo {
+            /**
+             * Converts an animated GIF into an MP4.
+             */
+            type: 'gif-to-video';
+            /**
+             * Optional transformation string to apply to the output video.
+             * **Example**: `q-80`
+             */
+            value?: string;
+        }
+        interface Thumbnail {
+            /**
+             * Generates a thumbnail image.
+             */
+            type: 'thumbnail';
+            /**
+             * Optional transformation string.
+             * **Example**: `w-150,h-150`
+             */
+            value?: string;
+        }
+        interface Abs {
+            /**
+             * Streaming protocol to use (`hls` or `dash`).
+             */
+            protocol: 'hls' | 'dash';
+            /**
+             * Adaptive Bitrate Streaming (ABS) setup.
+             */
+            type: 'abs';
+            /**
+             * List of different representations you want to create separated by an underscore.
+             */
+            value: string;
+        }
+    }
+}