diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..03d7092 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +## SDK Version 3.0.0 + +### Breaking Changes + +- **Overlay Syntax Update** + In version 3.0.0, the old overlay syntax parameters for transformations (e.g., `oi`, `ot`, `obg`, and others as detailed [here](https://imagekit.io/docs/add-overlays-on-images)) have been removed. These parameters are deprecated and will now return errors when used in URLs. + + **Action Required:** + Migrate to the new layers syntax which supports overlay nesting, offers improved positional control, and allows more transformations at the layer level. For a quick start, refer to the [examples](https://imagekit.io/docs/add-overlays-on-images). Use the `raw` transformation parameter to implement this migration. + +--- + +## SDK Version 2.0.0 + +### Breaking Changes + +- **Authentication Process Update** + Previously, client-side file uploads required the SDK to be initialized with both the `publicKey` and `authenticationEndpoint` to fetch security parameters (`signature`, `token`, and `expire`). + + **Action Required:** + With version 2.0.0, you must now generate the security parameters (`signature`, `token`, and `expire`) yourself, eliminating the need for the `authenticationEndpoint`. When invoking the SDK's upload method, be sure to include these parameters along with other [upload options](https://imagekit.io/docs/api-reference/upload-file/upload-file#Request). For further details, consult the documentation [here](https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload). diff --git a/README.md b/README.md index b996815..2b06eea 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [ImageKit.io](https://imagekit.io) -# ImageKit.io Javascript SDK +# ImageKit.io JavaScript SDK ![gzip size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=gzip&label=gzip) ![brotli size](https://img.badgesize.io/https://unpkg.com/imagekit-javascript/dist/imagekit.min.js?compression=brotli&label=brotli) @@ -10,268 +10,184 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo) -Javascript SDK for [ImageKit](https://imagekit.io/) provides URL generation for image & video resizing and provides an interface for file upload. This SDK is lightweight and has no dependency. You can also use this as an ES module. - -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 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). +Lightweight JavaScript SDK for generating optimized URLs for images and videos, and for handling file uploads via ImageKit. + +## Table of Contents +- [Installation](#installation) +- [Initialization](#initialization) +- [URL Generation](#url-generation) + - [Basic URL Generation](#basic-url-generation) + - [Advanced URL Generation Examples](#advanced-url-generation-examples) + - [Supported Transformations](#supported-transformations) + - [Handling Unsupported Transformations](#handling-unsupported-transformations) +- [File Upload](#file-upload) + - [Basic Upload Example](#basic-upload-example) + - [Promise-based Upload Example](#promise-based-upload-example) +- [Test Examples](#test-examples) +- [Changelog](#changelog) ## Installation ### Using npm -Install `imagekit-javascript` -``` +Install the SDK via npm: +```bash npm install imagekit-javascript --save -#or +# or yarn add imagekit-javascript ``` -Now import ImageKit +Then import ImageKit: ```js -import ImageKit from "imagekit-javascript" - -// or -const ImageKit = require("imagekit-javascript") +import ImageKit from "imagekit-javascript"; +// or with CommonJS: +const ImageKit = require("imagekit-javascript"); ``` ### Using CDN -You can download a specific version of this SDK from a global CDN. +You can also use the global CDN: + +Download a specific version: ``` https://unpkg.com/imagekit-javascript@1.3.0/dist/imagekit.min.js ``` - -For the latest version, remove the version number i.e. +Or for the latest version, remove the version number: ``` https://unpkg.com/imagekit-javascript/dist/imagekit.min.js ``` - -Now load it using a ` ``` ## Initialization -`urlEndpoint` is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard#url-endpoints - -``` +Initialize the SDK by specifying your URL endpoint. You can obtain your URL endpoint from [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints) and your public API key from [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys). For URL generation: +```js var imagekit = new ImageKit({ urlEndpoint: "https://ik.imagekit.io/your_imagekit_id" -}); -``` - -`publicKey` parameter is required if you want to use the SDK for client-side file upload. You can get this parameter from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard#developers +}); ``` +For client-side file uploads, include your public key: +```js var imagekit = new ImageKit({ publicKey: "your_public_api_key", urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", -}); -``` - -*Note: Do not include your Private Key in any client-side code, including this SDK or its initialization. If you pass the `privateKey` parameter while initializing this SDK, it throws an error* - -## Demo Application - -The fastest way to get started is by running the demo application in [samples/sample-app](https://github.com/imagekit-developer/imagekit-javascript/tree/master/samples/sample-app) folder. Follow these steps to run the application locally: - -``` -git clone https://github.com/imagekit-developer/imagekit-javascript.git - -cd imagekit-javascript -``` - -Create a file `.env` using `sample.env` in the directory `samples/sample-app` and fill in your `PRIVATE_KEY`, `PUBLIC_KEY` and `URL_ENDPOINT` from your [imageKit dashboard](https://imagekit.io/dashboard#developers). `SERVER_PORT` must also be included as per the `sample.env` file. - -Now start the sample application by running: - -``` -// Run it from the project root -yarn startSampleApp -``` - -## Usage -You can use this SDK for URL generation and client-side file uploads. - -### URL Generation - -**1. Using image path and image hostname or endpoint** - -This method allows you to create an URL to access a file using the relative file path and the ImageKit URL endpoint (`urlEndpoint`). The file can be an image, video, or any other static file supported by ImageKit. - -``` -var imageURL = imagekit.url({ - path: "/default-image.jpg", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", - transformation: [{ - "height": "300", - "width": "400" - }] -}); -``` - -This results in a URL like - -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg -``` - -**2. Using full image URL** - -This method allows you to add transformation parameters to an absolute URL. For example, if you have configured a custom CNAME and have absolute asset URLs in your database or CMS, you will often need this. - - -``` -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", - transformation: [{ - "height": "300", - "width": "400" - }] }); ``` +*Note: Never include your private key in client-side code. If provided, the SDK throws an error.* -This results in a URL like +## URL Generation -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400 -``` +The SDK’s `.url()` method enables you to generate optimized image and video URLs with a variety of transformations. +### Basic URL Generation -The `.url()` method accepts the following parameters - -| Option | Description | -| :----------------| :----------------------------- | -| urlEndpoint | Optional. The base URL to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/ | -| path | Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| src | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. | -| transformation | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be specified as different objects of the array. The complete list of supported transformations in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. | -| transformationPostion | Optional. The default value is `path`, which places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use the `src` parameter to create the URL, then the transformation string is always added as a query parameter. | -| queryParameters | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and are not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs. | +1. **Using an Image Path with a URL Endpoint** + ```js + var imageURL = imagekit.url({ + path: "/default-image.jpg", + urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", + transformation: [{ + "height": "300", + "width": "400" + }] + }); + ``` + *Result Example:* + ``` + https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg + ``` + +2. **Using a Full Image URL (src)** + ```js + var imageURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", + transformation: [{ + "height": "300", + "width": "400" + }] + }); + ``` + *Result Example:* + ``` + https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400 + ``` -#### Examples of generating URLs +### Advanced URL Generation Examples -**1. Chained Transformations as a query parameter** -``` +#### Chained Transformations +Apply multiple transformations by passing an array: +```js var imageURL = imagekit.url({ path: "/default-image.jpg", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", transformation: [{ "height": "300", "width": "400" }, { "rotation": 90 }], - transformationPosition: "query" -}); -``` -``` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400%3Art-90 -``` - -**2. Sharpening and contrast transforms and a progressive JPG image** - -There are some transforms like [Sharpening](https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation) that can be added to the URL with or without any other value. To use such transforms without specifying a value, specify the value as "-" in the transformation object. Otherwise, specify the value that you want to be added to this transformation. - -``` -var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", - transformation: [{ - "format": "jpg", - "progressive": "true", - "effectSharpen": "-", - "effectContrast": "1" - }] + transformationPosition: "query" // Use query parameter for transformations }); ``` +*Result Example:* ``` -//Note that because `src` parameter was used, the transformation string gets added as a query parameter `tr` -https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=f-jpg%2Cpr-true%2Ce-sharpen%2Ce-contrast-1 +https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300%2Cw-400%3Art-90 ``` -**3. Adding overlays** - -ImageKit.io enables you to apply overlays to [images](https://docs.imagekit.io/features/image-transformations/overlay-using-layers) and [videos](https://docs.imagekit.io/features/video-transformation/overlay) using the raw parameter with the concept of [layers](https://docs.imagekit.io/features/image-transformations/overlay-using-layers#layers). The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations. - -**Text as overlays** - -You can add any text string over a base video or image using a text layer (l-text). - -For example: - +#### Overlays and Effects +*Text Overlay Example:* ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ "width": 400, - "height": 300 + "height": 300, "raw": "l-text,i-Imagekit,fs-50,l-end" }] }); ``` -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg -``` - -**Image as overlays** - -You can add an image over a base video or image using an image layer (l-image). - -For example: - +*Image Overlay Example:* ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ "width": 400, - "height": 300 + "height": 300, "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end" }] }); ``` -**Sample Result URL** -``` -https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg -``` - -**Solid color blocks as overlays** - -You can add solid color blocks over a base video or image using an image layer (l-image). - -For example: +#### AI and Advanced Transformations +*Background Removal:* ```js var imageURL = imagekit.url({ - src: "https://ik.imagekit.io/your_imagekit_id/img/sample-video.mp4", - transformation: [{ - "width": 400, - "height": 300 - "raw": "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end" - }] + path: "/sample-image.jpg", + transformation: [{ + aiRemoveBackground: true + }] }); ``` -**Sample Result URL** +*Upscaling:* +```js +var upscaledURL = imagekit.url({ + path: "/sample-image.jpg", + transformation: [{ + aiUpscale: true + }] +}); ``` -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 +*Drop Shadow:* +```js +var dropShadowURL = imagekit.url({ + path: "/sample-image.jpg", + transformation: [{ + aiDropShadow: "az-45" + }] +}); ``` -**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: - +#### Arithmetic Expressions in Transformations ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", @@ -283,233 +199,149 @@ var imageURL = imagekit.url({ }); ``` -**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 +### Supported 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. + +If you want to generate transformations in your application and add them to the URL as it is, use the raw parameter. + +Check ImageKit [transformation documentation](https://imagekit.io/docs/transformations) for more details. + +| Transformation Name | URL Parameter | +| -------------------------- | ------------------------------------------------------------- | +| width | w | +| height | h | +| aspectRatio | ar | +| quality | q | +| aiRemoveBackground | e-bgremove (ImageKit powered) | +| aiRemoveBackgroundExternal | e-removedotbg (Using third party) | +| aiUpscale | e-upscale | +| aiRetouch | e-retouch | +| aiVariation | e-genvar | +| aiDropShadow | e-dropshadow | +| aiChangeBackground | e-changebg | +| crop | c | +| cropMode | cm | +| x | x | +| y | y | +| xCenter | xc | +| yCenter | yc | +| focus | fo | +| format | f | +| radius | r | +| background | bg | +| border | b | +| rotation | rt | +| blur | bl | +| named | n | +| dpr | dpr | +| progressive | pr | +| lossless | lo | +| trim | t | +| metadata | md | +| colorProfile | cp | +| defaultImage | di | +| original | orig | +| videoCodec | vc | +| audioCodec | ac | +| grayscale | e-grayscale | +| contrastStretch | e-contrast | +| shadow | e-shadow | +| sharpen | e-sharpen | +| unsharpMask | e-usm | +| gradient | e-gradient | +| flip | fl | +| opacity | o | +| zoom | z | +| page | pg | +| startOffset | so | +| endOffset | eo | +| duration | du | +| streamingResolutions | sr | +| raw | The string provided in raw will be added in the URL as it is. | + +### Handling Unsupported Transformations + +If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. + +For example: +```js +var imageURL = imagekit.url({ + path: "/test_path.jpg", + transformation: [{ + "newparam": "cool" + }] +}); +// Generated URL: https://ik.imagekit.io/test_url_endpoint/tr:newparam-cool/test_path.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. - -If you want to generate transformations in your application and add them to the URL as it is, use the `raw` parameter. - -| Supported Transformation Name | Translates to parameter | -|-------------------------------|-------------------------| -| height | h | -| width | w | -| aspectRatio | ar | -| quality | q | -| crop | c | -| cropMode | cm | -| x | x | -| y | y | -| focus | fo | -| format | f | -| radius | r | -| background | bg | -| border | b | -| rotation | rt | -| blur | bl | -| named | n | -| progressive | pr | -| lossless | lo | -| trim | t | -| metadata | md | -| colorProfile | cp | -| defaultImage | di | -| dpr | dpr | -| effectSharpen | e-sharpen | -| 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. | - - -### File Upload - -The SDK provides a simple interface using the `.upload()` method to upload files to the ImageKit Media Library. - -The `upload()` method requires mandatory `file` and the `fileName` parameter. In addition, it accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). - -Also, before making an upload request, please ensure you have generated mandatory security parameters: `signature`, `token`, and `expire`. To generate these security parameters, refer to the [documentation here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#signature-generation-for-client-side-file-upload). Obtain the parameters using a secure method and pass them, along with the mandatory `file` and `fileName` parameters, to the `upload()` method. - -You can pass other parameters supported by the ImageKit upload API using the same parameter name as specified in the upload API documentation. For example, to specify tags for a file at the time of upload, use the `tags` parameter as specified in the [documentation here](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload). - - -#### Sample usage +## File Upload + +The SDK offers a simple interface via the `.upload()` method to upload files to the ImageKit Media Library. This method requires the following: +- **file** (mandatory) +- **fileName** (mandatory) +- Security parameters: **signature**, **token**, and **expire** + +Before invoking the upload, generate the necessary security parameters as per the [ImageKit Upload API documentation](https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload). + +### Basic Upload Example + +Below is an HTML form example that uses a callback for handling the upload response: + ```html -
+
- - + ``` -If the upload succeeds, `err` will be `null`, and the `result` will be the same as what is received from ImageKit's servers. -If the upload fails, `err` will be the same as what is received from ImageKit's servers, and the `result` will be null. - -## Tracking upload progress using custom XMLHttpRequest -You can use a custom XMLHttpRequest object as the following to bind `progress` or any other events for a customized implementation. +### Promise-based Upload Example +You can also use promises for a cleaner asynchronous approach: ```js -var fileSize = file.files[0].size; -var customXHR = new XMLHttpRequest(); -customXHR.upload.addEventListener('progress', function (e) { - if (e.loaded <= fileSize) { - var percent = Math.round(e.loaded / fileSize * 100); - console.log(`Uploaded ${percent}%`); - } - - if(e.loaded == e.total){ - console.log("Upload done"); - } -}); - imagekit.upload({ - xhr: customXHR, file: file.files[0], fileName: "abc1.jpg", - tags: ["tag1"], token: 'generated_token', signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] + expire: 'generated_expire' }).then(result => { console.log(result); -}).then(error => { - console.log(error); -}) +}).catch(error => { + console.error(error); +}); ``` -## Access request-id, other response headers, and HTTP status code -You can access `$ResponseMetadata` on success or error object to access the HTTP status code and response headers. +## Test Examples -```js -// Success -var response = await imagekit.upload({ - file: file.files[0], - fileName: "abc1.jpg", - tags: ["tag1"], - token: 'generated_token', - signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] -}); -console.log(response.$ResponseMetadata.statusCode); // 200 - -// { 'content-length': "300", 'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'} -console.log(response.$ResponseMetadata.headers); - -// Error -try { - await imagekit.upload({ - file: file.files[0], - fileName: "abc1.jpg", - tags: ["tag1"], - token: 'generated_token', - signature: 'generated_signature', - expire: 'generated_expire', - extensions: [ - { - name: "aws-auto-tagging", - minConfidence: 80, - maxTags: 10 - } - ] - }); -} catch (ex) { - console.log(response.$ResponseMetadata.statusCode); // 400 +For a quick demonstration of the SDK features, refer to our test examples: +- URL Generation examples can be found in [test/url-generation.js](./test/url-generation.js) +- File Upload examples can be found in [test/upload.js](./test/upload.js) + +## Changelog - // {'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'} - console.log(response.$ResponseMetadata.headers); -} -``` \ No newline at end of file +For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). diff --git a/package-lock.json b/package-lock.json index 464ee1c..b1f0c3f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.0.2", + "version": "3.1.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index d101e93..1938f2e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.0.2", + "version": "3.1.0", "description": "Javascript SDK for using ImageKit.io in the browser", "main": "dist/imagekit.cjs.js", "module": "dist/imagekit.esm.js", diff --git a/samples/sample-app/server/server.js b/samples/sample-app/server/server.js index 5942f56..6558660 100644 --- a/samples/sample-app/server/server.js +++ b/samples/sample-app/server/server.js @@ -8,6 +8,7 @@ const path = require('path'); const pugTemplatePath = path.join(__dirname, "../views/index.pug"); const app = express(); +app.use(express.static('static')) app.use(cors()); app.set('view engine', 'pug'); diff --git a/samples/sample-app/views/index.pug b/samples/sample-app/views/index.pug index 6f0b44f..91d398f 100644 --- a/samples/sample-app/views/index.pug +++ b/samples/sample-app/views/index.pug @@ -1,5 +1,6 @@ html body + img(id="my-image") h3 Imagekit Demo form(action='#' onSubmit='upload(event)') input(type='file' id='file1') @@ -18,7 +19,8 @@ html p img(src="") - script(type='text/javascript' src="https://unpkg.com/imagekit-javascript/dist/imagekit.min.js") + // Copy paste manually from dist + script(type='text/javascript' src="./imagekit.min.js") script. try { var imagekit = new ImageKit({ @@ -26,8 +28,20 @@ html urlEndpoint: "!{urlEndpoint}", }); + window.imagekit = imagekit; + var url = imagekit.url({ + src: "https://ik.imagekit.io/demo/default-image.jpg", + transformation: [{ + height: 100 + }] + }) + + var img = document.getElementById("my-image"); + console.log(url); + img.src = url; + function upload(e) { e.preventDefault(); @@ -119,4 +133,4 @@ html } } catch(ex) { console.log(ex); - } \ No newline at end of file + } diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index d7fd27b..bbc560f 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -1,167 +1,75 @@ /** - * @link https://docs.imagekit.io/features/image-transformations + * {@link https://imagekit.io/docs/transformations} */ -const supportedTransforms: { [key: string]: string } = { - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#width-w - */ +export const supportedTransforms: { [key: string]: string } = { + // Basic sizing & layout width: "w", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#height-h - */ height: "h", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#aspect-ratio-ar - */ aspectRatio: "ar", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#quality-q - */ - quality: "q", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus - */ + background: "bg", + border: "b", crop: "c", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus - */ cropMode: "cm", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#focus-fo - */ + dpr: "dpr", focus: "fo", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#examples-focus-using-cropped-image-coordinates - */ + quality: "q", x: "x", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#examples-focus-using-cropped-image-coordinates - */ + xCenter: "xc", y: "y", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#format-f - */ + yCenter: "yc", format: "f", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#radius-r - */ + videoCodec: "vc", + audioCodec: "ac", radius: "r", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#background-color-bg - */ - background: "bg", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#border-b - */ - border: "b", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#rotate-rt - */ rotation: "rt", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#rotate-rt - */ - rotate: "rt", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#blur-bl - */ blur: "bl", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#named-transformation-n - */ named: "n", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#progressive-image-pr - */ - progressive: "pr", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#lossless-webp-and-png-lo - */ - lossless: "lo", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#trim-edges-t - */ - trim: "t", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#image-metadata-md - */ - metadata: "md", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#color-profile-cp - */ - colorProfile: "cp", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#default-image-di - */ defaultImage: "di", + flip: "fl", + original: "orig", + startOffset: "so", + endOffset: "eo", + duration: "du", + streamingResolutions: "sr", - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#dpr-dpr - */ - dpr: "dpr", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#sharpen-e-sharpen - */ + // Old deprecated mappings effectSharpen: "e-sharpen", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#unsharp-mask-e-usm - */ effectUSM: "e-usm", - - /** - * @link https://docs.imagekit.io/features/image-transformations/image-enhancement-and-color-manipulation#contrast-stretch-e-contrast - */ effectContrast: "e-contrast", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#grayscale-e-grayscale - */ effectGray: "e-grayscale", - - /** - * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#original-image-orig - */ - 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", + rotate: "rt", + + // AI & advanced effects + grayscale: "e-grayscale", + aiUpscale: "e-upscale", + aiRetouch: "e-retouch", + aiVariation: "e-genvar", + aiDropShadow: "e-dropshadow", + aiChangeBackground: "e-changebg", + aiRemoveBackground: "e-bgremove", + aiRemoveBackgroundExternal: "e-removedotbg", + contrastStretch: "e-contrast", + shadow: "e-shadow", + sharpen: "e-sharpen", + unsharpMask: "e-usm", + gradient: "e-gradient", + + // Other flags & finishing + progressive: "pr", + lossless: "lo", + colorProfile: "cp", + metadata: "md", + opacity: "o", + trim: "t", + zoom: "z", + page: "pg", + + // Raw pass-through + raw: "raw", +}; - /** - * @link https://docs.imagekit.io/features/image-transformations/conditional-transformations - */ - raw: "raw", -} export default supportedTransforms \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index c6d0bc3..9b88b33 100644 --- a/src/index.ts +++ b/src/index.ts @@ -55,27 +55,16 @@ class ImageKit { } /** - * You can add multiple origins in the same ImageKit.io account. - * URL endpoints allow you to configure which origins are accessible through your account and set their preference order as well. - * - * @see {@link https://github.com/imagekit-developer/imagekit-nodejs#url-generation} - * @see {@link https://docs.imagekit.io/integration/url-endpoints} - * - * @param urlOptions + * A utility function to generate asset URL. It applies the specified transformations and other parameters to the URL. */ url(urlOptions: UrlOptions): string { return url(urlOptions, this.options); } /** - * You can upload files to ImageKit.io media library from your server-side using private API key authentication. - * - * File size limit - * The maximum upload file size is limited to 25MB. - * - * @see {@link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload} + * For uploading files directly from the browser to ImageKit.io. * - * @param uploadOptions + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload} */ upload(uploadOptions: UploadOptions, options?: Partial): Promise> upload(uploadOptions: UploadOptions, callback: (err: Error | null, response: IKResponse | null) => void, options?: Partial): void; diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 0c74022..a963f8f 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -1,5 +1,426 @@ -import supportedTransforms from "../constants/supportedTransforms"; - export type TransformationPosition = "path" | "query"; -export type Transformation = Partial; +type StreamingResolution = "240" | "360" | "480" | "720" | "1080" | "1440" | "2160"; + +/** + * The SDK provides easy to use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. + * SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, you can use the `raw` parameter to pass the transformation string directly. + * + * {@link https://imagekit.io/docs/transformations} + */ +export interface Transformation { + /** + * The width of the output. If a value between 0 and 1 is used, it’s treated + * as a percentage (e.g., `0.4` -> 40% of original width). You can also supply + * arithmetic expressions (e.g., `"iw_div_2"`). + * + * {@link https://imagekit.io/docs/image-resize-and-crop#width---w} + */ + width?: number | string; + + /** + * The height of the output. If a value between 0 and 1 is used, it’s treated + * as a percentage (e.g., `0.5` -> 50% of original height). You can also supply + * arithmetic expressions (e.g., `"ih_mul_0.5"`). + * + * {@link https://imagekit.io/docs/image-resize-and-crop#height---h} + */ + height?: number | string; + + /** + * Specifies the aspect ratio for the output, e.g., `"ar-4-3"`. + * Typically used with either width or height (not both). + * Example usage: `aspectRatio = "4:3"` or `"4_3"` or an expression like `"iar_div_2"`. + * + * {@link https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar} + */ + aspectRatio?: number | string; + + /** + * Specify the background that can be used along with some cropping strategies while resizing an image: + * - A solid color: `"red"`, `"F3F3F3"`, `"AAFF0010"`. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#solid-color-background} + * + * - A blurred background: `"blurred"`, `"blurred_25_N15"`, etc. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background} + * + * - Expand the image boundaries using generative fill: `genfill`. Optionally control the background scene by passing text prompt: `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. + * + * {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill} + */ + background?: string; + + /** + * Add a border to the output media. Accepts `_`, + * e.g. `"5_FFF000"` (5px yellow border), or an expression like `"ih_div_20_FF00FF"`. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#border---b} + */ + border?: string; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} + */ + crop?: "force" | "at_max" | "at_max_enlarge" | "at_least" | "maintain_ratio"; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} + */ + cropMode?: "pad_resize" | "extract" | "pad_extract"; + + /** + * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. + * + * {@link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr} + */ + dpr?: number + + /** + * This parameter can be used along with pad resize, maintain ratio, or extract crop to change the behavior of padding or cropping + * + * {@link https://imagekit.io/docs/image-resize-and-crop#focus---fo} + */ + focus?: string; + + /** + * Used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF. A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. + * + * {@link https://imagekit.io/docs/image-optimization#quality---q} + */ + quality?: number; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + */ + x?: number | string; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + */ + xCenter?: number | string; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + */ + y?: number | string; + + /** + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + */ + yCenter?: number | string; + + /** + * Output format for images or videos, e.g., `"jpg"`, `"png"`, `"webp"`, `"mp4"`, `"auto"`. You can also pass `orig` which works only for images and will return the image in the original format. + * + * ImageKit will automatically deliver images and videos in best possible format based on the device support unless you disable it from the dashboard settings or override it using the `format` parameter. + * + * {@link https://imagekit.io/docs/image-optimization#format---f} + * + * {@link https://imagekit.io/docs/video-optimization#format---f}} + */ + format?: "auto" | "webp" | "jpg" | "jpeg" | "png" | "gif" | "svg" | "mp4" | "webm" | "avif" | "orig"; + + /** + * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"` or `"none"`. + * + * {@link https://imagekit.io/docs/video-optimization#video-codec---vc} + */ + videoCodec?: "h264" | "vp9" | "av1" | "none"; + + /** + * Audio codec, e.g., `"aac"`, `"opus"` or `"none"`. + * + * {@link https://imagekit.io/docs/video-optimization#audio-codec---ac} + */ + audioCodec?: "aac" | "opus" | "none"; + + /** + * Corner radius for rounded corners (e.g., `20`) or `"max"` for circular/oval shapes. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#radius---r} + */ + radius?: number | "max"; + + /** + * Rotation in degrees. Positive values rotate clockwise; you can + * also use e.g. `"N40"` for counterclockwise or `"auto"` to read EXIF data. + * For videos only 0 , 90 , 180 , 270 and 360 values are supported. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#rotate---rt} + */ + rotation?: number | string; + + /** + * Gaussian blur level. Ranges 1–100 or an expression like `"bl-10"`. Possible values include integers between 1 and 100. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#blur---bl} + */ + blur?: number; + + /** + * {@link https://imagekit.io/docs/transformations#named-transformations} + */ + named?: string; + + /** + * Fallback image if the resource is not found, e.g., a URL or path. + * + * {@link https://imagekit.io/docs/image-transformation#default-image---di} + */ + defaultImage?: string; + + /** + * It is used to flip/mirror an image horizontally, vertically, or in both directions. + * Possible values - h (horizontal), v (vertical), h_v (horizontal and vertical) + * + * {@link https://imagekit.io/docs/effects-and-enhancements#flip---fl} + */ + flip?: "h" | "v" | "h_v" | "v_h"; + + /** + * Whether to serve the original file without any transformations if `true`. + * + * {@link https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true} + */ + original?: boolean; + + /** + * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#start-offset---so} + */ + startOffset?: number | string; + + /** + * End offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Usually used with `startOffset` to define a time window. + * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#end-offset---eo} + */ + endOffset?: number | string; + + /** + * Duration (in seconds) for trimming videos. e.g., `5` or `"10.5"`. + * Typically used with `startOffset` to specify length from the start point. + * Also supports arithmetic expressions. + * + * {@link https://imagekit.io/docs/trim-videos#duration---du} + */ + duration?: number | string; + + /** + * Provide an array of resolutions (e.g. `["240", "360", "480", "720", "1080"]`). + * + * {@link https://imagekit.io/docs/adaptive-bitrate-streaming} + */ + streamingResolutions?: StreamingResolution[]; + + /** + * Enable grayscale effect for images. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale} + */ + grayscale?: true; + + /** + * Upscale images beyond their original dimensions with AI. + * + * {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale} + */ + aiUpscale?: true + + /** + * Retouch (AI-based) for improving faces or product shots. + * + * {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch} + */ + aiRetouch?: true + + /** + * Generate variation of an image using AI. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image. + * + * {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar} + */ + aiVariation?: true + + /** + * Add an AI-based drop shadow around a foreground object on a transparent or removed background. + * Optionally, you can control the direction, elevation, and saturation of the light source. E.g. change light direction `az-45`. + * + * Pass `true` for default drop shadow or a string for custom drop shadow. + * + * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow} + */ + aiDropShadow?: true | string + + /** + * Change background using AI. Provide a prompt or base64-encoded prompt. e.g. `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + * + * {@link https://imagekit.io/docs/ai-transformations#change-background-e-changebg} + */ + aiChangeBackground?: string; + + /** + * ImageKit’s in-house background removal. + * + * {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove} + */ + aiRemoveBackground?: true + + /** + * Use third-party background removal. Use `aiRemoveBackground` - ImageKit's in-house background removal which is 90% cheaper. + * + * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg} + */ + aiRemoveBackgroundExternal?: true + + /** + * Auto-enhance contrast for an image (contrast stretch). + * + * {@link https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast} + */ + contrastStretch?: true + + /** + * This adds a shadow under solid objects in an input image with a transparent background. Check `eDropshadow` for AI-based shadows. + * + * Pass `true` for default shadow or a string for custom shadow. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow} + */ + shadow?: true | string + + /** + * It is used to sharpen the input image. It is useful when highlighting the edges and finer details within an image. + * + * Pass `true` for default sharpening or a number for custom sharpening. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen} + */ + sharpen?: true | number + + /** + * Unsharp Masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp masks on your images. + * + * Pass `true` for default unsharp mask or a string for custom unsharp mask. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm} + */ + unsharpMask?: true | string; + + /** + * The gradient formed is a linear gradient containing two colors, and it can be customized. + * + * Pass `true` for default gradient or a string for custom gradient. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient} + */ + gradient?: true | string; + + /** + * Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time. + * + * {@link https://imagekit.io/docs/image-optimization#progressive-image---pr} + */ + progressive?: boolean; + + /** + * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. + * + * {@link https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo} + */ + lossless?: boolean + + /** + * It specifies whether the output image should contain the color profile initially available with the original image. + * + * {@link https://imagekit.io/docs/image-optimization#color-profile---cp} + */ + colorProfile?: boolean; + + /** + * By default, ImageKit removes all metadata as part of automatic image compression. Set this to `true` to preserve metadata. + * + * {@link https://imagekit.io/docs/image-optimization#image-metadata---md} + */ + metadata?: boolean; + + /** + * It is used to specify the opacity level of the output image. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#opacity---o} + */ + opacity?: number; + + /** + * Useful with images that have a solid or nearly solid background with the object in the center. This parameter trims the background from the image, leaving only the central object in the output image. + * + * {@link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t} + */ + trim?: true | number; + + /** + * This parameter accepts a number that determines how much to zoom in or out of the cropped area. + * It must be used along with fo-face or fo- + * + * {@link https://imagekit.io/docs/image-resize-and-crop#zoom---z} + */ + zoom?: number; + + /** + * Extract specific page/frame from multi-page or layered files (PDF, PSD, AI), + * Pick by number e.g., `2`. Or 2nd and 3rd layers combined using `3-4`. + * Or pick a layer from PSD by name, e.g., `name-layer-4`. + * + * {@link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files} + */ + page?: number | string; + + /** + * Pass any transformation that is not directly supported by the SDK. This transformation is passed as it is in the URL. + */ + raw?: string; + + // old as it is but deprecated + + /** + * @deprecated Use `rotation` instead. + */ + rotate?: string; + + /** + * @deprecated Use `sharpen` instead. + */ + effectSharpen?: string; + + /** + * @deprecated Use `unsharpMask` instead. + */ + effectUSM?: string; + + /** + * @deprecated Use `contrastStretch` instead. + */ + effectContrast?: string; + + /** + * @deprecated Use `grayscale` instead. + */ + effectGray?: string; + + /** + * @deprecated Use `shadow` instead. + */ + effectShadow?: string; + + /** + * @deprecated Use `gradient` instead. + */ + effectGradient?: string; +} + + diff --git a/src/interfaces/UploadOptions.ts b/src/interfaces/UploadOptions.ts index 092f263..9a45479 100644 --- a/src/interfaces/UploadOptions.ts +++ b/src/interfaces/UploadOptions.ts @@ -23,7 +23,7 @@ interface Transformation{ /** * Options used when uploading a file * - * @link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload#request-structure-multipart-form-data + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Request} */ export interface UploadOptions { /** diff --git a/src/interfaces/UploadResponse.ts b/src/interfaces/UploadResponse.ts index e3e2f93..b38cf27 100644 --- a/src/interfaces/UploadResponse.ts +++ b/src/interfaces/UploadResponse.ts @@ -4,13 +4,14 @@ * image - only search in image type files * non-image - only search in files which are not image, e.g., JS or CSS or video files. * - * @link https://docs.imagekit.io/api-reference/media-api/list-and-search-files + * {@link https://imagekit.io/docs/api-reference/digital-asset-management-dam/list-and-search-assets} */ export type FileType = "all" | "image" | "non-image"; /** * Metadata object structure - * @link https://docs.imagekit.io/api-reference/metadata-api#metadata-object-structure + * + * {@link https://imagekit.io/docs/api-reference/file-metadata/get-uploaded-file-metadata#Responses} * * Contents of Object * @@ -96,7 +97,7 @@ export interface Metadata { /** * Response from uploading a file * - * @link https://docs.imagekit.io/api-reference/upload-file-api/server-side-file-upload#response-code-and-structure-json + * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Responses} */ export interface UploadResponse { /** diff --git a/src/interfaces/UrlOptions.ts b/src/interfaces/UrlOptions.ts index c6af45d..5d1d38c 100644 --- a/src/interfaces/UrlOptions.ts +++ b/src/interfaces/UrlOptions.ts @@ -5,7 +5,8 @@ export interface UrlOptionsBase { /** * An array of objects specifying the transformations to be applied in the URL. * The transformation name and the value should be specified as a key-value pair in each object. - * @link https://docs.imagekit.io/features/image-transformations/chained-transformations + * + * {@link https://imagekit.io/docs/transformations#chained-transformations} */ transformation?: Array; /** @@ -49,6 +50,6 @@ export interface UrlOptionsPath extends UrlOptionsBase { /** * Options for generating an URL * - * @link https://github.com/imagekit-developer/imagekit-javascript#url-generation + * {@link https://github.com/imagekit-developer/imagekit-javascript#url-generation} */ export type UrlOptions = UrlOptionsSrc | UrlOptionsPath; diff --git a/src/url/builder.ts b/src/url/builder.ts index 485b41a..29e13f8 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -82,27 +82,54 @@ 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; + let value = transformation[i][key as keyof Transformation]; + if (value === undefined || value === null) { + continue; + } + var transformKey = transformationUtils.getTransformKey(key); if (!transformKey) { transformKey = key; } - if (transformation[i][key] === "-") { + if (transformKey === "") { + continue; + } + + if ( + ["e-grayscale", "e-contrast", "e-removedotbg", "e-bgremove", "e-upscale", "e-retouch", "e-genvar"].includes(transformKey) + ) { + if (value === true || value === "-" || value === "true") { + parsedTransformStep.push(transformKey); + } else { + // Any other value means that the effect should not be applied + continue; + } + } else if ( + ["e-sharpen", "e-shadow", "e-gradient", "e-usm", "e-dropshadow"].includes(transformKey) && + (value.toString().trim() === "" || value === true || value === "true") + ) { parsedTransformStep.push(transformKey); } else if (key === "raw") { parsedTransformStep.push(transformation[i][key]); } else { - var value = transformation[i][key]; if (transformKey === "di") { - value = removeTrailingSlash(removeLeadingSlash(value || "")); + value = removeTrailingSlash(removeLeadingSlash(value as string || "")); value = value.replace(/\//g, "@@"); } + if (transformKey === "sr" && Array.isArray(value)) { + value = value.join("_"); + } + // Special case for trim with empty string - should be treated as true + if (transformKey === "t" && value.toString().trim() === "") { + value = "true"; + } parsedTransformStep.push([transformKey, value].join(transformationUtils.getTransformKeyValueDelimiter())); } } - parsedTransforms.push(parsedTransformStep.join(transformationUtils.getTransformDelimiter())); + if (parsedTransformStep.length) { + parsedTransforms.push(parsedTransformStep.join(transformationUtils.getTransformDelimiter())); + } } return parsedTransforms.join(transformationUtils.getChainTransformDelimiter()); diff --git a/test/url-generation.js b/test/url-generation.js index 4091692..40c7e38 100644 --- a/test/url-generation.js +++ b/test/url-generation.js @@ -9,19 +9,19 @@ describe("URL generation", function () { var imagekit = new ImageKit(initializationParams); - it('no path no src', function () { + it('should return an empty string when neither path nor src is provided', function () { const url = imagekit.url({}); expect(url).equal(""); }); - it('invalid src url', function () { + it('should return an empty string for an invalid src URL', function () { const url = imagekit.url({ src: "/" }); expect(url).equal(""); }); - it('no transformation path', function () { + it('should generate a valid URL when a path is provided without transformation', function () { const url = imagekit.url({ path: "/test_path.jpg" }); @@ -29,7 +29,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg`); }); - it('no transformation src', function () { + it('should generate a valid URL when a src is provided without transformation', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg" }); @@ -37,7 +37,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg`); }); - it('Undefined parameters with path', function () { + it('should generate a valid URL when undefined transformation parameters are provided with path', function () { const url = imagekit.url({ path: "/test_path_alt.jpg", transformation: undefined, @@ -48,8 +48,8 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg`); }); - it('should generate the url without sdk-version', function () { - const ik = new ImageKit({...initializationParams, sdkVersion: ""}) + it('should generate the URL without sdk version', function () { + const ik = new ImageKit({ ...initializationParams, sdkVersion: "" }) const url = ik.url({ path: "/test_path.jpg", @@ -62,7 +62,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400/test_path.jpg`); }); - it('should generate the correct url with path param', function () { + it('should generate the correct URL with a valid path and transformation', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -74,7 +74,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400/test_path.jpg`); }); - it('should generate the correct url with path param with multiple leading slash', function () { + it('should generate the correct URL when the provided path contains multiple leading slashes', function () { const url = imagekit.url({ path: "///test_path.jpg", transformation: [{ @@ -87,7 +87,7 @@ describe("URL generation", function () { }); - it('should generate the correct url with path param with overidden urlEndpoint', function () { + it('should generate the correct URL when the urlEndpoint is overridden', function () { const url = imagekit.url({ urlEndpoint: "https://ik.imagekit.io/test_url_endpoint_alt", path: "/test_path.jpg", @@ -101,7 +101,7 @@ describe("URL generation", function () { }); - it('should generate the correct url with path param with transformationPostion as query', function () { + it('should generate the correct URL with transformationPosition as query parameter when path is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformationPosition: "query", @@ -114,7 +114,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with src param', function () { + it('should generate the correct URL with a valid src parameter and transformation', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg", transformation: [{ @@ -126,7 +126,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with transformationPostion as query', function () { + it('should generate the correct URL with transformationPosition as query parameter when src is provided', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg", transformationPosition: "query", @@ -139,7 +139,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); }); - it('should generate the correct url with query params properly merged', function () { + it('should merge query parameters correctly in the generated URL', function () { const url = imagekit.url({ src: "https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?t1=v1", queryParameters: { t2: "v2", t3: "v3" }, @@ -153,7 +153,7 @@ describe("URL generation", function () { }); - it('should generate the correct chained transformation', function () { + it('should generate the correct URL with chained transformations', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -168,7 +168,7 @@ describe("URL generation", function () { }); - it('should generate the correct chained transformation url with new undocumented tranforamtion parameter', function () { + it('should generate the correct URL with chained transformations including a new undocumented transformation parameter', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -182,7 +182,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400:rndm_trnsf-abcd/test_path.jpg`); }); - it('Overlay image', function () { + it('should generate the correct URL when overlay image transformation is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -195,7 +195,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,l-image,i-overlay.jpg,w-100,b-10_CDDC39,l-end/test_path.jpg`); }); - it('Overlay image with slash in path', function () { + it('should generate the correct URL when overlay image transformation contains a slash in the overlay path', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -208,7 +208,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,l-image,i-/path/to/overlay.jpg,w-100,b-10_CDDC39,l-end/test_path.jpg`); }); - it('Border', function () { + it('should generate the correct URL when border transformation is applied', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -221,7 +221,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,b-20_FF0000/test_path.jpg`); }); - it('transformation with empty key and empty value', function () { + it('should generate the correct URL when transformation has empty key and value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -229,13 +229,13 @@ describe("URL generation", function () { }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:-/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg`); }); - + /** * Provided to provide support to a new transform without sdk update */ - it('transformation with undefined transform', function () { + it('should generate the correct URL when an undefined transform is provided', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -246,7 +246,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:undefined-transform-true/test_path.jpg`); }); - it('transformation with empty value', function () { + it('should generate the correct URL when transformation key has an empty value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -257,7 +257,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-/test_path.jpg`); }); - it('transformation with - value', function () { + it('should generate the correct URL when transformation key has \'-\' as its value', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -268,7 +268,7 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-contrast/test_path.jpg`); }); - it('skip transformation if it is undefined or null', function () { + it('should skip transformation parameters that are undefined or null', function () { const url = imagekit.url({ path: "/test_path1.jpg", transformation: [{ @@ -281,7 +281,594 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); }); - it('All combined', function () { + it('should skip transformation parameters that are false', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + effectContrast: false + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg/test_path1.jpg`); + }); + + it('should include only the key when transformation value is an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + shadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow/test_path1.jpg`); + }); + + it('should include both key and value when transformation parameter value is provided', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + shadow: "bl-15_st-40_x-10_y-N5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); + }); + + it('should generate the correct URL when trim transformation is set to true as a boolean', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + trim: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); + }); + + it('should generate the correct URL when trim transformation is set to true as a string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + defaultImage: "/test_path.jpg", + trim: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:di-test_path.jpg,t-true/test_path1.jpg`); + }); + + it('should generate the correct URL for AI background removal when set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); + }); + + it('should generate the correct URL for AI background removal when \'true\' is provided as a string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-bgremove/test_path1.jpg`); + }); + + it('should not apply AI background removal when value is not true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackground: "false" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); + }); + + it('should generate the correct URL for external AI background removal when set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); + }); + + it('should generate the correct URL for external AI background removal when \'true\' is provided as a string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: "true" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-removedotbg/test_path1.jpg`); + }); + + it('should not apply external AI background removal when value is not true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiRemoveBackgroundExternal: "false" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path1.jpg`); + }); + + it('should generate the correct URL when gradient transformation is provided as a string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: "ld-top_from-green_to-00FF0010_sp-1" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient-ld-top_from-green_to-00FF0010_sp-1/test_path1.jpg`); + }); + + it('should generate the correct URL when gradient transformation is provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); + }); + + it('should generate the correct URL when gradient transformation is set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + gradient: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-gradient/test_path1.jpg`); + }); + + it('should generate the correct URL when AI drop shadow transformation is set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); + }); + + it('should generate the correct URL when AI drop shadow transformation is provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow/test_path1.jpg`); + }); + + it('should generate the correct URL when AI drop shadow transformation is provided with a specific string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aiDropShadow: "az-45" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-dropshadow-az-45/test_path1.jpg`); + }); + + it('should generate the correct URL when shadow transformation is set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); + }); + + it('should generate the correct URL when shadow transformation is provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow/test_path1.jpg`); + }); + + it('should generate the correct URL when shadow transformation is provided with a specific string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + shadow: "bl-15_st-40_x-10_y-N5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-shadow-bl-15_st-40_x-10_y-N5/test_path1.jpg`); + }); + + it('should generate the correct URL when sharpen transformation is set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); + }); + + it('should generate the correct URL when sharpen transformation is provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen/test_path1.jpg`); + }); + + it('should generate the correct URL when sharpen transformation is provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + sharpen: 10 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-sharpen-10/test_path1.jpg`); + }); + + it('should generate the correct URL when unsharpMask transformation is set to true', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); + }); + + it('should generate the correct URL when unsharpMask transformation is provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm/test_path1.jpg`); + }); + + it('should generate the correct URL when unsharpMask transformation is provided with a string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + unsharpMask: "2-2-0.8-0.024" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:e-usm-2-2-0.8-0.024/test_path1.jpg`); + }); + + it('should generate the correct URL for trim transformation when set to true (boolean)', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: true + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); + }); + + it('should generate the correct URL for trim transformation when provided as an empty string', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: "" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-true/test_path1.jpg`); + }); + + it('should generate the correct URL for trim transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + trim: 5 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:t-5/test_path1.jpg`); + }); + + // Width parameter tests + it('should generate the correct URL for width transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: 400 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); + }); + + it('should generate the correct URL for width transformation when provided with a string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: "400" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-400/test_path1.jpg`); + }); + + it('should generate the correct URL for width transformation when provided with an arithmetic expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + width: "iw_div_2" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:w-iw_div_2/test_path1.jpg`); + }); + + // Height parameter tests + it('should generate the correct URL for height transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: 300 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); + }); + + it('should generate the correct URL for height transformation when provided with a string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: "300" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300/test_path1.jpg`); + }); + + it('should generate the correct URL for height transformation when provided with an arithmetic expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + height: "ih_mul_0.5" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-ih_mul_0.5/test_path1.jpg`); + }); + + // AspectRatio parameter tests + it('should generate the correct URL for aspectRatio transformation when provided with a string value in colon format', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "4:3" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4:3/test_path1.jpg`); + }); + + it('should generate the correct URL for aspectRatio transformation when provided with an alternate underscore format', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "4_3" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-4_3/test_path1.jpg`); + }); + + it('should generate the correct URL for aspectRatio transformation when provided with an arithmetic expression', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + aspectRatio: "iar_div_2" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:ar-iar_div_2/test_path1.jpg`); + }); + + // Background parameter tests + it('should generate the correct URL for background transformation when provided with a solid color', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "FF0000" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-FF0000/test_path1.jpg`); + }); + + it('should generate the correct URL for background transformation when provided with the blurred option', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "blurred" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-blurred/test_path1.jpg`); + }); + + it('should generate the correct URL for background transformation when provided with the genfill option', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + background: "genfill" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:bg-genfill/test_path1.jpg`); + }); + + // Crop parameter tests + it('should generate the correct URL for crop transformation when provided with force value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + crop: "force" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:c-force/test_path1.jpg`); + }); + + it('should generate the correct URL for crop transformation when provided with at_max value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + crop: "at_max" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:c-at_max/test_path1.jpg`); + }); + + // CropMode parameter tests + it('should generate the correct URL for cropMode transformation when provided with pad_resize', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + cropMode: "pad_resize" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:cm-pad_resize/test_path1.jpg`); + }); + + it('should generate the correct URL for cropMode transformation when provided with extract value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + cropMode: "extract" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:cm-extract/test_path1.jpg`); + }); + + // Focus parameter tests + it('should generate the correct URL for focus transformation when provided with a string value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + focus: "center" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:fo-center/test_path1.jpg`); + }); + + it('should generate the correct URL for focus transformation when face detection is specified', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + focus: "face" + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:fo-face/test_path1.jpg`); + }); + + // Quality parameter test + it('should generate the correct URL for quality transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + quality: 80 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:q-80/test_path1.jpg`); + }); + + // Coordinate parameters tests + it('should generate the correct URL for x coordinate transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + x: 10 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:x-10/test_path1.jpg`); + }); + + it('should generate the correct URL for y coordinate transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + y: 20 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:y-20/test_path1.jpg`); + }); + + it('should generate the correct URL for xCenter transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + xCenter: 30 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:xc-30/test_path1.jpg`); + }); + + it('should generate the correct URL for yCenter transformation when provided with a number value', function () { + const url = imagekit.url({ + path: "/test_path1.jpg", + transformation: [{ + yCenter: 40 + }] + }) + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:yc-40/test_path1.jpg`); + }); + + // This is done just to test how SDK constructs URL, the actual transformation is not valid. + it('Including deprecated properties', function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ @@ -317,8 +904,68 @@ describe("URL generation", function () { }] }) - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast-true,e-grayscale-true,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,e-sharpen-10,e-usm-2-2-0.8-0.024,e-contrast,e-grayscale,e-shadow-bl-15_st-40_x-10_y-N5,e-gradient-from-red_to-white,orig-true,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); }); -}); + // This is done just to test how SDK constructs URL, the actual transformation is not valid + it('should generate the correct URL when comprehensive transformations, including video and AI transformations, are applied', function () { + const url = imagekit.url({ + path: "/test_path.jpg", + transformation: [{ + height: 300, + width: 400, + aspectRatio: '4-3', + quality: 40, + crop: 'force', + cropMode: 'extract', + focus: 'left', + format: 'jpeg', + radius: 50, + bg: "A94D34", + border: "5-A94D34", + rotation: 90, + blur: 10, + named: "some_name", + progressive: true, + lossless: true, + trim: 5, + metadata: true, + colorProfile: true, + defaultImage: "/folder/file.jpg/", //trailing and leading slash case + dpr: 3, + x: 10, + y: 20, + xCenter: 30, + yCenter: 40, + flip: "h", + opacity: 0.8, + zoom: 2, + // Video transformations + videoCodec: "h264", + audioCodec: "aac", + startOffset: 5, + endOffset: 15, + duration: 10, + streamingResolutions: ["1440", "1080"], + // AI transformations + grayscale: true, + aiUpscale: true, + aiRetouch: true, + aiVariation: true, + aiDropShadow: true, + aiChangeBackground: "prompt-car", + aiRemoveBackground: true, + contrastStretch: true, + shadow: 'bl-15_st-40_x-10_y-N5', + sharpen: 10, + unsharpMask: "2-2-0.8-0.024", + gradient: 'from-red_to-white', + original: true, + page: "2_4", + raw: "h-200,w-300,l-image,i-logo.png,l-end" + }] + }) + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end/test_path.jpg`); + }); +});