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

added parameters

Author: imagekitio

.github/workflows/nodejs.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x, 16.x, 18.x]
+        node-version: [12.x, 14.x, 16.x, 18.x]
 
     steps:
     - uses: actions/checkout@v1

.github/workflows/npmpublish.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x]
+        node-version: [12.x, 14.x]
 
     steps:
     - uses: actions/checkout@v1

README.md

@@ -14,6 +14,7 @@ Node.js SDK for [ImageKit](https://imagekit.io/) implements the new APIs and int
 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.
 
 ##### Table of contents
+* [Changelog](#changelog)
 * [Installation](#installation)
 * [Initialization](#initialization)
 * [URL generation](#url-generation)
@@ -24,6 +25,19 @@ ImageKit is complete media storage, optimization, and transformation solution th
 * [Support](#support)
 * [Links](#links)
 
+## Changelog
+
+### SDK Version 5.0.0
+
+#### Breaking changes
+
+**1. Overlay syntax update**
+* In version 5.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.
+
+**2. Remove Node.js 10.x support**
+* In version 5.0.0, we've removed support for Node.js version 10.x.
+
 ## Installation
 
 Use the following command to download this module. Use the optional `--save` parameter if you wish to save the dependency in your `package.json` file.
@@ -242,6 +256,29 @@ 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
 ```
 
+**5. 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/tr:w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow/default-image.jpg
+```
+
+
 #### List of supported transformations
 
 See the complete list of transformations supported in ImageKit [here](https://docs.imagekit.io/features/image-transformations). The SDK gives a name to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is.
@@ -278,6 +315,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 | `replaced by the parameter value` |
 

libs/constants/errorMessages.ts

@@ -47,4 +47,7 @@ export default {
     "VERIFY_WEBHOOK_EVENT_SIGNATURE_MISSING": { message: "Signature missing", help: "Please pass x-ik-signature header as utf8 string" },
     "VERIFY_WEBHOOK_EVENT_TIMESTAMP_MISSING": { message: "Timestamp missing", help: "Please pass x-ik-signature header as utf8 string" },
     "VERIFY_WEBHOOK_EVENT_TIMESTAMP_INVALID": { message: "Timestamp invalid", help: "Please pass x-ik-signature header as utf8 string" },
+    "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: ""},
 };

libs/constants/supportedTransforms.ts

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

libs/interfaces/FileDetails.ts

@@ -1,6 +1,46 @@
 import { FileType } from "./FileType";
 import { Item } from "./Item";
 
+export interface EmbeddedMetadataValues {
+  [key: string]:
+    | string
+    | number
+    | boolean
+    | Date
+    | Array<string | number | boolean | Date>
+}
+
+export interface AITagItem {
+  name: string
+  confidence: number
+  source: 'google-auto-tagging' | 'aws-auto-tagging'
+}
+
+export interface CMValues {
+  [key: string]: | string
+  | number
+  | boolean
+  | Array<string | number | boolean>
+}
+
+interface BgRemoval {
+  name: string
+  options: {
+    bg_color?: string
+    bg_image_url?: string
+    add_shadow: boolean
+    semitransparency: boolean
+  }
+}
+
+interface AutoTag {
+  name: string
+  maxTags: number
+  minConfidence: number
+}
+
+export type Extension = (BgRemoval | AutoTag)[];
+
 /**
  * Options when updating file details such as tags and customCoordinates attribute using update file detail API.
  *
@@ -19,7 +59,7 @@ export interface FileDetailsOptions {
   /* 
   * Object with array of extensions to be processed on the image.
   */
-  extensions?: object[];
+  extensions?: Extension;
   /*
     * Final status of pending extensions will be sent to this URL. 
     */
@@ -31,7 +71,7 @@ export interface FileDetailsOptions {
   /*
    * A key-value data to be associated with the asset. To unset a key, send null value for that key. Before setting any custom metadata on an asset you have to create the field using custom metadata fields API.
    */
-  customMetadata?: object;
+  customMetadata?: CMValues;
 }
 
 /**
@@ -86,19 +126,19 @@ export interface FileObject {
   /*
    * AITags field is populated only because the google-auto-tagging extension was executed synchronously and it received a successresponse.
    */
-  AITags?: object[];
+  AITags?: AITagItem[];
   /*
    * Field object which will contain the status of each extension at the time of completion of the update/upload request.
    */
   extensionStatus?: { [key: string]: string }
   /*
    * Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data.
    */
-  embeddedMetadata?: object | null;
+  embeddedMetadata?: EmbeddedMetadataValues | null;
   /*
    * A key-value data associated with the asset. Before setting any custom metadata on an asset, you have to create the field using custom metadata fields API.
    */
-  customMetadata?: object;
+  customMetadata?: CMValues;
   /*
    * Size of the file in bytes
    */
@@ -130,7 +170,7 @@ export interface FileObject {
   /**
    * An object containing the file or file version's id (versionId) and name.
    */
-  versionInfo?: object;
+  versionInfo?: { name: string; id: string };
 }
 
 

libs/interfaces/UploadOptions.ts

@@ -1,4 +1,27 @@
 import { ReadStream } from "fs";
+import { Extension } from "./FileDetails";
+
+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
@@ -72,7 +95,7 @@ export interface UploadOptions {
   /* 
    * Object with array of extensions to be processed on the image.
    */
-  extensions?: object[];
+  extensions?: Extension;
   /*
    * Final status of pending extensions will be sent to this URL. 
    */
@@ -83,5 +106,6 @@ export interface UploadOptions {
   overwriteCustomMetadata?: boolean;
   customMetadata?: {
     [key: string]: string | number | boolean | Array<string | number | boolean>;
-  }
+  },
+  transformation?: Transformation
 }