Merge pull request #84 from imagekit-developer/SDK-94

Added transformation, e-shadow, e-gradient parameter

Author: imagekitio

README.md

@@ -14,8 +14,14 @@ Javascript SDK for [ImageKit](https://imagekit.io/) provides URL generation for
 
 ImageKit is complete media storage, optimization, and transformation solution that comes with an [image and video CDN](https://imagekit.io/features/imagekit-infrastructure). It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.
 
-## Changelog - SDK Version 2.0.0
-### Breaking changes
+## Changelog
+### SDK Version 3.0.0
+#### Breaking changes
+**1. Overlay syntax update**
+* In version 3.0.0, we've removed the old overlay syntax parameters for transformations, such as `oi`, `ot`, `obg`, and [more](https://docs.imagekit.io/features/image-transformations/overlay). These parameters are deprecated and will start returning errors when used in URLs. Please migrate to the new layers syntax that supports overlay nesting, provides better positional control, and allows more transformations at the layer level. You can start with [examples](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#examples) to learn quickly.
+* You can migrate to the new layers syntax using the `raw` transformation parameter.
+### SDK Version 2.0.0
+#### Breaking changes
 **1. Authentication Process Update:**
 * Previously, when using client side file upload, the SDK required the `publicKey` and `authenticationEndpoint` parameters during SDK initialization to fetch security parameters (`signature`, `token`, and `expire`).
 * In version 2.0.0, we've updated the authentication process for the SDK. As a user of the SDK, you are now responsible for generating the security parameters (`signature`, `token`, and `expire`) yourself. This means you no longer need to provide the `authenticationEndpoint`. When using the SDK's upload method, make sure to pass these security parameters explicitly along with other [upload options](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). For guidance on generating these security parameters, please refer to the documentation available [here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload).
@@ -260,6 +266,27 @@ var imageURL = imagekit.url({
 https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/img/sample-video.mp4
 ```
 
+**4. Arithmetic expressions in transformations**
+
+ImageKit allows use of [arithmetic expressions](https://docs.imagekit.io/features/arithmetic-expressions-in-transformations) in certain dimension and position-related parameters, making media transformations more flexible and dynamic.
+
+For example:
+
+```js
+var imageURL = imagekit.url({
+    src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg",
+    transformation: [{
+        "width": "iw_div_4",
+        "height": "ih_div_2",
+        "border": "cw_mul_0.05_yellow"
+    }]
+});
+```
+
+**Sample Result URL**
+```
+https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow
+```
 
 #### List of supported transformations
 
@@ -296,6 +323,8 @@ If you want to generate transformations in your application and add them to the
 | effectUSM | e-usm |
 | effectContrast | e-contrast |
 | effectGray | e-grayscale |
+| effectShadow | e-shadow |
+| effectGradient | e-gradient |
 | original | orig |
 | raw | The string provided in raw will be added in the URL as it is. |
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "imagekit-javascript",
-    "version": "2.0.0",
+    "version": "3.0.0",
     "description": "Javascript SDK for using ImageKit.io in the browser",
     "main": "dist/imagekit.cjs.js",
     "module": "dist/imagekit.esm.js",

src/constants/errorMessages.ts

@@ -18,4 +18,7 @@ export default {
   MISSING_SIGNATURE: { message: "Missing signature for upload. The SDK expects token, sginature and expire for authentication.", help: ""},
   MISSING_TOKEN: { message: "Missing token for upload. The SDK expects token, sginature and expire for authentication.", help: ""},
   MISSING_EXPIRE: { message: "Missing expire for upload. The SDK expects token, sginature and expire for authentication.", help: ""},
+  INVALID_TRANSFORMATION: { message: "Invalid transformation parameter. Please include at least pre, post, or both.", help: ""},
+  INVALID_PRE_TRANSFORMATION: { message: "Invalid pre transformation parameter.", help: ""},
+  INVALID_POST_TRANSFORMATION: { message: "Invalid post transformation parameter.", help: ""},
 };

src/constants/supportedTransforms.ts

@@ -87,141 +87,6 @@ const supportedTransforms: { [key: string]: string } = {
    */
   named: "n",
 
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-oi
-   */
-  overlayImage: "oi",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-aspect-ratio-oiar
-   */
-  overlayImageAspectRatio: "oiar",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-background-oibg
-   */
-  overlayImageBackground: "oibg",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-border-oib
-   */
-  overlayImageBorder: "oib",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-dpr-oidpr
-   */
-  overlayImageDPR: "oidpr",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-quality-oiq
-   */
-  overlayImageQuality: "oiq",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-image-cropping
-   */
-  overlayImageCropping: "oic",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#trimming-of-the-overlay-image
-   */
-  overlayImageTrim: "oit",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-x-position-ox
-   */
-  overlayX: "ox",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-y-position-oy
-   */
-  overlayY: "oy",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-focus-ofo
-   */
-  overlayFocus: "ofo",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-height-oh
-   */
-  overlayHeight: "oh",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-width-ow
-   */
-  overlayWidth: "ow",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-ot
-   */
-  overlayText: "ot",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-size-ots
-   */
-  overlayTextFontSize: "ots",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-font-otf
-   */
-  overlayTextFontFamily: "otf",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-color-otc
-   */
-  overlayTextColor: "otc",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-transparency-oa
-   */
-  overlayTextTransparency: "oa",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-transparency-oa
-   */
-  overlayAlpha: "oa",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-typography-ott
-   */
-  overlayTextTypography: "ott",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-background-obg
-   */
-  overlayBackground: "obg",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-encoded-ote
-   */
-  overlayTextEncoded: "ote",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-width-otw
-   */
-  overlayTextWidth: "otw",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-background-otbg
-   */
-  overlayTextBackground: "otbg",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-padding-otp
-   */
-  overlayTextPadding: "otp",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-text-inner-alignment-otia
-   */
-  overlayTextInnerAlignment: "otia",
-
-  /**
-   * @link https://docs.imagekit.io/features/image-transformations/overlay#overlay-radius-or
-   */
-  overlayRadius: "or",
-
   /**
    * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#progressive-image-pr
    */
@@ -282,6 +147,16 @@ const supportedTransforms: { [key: string]: string } = {
    */
   original: "orig",
 
+  /**
+   * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#shadow-e-shadow
+   */
+  effectShadow: "e-shadow",
+
+  /**
+   * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#gradient-e-gradient
+   */
+  effectGradient: "e-gradient",
+
   /**
    * @link https://docs.imagekit.io/features/image-transformations/conditional-transformations
    */

src/interfaces/UploadOptions.ts

@@ -1,3 +1,25 @@
+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{
+  pre?: string
+  post?: PostTransformation[]
+}
 /**
  * Options used when uploading a file
  *
@@ -113,6 +135,8 @@ export interface UploadOptions {
    */
   customMetadata?: string | Record<string, string | number | boolean | Array<string | number | boolean>>
 
+  transformation?: Transformation
+
   /**
    * Optional XMLHttpRequest object that you can send for upload API request. You can listen to `progress` and other events on this object for any custom logic. 
    */

src/upload/index.ts

@@ -39,6 +39,33 @@ export const upload = (
     return
   }
 
+  if (uploadOptions.transformation) {
+    if (!(Object.keys(uploadOptions.transformation).includes("pre") || Object.keys(uploadOptions.transformation).includes("post"))) {
+      respond(true, errorMessages.INVALID_TRANSFORMATION, callback);
+      return;
+    }
+    if (Object.keys(uploadOptions.transformation).includes("pre") && !uploadOptions.transformation.pre) {
+      respond(true, errorMessages.INVALID_PRE_TRANSFORMATION, callback);
+      return;
+    }
+    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)) {
+            respond(true, errorMessages.INVALID_POST_TRANSFORMATION, callback);
+            return;
+          } else if (transformation.type === "transformation" && !transformation.value) {
+            respond(true, errorMessages.INVALID_POST_TRANSFORMATION, callback);
+            return;
+          }
+        }
+      } else {
+        respond(true, errorMessages.INVALID_POST_TRANSFORMATION, callback);
+        return;
+      }
+    }
+  }
+
   var formData = new FormData();
   let key: keyof typeof uploadOptions;
   for (key in uploadOptions) {
@@ -60,6 +87,9 @@ export const upload = (
       } else if (key === "customMetadata" && typeof uploadOptions.customMetadata === "object" &&
         !Array.isArray(uploadOptions.customMetadata) && uploadOptions.customMetadata !== null) {
         formData.append('customMetadata', JSON.stringify(uploadOptions.customMetadata));
+      } else if(key === "transformation" && typeof uploadOptions.transformation === "object" &&
+        uploadOptions.transformation !== null) {
+        formData.append(key, JSON.stringify(uploadOptions.transformation));
       } else if(uploadOptions[key] !== undefined) {
         formData.append(key, String(uploadOptions[key]));
       }

src/url/builder.ts

@@ -82,6 +82,8 @@ function constructTransformationString(transformation: Transformation[] | undefi
   for (var i = 0, l = transformation.length; i < l; i++) {
     var parsedTransformStep = [];
     for (var key in transformation[i]) {
+      if(transformation[i][key] === undefined || transformation[i][key] === null )
+      continue;
       var transformKey = transformationUtils.getTransformKey(key);
       if (!transformKey) {
         transformKey = key;
@@ -93,7 +95,7 @@ function constructTransformationString(transformation: Transformation[] | undefi
         parsedTransformStep.push(transformation[i][key]);
       } else {
         var value = transformation[i][key];
-        if (transformKey === "oi" || transformKey === "di") {
+        if (transformKey === "di") {
           value = removeTrailingSlash(removeLeadingSlash(value || ""));
           value = value.replace(/\//g, "@@");
         }