@imagekit/javascript 5.1.0-beta.1 → 5.2.0

package/README.md

@@ -20,16 +20,27 @@ You can install the SDK in your project using npm or yarn.
 npm install @imagekit/javascript
 ```
 
+## Documentation
+
+Refer to the ImageKit [official documentation](https://imagekit.io/docs/integration/javascript) for more details on how to use the SDK.
+
 ## TypeScript support
 
 The SDK is written in TypeScript, offering first-class TypeScript support. Enjoy excellent type safety and IntelliSense in your IDE. You can use it in your TypeScript projects without any additional configuration.
 
-
 To enable type checking in JavaScript projects, add `//@ts-check` at the top of your JavaScript files. This will activate type checking in your IDE.
 
-## Documentation
+### TypeScript and the SDK versioning policy
 
-Refer to the ImageKit [official documentation](https://imagekit.io/docs/integration/javascript) for more details on how to use the SDK.
+The TypeScript types in this SDK always reflect the latest shape of the ImageKit API. When we make improvements to the type definitions to better reflect the actual runtime behavior, we may release these changes in minor or patch versions. While these changes align types more closely with reality and are not breaking changes at runtime, they might cause new type errors when you upgrade.
+
+We judge this approach to be better than the alternatives: outdated, inaccurate types, or vastly more frequent major releases that would distract from any truly breaking runtime changes. If you encounter type errors after upgrading, you can resolve them by:
+
+- Adding appropriate type guards or assertions
+- Updating your code to match the corrected types
+- Using `// @ts-ignore` temporarily if you need more time to adjust
+
+Please feel welcome to share your thoughts about the versioning policy in a GitHub issue.
 
 ## Changelog
 

package/dist/imagekit.cjs.js

@@ -2,234 +2,6 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var errorMessages = {
-  MISSING_UPLOAD_FILE_PARAMETER: {
-    message: "Missing file parameter for upload"
-  },
-  MISSING_UPLOAD_FILENAME_PARAMETER: {
-    message: "Missing fileName parameter for upload"
-  },
-  MISSING_PUBLIC_KEY: {
-    message: "Missing public key for upload"
-  },
-  UPLOAD_ENDPOINT_NETWORK_ERROR: {
-    message: "Request to ImageKit upload endpoint failed due to network error"
-  },
-  MISSING_SIGNATURE: {
-    message: "Missing signature for upload. The SDK expects token, signature and expire for authentication."
-  },
-  MISSING_TOKEN: {
-    message: "Missing token for upload. The SDK expects token, signature and expire for authentication."
-  },
-  MISSING_EXPIRE: {
-    message: "Missing expire for upload. The SDK expects token, signature and expire for authentication."
-  },
-  INVALID_TRANSFORMATION: {
-    message: "Invalid transformation parameter. Please include at least pre, post, or both."
-  },
-  INVALID_PRE_TRANSFORMATION: {
-    message: "Invalid pre transformation parameter."
-  },
-  INVALID_POST_TRANSFORMATION: {
-    message: "Invalid post transformation parameter."
-  }
-};
-
-class ImageKitInvalidRequestError extends Error {
-  constructor(message, responseMetadata) {
-    super(message);
-    this.$ResponseMetadata = void 0;
-    this.name = "ImageKitInvalidRequestError";
-    this.$ResponseMetadata = responseMetadata;
-  }
-}
-class ImageKitAbortError extends Error {
-  constructor(message, reason) {
-    super(message);
-    this.reason = void 0;
-    this.name = "ImageKitAbortError";
-    this.reason = reason;
-  }
-}
-class ImageKitUploadNetworkError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ImageKitUploadNetworkError";
-  }
-}
-class ImageKitServerError extends Error {
-  constructor(message, responseMetadata) {
-    super(message);
-    this.$ResponseMetadata = void 0;
-    this.name = "ImageKitServerError";
-    this.$ResponseMetadata = responseMetadata;
-  }
-}
-const upload = uploadOptions => {
-  if (!uploadOptions) {
-    return Promise.reject(new ImageKitInvalidRequestError("Invalid options provided for upload"));
-  }
-  return new Promise((resolve, reject) => {
-    const {
-      xhr: userProvidedXHR
-    } = uploadOptions || {};
-    delete uploadOptions.xhr;
-    const xhr = userProvidedXHR || new XMLHttpRequest();
-    if (!uploadOptions.file) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILE_PARAMETER.message));
-    }
-    if (!uploadOptions.fileName) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILENAME_PARAMETER.message));
-    }
-    if (!uploadOptions.publicKey || uploadOptions.publicKey.length === 0) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_PUBLIC_KEY.message));
-    }
-    if (!uploadOptions.token) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_TOKEN.message));
-    }
-    if (!uploadOptions.signature) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_SIGNATURE.message));
-    }
-    if (!uploadOptions.expire) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_EXPIRE.message));
-    }
-    if (uploadOptions.transformation) {
-      if (!(Object.keys(uploadOptions.transformation).includes("pre") || Object.keys(uploadOptions.transformation).includes("post"))) {
-        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_TRANSFORMATION.message));
-      }
-      if (Object.keys(uploadOptions.transformation).includes("pre") && !uploadOptions.transformation.pre) {
-        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_PRE_TRANSFORMATION.message));
-      }
-      if (Object.keys(uploadOptions.transformation).includes("post")) {
-        if (Array.isArray(uploadOptions.transformation.post)) {
-          for (let transformation of uploadOptions.transformation.post) {
-            if (transformation.type === "abs" && !(transformation.protocol || transformation.value)) {
-              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-            } else if (transformation.type === "transformation" && !transformation.value) {
-              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-            }
-          }
-        } else {
-          return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-        }
-      }
-    }
-    var formData = new FormData();
-    let key;
-    for (key in uploadOptions) {
-      if (key) {
-        if (key === "file" && typeof uploadOptions.file != "string") {
-          formData.set('file', uploadOptions.file, String(uploadOptions.fileName));
-        } else if (key === "tags" && Array.isArray(uploadOptions.tags)) {
-          formData.set('tags', uploadOptions.tags.join(","));
-        } else if (key === 'signature') {
-          formData.set("signature", uploadOptions.signature);
-        } else if (key === 'expire') {
-          formData.set("expire", String(uploadOptions.expire));
-        } else if (key === 'token') {
-          formData.set("token", uploadOptions.token);
-        } else if (key === "responseFields" && Array.isArray(uploadOptions.responseFields)) {
-          formData.set('responseFields', uploadOptions.responseFields.join(","));
-        } else if (key === "extensions" && Array.isArray(uploadOptions.extensions)) {
-          formData.set('extensions', JSON.stringify(uploadOptions.extensions));
-        } else if (key === "customMetadata" && typeof uploadOptions.customMetadata === "object" && !Array.isArray(uploadOptions.customMetadata) && uploadOptions.customMetadata !== null) {
-          formData.set('customMetadata', JSON.stringify(uploadOptions.customMetadata));
-        } else if (key === "transformation" && typeof uploadOptions.transformation === "object" && uploadOptions.transformation !== null) {
-          formData.set(key, JSON.stringify(uploadOptions.transformation));
-        } else if (key === 'checks' && uploadOptions.checks) {
-          formData.set("checks", uploadOptions.checks);
-        } else if (uploadOptions[key] !== undefined) {
-          if (["onProgress", "abortSignal"].includes(key)) continue;
-          formData.set(key, String(uploadOptions[key]));
-        }
-      }
-    }
-    if (uploadOptions.onProgress) {
-      xhr.upload.onprogress = function (event) {
-        if (uploadOptions.onProgress) uploadOptions.onProgress(event);
-      };
-    }
-    function onAbortHandler() {
-      var _uploadOptions$abortS;
-      xhr.abort();
-      return reject(new ImageKitAbortError("Upload aborted", (_uploadOptions$abortS = uploadOptions.abortSignal) === null || _uploadOptions$abortS === void 0 ? void 0 : _uploadOptions$abortS.reason));
-    }
-    if (uploadOptions.abortSignal) {
-      if (uploadOptions.abortSignal.aborted) {
-        var _uploadOptions$abortS2;
-        return reject(new ImageKitAbortError("Upload aborted", (_uploadOptions$abortS2 = uploadOptions.abortSignal) === null || _uploadOptions$abortS2 === void 0 ? void 0 : _uploadOptions$abortS2.reason));
-      }
-      uploadOptions.abortSignal.addEventListener("abort", onAbortHandler);
-      xhr.addEventListener("loadend", () => {
-        if (uploadOptions.abortSignal) {
-          uploadOptions.abortSignal.removeEventListener("abort", onAbortHandler);
-        }
-      });
-    }
-    xhr.open('POST', 'https://upload.imagekit.io/api/v1/files/upload');
-    xhr.onerror = function (e) {
-      return reject(new ImageKitUploadNetworkError(errorMessages.UPLOAD_ENDPOINT_NETWORK_ERROR.message));
-    };
-    xhr.onload = function () {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        try {
-          var body = JSON.parse(xhr.responseText);
-          var uploadResponse = addResponseHeadersAndBody(body, xhr);
-          return resolve(uploadResponse);
-        } catch (ex) {
-          return reject(ex);
-        }
-      } else if (xhr.status >= 400 && xhr.status < 500) {
-        try {
-          var body = JSON.parse(xhr.responseText);
-          return reject(new ImageKitInvalidRequestError(body.message ?? "Invalid request. Please check the parameters.", getResponseMetadata(xhr)));
-        } catch (ex) {
-          return reject(ex);
-        }
-      } else {
-        try {
-          var body = JSON.parse(xhr.responseText);
-          return reject(new ImageKitServerError(body.message ?? "Server error occurred while uploading the file. This is rare and usually temporary.", getResponseMetadata(xhr)));
-        } catch (ex) {
-          return reject(new ImageKitServerError("Server error occurred while uploading the file. This is rare and usually temporary.", getResponseMetadata(xhr)));
-        }
-      }
-    };
-    xhr.send(formData);
-  });
-};
-const addResponseHeadersAndBody = (body, xhr) => {
-  let response = {
-    ...body
-  };
-  const responseMetadata = getResponseMetadata(xhr);
-  Object.defineProperty(response, "$ResponseMetadata", {
-    value: responseMetadata,
-    enumerable: false,
-    writable: false
-  });
-  return response;
-};
-const getResponseMetadata = xhr => {
-  const headers = getResponseHeaderMap(xhr);
-  const responseMetadata = {
-    statusCode: xhr.status,
-    headers: headers,
-    requestId: headers["x-request-id"]
-  };
-  return responseMetadata;
-};
-function getResponseHeaderMap(xhr) {
-  const headers = {};
-  const responseHeaders = xhr.getAllResponseHeaders();
-  if (Object.keys(responseHeaders).length) {
-    responseHeaders.trim().split(/[\r\n]+/).map(value => value.split(/: /)).forEach(keyValue => {
-      headers[keyValue[0].trim().toLowerCase()] = keyValue[1].trim();
-    });
-  }
-  return headers;
-}
-
 const supportedTransforms = {
   width: "w",
   height: "h",
@@ -265,6 +37,7 @@ const supportedTransforms = {
   aiVariation: "e-genvar",
   aiDropShadow: "e-dropshadow",
   aiChangeBackground: "e-changebg",
+  aiEdit: "e-edit",
   aiRemoveBackground: "e-bgremove",
   aiRemoveBackgroundExternal: "e-removedotbg",
   contrastStretch: "e-contrast",
@@ -272,6 +45,8 @@ const supportedTransforms = {
   sharpen: "e-sharpen",
   unsharpMask: "e-usm",
   gradient: "e-gradient",
+  colorReplace: "cr",
+  distort: "e-distort",
   progressive: "pr",
   lossless: "lo",
   colorProfile: "cp",
@@ -280,6 +55,7 @@ const supportedTransforms = {
   trim: "t",
   zoom: "z",
   page: "pg",
+  layerMode: "lm",
   fontSize: "fs",
   fontFamily: "ff",
   fontColor: "co",
@@ -421,6 +197,7 @@ function processOverlay(overlay) {
   const entries = [];
   const {
     type,
+    layerMode,
     position = {},
     timing = {},
     transformation = []
@@ -489,6 +266,9 @@ function processOverlay(overlay) {
       }
       break;
   }
+  if (layerMode) {
+    entries.push(`lm-${layerMode}`);
+  }
   const {
     x,
     y,
@@ -666,6 +446,234 @@ function computeCandidateWidths(params) {
   };
 }
 
+var errorMessages = {
+  MISSING_UPLOAD_FILE_PARAMETER: {
+    message: "Missing file parameter for upload"
+  },
+  MISSING_UPLOAD_FILENAME_PARAMETER: {
+    message: "Missing fileName parameter for upload"
+  },
+  MISSING_PUBLIC_KEY: {
+    message: "Missing public key for upload"
+  },
+  UPLOAD_ENDPOINT_NETWORK_ERROR: {
+    message: "Request to ImageKit upload endpoint failed due to network error"
+  },
+  MISSING_SIGNATURE: {
+    message: "Missing signature for upload. The SDK expects token, signature and expire for authentication."
+  },
+  MISSING_TOKEN: {
+    message: "Missing token for upload. The SDK expects token, signature and expire for authentication."
+  },
+  MISSING_EXPIRE: {
+    message: "Missing expire for upload. The SDK expects token, signature and expire for authentication."
+  },
+  INVALID_TRANSFORMATION: {
+    message: "Invalid transformation parameter. Please include at least pre, post, or both."
+  },
+  INVALID_PRE_TRANSFORMATION: {
+    message: "Invalid pre transformation parameter."
+  },
+  INVALID_POST_TRANSFORMATION: {
+    message: "Invalid post transformation parameter."
+  }
+};
+
+class ImageKitInvalidRequestError extends Error {
+  constructor(message, responseMetadata) {
+    super(message);
+    this.$ResponseMetadata = void 0;
+    this.name = "ImageKitInvalidRequestError";
+    this.$ResponseMetadata = responseMetadata;
+  }
+}
+class ImageKitAbortError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = void 0;
+    this.name = "ImageKitAbortError";
+    this.reason = reason;
+  }
+}
+class ImageKitUploadNetworkError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ImageKitUploadNetworkError";
+  }
+}
+class ImageKitServerError extends Error {
+  constructor(message, responseMetadata) {
+    super(message);
+    this.$ResponseMetadata = void 0;
+    this.name = "ImageKitServerError";
+    this.$ResponseMetadata = responseMetadata;
+  }
+}
+const upload = uploadOptions => {
+  if (!uploadOptions) {
+    return Promise.reject(new ImageKitInvalidRequestError("Invalid options provided for upload"));
+  }
+  return new Promise((resolve, reject) => {
+    const {
+      xhr: userProvidedXHR
+    } = uploadOptions || {};
+    delete uploadOptions.xhr;
+    const xhr = userProvidedXHR || new XMLHttpRequest();
+    if (!uploadOptions.file) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILE_PARAMETER.message));
+    }
+    if (!uploadOptions.fileName) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILENAME_PARAMETER.message));
+    }
+    if (!uploadOptions.publicKey || uploadOptions.publicKey.length === 0) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_PUBLIC_KEY.message));
+    }
+    if (!uploadOptions.token) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_TOKEN.message));
+    }
+    if (!uploadOptions.signature) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_SIGNATURE.message));
+    }
+    if (!uploadOptions.expire) {
+      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_EXPIRE.message));
+    }
+    if (uploadOptions.transformation) {
+      if (!(Object.keys(uploadOptions.transformation).includes("pre") || Object.keys(uploadOptions.transformation).includes("post"))) {
+        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_TRANSFORMATION.message));
+      }
+      if (Object.keys(uploadOptions.transformation).includes("pre") && !uploadOptions.transformation.pre) {
+        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_PRE_TRANSFORMATION.message));
+      }
+      if (Object.keys(uploadOptions.transformation).includes("post")) {
+        if (Array.isArray(uploadOptions.transformation.post)) {
+          for (let transformation of uploadOptions.transformation.post) {
+            if (transformation.type === "abs" && !(transformation.protocol || transformation.value)) {
+              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
+            } else if (transformation.type === "transformation" && !transformation.value) {
+              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
+            }
+          }
+        } else {
+          return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
+        }
+      }
+    }
+    var formData = new FormData();
+    let key;
+    for (key in uploadOptions) {
+      if (key) {
+        if (key === "file" && typeof uploadOptions.file != "string") {
+          formData.set('file', uploadOptions.file, String(uploadOptions.fileName));
+        } else if (key === "tags" && Array.isArray(uploadOptions.tags)) {
+          formData.set('tags', uploadOptions.tags.join(","));
+        } else if (key === 'signature') {
+          formData.set("signature", uploadOptions.signature);
+        } else if (key === 'expire') {
+          formData.set("expire", String(uploadOptions.expire));
+        } else if (key === 'token') {
+          formData.set("token", uploadOptions.token);
+        } else if (key === "responseFields" && Array.isArray(uploadOptions.responseFields)) {
+          formData.set('responseFields', uploadOptions.responseFields.join(","));
+        } else if (key === "extensions" && Array.isArray(uploadOptions.extensions)) {
+          formData.set('extensions', JSON.stringify(uploadOptions.extensions));
+        } else if (key === "customMetadata" && typeof uploadOptions.customMetadata === "object" && !Array.isArray(uploadOptions.customMetadata) && uploadOptions.customMetadata !== null) {
+          formData.set('customMetadata', JSON.stringify(uploadOptions.customMetadata));
+        } else if (key === "transformation" && typeof uploadOptions.transformation === "object" && uploadOptions.transformation !== null) {
+          formData.set(key, JSON.stringify(uploadOptions.transformation));
+        } else if (key === 'checks' && uploadOptions.checks) {
+          formData.set("checks", uploadOptions.checks);
+        } else if (uploadOptions[key] !== undefined) {
+          if (["onProgress", "abortSignal"].includes(key)) continue;
+          formData.set(key, String(uploadOptions[key]));
+        }
+      }
+    }
+    if (uploadOptions.onProgress) {
+      xhr.upload.onprogress = function (event) {
+        if (uploadOptions.onProgress) uploadOptions.onProgress(event);
+      };
+    }
+    function onAbortHandler() {
+      var _uploadOptions$abortS;
+      xhr.abort();
+      return reject(new ImageKitAbortError("Upload aborted", (_uploadOptions$abortS = uploadOptions.abortSignal) === null || _uploadOptions$abortS === void 0 ? void 0 : _uploadOptions$abortS.reason));
+    }
+    if (uploadOptions.abortSignal) {
+      if (uploadOptions.abortSignal.aborted) {
+        var _uploadOptions$abortS2;
+        return reject(new ImageKitAbortError("Upload aborted", (_uploadOptions$abortS2 = uploadOptions.abortSignal) === null || _uploadOptions$abortS2 === void 0 ? void 0 : _uploadOptions$abortS2.reason));
+      }
+      uploadOptions.abortSignal.addEventListener("abort", onAbortHandler);
+      xhr.addEventListener("loadend", () => {
+        if (uploadOptions.abortSignal) {
+          uploadOptions.abortSignal.removeEventListener("abort", onAbortHandler);
+        }
+      });
+    }
+    xhr.open('POST', 'https://upload.imagekit.io/api/v1/files/upload');
+    xhr.onerror = function (e) {
+      return reject(new ImageKitUploadNetworkError(errorMessages.UPLOAD_ENDPOINT_NETWORK_ERROR.message));
+    };
+    xhr.onload = function () {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          var body = JSON.parse(xhr.responseText);
+          var uploadResponse = addResponseHeadersAndBody(body, xhr);
+          return resolve(uploadResponse);
+        } catch (ex) {
+          return reject(ex);
+        }
+      } else if (xhr.status >= 400 && xhr.status < 500) {
+        try {
+          var body = JSON.parse(xhr.responseText);
+          return reject(new ImageKitInvalidRequestError(body.message ?? "Invalid request. Please check the parameters.", getResponseMetadata(xhr)));
+        } catch (ex) {
+          return reject(ex);
+        }
+      } else {
+        try {
+          var body = JSON.parse(xhr.responseText);
+          return reject(new ImageKitServerError(body.message ?? "Server error occurred while uploading the file. This is rare and usually temporary.", getResponseMetadata(xhr)));
+        } catch (ex) {
+          return reject(new ImageKitServerError("Server error occurred while uploading the file. This is rare and usually temporary.", getResponseMetadata(xhr)));
+        }
+      }
+    };
+    xhr.send(formData);
+  });
+};
+const addResponseHeadersAndBody = (body, xhr) => {
+  let response = {
+    ...body
+  };
+  const responseMetadata = getResponseMetadata(xhr);
+  Object.defineProperty(response, "$ResponseMetadata", {
+    value: responseMetadata,
+    enumerable: false,
+    writable: false
+  });
+  return response;
+};
+const getResponseMetadata = xhr => {
+  const headers = getResponseHeaderMap(xhr);
+  const responseMetadata = {
+    statusCode: xhr.status,
+    headers: headers,
+    requestId: headers["x-request-id"]
+  };
+  return responseMetadata;
+};
+function getResponseHeaderMap(xhr) {
+  const headers = {};
+  const responseHeaders = xhr.getAllResponseHeaders();
+  if (Object.keys(responseHeaders).length) {
+    responseHeaders.trim().split(/[\r\n]+/).map(value => value.split(/: /)).forEach(keyValue => {
+      headers[keyValue[0].trim().toLowerCase()] = keyValue[1].trim();
+    });
+  }
+  return headers;
+}
+
 exports.ImageKitAbortError = ImageKitAbortError;
 exports.ImageKitInvalidRequestError = ImageKitInvalidRequestError;
 exports.ImageKitServerError = ImageKitServerError;