From 751bf46c71c15447dd1b4e0f7cb2bfd3f03b0d5f Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 21 Mar 2025 18:05:22 +0700 Subject: [PATCH 01/29] add type defination for overlay --- src/interfaces/Transformation.ts | 129 ++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 1 deletion(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index a963f8f..b5d942f 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -1,6 +1,6 @@ export type TransformationPosition = "path" | "query"; -type StreamingResolution = "240" | "360" | "480" | "720" | "1080" | "1440" | "2160"; +export 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. @@ -421,6 +421,133 @@ export interface Transformation { * @deprecated Use `gradient` instead. */ effectGradient?: string; + + /** + * Overlay to be applied on the parent image or video. ImageKit allows you to overlay images, text, videos, subtitles, and solid colors on the parent image or video. + * + * {@link https://imagekit.io/docs/transformations#overlay-using-layers} + */ + overlay?: Overlay; +} + +export interface OverlayPosition { + /** + * `x` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bw_mul_0.4`, or `bw_sub_cw`. + * + * It maps to `lx` in the URL. + * + * Learn about [Arthmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + */ + x?: number | string; + + /** + * `y` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bh_mul_0.4`, or `bh_sub_ch`. + * + * It maps to `ly` in the URL. + * + * Learn about [Arthmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + */ + y?: number | string; + + /** + * Position of the overlay in relation to the parent image or video. The overlay can be positioned at the center, top, left, bottom, right, top_left, top_right, bottom_left, or bottom_right of the parent image or video. + * + * This maps to `lfo` in the URL. + */ + focus?: `center` | `top` | `left` | `bottom` | `right` | `top_left` | `top_right` | `bottom_left` | `bottom_right`; +} + +export interface OverlayTiming { + /** + * Start time of the base video in seconds when the layer should appear. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * + * It maps to `lso` in the URL. + */ + start?: number | string; + + /** + * Duration in seconds during which layer should appear on the base video. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * + * It maps to `ldu` in the URL. + */ + duration?: number | string; + + /** + * End time of the base video when this layer should disappear. In case both `end` and `duration` are present, `duration` is ignored. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * + * It maps to `leo` in the URL. + */ + end?: number | string; } +interface BaseOverlay { + /** + * Positioning relative to parent. Accepts a JSON object with `x` and `y` (or `focus`) properties. + * + * {@link https://imagekit.io/docs/transformations#position-of-layer} + */ + position?: OverlayPosition; + + /** + * Timing (only valid if parent/base is a video). Accepts a JSON object with `start` (lso), `end` (leo), and `duration` (ldu) properties. + * + * {@link https://imagekit.io/docs/transformations#position-of-layer} + */ + timing?: OverlayTiming; + + /** + * Array of transformations to be applied to this overlay. Support of supported transformations also depends on the type of base and overlay asset. Refer to the docs below for more information. + */ + transformations?: Transformation[]; +} + + +export interface TextOverlay extends BaseOverlay { + type: "text"; + + /** + * Text to be displayed in the overlay. The SDK will automatically handle special characters and URL encoding for you. + */ + text: string; +} + +export interface ImageOverlay extends BaseOverlay { + type: "image"; + + /** + * Relative path to the image to be used as an overlay. + */ + input: string; +} + +export interface VideoOverlay extends BaseOverlay { + type: "video"; + /** + * Relative path to the video to be used as an overlay. + */ + input: string; +} + +export interface SubtitleOverlay extends BaseOverlay { + type: "subtitle"; + /** + * Relative path to the subtitle file to be used as an overlay. + */ + input: string; +} + +export interface SolidColorOverlay extends BaseOverlay { + type: "solidColor"; + /** + * It is used to specify the color of the block in RGB Hex Code (e.g. `FF0000`), or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicates the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. + */ + color: string; +} + +export type Overlay = + | TextOverlay + | ImageOverlay + | VideoOverlay + | SubtitleOverlay + | SolidColorOverlay; From 09b31c4ff1298d8490f448b7e60ffcf8ff1aa039 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 21 Mar 2025 18:35:38 +0700 Subject: [PATCH 02/29] Improved JSDocs --- src/interfaces/Transformation.ts | 332 ++++++++++++++++--------------- 1 file changed, 171 insertions(+), 161 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index b5d942f..a0e418f 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -3,385 +3,382 @@ export type TransformationPosition = "path" | "query"; export 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. + * 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} + * {@link https://imagekit.io/docs/transformations|Transformations Documentation} */ 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"`). + * Specifies the width of the output. If a value between 0 and 1 is provided, it is treated as a percentage + * (e.g., `0.4` represents 40% of the original width). You can also supply arithmetic expressions (e.g., `iw_div_2`). * - * {@link https://imagekit.io/docs/image-resize-and-crop#width---w} + * {@link https://imagekit.io/docs/image-resize-and-crop#width---w|Image Resize and Crop - Width} */ 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"`). + * Specifies the height of the output. If a value between 0 and 1 is provided, it is treated as a percentage + * (e.g., `0.5` represents 50% of the 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} + * {@link https://imagekit.io/docs/image-resize-and-crop#height---h|Image Resize and Crop - Height} */ 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"`. + * Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with either width or height (but not both). + * For example: aspectRatio = `4:3`, `4_3`, or an expression like `iar_div_2`. * - * {@link https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar} + * {@link https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar|Image Resize and Crop - Aspect Ratio} */ 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"`. + * Specifies the background to be used in conjunction with certain cropping strategies when resizing an image. + * - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. * - * {@link https://imagekit.io/docs/effects-and-enhancements#solid-color-background} + * {@link https://imagekit.io/docs/effects-and-enhancements#solid-color-background|Effects and Enhancements - Solid Color Background} * - * - A blurred background: `"blurred"`, `"blurred_25_N15"`, etc. + * - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. * - * {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background} + * {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background|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}]`. + * - Expand the image boundaries using generative fill: `genfill`. Optionally, control the background scene by passing a text prompt: + * `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. * - * {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill} + * {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill|AI Transformations - Generative Fill Background} */ 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"`. + * Adds a border to the output media. Accepts a string in the format `_` + * (e.g., `5_FFF000` for a 5px yellow border), or an expression like `ih_div_20_FF00FF`. * - * {@link https://imagekit.io/docs/effects-and-enhancements#border---b} + * {@link https://imagekit.io/docs/effects-and-enhancements#border---b|Effects and Enhancements - Border} */ border?: string; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus|Image Resize and Crop - Crop Modes} */ crop?: "force" | "at_max" | "at_max_enlarge" | "at_least" | "maintain_ratio"; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus} + * {@link https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus|Image Resize and Crop - Crop Modes} */ cropMode?: "pad_resize" | "extract" | "pad_extract"; /** - * Possible values 0.1 to 5 or `auto` for automatic DPR calculation. + * Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio (DPR) calculation. * - * {@link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr} + * {@link https://imagekit.io/docs/image-resize-and-crop#dpr---dpr|Image Resize and Crop - 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 + * This parameter can be used with pad resize, maintain ratio, or extract crop to modify the padding or cropping behavior. * - * {@link https://imagekit.io/docs/image-resize-and-crop#focus---fo} + * {@link https://imagekit.io/docs/image-resize-and-crop#focus---fo|Image Resize and Crop - Focus} */ 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. + * Specifies the quality of the output image for lossy formats such as JPEG, WebP, and AVIF. + * A higher quality value results in a larger file size with better quality, while a lower value produces a smaller file size with reduced quality. * - * {@link https://imagekit.io/docs/image-optimization#quality---q} + * {@link https://imagekit.io/docs/image-optimization#quality---q|Image Optimization - Quality} */ quality?: number; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates|Image Resize and Crop - Focus Using Cropped Image Coordinates} */ x?: number | string; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates|Image Resize and Crop - Focus Using Cropped Image Coordinates} */ xCenter?: number | string; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates|Image Resize and Crop - Focus Using Cropped Image Coordinates} */ y?: number | string; /** - * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates} + * {@link https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates|Image Resize and Crop - 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. + * Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, `mp4`, or `auto`. + * You can also pass `orig` for images to return the original format. + * ImageKit automatically delivers images and videos in the optimal format based on device support unless overridden by the dashboard settings or the format parameter. * - * 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}} + * {@link https://imagekit.io/docs/image-optimization#format---f|Image Optimization - Format} & {@link https://imagekit.io/docs/video-optimization#format---f|Video Optimization - Format} */ format?: "auto" | "webp" | "jpg" | "jpeg" | "png" | "gif" | "svg" | "mp4" | "webm" | "avif" | "orig"; /** - * Video codec, e.g., `"h264"`, `"vp9"`, `"av1"` or `"none"`. + * Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. * - * {@link https://imagekit.io/docs/video-optimization#video-codec---vc} + * {@link https://imagekit.io/docs/video-optimization#video-codec---vc|Video Optimization - Video Codec} */ videoCodec?: "h264" | "vp9" | "av1" | "none"; /** - * Audio codec, e.g., `"aac"`, `"opus"` or `"none"`. + * Specifies the audio codec, e.g., `aac`, `opus`, or `none`. * - * {@link https://imagekit.io/docs/video-optimization#audio-codec---ac} + * {@link https://imagekit.io/docs/video-optimization#audio-codec---ac|Video Optimization - Audio Codec} */ audioCodec?: "aac" | "opus" | "none"; /** - * Corner radius for rounded corners (e.g., `20`) or `"max"` for circular/oval shapes. + * Specifies the corner radius for rounded corners (e.g., 20) or `max` for circular/oval shapes. * - * {@link https://imagekit.io/docs/effects-and-enhancements#radius---r} + * {@link https://imagekit.io/docs/effects-and-enhancements#radius---r|Effects and Enhancements - Radius} */ 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. + * Specifies the rotation angle in degrees. Positive values rotate the image clockwise; you can also use, for example, `N40` for counterclockwise rotation + * or `auto` to use the orientation specified in the image's EXIF data. + * For videos, only the following values are supported: 0, 90, 180, 270, or 360. * - * {@link https://imagekit.io/docs/effects-and-enhancements#rotate---rt} + * {@link https://imagekit.io/docs/effects-and-enhancements#rotate---rt|Effects and Enhancements - Rotate} */ rotation?: number | string; /** - * Gaussian blur level. Ranges 1–100 or an expression like `"bl-10"`. Possible values include integers between 1 and 100. + * Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, or an expression like `bl-10`. * - * {@link https://imagekit.io/docs/effects-and-enhancements#blur---bl} + * {@link https://imagekit.io/docs/effects-and-enhancements#blur---bl|Effects and Enhancements - Blur} */ blur?: number; /** - * {@link https://imagekit.io/docs/transformations#named-transformations} + * {@link https://imagekit.io/docs/transformations#named-transformations|Transformations - Named Transformations} */ named?: string; /** - * Fallback image if the resource is not found, e.g., a URL or path. + * Specifies a fallback image if the resource is not found, e.g., a URL or file path. * - * {@link https://imagekit.io/docs/image-transformation#default-image---di} + * {@link https://imagekit.io/docs/image-transformation#default-image---di|Image Transformation - Default Image} */ 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) + * Flips or mirrors an image either horizontally, vertically, or both. + * Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. * - * {@link https://imagekit.io/docs/effects-and-enhancements#flip---fl} + * {@link https://imagekit.io/docs/effects-and-enhancements#flip---fl|Effects and Enhancements - Flip} */ flip?: "h" | "v" | "h_v" | "v_h"; /** - * Whether to serve the original file without any transformations if `true`. + * If set to true, serves the original file without applying any transformations. * - * {@link https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true} + * {@link https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true|Core Delivery Features - Deliver Original File As Is} */ original?: boolean; /** - * Start offset (in seconds) for trimming videos. e.g., `5` or `"10.5"`. - * Also supports arithmetic expressions. + * Specifies the start offset (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Arithmetic expressions are also supported. * - * {@link https://imagekit.io/docs/trim-videos#start-offset---so} + * {@link https://imagekit.io/docs/trim-videos#start-offset---so|Trim Videos - Start Offset} */ 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. + * Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to define a time window. Arithmetic expressions are supported. * - * {@link https://imagekit.io/docs/trim-videos#end-offset---eo} + * {@link https://imagekit.io/docs/trim-videos#end-offset---eo|Trim Videos - End Offset} */ 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. + * Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to indicate the length from the start offset. Arithmetic expressions are supported. * - * {@link https://imagekit.io/docs/trim-videos#duration---du} + * {@link https://imagekit.io/docs/trim-videos#duration---du|Trim Videos - Duration} */ duration?: number | string; /** - * Provide an array of resolutions (e.g. `["240", "360", "480", "720", "1080"]`). + * An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, `480`, `720`, `1080`]. * - * {@link https://imagekit.io/docs/adaptive-bitrate-streaming} + * {@link https://imagekit.io/docs/adaptive-bitrate-streaming|Adaptive Bitrate Streaming} */ streamingResolutions?: StreamingResolution[]; /** - * Enable grayscale effect for images. + * Enables a grayscale effect for images. * - * {@link https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale} + * {@link https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale|Effects and Enhancements - Grayscale} */ grayscale?: true; /** - * Upscale images beyond their original dimensions with AI. + * Upscales images beyond their original dimensions using AI. * - * {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale} + * {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale|AI Transformations - Upscale} */ aiUpscale?: true /** - * Retouch (AI-based) for improving faces or product shots. + * Performs AI-based retouching to improve faces or product shots. * - * {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch} + * {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch|AI Transformations - 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. + * Generates a variation of an image using AI. This produces a new image with slight variations from the original, + * such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. * - * {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar} + * {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar|AI Transformations - Generate Variations} */ 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. + * Adds an AI-based drop shadow around a foreground object on a transparent or removed background. + * Optionally, control the direction, elevation, and saturation of the light source (e.g., `az-45` to change light direction). + * Pass true for the default drop shadow, or provide a string for a custom drop shadow. * - * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow} + * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow|AI Transformations - Drop Shadow} */ 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]`. + * Uses AI to change the background. Provide a text prompt or a 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} + * {@link https://imagekit.io/docs/ai-transformations#change-background-e-changebg|AI Transformations - Change Background} */ aiChangeBackground?: string; /** - * ImageKit’s in-house background removal. + * Applies ImageKit’s in-house background removal. * - * {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove} + * {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove|AI Transformations - Background Removal} */ aiRemoveBackground?: true /** - * Use third-party background removal. Use `aiRemoveBackground` - ImageKit's in-house background removal which is 90% cheaper. + * Uses third-party background removal. + * Note: It is recommended to use aiRemoveBackground, ImageKit’s in-house solution, which is more cost-effective. * - * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg} + * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg|AI Transformations - External Background Removal} */ aiRemoveBackgroundExternal?: true /** - * Auto-enhance contrast for an image (contrast stretch). + * Automatically enhances the contrast of an image (contrast stretch). * - * {@link https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast} + * {@link https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast|Effects and Enhancements - Contrast Stretch} */ contrastStretch?: true /** - * This adds a shadow under solid objects in an input image with a transparent background. Check `eDropshadow` for AI-based shadows. + * Adds a shadow beneath solid objects in an image with a transparent background. + * For AI-based drop shadows, refer to aiDropShadow. + * Pass true for a default shadow, or provide a string for a custom shadow. * - * Pass `true` for default shadow or a string for custom shadow. - * - * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow} + * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow|Effects and Enhancements - 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. + * Sharpens the input image, highlighting edges and finer details. + * Pass true for default sharpening, or provide a numeric value for custom sharpening. * - * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen} + * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen|Effects and Enhancements - 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. + * Applies Unsharp Masking (USM), an image sharpening technique. + * Pass true for a default unsharp mask, or provide a string for a custom unsharp mask. * - * 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} + * {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm|Effects and Enhancements - Unsharp Mask} */ 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. + * Creates a linear gradient with two colors. Pass true for a default gradient, or provide a string for a custom gradient. * - * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient} + * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient|Effects and Enhancements - 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. + * Specifies whether the output JPEG image should be rendered progressively. Progressive loading begins with a low-quality, + * pixelated version of the full image, which gradually improves to provide a faster perceived load time. * - * {@link https://imagekit.io/docs/image-optimization#progressive-image---pr} + * {@link https://imagekit.io/docs/image-optimization#progressive-image---pr|Image Optimization - Progressive Image} */ progressive?: boolean; /** - * Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. + * Specifies whether the output image (in JPEG or PNG) should be compressed losslessly. * - * {@link https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo} + * {@link https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo|Image Optimization - Lossless Compression} */ lossless?: boolean /** - * It specifies whether the output image should contain the color profile initially available with the original image. + * Indicates whether the output image should retain the original color profile. * - * {@link https://imagekit.io/docs/image-optimization#color-profile---cp} + * {@link https://imagekit.io/docs/image-optimization#color-profile---cp|Image Optimization - Color Profile} */ colorProfile?: boolean; /** - * By default, ImageKit removes all metadata as part of automatic image compression. Set this to `true` to preserve metadata. + * By default, ImageKit removes all metadata during automatic image compression. + * Set this to true to preserve metadata. * - * {@link https://imagekit.io/docs/image-optimization#image-metadata---md} + * {@link https://imagekit.io/docs/image-optimization#image-metadata---md|Image Optimization - Image Metadata} */ metadata?: boolean; /** - * It is used to specify the opacity level of the output image. + * Specifies the opacity level of the output image. * - * {@link https://imagekit.io/docs/effects-and-enhancements#opacity---o} + * {@link https://imagekit.io/docs/effects-and-enhancements#opacity---o|Effects and Enhancements - Opacity} */ 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. + * Useful for images with a solid or nearly solid background and a central object. This parameter trims the background, + * leaving only the central object in the output image. * - * {@link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t} + * {@link https://imagekit.io/docs/effects-and-enhancements#trim-edges---t|Effects and Enhancements - Trim Edges} */ 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- + * Accepts a numeric value that determines how much to zoom in or out of the cropped area. + * It should be used in conjunction with fo-face or fo-. * - * {@link https://imagekit.io/docs/image-resize-and-crop#zoom---z} + * {@link https://imagekit.io/docs/image-resize-and-crop#zoom---z|Image Resize and Crop - Zoom} */ 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`. + * Extracts a specific page or frame from multi-page or layered files (PDF, PSD, AI). + * For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the 2nd and 3rd layers), + * or by name (e.g., `name-layer-4` for a PSD layer). * - * {@link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files} + * {@link https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files|Vector and Animated Images - Thumbnail Extraction} */ page?: number | string; /** - * Pass any transformation that is not directly supported by the SDK. This transformation is passed as it is in the URL. + * Pass any transformation not directly supported by the SDK. + * This transformation string is appended to the URL as provided. */ raw?: string; @@ -423,59 +420,67 @@ export interface Transformation { effectGradient?: string; /** - * Overlay to be applied on the parent image or video. ImageKit allows you to overlay images, text, videos, subtitles, and solid colors on the parent image or video. + * Specifies an overlay to be applied on the parent image or video. + * ImageKit supports overlays including images, text, videos, subtitles, and solid colors. * - * {@link https://imagekit.io/docs/transformations#overlay-using-layers} + * {@link https://imagekit.io/docs/transformations#overlay-using-layers|Transformations - Overlay Using Layers} */ overlay?: Overlay; } export interface OverlayPosition { /** - * `x` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bw_mul_0.4`, or `bw_sub_cw`. - * - * It maps to `lx` in the URL. + * Specifies the x-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. + * It also accepts arithmetic expressions such as `bw_mul_0.4` or `bw_sub_cw`. + * Maps to `lx` in the URL. * - * Learn about [Arthmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + * Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) */ x?: number | string; /** - * `y` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bh_mul_0.4`, or `bh_sub_ch`. + * Specifies the y-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. + * It also accepts arithmetic expressions such as `bh_mul_0.4` or `bh_sub_ch`. + * Maps to `ly` in the URL. * - * It maps to `ly` in the URL. - * - * Learn about [Arthmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + * Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) */ y?: number | string; /** - * Position of the overlay in relation to the parent image or video. The overlay can be positioned at the center, top, left, bottom, right, top_left, top_right, bottom_left, or bottom_right of the parent image or video. - * - * This maps to `lfo` in the URL. + * Specifies the position of the overlay relative to the parent image or video. + * Acceptable values: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. + * Maps to `lfo` in the URL. */ focus?: `center` | `top` | `left` | `bottom` | `right` | `top_left` | `top_right` | `bottom_left` | `bottom_right`; } export interface OverlayTiming { /** - * Start time of the base video in seconds when the layer should appear. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * Specifies the start time (in seconds) for when the overlay should appear on the base video. + * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. * - * It maps to `lso` in the URL. + * Maps to `lso` in the URL. */ start?: number | string; /** - * Duration in seconds during which layer should appear on the base video. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * Specifies the duration (in seconds) during which the overlay should appear on the base video. + * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. * - * It maps to `ldu` in the URL. + * Maps to `ldu` in the URL. */ duration?: number | string; /** - * End time of the base video when this layer should disappear. In case both `end` and `duration` are present, `duration` is ignored. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). + * Specifies the end time (in seconds) for when the overlay should disappear from the base video. + * If both end and duration are provided, duration is ignored. + * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. * - * It maps to `leo` in the URL. + * Maps to `leo` in the URL. */ end?: number | string; } @@ -483,21 +488,24 @@ export interface OverlayTiming { interface BaseOverlay { /** - * Positioning relative to parent. Accepts a JSON object with `x` and `y` (or `focus`) properties. + * Specifies the overlay's position relative to the parent asset. + * Accepts a JSON object with `x` and `y` (or `focus`) properties. * - * {@link https://imagekit.io/docs/transformations#position-of-layer} + * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} */ position?: OverlayPosition; /** - * Timing (only valid if parent/base is a video). Accepts a JSON object with `start` (lso), `end` (leo), and `duration` (ldu) properties. + * Specifies timing information for the overlay (only applicable if the base asset is a video). + * Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties. * - * {@link https://imagekit.io/docs/transformations#position-of-layer} + * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} */ timing?: OverlayTiming; /** - * Array of transformations to be applied to this overlay. Support of supported transformations also depends on the type of base and overlay asset. Refer to the docs below for more information. + * An array of transformations to be applied to the overlay. + * The supported transformations depend on the type of the base and overlay asset. */ transformations?: Transformation[]; } @@ -507,7 +515,8 @@ export interface TextOverlay extends BaseOverlay { type: "text"; /** - * Text to be displayed in the overlay. The SDK will automatically handle special characters and URL encoding for you. + * Specifies the text to be displayed in the overlay. + * The SDK automatically handles special characters and URL encoding. */ text: string; } @@ -516,7 +525,7 @@ export interface ImageOverlay extends BaseOverlay { type: "image"; /** - * Relative path to the image to be used as an overlay. + * Specifies the relative path to the image used as an overlay. */ input: string; } @@ -524,7 +533,7 @@ export interface ImageOverlay extends BaseOverlay { export interface VideoOverlay extends BaseOverlay { type: "video"; /** - * Relative path to the video to be used as an overlay. + * Specifies the relative path to the video used as an overlay. */ input: string; } @@ -532,7 +541,7 @@ export interface VideoOverlay extends BaseOverlay { export interface SubtitleOverlay extends BaseOverlay { type: "subtitle"; /** - * Relative path to the subtitle file to be used as an overlay. + * Specifies the relative path to the subtitle file used as an overlay. */ input: string; } @@ -540,7 +549,8 @@ export interface SubtitleOverlay extends BaseOverlay { export interface SolidColorOverlay extends BaseOverlay { type: "solidColor"; /** - * It is used to specify the color of the block in RGB Hex Code (e.g. `FF0000`), or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicates the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. + * Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name (e.g., `red`). + * If an 8-character value is provided, the last two characters represent the opacity level (from `00` for 0.00 to `99` for 0.99). */ color: string; } From 9769f409e1ec84ea37e45c1fabc746f6164e5392 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 21 Mar 2025 18:44:10 +0700 Subject: [PATCH 03/29] fix: update test script to include all test files in subdirectories and split the test script into multiple test scripts --- package.json | 2 +- test/{url-generation.js => url-generation/basic.js} | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename test/{url-generation.js => url-generation/basic.js} (99%) diff --git a/package.json b/package.json index 1938f2e..1bbfb44 100644 --- a/package.json +++ b/package.json @@ -43,7 +43,7 @@ "dev": "rollup -c -w", "export-types": "tsc", "build": "rm -rf dist*;rollup -c && yarn export-types", - "test": "NODE_ENV=test nyc ./node_modules/mocha/bin/mocha test/*.js", + "test": "NODE_ENV=test nyc ./node_modules/mocha/bin/mocha \"test/**/*.js\"", "startSampleApp": "yarn build && cd samples/sample-app/ && yarn install && node index.js", "report-coverage": "codecov" }, diff --git a/test/url-generation.js b/test/url-generation/basic.js similarity index 99% rename from test/url-generation.js rename to test/url-generation/basic.js index 40c7e38..739f240 100644 --- a/test/url-generation.js +++ b/test/url-generation/basic.js @@ -1,9 +1,9 @@ const chai = require("chai"); -const pkg = require("../package.json"); +const pkg = require("../../package.json"); global.FormData = require('formdata-node'); const expect = chai.expect; -const initializationParams = require("./data").initializationParams -import ImageKit from "../src/index"; +const initializationParams = require("../data").initializationParams +import ImageKit from "../../src/index"; describe("URL generation", function () { From 2298a72779c3ddf71174f07c6764a83b4aed9748 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 21 Mar 2025 20:15:57 +0700 Subject: [PATCH 04/29] add transformation types for different type of overlays --- src/interfaces/Transformation.ts | 235 +++++++++++++++++++++++++------ 1 file changed, 192 insertions(+), 43 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index a0e418f..4909bf5 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -13,7 +13,7 @@ export interface Transformation { * Specifies the width of the output. If a value between 0 and 1 is provided, it is treated as a percentage * (e.g., `0.4` represents 40% of the original width). You can also supply arithmetic expressions (e.g., `iw_div_2`). * - * {@link https://imagekit.io/docs/image-resize-and-crop#width---w|Image Resize and Crop - Width} + * Width transformation - {@link https://imagekit.io/docs/image-resize-and-crop#width---w|Images} | {@link https://imagekit.io/docs/video-resize-and-crop#width---w|Videos} */ width?: number | string; @@ -21,7 +21,7 @@ export interface Transformation { * Specifies the height of the output. If a value between 0 and 1 is provided, it is treated as a percentage * (e.g., `0.5` represents 50% of the 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|Image Resize and Crop - Height} + * Height transformation - {@link https://imagekit.io/docs/image-resize-and-crop#height---h|Images} | {@link https://imagekit.io/docs/video-resize-and-crop#height---h|Videos} */ height?: number | string; @@ -43,7 +43,7 @@ export interface Transformation { * * {@link https://imagekit.io/docs/effects-and-enhancements#blurred-background|Effects and Enhancements - Blurred Background} * - * - Expand the image boundaries using generative fill: `genfill`. Optionally, control the background scene by passing a text prompt: + * - Expand the image boundaries using generative fill: `genfill`. Not supported inside overlay. Optionally, control the background scene by passing a text prompt: * `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. * * {@link https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill|AI Transformations - Generative Fill Background} @@ -222,14 +222,14 @@ export interface Transformation { grayscale?: true; /** - * Upscales images beyond their original dimensions using AI. + * Upscales images beyond their original dimensions using AI. Not supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#upscale-e-upscale|AI Transformations - Upscale} */ aiUpscale?: true /** - * Performs AI-based retouching to improve faces or product shots. + * Performs AI-based retouching to improve faces or product shots. Not supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#retouch-e-retouch|AI Transformations - Retouch} */ @@ -237,7 +237,7 @@ export interface Transformation { /** * Generates a variation of an image using AI. This produces a new image with slight variations from the original, - * such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. + * such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. Not supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar|AI Transformations - Generate Variations} */ @@ -246,7 +246,8 @@ export interface Transformation { /** * Adds an AI-based drop shadow around a foreground object on a transparent or removed background. * Optionally, control the direction, elevation, and saturation of the light source (e.g., `az-45` to change light direction). - * Pass true for the default drop shadow, or provide a string for a custom drop shadow. + * Pass `true` for the default drop shadow, or provide a string for a custom drop shadow. + * Supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow|AI Transformations - Drop Shadow} */ @@ -255,6 +256,7 @@ export interface Transformation { /** * Uses AI to change the background. Provide a text prompt or a base64-encoded prompt, * e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + * Not supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#change-background-e-changebg|AI Transformations - Change Background} */ @@ -262,6 +264,7 @@ export interface Transformation { /** * Applies ImageKit’s in-house background removal. + * Supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove|AI Transformations - Background Removal} */ @@ -270,6 +273,7 @@ export interface Transformation { /** * Uses third-party background removal. * Note: It is recommended to use aiRemoveBackground, ImageKit’s in-house solution, which is more cost-effective. + * Supported inside overlay. * * {@link https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg|AI Transformations - External Background Removal} */ @@ -285,7 +289,7 @@ export interface Transformation { /** * Adds a shadow beneath solid objects in an image with a transparent background. * For AI-based drop shadows, refer to aiDropShadow. - * Pass true for a default shadow, or provide a string for a custom shadow. + * Pass `true` for a default shadow, or provide a string for a custom shadow. * * {@link https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow|Effects and Enhancements - Shadow} */ @@ -293,7 +297,7 @@ export interface Transformation { /** * Sharpens the input image, highlighting edges and finer details. - * Pass true for default sharpening, or provide a numeric value for custom sharpening. + * Pass `true` for default sharpening, or provide a numeric value for custom sharpening. * * {@link https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen|Effects and Enhancements - Sharpen} */ @@ -301,14 +305,14 @@ export interface Transformation { /** * Applies Unsharp Masking (USM), an image sharpening technique. - * Pass true for a default unsharp mask, or provide a string for a custom unsharp mask. + * Pass `true` for a default unsharp mask, or provide a string for a custom unsharp mask. * * {@link https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm|Effects and Enhancements - Unsharp Mask} */ unsharpMask?: true | string; /** - * Creates a linear gradient with two colors. Pass true for a default gradient, or provide a string for a custom gradient. + * Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. * * {@link https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient|Effects and Enhancements - Gradient} */ @@ -428,6 +432,31 @@ export interface Transformation { overlay?: Overlay; } +export type Overlay = + | TextOverlay + | ImageOverlay + | VideoOverlay + | SubtitleOverlay + | SolidColorOverlay + +export interface BaseOverlay { + /** + * Specifies the overlay's position relative to the parent asset. + * Accepts a JSON object with `x` and `y` (or `focus`) properties. + * + * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} + */ + position?: OverlayPosition; + + /** + * Specifies timing information for the overlay (only applicable if the base asset is a video). + * Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties. + * + * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} + */ + timing?: OverlayTiming; +} + export interface OverlayPosition { /** * Specifies the x-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. @@ -485,32 +514,6 @@ export interface OverlayTiming { end?: number | string; } - -interface BaseOverlay { - /** - * Specifies the overlay's position relative to the parent asset. - * Accepts a JSON object with `x` and `y` (or `focus`) properties. - * - * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} - */ - position?: OverlayPosition; - - /** - * Specifies timing information for the overlay (only applicable if the base asset is a video). - * Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties. - * - * {@link https://imagekit.io/docs/transformations#position-of-layer|Transformations - Position of Layer} - */ - timing?: OverlayTiming; - - /** - * An array of transformations to be applied to the overlay. - * The supported transformations depend on the type of the base and overlay asset. - */ - transformations?: Transformation[]; -} - - export interface TextOverlay extends BaseOverlay { type: "text"; @@ -519,6 +522,11 @@ export interface TextOverlay extends BaseOverlay { * The SDK automatically handles special characters and URL encoding. */ text: string; + + /** + * Control styling of the text overlay. + */ + transformations?: TextOverlayTransformation[]; } export interface ImageOverlay extends BaseOverlay { @@ -528,6 +536,13 @@ export interface ImageOverlay extends BaseOverlay { * Specifies the relative path to the image used as an overlay. */ input: string; + + /** + * List of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. + * + * {@link https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay|Video} + */ + transformations?: Transformation[]; } export interface VideoOverlay extends BaseOverlay { @@ -536,6 +551,13 @@ export interface VideoOverlay extends BaseOverlay { * Specifies the relative path to the video used as an overlay. */ input: string; + + /** + * List of transformations to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. + * + * {@link https://imagekit.io/docs/video-transformation|Video Transformations} + */ + transformations?: Transformation[]; } export interface SubtitleOverlay extends BaseOverlay { @@ -544,6 +566,13 @@ export interface SubtitleOverlay extends BaseOverlay { * Specifies the relative path to the subtitle file used as an overlay. */ input: string; + + /** + * Control styling of the subtitle. + * + * {@link https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer|Styling subtitles} + */ + transformations?: SubtitleOverlayTransformation[]; } export interface SolidColorOverlay extends BaseOverlay { @@ -553,11 +582,131 @@ export interface SolidColorOverlay extends BaseOverlay { * If an 8-character value is provided, the last two characters represent the opacity level (from `00` for 0.00 to `99` for 0.99). */ color: string; + + /** + * Control width and height of the solid color overlay. Supported transformations depend on the base/parent asset. + * + * {@link https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay|Video} + */ + transformations?: SolidColorOverlayTransformation[]; } -export type Overlay = - | TextOverlay - | ImageOverlay - | VideoOverlay - | SubtitleOverlay - | SolidColorOverlay; +export type TextOverlayTransformation = { + /** + * Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `backgroundColor`. + */ + width?: number | string; + + /** + * Specifies the font size of the overlaid text. Accepts a numeric value, a percentage, or an arithmetic expression. + */ + fontSize?: number | string; + + /** + * Specifies the font family of the overlaid text. Choose from the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) or use a [custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). + */ + fontFamily?: string; + + /** + * Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. + */ + fontColor?: string; + + /** + * Specifies the inner alignment of the text when width is more than the text length. + * Supported values: `left`, `right`, and `center` (default). + */ + innerAlignment?: "left" | "right" | "center"; + + /** + * Specifies the padding around the overlaid text. + * Can be provided as a single positive integer or multiple values separated by underscores (following CSS shorthand order). + * Arithmetic expressions are also accepted. + */ + padding?: number | string; + + /** + * Specifies the transparency level of the text overlay. Accepts integers from `1` to `9`. + */ + alpha?: number; + + /** + * Specifies the typography style of the text. + * Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. + */ + typography?: "b" | "i" | "b_i"; + + /** + * Specifies the background color of the text overlay. + * Accepts an RGB hex code, an RGBA code, or a color name. + */ + background?: string; + + /** + * Specifies the corner radius of the text overlay. + * Set to `max` to achieve a circular or oval shape. + */ + radius?: number | "max"; + + /** + * Specifies the rotation angle of the text overlay. + * Accepts a numeric value for clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. + */ + rotation?: number | string; + + /** + * Flip/mirror the text horizontally, vertically, or in both directions. + * Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. + */ + flip?: "h" | "v" | "h_v" | "v_h"; + + /** + * Specifies the line height for multi-line text overlays. It will come into effect only if the text wraps over multiple lines. + * Accepts either an integer value or an arithmetic expression. + */ + lineHeight?: number | string; +} + +export type SubtitleOverlayTransformation = { + /** + * Specifies the subtitle background color using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). + */ + background?: string; + /** + * Sets the font size of subtitle text. + */ + fontSize?: number | string; + /** + * Sets the font family of subtitle text. + * Refer to the [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) in the ImageKit transformations guide. + */ + fontFamily?: string; + /** + * Sets the font color of the subtitle text using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). + */ + color?: string; + /** + * Sets the typography style of the subtitle text. + * Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. + */ + typography?: "b" | "i" | "b_i"; + /** + * Sets the font outline of the subtitle text. + * Requires the outline width (an integer) and the outline color (as an RGB color code, RGBA color code, or standard web color name) separated by an underscore. + * Examples: `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`. + */ + fontOutline?: string; + /** + * Sets the font shadow for the subtitle text. + * Requires the shadow color (as an RGB color code, RGBA color code, or standard web color name) and the shadow indent (an integer) separated by an underscore. + * Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`. + */ + fontShadow?: string; +} + +export type SolidColorOverlayTransformation = Pick & { + /** + * Specifies the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`. + */ + alpha?: number; +} From 82b5f63c946c40ef6d3bc8c5f26808a3494663a4 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sat, 22 Mar 2025 19:26:43 +0700 Subject: [PATCH 05/29] test cases and logic for overlay handling --- src/constants/supportedTransforms.ts | 14 ++ src/interfaces/Transformation.ts | 14 +- src/url/builder.ts | 93 +++++++++++- src/utils/transformation.ts | 23 ++- test/url-generation/overlay.js | 212 +++++++++++++++++++++++++++ 5 files changed, 339 insertions(+), 17 deletions(-) create mode 100644 test/url-generation/overlay.js diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index bbc560f..52a64c3 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -66,6 +66,20 @@ export const supportedTransforms: { [key: string]: string } = { zoom: "z", page: "pg", + // Text overlay transformations which are not defined yet + fontSize: "fs", + fontFamily: "ff", + fontColor: "co", + innerAlignment: "ia", + padding: "pa", + alpha: "al", + typography: "tg", + lineHeight: "lh", + + // Subtitles transformations which are not defined + fontOutline: "fol", + fontShadow: "fsh", + // Raw pass-through raw: "raw", }; diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 4909bf5..7090985 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -526,7 +526,7 @@ export interface TextOverlay extends BaseOverlay { /** * Control styling of the text overlay. */ - transformations?: TextOverlayTransformation[]; + transformation?: TextOverlayTransformation[]; } export interface ImageOverlay extends BaseOverlay { @@ -538,11 +538,11 @@ export interface ImageOverlay extends BaseOverlay { input: string; /** - * List of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. + * Array of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. * * {@link https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay|Video} */ - transformations?: Transformation[]; + transformation?: Transformation[]; } export interface VideoOverlay extends BaseOverlay { @@ -553,11 +553,11 @@ export interface VideoOverlay extends BaseOverlay { input: string; /** - * List of transformations to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. + * Array of transformation to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. * * {@link https://imagekit.io/docs/video-transformation|Video Transformations} */ - transformations?: Transformation[]; + transformation?: Transformation[]; } export interface SubtitleOverlay extends BaseOverlay { @@ -572,7 +572,7 @@ export interface SubtitleOverlay extends BaseOverlay { * * {@link https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer|Styling subtitles} */ - transformations?: SubtitleOverlayTransformation[]; + transformation?: SubtitleOverlayTransformation[]; } export interface SolidColorOverlay extends BaseOverlay { @@ -588,7 +588,7 @@ export interface SolidColorOverlay extends BaseOverlay { * * {@link https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay|Image} | {@link https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay|Video} */ - transformations?: SolidColorOverlayTransformation[]; + transformation?: SolidColorOverlayTransformation[]; } export type TextOverlayTransformation = { diff --git a/src/url/builder.ts b/src/url/builder.ts index 29e13f8..226d969 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -1,6 +1,7 @@ import { ImageKitOptions, UrlOptions } from "../interfaces"; import { Transformation } from "../interfaces/Transformation"; import transformationUtils from "../utils/transformation"; +import { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; function removeTrailingSlash(str: string) { @@ -73,20 +74,106 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => { return urlObj.href; }; + +function processOverlay(overlay: Transformation["overlay"]): string | undefined { + const entries = []; + if (!overlay) { + return; + } + const { type, position = {}, timing = {}, transformation = [] } = overlay; + + if (!type) { + throw new Error("Overlay type is required"); + } + + switch (type) { + case "text": + entries.push("l-text"); + if (overlay.text) { + entries.push(`ie-${encodeURIComponent(safeBtoa(overlay.text))}`); + } + break; + case "image": + entries.push("l-image"); + if (overlay.input) { + entries.push(`i-${overlay.input}`); + } + break; + case "video": + entries.push("l-video"); + if (overlay.input) { + entries.push(`i-${overlay.input}`); + } + break; + case "subtitle": + entries.push("l-subtitle"); + if (overlay.input) { + entries.push(`i-${overlay.input}`); + } + break; + case "solidColor": + entries.push("l-image"); + entries.push(`i-ik_canvas`); + if (overlay.color) { + entries.push(`bg-${overlay.color}`); + } + break; + } + + const { x, y, focus } = position; + if (x) { + entries.push(`lxo-${x}`); + } + if (y) { + entries.push(`lyo-${y}`); + } + if (focus) { + entries.push(`lfo-${focus}`); + } + + const { start, end, duration } = timing; + + if (start) { + entries.push(`lso-${start}`); + } + if (end) { + entries.push(`leo-${end}`); + } + if (duration) { + entries.push(`ldu-${duration}`); + } + + const transformationString = constructTransformationString(transformation); + + if (transformationString && transformationString.trim() !== "") entries.push(transformationString); + + entries.push("l-end"); + + return entries.join(transformationUtils.getTransformDelimiter()); +} + function constructTransformationString(transformation: Transformation[] | undefined) { if (!Array.isArray(transformation)) { return ""; } - var parsedTransforms = []; + var parsedTransforms: string[] = []; for (var i = 0, l = transformation.length; i < l; i++) { - var parsedTransformStep = []; + var parsedTransformStep: string[] = []; for (var key in transformation[i]) { let value = transformation[i][key as keyof Transformation]; if (value === undefined || value === null) { continue; } + if (key === "overlay" && typeof value === "object") { + var rawString = processOverlay(value as Transformation["overlay"]); + if (rawString) { + parsedTransformStep.push(rawString); + continue; + } + } + var transformKey = transformationUtils.getTransformKey(key); if (!transformKey) { transformKey = key; @@ -111,7 +198,7 @@ function constructTransformationString(transformation: Transformation[] | undefi ) { parsedTransformStep.push(transformKey); } else if (key === "raw") { - parsedTransformStep.push(transformation[i][key]); + parsedTransformStep.push(transformation[i][key] as string); } else { if (transformKey === "di") { value = removeTrailingSlash(removeLeadingSlash(value as string || "")); diff --git a/src/utils/transformation.ts b/src/utils/transformation.ts index ef4ec26..c107a69 100644 --- a/src/utils/transformation.ts +++ b/src/utils/transformation.ts @@ -1,12 +1,12 @@ import supportedTransforms from "../constants/supportedTransforms"; import { ImageKitOptions, TransformationPosition } from "../interfaces"; -const DEFAULT_TRANSFORMATION_POSITION : TransformationPosition = "path"; -const QUERY_TRANSFORMATION_POSITION : TransformationPosition = "query"; +const DEFAULT_TRANSFORMATION_POSITION: TransformationPosition = "path"; +const QUERY_TRANSFORMATION_POSITION: TransformationPosition = "query"; const VALID_TRANSFORMATION_POSITIONS = [DEFAULT_TRANSFORMATION_POSITION, QUERY_TRANSFORMATION_POSITION]; -const CHAIN_TRANSFORM_DELIMITER : string = ":"; -const TRANSFORM_DELIMITER : string = ","; -const TRANSFORM_KEY_VALUE_DELIMITER : string = "-"; +const CHAIN_TRANSFORM_DELIMITER: string = ":"; +const TRANSFORM_DELIMITER: string = ","; +const TRANSFORM_KEY_VALUE_DELIMITER: string = "-"; export default { getDefault: (): TransformationPosition => { @@ -15,8 +15,8 @@ export default { addAsQueryParameter: (options: ImageKitOptions) => { return options.transformationPosition === QUERY_TRANSFORMATION_POSITION; }, - validParameters: (options: ImageKitOptions) => { - if(typeof options.transformationPosition == "undefined") return false; + validParameters: (options: ImageKitOptions) => { + if (typeof options.transformationPosition == "undefined") return false; return VALID_TRANSFORMATION_POSITIONS.indexOf(options.transformationPosition) != -1; }, getTransformKey: function (transform: string) { @@ -33,4 +33,13 @@ export default { getTransformKeyValueDelimiter: function () { return TRANSFORM_KEY_VALUE_DELIMITER; } +} + +export const safeBtoa = function (str: string): string { + if (typeof btoa !== "undefined") { + return btoa(str); + } else { + // Node fallback + return Buffer.from(str, "utf8").toString("base64"); + } } \ No newline at end of file diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js new file mode 100644 index 0000000..c4d71bc --- /dev/null +++ b/test/url-generation/overlay.js @@ -0,0 +1,212 @@ +const chai = require("chai"); +const expect = chai.expect; +const initializationParams = require("../data").initializationParams; +import ImageKit from "../../src/index"; +import { safeBtoa } from "../../src/utils/transformation"; +describe.only("Comprehensive Overlay Transformation Cases", function () { + const imagekit = new ImageKit(initializationParams); + + it('simple text overlay', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "text", + text: "Minimal Text", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Minimal Text"))},l-end/base-image.jpg`); + }); + + it('simple image overlay', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image", + input: "logo.png", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-logo.png,l-end/base-image.jpg`); + }); + + it('simple video overlay', function () { + const url = imagekit.url({ + path: "/base-video.mp4", + transformation: [{ + overlay: { + type: "video", + input: "play-pause-loop.mp4", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-video,i-play-pause-loop.mp4,l-end/base-video.mp4`); + }); + + it("simple subtitle overlay", function () { + const url = imagekit.url({ + path: "/base-video.mp4", + transformation: [{ + overlay: { + type: "subtitle", + input: "subtitle.srt", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-subtitle,i-subtitle.srt,l-end/base-video.mp4`); + }); + + it("simple solid color overlay", function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "solidColor", + color: "FF0000", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-ik_canvas,bg-FF0000,l-end/base-image.jpg`); + }); + + it('All combined', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [ + { + // Text overlay + overlay: { + type: "text", + text: "Every thing", + position: { + x: "10", + y: "20", + focus: "center" + }, + timing: { + start: 5, + duration: "10", + end: 15 + }, + transformations: [{ + width: "bw_mul_0.5", + fontSize: 20, + fontFamily: "Arial", + fontColor: "0000ff", + innerAlignment: "left", + padding: 5, + alpha: 7, + typography: "b", + background: "red", + radius: 10, + rotation: "N45", + flip: "h", + lineHeight: 20 + }] + } + }, + { + // Image overlay + overlay: { + type: "image", + input: "logo.png", + position: { + x: "10", + y: "20", + focus: "center" + }, + timing: { + start: 5, + duration: "10", + end: 15 + }, + transformations: [ + { + width: "bw_mul_0.5", + height: "bh_mul_0.5", + rotation: "N45", + flip: "h", + overlay: { + type: "text", + text: "Nested text overlay", + } + } + ] + } + }, + { + // Video overlay. Just for url generation testing, you can't overlay a video on an image. + overlay: { + type: "video", + input: "play-pause-loop.mp4", + position: { + x: "10", + y: "20", + focus: "center" + }, + timing: { + start: 5, + duration: "10", + end: 15 + }, + transformations: [{ + width: "bw_mul_0.5", + height: "bh_mul_0.5", + rotation: "N45", + flip: "h", + }] + } + }, + { + // Subtitle overlay. Just for url generation testing, you can't overlay a subtitle on an image. + overlay: { + type: "subtitle", + input: "subtitle.srt", + position: { + x: "10", + y: "20", + focus: "center" + }, + timing: { + start: 5, + duration: "10", + end: 15 + }, + transformations: [{ + width: "bw_mul_0.5", + height: "bh_mul_0.5", + rotation: "N45", + flip: "h", + }] + } + }, + { + // Solid color overlay + overlay: { + type: "solidColor", + color: "FF0000", + position: { + x: "10", + y: "20", + focus: "center" + }, + timing: { + start: 5, + duration: "10", + end: 15 + }, + transformations: [{ + width: "bw_mul_0.5", + height: "bh_mul_0.5", + rotation: "N45", + flip: "h", + }] + } + } + ] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Every thing"))},lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,fs-20,ff-Arial,fc-0000ff,ia-left,pa-5,al-7,tg-b,bg-red,r-10,rt-N45,fl-h,lh-20,l-end:l-image,i-logo.png,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-text,ie-${encodeURIComponent(safeBtoa("Nested text overlay"))},l-end,l-end:l-video,i-play-pause-loop.mp4,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-subtitle,i-subtitle.srt,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,l-end/base-image.jpg`); + }); +}); From 6f93838585ccf737fa5b200119106c279cc232dd Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sat, 22 Mar 2025 19:35:14 +0700 Subject: [PATCH 06/29] fix test case --- test/url-generation/overlay.js | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index c4d71bc..3328830 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -3,10 +3,10 @@ const expect = chai.expect; const initializationParams = require("../data").initializationParams; import ImageKit from "../../src/index"; import { safeBtoa } from "../../src/utils/transformation"; -describe.only("Comprehensive Overlay Transformation Cases", function () { +describe("Overlay Transformation Test Cases", function () { const imagekit = new ImageKit(initializationParams); - it('simple text overlay', function () { + it('Text overlay generates correct URL with encoded overlay text', function () { const url = imagekit.url({ path: "/base-image.jpg", transformation: [{ @@ -19,7 +19,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Minimal Text"))},l-end/base-image.jpg`); }); - it('simple image overlay', function () { + it('Image overlay generates correct URL with input logo.png', function () { const url = imagekit.url({ path: "/base-image.jpg", transformation: [{ @@ -32,7 +32,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-logo.png,l-end/base-image.jpg`); }); - it('simple video overlay', function () { + it('Video overlay generates correct URL with input play-pause-loop.mp4', function () { const url = imagekit.url({ path: "/base-video.mp4", transformation: [{ @@ -45,7 +45,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-video,i-play-pause-loop.mp4,l-end/base-video.mp4`); }); - it("simple subtitle overlay", function () { + it("Subtitle overlay generates correct URL with input subtitle.srt", function () { const url = imagekit.url({ path: "/base-video.mp4", transformation: [{ @@ -58,7 +58,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-subtitle,i-subtitle.srt,l-end/base-video.mp4`); }); - it("simple solid color overlay", function () { + it("Solid color overlay generates correct URL with background color FF0000", function () { const url = imagekit.url({ path: "/base-image.jpg", transformation: [{ @@ -71,7 +71,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-ik_canvas,bg-FF0000,l-end/base-image.jpg`); }); - it('All combined', function () { + it('Combined overlay transformations generate correct URL including nested overlays', function () { const url = imagekit.url({ path: "/base-image.jpg", transformation: [ @@ -90,7 +90,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { duration: "10", end: 15 }, - transformations: [{ + transformation: [{ width: "bw_mul_0.5", fontSize: 20, fontFamily: "Arial", @@ -122,7 +122,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { duration: "10", end: 15 }, - transformations: [ + transformation: [ { width: "bw_mul_0.5", height: "bh_mul_0.5", @@ -197,7 +197,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { duration: "10", end: 15 }, - transformations: [{ + transformation: [{ width: "bw_mul_0.5", height: "bh_mul_0.5", rotation: "N45", @@ -207,6 +207,7 @@ describe.only("Comprehensive Overlay Transformation Cases", function () { } ] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Every thing"))},lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,fs-20,ff-Arial,fc-0000ff,ia-left,pa-5,al-7,tg-b,bg-red,r-10,rt-N45,fl-h,lh-20,l-end:l-image,i-logo.png,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-text,ie-${encodeURIComponent(safeBtoa("Nested text overlay"))},l-end,l-end:l-video,i-play-pause-loop.mp4,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-subtitle,i-subtitle.srt,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,ldu-10,leo-15,w-bw_mul_0.5,l-end/base-image.jpg`); + + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Every thing"))},lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,fs-20,ff-Arial,co-0000ff,ia-left,pa-5,al-7,tg-b,bg-red,r-10,rt-N45,fl-h,lh-20,l-end:l-image,i-logo.png,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-text,ie-${encodeURIComponent(safeBtoa("Nested text overlay"))},l-end,l-end:l-video,i-play-pause-loop.mp4,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-subtitle,i-subtitle.srt,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end/base-image.jpg`) }); }); From 2d95621d72e96c1af7deebff7ca3c228d4e5a303 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sat, 22 Mar 2025 19:44:30 +0700 Subject: [PATCH 07/29] fix build --- src/url/builder.ts | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 226d969..1e5432b 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -1,7 +1,6 @@ import { ImageKitOptions, UrlOptions } from "../interfaces"; -import { Transformation } from "../interfaces/Transformation"; -import transformationUtils from "../utils/transformation"; -import { safeBtoa } from "../utils/transformation"; +import { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transformation, VideoOverlay } from "../interfaces/Transformation"; +import transformationUtils, { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; function removeTrailingSlash(str: string) { @@ -89,33 +88,48 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined switch (type) { case "text": entries.push("l-text"); - if (overlay.text) { - entries.push(`ie-${encodeURIComponent(safeBtoa(overlay.text))}`); + { + const textOverlay = overlay as TextOverlay; + if (textOverlay.text) { + entries.push(`ie-${encodeURIComponent(safeBtoa(textOverlay.text))}`); + } } break; case "image": entries.push("l-image"); - if (overlay.input) { - entries.push(`i-${overlay.input}`); + { + const imageOverlay = overlay as ImageOverlay; + if (imageOverlay.input) { + entries.push(`i-${imageOverlay.input}`); + } } break; case "video": entries.push("l-video"); - if (overlay.input) { - entries.push(`i-${overlay.input}`); + { + const videoOverlay = overlay as VideoOverlay; + if (videoOverlay.input) { + entries.push(`i-${videoOverlay.input}`); + } } break; case "subtitle": entries.push("l-subtitle"); - if (overlay.input) { - entries.push(`i-${overlay.input}`); + { + const subtitleOverlay = overlay as SubtitleOverlay; + if (subtitleOverlay.input) { + entries.push(`i-${subtitleOverlay.input}`); + } } break; case "solidColor": entries.push("l-image"); entries.push(`i-ik_canvas`); - if (overlay.color) { - entries.push(`bg-${overlay.color}`); + { + const solidColorOverlay = overlay as SolidColorOverlay; + if (solidColorOverlay.color) { + entries.push(`bg-${solidColorOverlay.color}`); + } } break; } From 397ab3171bc29321ee3d7e77c3c6c8219017b039 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sat, 22 Mar 2025 19:52:00 +0700 Subject: [PATCH 08/29] fix: handle missing values in overlay processing to prevent invalid URLs --- src/url/builder.ts | 26 ++++++++++----- test/url-generation/overlay.js | 60 ++++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+), 9 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 1e5432b..d3be494 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -86,14 +86,14 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined } switch (type) { - case "text": - entries.push("l-text"); - { - const textOverlay = overlay as TextOverlay; - if (textOverlay.text) { - entries.push(`ie-${encodeURIComponent(safeBtoa(textOverlay.text))}`); - } + case "text": { + const textOverlay = overlay as TextOverlay; + if (!textOverlay.text) { + return; } + entries.push("l-text"); + entries.push(`ie-${encodeURIComponent(safeBtoa(textOverlay.text))}`); + } break; case "image": entries.push("l-image"); @@ -101,6 +101,8 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined const imageOverlay = overlay as ImageOverlay; if (imageOverlay.input) { entries.push(`i-${imageOverlay.input}`); + } else { + return; } } break; @@ -110,6 +112,8 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined const videoOverlay = overlay as VideoOverlay; if (videoOverlay.input) { entries.push(`i-${videoOverlay.input}`); + } else { + return; } } break; @@ -119,6 +123,8 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined const subtitleOverlay = overlay as SubtitleOverlay; if (subtitleOverlay.input) { entries.push(`i-${subtitleOverlay.input}`); + } else { + return; } } break; @@ -129,6 +135,8 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined const solidColorOverlay = overlay as SolidColorOverlay; if (solidColorOverlay.color) { entries.push(`bg-${solidColorOverlay.color}`); + } else { + return; } } break; @@ -182,10 +190,10 @@ function constructTransformationString(transformation: Transformation[] | undefi if (key === "overlay" && typeof value === "object") { var rawString = processOverlay(value as Transformation["overlay"]); - if (rawString) { + if (rawString && rawString.trim() !== "") { parsedTransformStep.push(rawString); - continue; } + continue; // Always continue as overlay is processed. } var transformKey = transformationUtils.getTransformKey(key); diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 3328830..3456041 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -6,6 +6,66 @@ import { safeBtoa } from "../../src/utils/transformation"; describe("Overlay Transformation Test Cases", function () { const imagekit = new ImageKit(initializationParams); + it('Ignore invalid values if text is missing', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "text" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/base-image.jpg`); + }); + + it('Ignore invalid values if input', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/base-image.jpg`); + }); + + it('Ignore invalid values if input', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "video" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/base-image.jpg`); + }); + + it('Ignore invalid values if input', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "subtitle" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/base-image.jpg`); + }); + + it('Ignore invalid values if color is missing', function () { + const url = imagekit.url({ + path: "/base-image.jpg", + transformation: [{ + overlay: { + type: "solidColor" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/base-image.jpg`); + }); + it('Text overlay generates correct URL with encoded overlay text', function () { const url = imagekit.url({ path: "/base-image.jpg", From bc036204e89785e7792397ebb85a4bd0887222eb Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sat, 22 Mar 2025 20:01:57 +0700 Subject: [PATCH 09/29] Add proper overlay examples --- README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 103 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2b06eea..f9c0bdf 100644 --- a/README.md +++ b/README.md @@ -88,8 +88,8 @@ The SDK’s `.url()` method enables you to generate optimized image and video UR path: "/default-image.jpg", urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", transformation: [{ - "height": "300", - "width": "400" + height: 300, + width: 400 }] }); ``` @@ -103,8 +103,8 @@ The SDK’s `.url()` method enables you to generate optimized image and video UR var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg", transformation: [{ - "height": "300", - "width": "400" + height: 300, + width: 400 }] }); ``` @@ -121,10 +121,10 @@ Apply multiple transformations by passing an array: var imageURL = imagekit.url({ path: "/default-image.jpg", transformation: [{ - "height": "300", - "width": "400" + height: 300, + width: 400 }, { - "rotation": 90 + rotation: 90 }], transformationPosition: "query" // Use query parameter for transformations }); @@ -140,20 +140,106 @@ https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300%2Cw-400%3Art- var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ - "width": 400, - "height": 300, - "raw": "l-text,i-Imagekit,fs-50,l-end" + width: 400, + height: 300, + overlay: { + text: "Imagekit", + fontSize: 50, + color: "red", + position: { + x: 10, + y: 20 + } + } }] }); ``` + *Image Overlay Example:* + ```js var imageURL = imagekit.url({ src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg", transformation: [{ - "width": 400, - "height": 300, - "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end" + width: 400, + height: 300, + overlay: { + type: "image", + input: "logo.png", + transformation: [{ + width: 100, + border: "10_CDDC39" + }], + position: { + focus: "top_left" + } + } + }] +}); +``` + +*Video Overlay Example:* + +```js +var videoOverlayURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/base-video.mp4", + transformation: [{ + overlay: { + type: "video", + input: "overlay-video.mp4", + position: { + x: "10", + y: "20" + }, + timing: { + start: 5, + duration: 10 + } + } + }] +}); +``` + +*Subtitle Overlay Example:* + +```js +var subtitleOverlayURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/base-video.mp4", + transformation: [{ + overlay: { + type: "subtitle", + input: "subtitle.vtt", + transformation: [{ + fontSize: 16, + fontFamily: "Arial" + }], + position: { + focus: "bottom" + }, + timing: { + start: 0, + duration: 5 + } + } + }] +}); +``` + +*Solid Color Overlay Example:* +```js +var solidColorOverlayURL = imagekit.url({ + src: "https://ik.imagekit.io/your_imagekit_id/base-image.jpg", + transformation: [{ + overlay: { + type: "solidColor", + color: "FF0000", + transformation: [{ + width: 100, + height: 50, + alpha: 5 + }], + position: { x: 20, y: 20 } + } }] }); ``` @@ -192,9 +278,9 @@ var dropShadowURL = imagekit.url({ 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" + width: "iw_div_4", + height: "ih_div_2", + border: "cw_mul_0.05_yellow" }] }); ``` @@ -269,7 +355,7 @@ For example: var imageURL = imagekit.url({ path: "/test_path.jpg", transformation: [{ - "newparam": "cool" + newparam: "cool" }] }); // Generated URL: https://ik.imagekit.io/test_url_endpoint/tr:newparam-cool/test_path.jpg From 57e0066bf65319727ee4e61034b7ba887dc4bfba Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 12:30:23 +0530 Subject: [PATCH 10/29] feat: add encoding options for overlay input paths and texts --- src/interfaces/Transformation.ts | 50 +++++++++++++++++++++ src/url/builder.ts | 43 ++++++++++++++++-- src/utils/transformation.ts | 2 +- test/url-generation/overlay.js | 77 +++++++++++++++++++++++++++++++- 4 files changed, 165 insertions(+), 7 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 7090985..ff1c9c6 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -523,6 +523,17 @@ export interface TextOverlay extends BaseOverlay { */ text: string; + /** + * Specifies how the overlay input text should be encoded. The default is `auto`, which means the SDK will initially treat the text as plain text to improve URL readability. If the text contains special characters, the SDK will automatically switch to `base64` encoding. + * + * You can also explicitly set the encoding to either `plain` or `base64`. + * + * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * + * * Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. + */ + encoding: "auto" | "plain" | "base64"; + /** * Control styling of the text overlay. */ @@ -537,6 +548,19 @@ export interface ImageOverlay extends BaseOverlay { */ input: string; + /** + * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. + * + * You can also explicitly set the encoding to either `plain` or `base64`. + * + * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * + * * Regardless of the encoding method: + * - Leading and trailing slashes are removed. + * - Any remaining slashes within the path are replaced with `@@` when using plain text. + */ + encoding: "auto" | "plain" | "base64"; + /** * Array of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. * @@ -552,6 +576,19 @@ export interface VideoOverlay extends BaseOverlay { */ input: string; + /** + * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. + * + * You can also explicitly set the encoding to either `plain` or `base64`. + * + * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * + * * Regardless of the encoding method: + * - Leading and trailing slashes are removed. + * - Any remaining slashes within the path are replaced with `@@` when using plain text. + */ + encoding: "auto" | "plain" | "base64"; + /** * Array of transformation to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. * @@ -567,6 +604,19 @@ export interface SubtitleOverlay extends BaseOverlay { */ input: string; + /** + * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. + * + * You can also explicitly set the encoding to either `plain` or `base64`. + * + * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * + * * Regardless of the encoding method: + * - Leading and trailing slashes are removed. + * - Any remaining slashes within the path are replaced with `@@` when using plain text. + */ + encoding: "auto" | "plain" | "base64"; + /** * Control styling of the subtitle. * diff --git a/src/url/builder.ts b/src/url/builder.ts index d3be494..d014230 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -2,6 +2,8 @@ import { ImageKitOptions, UrlOptions } from "../interfaces"; import { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transformation, VideoOverlay } from "../interfaces/Transformation"; import transformationUtils, { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; +const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._,/ ]*$') +const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._, ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. function removeTrailingSlash(str: string) { if (typeof str == "string" && str[str.length - 1] == "/") { @@ -73,6 +75,34 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => { return urlObj.href; }; +function processInputPath(str: string, enccoding: string): string { + // Remove leading and trailing slashes + str = removeTrailingSlash(removeLeadingSlash(str)); + if(enccoding === "plain") { + return `i-${str.replace(/\//g, "@@")}`; + } + if(enccoding === "base64") { + return `ie-${encodeURIComponent(safeBtoa(str))}`; + } + if (SIMPLE_OVERLAY_PATH_REGEX.test(str)) { + return `i-${str.replace(/\//g, "@@")}`; + } else { + return `ie-${encodeURIComponent(safeBtoa(str))}`; + } +} + +function processText(str: string, enccoding: TextOverlay["encoding"]): string { + if (enccoding === "plain") { + return `i-${encodeURIComponent(str)}`; + } + if (enccoding === "base64") { + return `ie-${encodeURIComponent(safeBtoa(str))}`; + } + if (SIMPLE_OVERLAY_TEXT_REGEX.test(str)) { + return `i-${encodeURIComponent(str)}`; + } + return `ie-${encodeURIComponent(safeBtoa(str))}`; +} function processOverlay(overlay: Transformation["overlay"]): string | undefined { const entries = []; @@ -91,16 +121,19 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined if (!textOverlay.text) { return; } + const enccoding = textOverlay.encoding || "auto"; + entries.push("l-text"); - entries.push(`ie-${encodeURIComponent(safeBtoa(textOverlay.text))}`); + entries.push(processText(textOverlay.text, enccoding)); } break; case "image": entries.push("l-image"); { const imageOverlay = overlay as ImageOverlay; + const enccoding = imageOverlay.encoding || "auto"; if (imageOverlay.input) { - entries.push(`i-${imageOverlay.input}`); + entries.push(processInputPath(imageOverlay.input, enccoding)); } else { return; } @@ -110,8 +143,9 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined entries.push("l-video"); { const videoOverlay = overlay as VideoOverlay; + const enccoding = videoOverlay.encoding || "auto"; if (videoOverlay.input) { - entries.push(`i-${videoOverlay.input}`); + entries.push(processInputPath(videoOverlay.input, enccoding)); } else { return; } @@ -121,8 +155,9 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined entries.push("l-subtitle"); { const subtitleOverlay = overlay as SubtitleOverlay; + const enccoding = subtitleOverlay.encoding || "auto"; if (subtitleOverlay.input) { - entries.push(`i-${subtitleOverlay.input}`); + entries.push(processInputPath(subtitleOverlay.input, enccoding)); } else { return; } diff --git a/src/utils/transformation.ts b/src/utils/transformation.ts index c107a69..0ef2c25 100644 --- a/src/utils/transformation.ts +++ b/src/utils/transformation.ts @@ -36,7 +36,7 @@ export default { } export const safeBtoa = function (str: string): string { - if (typeof btoa !== "undefined") { + if (typeof window !== "undefined") { return btoa(str); } else { // Node fallback diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 3456041..b4367b8 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -76,7 +76,7 @@ describe("Overlay Transformation Test Cases", function () { } }] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Minimal Text"))},l-end/base-image.jpg`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,i-${encodeURIComponent("Minimal Text")},l-end/base-image.jpg`); }); it('Image overlay generates correct URL with input logo.png', function () { @@ -268,6 +268,79 @@ describe("Overlay Transformation Test Cases", function () { ] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,ie-${encodeURIComponent(safeBtoa("Every thing"))},lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,fs-20,ff-Arial,co-0000ff,ia-left,pa-5,al-7,tg-b,bg-red,r-10,rt-N45,fl-h,lh-20,l-end:l-image,i-logo.png,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-text,ie-${encodeURIComponent(safeBtoa("Nested text overlay"))},l-end,l-end:l-video,i-play-pause-loop.mp4,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-subtitle,i-subtitle.srt,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end/base-image.jpg`) + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-text,i-${encodeURIComponent("Every thing")},lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,fs-20,ff-Arial,co-0000ff,ia-left,pa-5,al-7,tg-b,bg-red,r-10,rt-N45,fl-h,lh-20,l-end:l-image,i-logo.png,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-text,i-${encodeURIComponent("Nested text overlay")},l-end,l-end:l-video,i-play-pause-loop.mp4,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-subtitle,i-subtitle.srt,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,l-end:l-image,i-ik_canvas,bg-FF0000,lxo-10,lyo-20,lfo-center,lso-5,leo-15,ldu-10,w-bw_mul_0.5,h-bh_mul_0.5,rt-N45,fl-h,l-end/base-image.jpg`) }); }); + + +describe("Edge cases", function () { + const imagekit = new ImageKit({ + ...initializationParams, + urlEndpoint: "https://ik.imagekit.io/demo", // Using real url to test correctness quickly by clicking link + }); + + it('Nested simple path, should use i instead of ie, handle slash properly', function () { + const url = imagekit.url({ + path: "/medium_cafe_B1iTdD0C.jpg", + transformation: [{ + overlay: { + type: "image", + input: "/customer_logo/nykaa.png", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-image,i-customer_logo@@nykaa.png,l-end/medium_cafe_B1iTdD0C.jpg`); + }); + + it('Nested non-simple path, should use ie instead of i', function () { + const url = imagekit.url({ + path: "/medium_cafe_B1iTdD0C.jpg", + transformation: [{ + overlay: { + type: "image", + input: "/customer_logo/Ñykaa.png" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-image,ie-Y3VzdG9tZXJfbG9nby9OzIN5a2FhLnBuZw%3D%3D,l-end/medium_cafe_B1iTdD0C.jpg`); + }); + + it('Simple text overlay, should use i instead of ie', function () { + const url = imagekit.url({ + path: "/medium_cafe_B1iTdD0C.jpg", + transformation: [{ + overlay: { + type: "text", + text: "Manu", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-Manu,l-end/medium_cafe_B1iTdD0C.jpg`); + }); + + it('Simple text overlay with spaces and comma, should use i instead of ie', function () { + const url = imagekit.url({ + path: "/medium_cafe_B1iTdD0C.jpg", + transformation: [{ + overlay: { + type: "text", + text: "alnum123-._, ", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123-._, ")},l-end/medium_cafe_B1iTdD0C.jpg`); + }); + + it('Non simple text overlay, should use ie instead of i', function () { + const url = imagekit.url({ + path: "/medium_cafe_B1iTdD0C.jpg", + transformation: [{ + overlay: { + type: "text", + text: "Let's use ©, ®, ™, etc", + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,ie-TGV0J3MgdXNlIMKpLCDCriwg4oSiLCBldGM%3D,l-end/medium_cafe_B1iTdD0C.jpg`); + }); +}); \ No newline at end of file From 9275a502afdcc4d61a8b2afa91717bd4637b0a9c Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 12:38:04 +0530 Subject: [PATCH 11/29] explict encoding test cases --- test/url-generation/overlay.js | 102 ++++++++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 2 deletions(-) diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index b4367b8..3a163f9 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -273,7 +273,7 @@ describe("Overlay Transformation Test Cases", function () { }); -describe("Edge cases", function () { +describe("Overlay encoding test cases", function () { const imagekit = new ImageKit({ ...initializationParams, urlEndpoint: "https://ik.imagekit.io/demo", // Using real url to test correctness quickly by clicking link @@ -343,4 +343,102 @@ describe("Edge cases", function () { }); expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,ie-TGV0J3MgdXNlIMKpLCDCriwg4oSiLCBldGM%3D,l-end/medium_cafe_B1iTdD0C.jpg`); }); -}); \ No newline at end of file + + it('Text overlay with explicit plain encoding', function () { + const url = imagekit.url({ + path: "/sample.jpg", + transformation: [{ + overlay: { + type: "text", + text: "HelloWorld", + encoding: "plain" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-HelloWorld,l-end/sample.jpg`); + }); + + it('Text overlay with explicit base64 encoding', function () { + const url = imagekit.url({ + path: "/sample.jpg", + transformation: [{ + overlay: { + type: "text", + text: "HelloWorld", + encoding: "base64" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,ie-${encodeURIComponent(safeBtoa("HelloWorld"))},l-end/sample.jpg`); + }); + + it('Image overlay with explicit plain encoding', function () { + const url = imagekit.url({ + path: "/sample.jpg", + transformation: [{ + overlay: { + type: "image", + input: "/customer/logo.png", + encoding: "plain" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-image,i-customer@@logo.png,l-end/sample.jpg`); + }); + + it('Image overlay with explicit base64 encoding', function () { + const url = imagekit.url({ + path: "/sample.jpg", + transformation: [{ + overlay: { + type: "image", + input: "/customer/logo.png", + encoding: "base64" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-image,ie-${encodeURIComponent(safeBtoa("customer/logo.png"))},l-end/sample.jpg`); + }); + + it('Video overlay with explicit base64 encoding', function () { + const url = imagekit.url({ + path: "/sample.mp4", + transformation: [{ + overlay: { + type: "video", + input: "/path/to/video.mp4", + encoding: "base64" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-video,ie-${encodeURIComponent(safeBtoa("path/to/video.mp4"))},l-end/sample.mp4`); + }); + + it('Subtitle overlay with explicit plain encoding', function () { + const url = imagekit.url({ + path: "/sample.mp4", + transformation: [{ + overlay: { + type: "subtitle", + input: "/sub.srt", + encoding: "plain" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-subtitle,i-sub.srt,l-end/sample.mp4`); + }); + + it('Subtitle overlay with explicit base64 encoding', function () { + const url = imagekit.url({ + path: "/sample.mp4", + transformation: [{ + overlay: { + type: "subtitle", + input: "sub.srt", + encoding: "base64" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-subtitle,ie-${encodeURIComponent(safeBtoa("sub.srt"))},l-end/sample.mp4`); + }); +}); From f9105100c878b9eb93e572c274c8d3acc0d25eb5 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 12:39:23 +0530 Subject: [PATCH 12/29] fix: correct formatting in documentation comments for overlay encoding methods --- src/interfaces/Transformation.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index ff1c9c6..ead7b23 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -530,7 +530,7 @@ export interface TextOverlay extends BaseOverlay { * * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. * - * * Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. + * Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. */ encoding: "auto" | "plain" | "base64"; @@ -555,7 +555,7 @@ export interface ImageOverlay extends BaseOverlay { * * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. * - * * Regardless of the encoding method: + * Regardless of the encoding method: * - Leading and trailing slashes are removed. * - Any remaining slashes within the path are replaced with `@@` when using plain text. */ @@ -583,7 +583,7 @@ export interface VideoOverlay extends BaseOverlay { * * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. * - * * Regardless of the encoding method: + * Regardless of the encoding method: * - Leading and trailing slashes are removed. * - Any remaining slashes within the path are replaced with `@@` when using plain text. */ @@ -611,7 +611,7 @@ export interface SubtitleOverlay extends BaseOverlay { * * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. * - * * Regardless of the encoding method: + * Regardless of the encoding method: * - Leading and trailing slashes are removed. * - Any remaining slashes within the path are replaced with `@@` when using plain text. */ From 2485020cc0c035657a1b999eec21b61acb70436d Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 12:55:37 +0530 Subject: [PATCH 13/29] docs: update README to include overlay options and configuration details --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index f9c0bdf..ef5a403 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ Lightweight JavaScript SDK for generating optimized URLs for images and videos, - [URL Generation](#url-generation) - [Basic URL Generation](#basic-url-generation) - [Advanced URL Generation Examples](#advanced-url-generation-examples) + - [Chained Transformations](#chained-transformations) + - [Overlays and Effects](#overlays-and-effects) + - [AI and Advanced Transformations](#ai-and-advanced-transformations) + - [Arithmetic Expressions in Transformations](#arithmetic-expressions-in-transformations) - [Supported Transformations](#supported-transformations) - [Handling Unsupported Transformations](#handling-unsupported-transformations) - [File Upload](#file-upload) @@ -244,6 +248,18 @@ var solidColorOverlayURL = imagekit.url({ }); ``` +**Overlay Options** + +The following table details the overlay configuration options as defined in the SDK. These options are passed in the overlay object and directly map to URL parameters: + +| option | Description | Example | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| encoding | Specifies how the overlay input is encoded. The default is "auto", meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to "plain" or "base64". | `encoding: "plain"` | +| position | Defines the overlay's placement relative to the parent asset. Accepts a JSON object with properties: `x` and `y` for coordinates (which can be arithmetic expressions) or a `focus` value such as "center", "top_left", etc. | `position: { x: 10, y: 20, focus: "center" }` | +| timing | When the base asset is video, specifies when the overlay appears. It accepts a JSON object with values for `start`, `duration`, and `end`. If both `duration` and `end` are provided, `duration` is ignored. | `timing: { start: 5, duration: 10, end: 15 }` | + +These options provide developers with fine-grained control over overlay transformations, ensuring that the generated URL accurately reflects the desired overlay configuration. + #### AI and Advanced Transformations *Background Removal:* ```js From c09f3d2d30a401f2d02b366a22fe28a08a59fb05 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 12:58:18 +0530 Subject: [PATCH 14/29] docs: improve formatting and clarity in overlay options section of README --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ef5a403..0ec9384 100644 --- a/README.md +++ b/README.md @@ -248,14 +248,14 @@ var solidColorOverlayURL = imagekit.url({ }); ``` -**Overlay Options** +##### Overlay Options The following table details the overlay configuration options as defined in the SDK. These options are passed in the overlay object and directly map to URL parameters: | option | Description | Example | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| encoding | Specifies how the overlay input is encoded. The default is "auto", meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to "plain" or "base64". | `encoding: "plain"` | -| position | Defines the overlay's placement relative to the parent asset. Accepts a JSON object with properties: `x` and `y` for coordinates (which can be arithmetic expressions) or a `focus` value such as "center", "top_left", etc. | `position: { x: 10, y: 20, focus: "center" }` | +| encoding | Specifies how the overlay input is encoded. The default is `auto`, meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to `plain` or `base64`. | `encoding: "plain"` | +| position | Defines the overlay's placement relative to the parent asset. Accepts a JSON object with properties: `x` and `y` for coordinates (which can be arithmetic expressions) or a `focus` value such as `center`, `top_left`, etc. | `position: { x: 10, y: 20, focus: "center" }` | | timing | When the base asset is video, specifies when the overlay appears. It accepts a JSON object with values for `start`, `duration`, and `end`. If both `duration` and `end` are provided, `duration` is ignored. | `timing: { start: 5, duration: 10, end: 15 }` | These options provide developers with fine-grained control over overlay transformations, ensuring that the generated URL accurately reflects the desired overlay configuration. From 42fbc20be939e521b97384ab101ae4d39a4e2f21 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Sun, 30 Mar 2025 15:21:49 +0530 Subject: [PATCH 15/29] docs: correct table header and update encoding example in overlay options section of README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0ec9384..5c83fce 100644 --- a/README.md +++ b/README.md @@ -252,9 +252,9 @@ var solidColorOverlayURL = imagekit.url({ The following table details the overlay configuration options as defined in the SDK. These options are passed in the overlay object and directly map to URL parameters: -| option | Description | Example | +| Option | Description | Example | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| encoding | Specifies how the overlay input is encoded. The default is `auto`, meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to `plain` or `base64`. | `encoding: "plain"` | +| encoding | Specifies how the overlay input is encoded. The default is `auto`, meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to `plain` or `base64`. | `encoding: "base64"` | | position | Defines the overlay's placement relative to the parent asset. Accepts a JSON object with properties: `x` and `y` for coordinates (which can be arithmetic expressions) or a `focus` value such as `center`, `top_left`, etc. | `position: { x: 10, y: 20, focus: "center" }` | | timing | When the base asset is video, specifies when the overlay appears. It accepts a JSON object with values for `start`, `duration`, and `end`. If both `duration` and `end` are provided, `duration` is ignored. | `timing: { start: 5, duration: 10, end: 15 }` | From 45d8a871922ad0a08d4b67832e97d55f697ef274 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 14:35:25 +0530 Subject: [PATCH 16/29] docs: enhance encoding descriptions and clarify overlay input formats in Transformation interface --- README.md | 87 ++++++++++++++++++++++++++++---- src/interfaces/Transformation.ts | 50 +++++++++--------- 2 files changed, 101 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 5c83fce..e05f0aa 100644 --- a/README.md +++ b/README.md @@ -250,15 +250,84 @@ var solidColorOverlayURL = imagekit.url({ ##### Overlay Options -The following table details the overlay configuration options as defined in the SDK. These options are passed in the overlay object and directly map to URL parameters: - -| Option | Description | Example | -| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| encoding | Specifies how the overlay input is encoded. The default is `auto`, meaning the SDK automatically determines whether to use plain (`i-{input}`) or base64 (`ie-{base64_encoded_input}`) encoding based on the content. You can explicitly set it to `plain` or `base64`. | `encoding: "base64"` | -| position | Defines the overlay's placement relative to the parent asset. Accepts a JSON object with properties: `x` and `y` for coordinates (which can be arithmetic expressions) or a `focus` value such as `center`, `top_left`, etc. | `position: { x: 10, y: 20, focus: "center" }` | -| timing | When the base asset is video, specifies when the overlay appears. It accepts a JSON object with values for `start`, `duration`, and `end`. If both `duration` and `end` are provided, `duration` is ignored. | `timing: { start: 5, duration: 10, end: 15 }` | - -These options provide developers with fine-grained control over overlay transformations, ensuring that the generated URL accurately reflects the desired overlay configuration. +The table below outlines the available overlay configuration options: + +| Option | Description | Example | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| type | Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. | `type: "text"` | +| text | (For text overlays) The text content to display. | `text: "ImageKit"` | +| input | (For image, video, or subtitle overlays) Relative path to the overlay asset. | `input: "logo.png"` or `input: "overlay-video.mp4"` | +| color | (For solidColor overlays) RGB/RGBA hex code or color name for the overlay color. | `color: "FF0000"` | +| encoding | Defines how the overlay input is encoded. Accepted values: `auto`, `plain`, `base64`. | `encoding: "auto"` | +| transformation | An array of transformation objects to style the overlay.
- [Text Overlay Transformations](#text-overlay-transformations)
- [Subtitle Overlay Transformations](#subtitle-overlay-transformations)
- Image and video overlays support most [transformations](#supported-transformations).
See [ImageKit docs](https://imagekit.io/docs/transformations#overlay-using-layers) for more details. | `transformation: [{ fontSize: 50 }]` | +| position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus` (e.g., `center`). | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | +| timing | (When base is a video) Defines when the overlay appears. Accepts an object with `start`, `duration`, and `end` properties (in seconds). | `timing: { start: 5, duration: 10 }` | + + +##### Encoding Options + +Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content. + +For text overlays: +- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`. +- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`). +- Note: In all cases, the text is percent-encoded to ensure URL safety. + +For image, video, and subtitle overlays: +- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used. +- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present. +- For explicit behavior, use `plain` or `base64` to enforce the desired encoding. + +Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required. + +Below is a table describing these options: + +| Option | Description | Use Case | +| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| `auto` | SDK automatically selects between plain and base64 encoding based on the input. | Best for most cases when unsure or input is simple. | +| `plain` | SDK treats the input as plain text. | Use for inputs that are already URL-safe. | +| `base64` | SDK encodes the input using Base64 to ensure URL safety when special characters are present. | Use for complex inputs with characters that require encoding. | + +##### Solid Color Overlay Transformations + +| Option | Description | Example | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| width | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression). | `width: 100` | +| height | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression). | `height: 50` | +| radius | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes. | `radius: "max"` | +| alpha | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent). | `alpha: 5` | + +##### Text Overlay Transformations + +| Option | Description | Example | +| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `width` | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. | `width: 400` | +| `fontSize` | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. | `fontSize: 50` | +| `fontFamily` | Specifies the font family of the overlaid text. Choose from the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) or provide a [custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). | `fontFamily: "Arial"` | +| `fontColor` | Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a standard color name. | `fontColor: "FF0000"` | +| `innerAlignment` | Specifies the inner alignment of the text when the content does not occupy the full width. Supported values: `left`, `right`, `center`. | `innerAlignment: "center"` | +| `padding` | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted. | `padding: 10` | +| `alpha` | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`. | `alpha: 5` | +| `typography` | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, `b_i` for both bold and italics. | `typography: "b"` | +| `background` | Specifies the background color of the text overlay. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. | `background: "red"` | +| `radius` | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` to achieve a circular/oval shape. | `radius: "max"` | +| `rotation` | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation. | `rotation: 90` | +| `flip` | Specifies the flip or mirror option for the text overlay. Supported values: `h` (horizontal), `v` (vertical), `h_v` (both horizontal and vertical), `v_h` (alternative order). | `flip: "h"` | +| `lineHeight` | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression. | `lineHeight: 1.5` | + +##### Subtitle Overlay Transformations + +| Option | Description | Example | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | +| `background` | Specifies the subtitle background color using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). | `background: "blue"` | +| `fontSize` | Sets the font size of subtitle text. Can be specified as a number. | `fontSize: 16` | +| `fontFamily` | Sets the font family of subtitle text. Refer to the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) for available options. | `fontFamily: "Arial"` | +| `color` | Specifies the font color of the subtitle text using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). | `color: "FF0000"` | +| `typography` | Sets the typography style of the subtitle text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. | `typography: "b"` | +| `fontOutline` | Specifies the font outline for subtitles. Requires the outline width (an integer) and the outline color (as a standard color name, RGB, or RGBA) separated by an underscore. Examples include `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`. | `fontOutline: "2_blue"` | +| `fontShadow` | Specifies the font shadow for subtitles. Requires the shadow color (as a standard color name, RGB, or RGBA) and a shadow indent (an integer) separated by an underscore. Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`. | `fontShadow: "blue_2"` | + +For image and video overlay transformation options, refer to the [ImageKit Transformations Documentation](https://imagekit.io/docs/transformations). #### AI and Advanced Transformations *Background Removal:* diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index ead7b23..7afba53 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -518,20 +518,19 @@ export interface TextOverlay extends BaseOverlay { type: "text"; /** - * Specifies the text to be displayed in the overlay. - * The SDK automatically handles special characters and URL encoding. + * Specifies the text to be displayed in the overlay. The SDK automatically handles special characters and encoding. */ text: string; /** - * Specifies how the overlay input text should be encoded. The default is `auto`, which means the SDK will initially treat the text as plain text to improve URL readability. If the text contains special characters, the SDK will automatically switch to `base64` encoding. - * - * You can also explicitly set the encoding to either `plain` or `base64`. - * - * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * Text can be included in the layer as either `i-{input}` (plain text) or `ie-{base64_encoded_input}` (base64). + * By default, the SDK selects the appropriate format based on the input text. + * To always use base64 (`ie-{base64}`), set this parameter to `base64`. + * To always use plain text (`i-{input}`), set it to `plain`. * * Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. */ + encoding: "auto" | "plain" | "base64"; /** @@ -549,15 +548,14 @@ export interface ImageOverlay extends BaseOverlay { input: string; /** - * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. - * - * You can also explicitly set the encoding to either `plain` or `base64`. - * - * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. + * By default, the SDK determines the appropriate format automatically. + * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. + * To always use plain text (`i-{input}`), set it to `plain`. * * Regardless of the encoding method: * - Leading and trailing slashes are removed. - * - Any remaining slashes within the path are replaced with `@@` when using plain text. + * - Remaining slashes within the path are replaced with `@@` when using plain text. */ encoding: "auto" | "plain" | "base64"; @@ -577,15 +575,14 @@ export interface VideoOverlay extends BaseOverlay { input: string; /** - * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. - * - * You can also explicitly set the encoding to either `plain` or `base64`. - * - * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. + * By default, the SDK determines the appropriate format automatically. + * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. + * To always use plain text (`i-{input}`), set it to `plain`. * * Regardless of the encoding method: * - Leading and trailing slashes are removed. - * - Any remaining slashes within the path are replaced with `@@` when using plain text. + * - Remaining slashes within the path are replaced with `@@` when using plain text. */ encoding: "auto" | "plain" | "base64"; @@ -605,15 +602,14 @@ export interface SubtitleOverlay extends BaseOverlay { input: string; /** - * Specifies how the overlay input path should be encoded. The default is `auto`, which means the SDK will initially treat the path as plain text to improve URL readability. If the path contains special characters, the SDK will automatically switch to `base64` encoding. - * - * You can also explicitly set the encoding to either `plain` or `base64`. - * - * The `plain` option uses the format `i-{input}`, while `base64` uses `ie-{base64_encoded_input}`. + * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. + * By default, the SDK determines the appropriate format automatically. + * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. + * To always use plain text (`i-{input}`), set it to `plain`. * * Regardless of the encoding method: * - Leading and trailing slashes are removed. - * - Any remaining slashes within the path are replaced with `@@` when using plain text. + * - Remaining slashes within the path are replaced with `@@` when using plain text. */ encoding: "auto" | "plain" | "base64"; @@ -643,12 +639,12 @@ export interface SolidColorOverlay extends BaseOverlay { export type TextOverlayTransformation = { /** - * Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `backgroundColor`. + * Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `background`. */ width?: number | string; /** - * Specifies the font size of the overlaid text. Accepts a numeric value, a percentage, or an arithmetic expression. + * Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. */ fontSize?: number | string; From fbd63f02a205bb2d35975985aa1de4f655acdad2 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 14:50:12 +0530 Subject: [PATCH 17/29] docs: update README to clarify overlay options and improve encoding descriptions --- README.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e05f0aa..ac6ec1f 100644 --- a/README.md +++ b/README.md @@ -54,10 +54,11 @@ Download a specific version: ``` https://unpkg.com/imagekit-javascript@1.3.0/dist/imagekit.min.js ``` -Or for the latest version, remove the version number: +Or for the latest version, remove the version number (don't use in production as it may break your code if a new major version is released): ``` https://unpkg.com/imagekit-javascript/dist/imagekit.min.js ``` + And include it in your HTML: ```html @@ -250,6 +251,8 @@ var solidColorOverlayURL = imagekit.url({ ##### Overlay Options +ImageKit supports various overlay types, including text, image, video, subtitle, and solid color overlays. Each overlay type has specific configuration options to customize the overlay appearance and behavior. To learn more about how overlays work, refer to the [ImageKit documentation](https://imagekit.io/docs/transformations#overlay-using-layers). + The table below outlines the available overlay configuration options: | Option | Description | Example | @@ -260,8 +263,8 @@ The table below outlines the available overlay configuration options: | color | (For solidColor overlays) RGB/RGBA hex code or color name for the overlay color. | `color: "FF0000"` | | encoding | Defines how the overlay input is encoded. Accepted values: `auto`, `plain`, `base64`. | `encoding: "auto"` | | transformation | An array of transformation objects to style the overlay.
- [Text Overlay Transformations](#text-overlay-transformations)
- [Subtitle Overlay Transformations](#subtitle-overlay-transformations)
- Image and video overlays support most [transformations](#supported-transformations).
See [ImageKit docs](https://imagekit.io/docs/transformations#overlay-using-layers) for more details. | `transformation: [{ fontSize: 50 }]` | -| position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus` (e.g., `center`). | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | -| timing | (When base is a video) Defines when the overlay appears. Accepts an object with `start`, `duration`, and `end` properties (in seconds). | `timing: { start: 5, duration: 10 }` | +| position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. The `focus` value can be one of: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | +| timing | (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. | `timing: { start: 5, duration: 10 }` | ##### Encoding Options @@ -280,14 +283,6 @@ For image, video, and subtitle overlays: Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required. -Below is a table describing these options: - -| Option | Description | Use Case | -| -------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -| `auto` | SDK automatically selects between plain and base64 encoding based on the input. | Best for most cases when unsure or input is simple. | -| `plain` | SDK treats the input as plain text. | Use for inputs that are already URL-safe. | -| `base64` | SDK encodes the input using Base64 to ensure URL safety when special characters are present. | Use for complex inputs with characters that require encoding. | - ##### Solid Color Overlay Transformations | Option | Description | Example | @@ -327,8 +322,6 @@ Below is a table describing these options: | `fontOutline` | Specifies the font outline for subtitles. Requires the outline width (an integer) and the outline color (as a standard color name, RGB, or RGBA) separated by an underscore. Examples include `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`. | `fontOutline: "2_blue"` | | `fontShadow` | Specifies the font shadow for subtitles. Requires the shadow color (as a standard color name, RGB, or RGBA) and a shadow indent (an integer) separated by an underscore. Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`. | `fontShadow: "blue_2"` | -For image and video overlay transformation options, refer to the [ImageKit Transformations Documentation](https://imagekit.io/docs/transformations). - #### AI and Advanced Transformations *Background Removal:* ```js From b4ce1dc7ec9730ab4940ed2cecd7072fd99b47bb Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 15:38:37 +0530 Subject: [PATCH 18/29] change default transformation position to query to better handle wildcard purge. Update test cases to reflect this change. Bump major version to reflect breaking change. --- package-lock.json | 2 +- package.json | 2 +- src/url/builder.ts | 21 +++++++++++++-------- src/utils/transformation.ts | 5 +++-- test/data/index.js | 1 + test/url-generation/basic.js | 23 +++++++++++++++++++---- test/url-generation/overlay.js | 14 ++++++++++++++ 7 files changed, 52 insertions(+), 16 deletions(-) diff --git a/package-lock.json b/package-lock.json index b1f0c3f..7f04be8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.1.0", + "version": "4.0.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 1bbfb44..bdfe653 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "imagekit-javascript", - "version": "3.1.0", + "version": "4.0.0", "description": "Javascript SDK for using ImageKit.io in the browser", "main": "dist/imagekit.cjs.js", "module": "dist/imagekit.esm.js", diff --git a/src/url/builder.ts b/src/url/builder.ts index d014230..932c969 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -45,10 +45,6 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => { return ""; } - // if (opts.sdkVersion && opts.sdkVersion.trim() != "") { - // urlObj.searchParams.append("ik-sdk-version", opts.sdkVersion.trim()); - // } - for (var i in opts.queryParameters) { urlObj.searchParams.append(i, String(opts.queryParameters[i])); } @@ -56,14 +52,12 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => { var transformationString = constructTransformationString(opts.transformation); if (transformationString && transformationString.length) { - if (transformationUtils.addAsQueryParameter(opts) || isSrcParameterUsedForURL) { - urlObj.searchParams.append(TRANSFORMATION_PARAMETER, transformationString); - } else { + if (!transformationUtils.addAsQueryParameter(opts) && !isSrcParameterUsedForURL) { urlObj.pathname = pathJoin([ TRANSFORMATION_PARAMETER + transformationUtils.getChainTransformDelimiter() + transformationString, urlObj.pathname, ]); - } + } } if (urlEndpointPattern) { @@ -72,6 +66,17 @@ export const buildURL = (opts: UrlOptions & ImageKitOptions) => { urlObj.pathname = pathJoin([urlObj.pathname]); } + if (transformationString && transformationString.length) { + if(transformationUtils.addAsQueryParameter(opts) || isSrcParameterUsedForURL) { + if(urlObj.searchParams.toString() !== "") { // In 12 node.js .size was not there. So, we need to check if it is an object or not. + return `${urlObj.href}&${TRANSFORMATION_PARAMETER}=${transformationString}`; + } + else { + return `${urlObj.href}?${TRANSFORMATION_PARAMETER}=${transformationString}`; + } + } + } + return urlObj.href; }; diff --git a/src/utils/transformation.ts b/src/utils/transformation.ts index 0ef2c25..5034d0f 100644 --- a/src/utils/transformation.ts +++ b/src/utils/transformation.ts @@ -1,9 +1,10 @@ import supportedTransforms from "../constants/supportedTransforms"; import { ImageKitOptions, TransformationPosition } from "../interfaces"; -const DEFAULT_TRANSFORMATION_POSITION: TransformationPosition = "path"; const QUERY_TRANSFORMATION_POSITION: TransformationPosition = "query"; -const VALID_TRANSFORMATION_POSITIONS = [DEFAULT_TRANSFORMATION_POSITION, QUERY_TRANSFORMATION_POSITION]; +const PATH_TRANSFORMATION_POSITION: TransformationPosition = "path"; +const DEFAULT_TRANSFORMATION_POSITION: TransformationPosition = QUERY_TRANSFORMATION_POSITION; +const VALID_TRANSFORMATION_POSITIONS = [PATH_TRANSFORMATION_POSITION, QUERY_TRANSFORMATION_POSITION]; const CHAIN_TRANSFORM_DELIMITER: string = ":"; const TRANSFORM_DELIMITER: string = ","; const TRANSFORM_KEY_VALUE_DELIMITER: string = "-"; diff --git a/test/data/index.js b/test/data/index.js index d7676c2..1ec1645 100644 --- a/test/data/index.js +++ b/test/data/index.js @@ -1,4 +1,5 @@ module.exports.initializationParams = { publicKey: "test_public_key", urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + transformationPosition: "path", } \ No newline at end of file diff --git a/test/url-generation/basic.js b/test/url-generation/basic.js index 739f240..b39f645 100644 --- a/test/url-generation/basic.js +++ b/test/url-generation/basic.js @@ -48,6 +48,21 @@ describe("URL generation", function () { expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg`); }); + it("By default transformationPosition should be query", function () { + var imagekitNew = new ImageKit({ + publicKey: "test_public_key", + urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + }); + const url = imagekitNew.url({ + path: "/test_path.jpg", + transformation: [{ + "height": "300", + "width": "400" + }] + }); + expect(url).equal("https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400"); + }); + it('should generate the URL without sdk version', function () { const ik = new ImageKit({ ...initializationParams, sdkVersion: "" }) @@ -111,7 +126,7 @@ describe("URL generation", function () { }] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300%2Cw-400`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400`); }); it('should generate the correct URL with a valid src parameter and transformation', function () { @@ -123,7 +138,7 @@ describe("URL generation", function () { }] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300,w-400`); }); it('should generate the correct URL with transformationPosition as query parameter when src is provided', function () { @@ -136,7 +151,7 @@ describe("URL generation", function () { }] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300%2Cw-400`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?tr=h-300,w-400`); }); it('should merge query parameters correctly in the generated URL', function () { @@ -149,7 +164,7 @@ describe("URL generation", function () { }] }); - expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?t1=v1&t2=v2&t3=v3&tr=h-300%2Cw-400`); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/test_path_alt.jpg?t1=v1&t2=v2&t3=v3&tr=h-300,w-400`); }); diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 3a163f9..86eb13f 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -441,4 +441,18 @@ describe("Overlay encoding test cases", function () { }); expect(url).equal(`https://ik.imagekit.io/demo/tr:l-subtitle,ie-${encodeURIComponent(safeBtoa("sub.srt"))},l-end/sample.mp4`); }); + + it("Avoid double encoding when transformation string is in query params", function () { + const url = imagekit.url({ + path: "/sample.jpg", + transformation: [{ + overlay: { + type: "text", + text: "Minimal Text" + } + }], + transformationPosition: "query" + }); + expect(url).equal(`https://ik.imagekit.io/demo/sample.jpg?tr=l-text,i-Minimal%20Text,l-end`); + }); }); From 34a2b81ba8b65b948b4553acf625590c9a2ac3ad Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 16:29:06 +0530 Subject: [PATCH 19/29] refactor: remove sdkVersion from ImageKitOptions and update constructor accordingly --- README.md | 265 +++++++++++++++++------------- src/index.ts | 3 +- src/interfaces/ImageKitOptions.ts | 1 - test/url-generation/basic.js | 6 +- 4 files changed, 153 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index ac6ec1f..25b159d 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ Lightweight JavaScript SDK for generating optimized URLs for images and videos, - [Promise-based Upload Example](#promise-based-upload-example) - [Test Examples](#test-examples) - [Changelog](#changelog) +- [Options Reference](#options-reference) ## Installation @@ -66,29 +67,47 @@ And include it in your HTML: ## Initialization -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" -}); -``` -For client-side file uploads, include your public key: +Initialize the SDK by specifying your URL endpoint. Obtain your URL endpoint from [here](https://imagekit.io/dashboard/url-endpoints) and your public API key from [developer section](https://imagekit.io/dashboard/developer/api-keys). For URL generation: + ```js var imagekit = new ImageKit({ - publicKey: "your_public_api_key", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", + urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", // Required + transformationPosition: "query", // Optional. Default is "query" + publicKey: "your_public_api_key", // Optional. Only needef for client-side file uploads. }); ``` -*Note: Never include your private key in client-side code. If provided, the SDK throws an error.* + +> Note: Never include your private key in client-side code. If provided, the SDK throws an error. + +### Initialization Options + +| Option | Description | Example | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| urlEndpoint | Required. It is always `https://ik.imagekit.io/your_imagekit_id` or configued custom domain name. | `urlEndpoint: "https://ik.imagekit.io/your_id"` | +| transformationPosition | Optional. Determines the position of the transformation string in the URL. Accepts `path` (as URL segment) or `query` (as query parameter). Default value is `query` so that it is possible for you to issue a wild card purge to remove all generated transformations from the CDN cache. | `transformationPosition: "query"` | +| publicKey | Optional. Your ImageKit public API key. Required for client-side file uploads. | `publicKey: "your_public_api_key"` | + ## URL Generation The SDK’s `.url()` method enables you to generate optimized image and video URLs with a variety of transformations. +The method accepts an object with the following parameters: + +| Option | Description | Example | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| path | The relative path of the image. Either `src` or `path` must be provided. | `"/path/to/image.jpg"` | +| src | The full URL of an image already mapped to ImageKit. Either `src` or `path` must be provided. | `"https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg"` | +| transformation | An array of objects specifying the transformations to be applied in the URL. Each object contains key-value pairs representing transformation parameters. | `[ { width: 300, height: 400 } ]` | +| queryParameters | Additional query parameters to be appended to the URL. | `{ v: 1 }` | + +Optionally, you can include `transformationPosition` and `urlEndpoint` in the object to override the initialization settings on per `.url()` call basis. + ### Basic URL Generation -1. **Using an Image Path with a URL Endpoint** - ```js +*A simple height and width transformation:* + +```js var imageURL = imagekit.url({ path: "/default-image.jpg", urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", @@ -97,26 +116,13 @@ The SDK’s `.url()` method enables you to generate optimized image and video UR 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 - ``` +``` +*Result Example:* +``` +https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300,w-400 +``` + +SDK automatically generates the URL based on the provided parameters. The generated URL includes the base URL, path, and transformation parameters. ### Advanced URL Generation Examples @@ -131,12 +137,12 @@ var imageURL = imagekit.url({ }, { rotation: 90 }], - transformationPosition: "query" // Use query parameter for transformations }); ``` + *Result Example:* ``` -https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300%2Cw-400%3Art-90 +https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300,w-400:rt-90 ``` #### Overlays and Effects @@ -263,10 +269,9 @@ The table below outlines the available overlay configuration options: | color | (For solidColor overlays) RGB/RGBA hex code or color name for the overlay color. | `color: "FF0000"` | | encoding | Defines how the overlay input is encoded. Accepted values: `auto`, `plain`, `base64`. | `encoding: "auto"` | | transformation | An array of transformation objects to style the overlay.
- [Text Overlay Transformations](#text-overlay-transformations)
- [Subtitle Overlay Transformations](#subtitle-overlay-transformations)
- Image and video overlays support most [transformations](#supported-transformations).
See [ImageKit docs](https://imagekit.io/docs/transformations#overlay-using-layers) for more details. | `transformation: [{ fontSize: 50 }]` | -| position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. The `focus` value can be one of: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | +| position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. The `focus` value can be one of: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | | timing | (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. | `timing: { start: 5, duration: 10 }` | - ##### Encoding Options Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content. @@ -294,33 +299,33 @@ Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or ` ##### Text Overlay Transformations -| Option | Description | Example | -| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -| `width` | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. | `width: 400` | -| `fontSize` | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. | `fontSize: 50` | -| `fontFamily` | Specifies the font family of the overlaid text. Choose from the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) or provide a [custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). | `fontFamily: "Arial"` | -| `fontColor` | Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a standard color name. | `fontColor: "FF0000"` | -| `innerAlignment` | Specifies the inner alignment of the text when the content does not occupy the full width. Supported values: `left`, `right`, `center`. | `innerAlignment: "center"` | -| `padding` | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted. | `padding: 10` | -| `alpha` | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`. | `alpha: 5` | -| `typography` | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, `b_i` for both bold and italics. | `typography: "b"` | -| `background` | Specifies the background color of the text overlay. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. | `background: "red"` | -| `radius` | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` to achieve a circular/oval shape. | `radius: "max"` | -| `rotation` | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation. | `rotation: 90` | -| `flip` | Specifies the flip or mirror option for the text overlay. Supported values: `h` (horizontal), `v` (vertical), `h_v` (both horizontal and vertical), `v_h` (alternative order). | `flip: "h"` | -| `lineHeight` | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression. | `lineHeight: 1.5` | +| Option | Description | Example | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | +| width | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400` | +| fontSize | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. | `fontSize: 50` | +| fontFamily | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font. | `fontFamily: "Arial"` | +| fontColor | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name. | `fontColor: "FF0000"` | +| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`. | `innerAlignment: "center"` | +| padding | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted. | `padding: 10` | +| alpha | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`. | `alpha: 5` | +| typography | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. | `typography: "b"` | +| background | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name. | `background: "red"` | +| radius | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape. | `radius: "max"` | +| rotation | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation. | `rotation: 90` | +| flip | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`. | `flip: "h"` | +| lineHeight | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression. | `lineHeight: 1.5` | ##### Subtitle Overlay Transformations -| Option | Description | Example | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | -| `background` | Specifies the subtitle background color using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). | `background: "blue"` | -| `fontSize` | Sets the font size of subtitle text. Can be specified as a number. | `fontSize: 16` | -| `fontFamily` | Sets the font family of subtitle text. Refer to the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) for available options. | `fontFamily: "Arial"` | -| `color` | Specifies the font color of the subtitle text using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). | `color: "FF0000"` | -| `typography` | Sets the typography style of the subtitle text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. | `typography: "b"` | -| `fontOutline` | Specifies the font outline for subtitles. Requires the outline width (an integer) and the outline color (as a standard color name, RGB, or RGBA) separated by an underscore. Examples include `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`. | `fontOutline: "2_blue"` | -| `fontShadow` | Specifies the font shadow for subtitles. Requires the shadow color (as a standard color name, RGB, or RGBA) and a shadow indent (an integer) separated by an underscore. Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`. | `fontShadow: "blue_2"` | +| Option | Description | Example | +| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- | +| background | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code. | `background: "blue"` | +| fontSize | Sets the font size of subtitle text. | `fontSize: 16` | +| fontFamily | Sets the font family of subtitle text. | `fontFamily: "Arial"` | +| color | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code. | `color: "FF0000"` | +| typography | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`. | `typography: "b"` | +| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` | +| fontShadow | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore. | `fontShadow: "blue_2"` | #### AI and Advanced Transformations *Background Removal:* @@ -365,64 +370,65 @@ var imageURL = imagekit.url({ ### 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. +The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is. -If you want to generate transformations in your application and add them to the URL as it is, use the raw parameter. +If you want to generate transformations without any modifications, 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. | +| 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 | +| overlay | Generated correct layer syntax for image, video, text and subtitle overlays. | +| raw | The string provided in raw will be added in the URL as is. | ### Handling Unsupported Transformations @@ -436,7 +442,7 @@ var imageURL = imagekit.url({ newparam: "cool" }] }); -// Generated URL: https://ik.imagekit.io/test_url_endpoint/tr:newparam-cool/test_path.jpg +// Generated URL: https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=newparam-cool ``` ## File Upload @@ -448,6 +454,31 @@ The SDK offers a simple interface via the `.upload()` method to upload files to 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). +### Upload Options +| Option | Description | Example | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| file | The file content to be uploaded. Accepts binary, base64 string, or URL. | `file: fileInput.files[0]` | +| fileName | The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. | `fileName: "myImage.jpg"` | +| signature | HMAC-SHA1 digest computed using the private API key. Must be calculated on the server side. | `signature: "generated_signature"` | +| token | A unique token to prevent duplicate upload retries. Typically a V4 UUID or similar unique string. | `token: "unique_upload_token"` | +| expire | Unix timestamp (in seconds) indicating the signature expiry time (should be within 1 hour). | `expire: 1616161616` | +| useUniqueFileName | Boolean flag to automatically generate a unique filename if set to true. Defaults to true. | `useUniqueFileName: true` | +| folder | The folder path where the file will be uploaded. Automatically creates nested folders if they don’t exist. | `folder: "/images/uploads"` | +| isPrivateFile | Boolean to mark the file as private, restricting access to the original file URL. Defaults to false. | `isPrivateFile: false` | +| tags | Tags to associate with the file. Can be a comma-separated string or an array of tags. | `tags: "summer,holiday"` or `tags: ["summer","holiday"]` | +| customCoordinates | Specifies an area of interest in the image formatted as `x,y,width,height`. | `customCoordinates: "10,10,100,100"` | +| responseFields | Comma-separated list of fields to include in the upload response. | `responseFields: "tags,customCoordinates"` | +| extensions | Array of extension objects for additional image processing. | `extensions: [{ name: "auto-tagging" }]` | +| webhookUrl | URL to which the final status of extension processing will be sent. | `webhookUrl: "https://example.com/webhook"` | +| overwriteFile | Boolean flag indicating whether to overwrite a file if it exists. Defaults to true. | `overwriteFile: true` | +| overwriteAITags | Boolean flag to remove AITags from a file if overwritten. Defaults to true. | `overwriteAITags: true` | +| overwriteTags | Boolean flag that determines if existing tags should be removed when new tags are not provided. Defaults to true when file is overwritten without tags. | `overwriteTags: true` | +| overwriteCustomMetadata | Boolean flag dictating if existing custom metadata should be removed when not provided. Defaults to true under similar conditions as tags. | `overwriteCustomMetadata: true` | +| customMetadata | Stringified JSON or an object containing custom metadata key-value pairs to associate with the file. | `customMetadata: {author: "John Doe"}` | +| transformation | Optional transformation object to apply during the upload process. It follows the same structure as in URL generation. | `transformation: { pre: "w-200,h-200", post: [...] }` | +| xhr | An optional XMLHttpRequest object provided to monitor upload progress. | `xhr: new XMLHttpRequest()` | +| checks | Optional string value for specifying server-side checks to run before file upload. | `checks: "file.size' < '1MB'"` | + ### Basic Upload Example Below is an HTML form example that uses a callback for handling the upload response: @@ -503,9 +534,9 @@ imagekit.upload({ ## Test Examples 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) +- URL Generation examples can be found in [basic](./test/url-generation/basic.js) and [overlay](./test/url-generation/overlay.js) - File Upload examples can be found in [test/upload.js](./test/upload.js) ## Changelog -For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). +For a detailed history of changes, please refer to [CHANGELOG.md](CHANGELOG.md). \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index 9b88b33..6594fa7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -37,13 +37,12 @@ const promisify = function (thisContext: ImageKit, fn: Function) { class ImageKit { options: ImageKitOptions = { - sdkVersion: `javascript-${version}`, publicKey: "", urlEndpoint: "", transformationPosition: transformationUtils.getDefault(), }; - constructor(opts: Omit) { + constructor(opts: ImageKitOptions) { this.options = { ...this.options, ...(opts || {}) }; if (!mandatoryParametersAvailable(this.options)) { throw errorMessages.MANDATORY_INITIALIZATION_MISSING; diff --git a/src/interfaces/ImageKitOptions.ts b/src/interfaces/ImageKitOptions.ts index d7394f0..6f8b78f 100644 --- a/src/interfaces/ImageKitOptions.ts +++ b/src/interfaces/ImageKitOptions.ts @@ -2,7 +2,6 @@ import { TransformationPosition } from "."; export interface ImageKitOptions { urlEndpoint: string; - sdkVersion?: string; publicKey?: string; transformationPosition?: TransformationPosition; } diff --git a/test/url-generation/basic.js b/test/url-generation/basic.js index b39f645..647b539 100644 --- a/test/url-generation/basic.js +++ b/test/url-generation/basic.js @@ -58,13 +58,15 @@ describe("URL generation", function () { transformation: [{ "height": "300", "width": "400" + }, { + rotation: 90 }] }); - expect(url).equal("https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400"); + expect(url).equal("https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400:rt-90"); }); it('should generate the URL without sdk version', function () { - const ik = new ImageKit({ ...initializationParams, sdkVersion: "" }) + const ik = new ImageKit(initializationParams) const url = ik.url({ path: "/test_path.jpg", From 02033ee99137691c6e90173742c390f259e7443c Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:05:49 +0530 Subject: [PATCH 20/29] refactor: remove deprecated transformation effects and update related tests --- src/constants/supportedTransforms.ts | 9 ------- src/interfaces/Transformation.ts | 36 ---------------------------- test/url-generation/basic.js | 18 +++++++------- 3 files changed, 9 insertions(+), 54 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index 52a64c3..8353ceb 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -32,15 +32,6 @@ export const supportedTransforms: { [key: string]: string } = { duration: "du", streamingResolutions: "sr", - // Old deprecated mappings - effectSharpen: "e-sharpen", - effectUSM: "e-usm", - effectContrast: "e-contrast", - effectGray: "e-grayscale", - effectShadow: "e-shadow", - effectGradient: "e-gradient", - rotate: "rt", - // AI & advanced effects grayscale: "e-grayscale", aiUpscale: "e-upscale", diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 7afba53..adbe8dd 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -386,42 +386,6 @@ export interface Transformation { */ 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; /** * Specifies an overlay to be applied on the parent image or video. diff --git a/test/url-generation/basic.js b/test/url-generation/basic.js index 647b539..cb81ef2 100644 --- a/test/url-generation/basic.js +++ b/test/url-generation/basic.js @@ -278,7 +278,7 @@ describe("URL generation", function () { const url = imagekit.url({ path: "/test_path.jpg", transformation: [{ - effectContrast: "-" + contrastStretch: "-" }] }) @@ -291,7 +291,7 @@ describe("URL generation", function () { transformation: [{ defaultImage: "/test_path.jpg", quality: undefined, - effectContrast: null + contrastStretch: null }] }) @@ -303,7 +303,7 @@ describe("URL generation", function () { path: "/test_path1.jpg", transformation: [{ defaultImage: "/test_path.jpg", - effectContrast: false + contrastStretch: false }] }) @@ -910,12 +910,12 @@ describe("URL generation", function () { colorProfile: true, defaultImage: "/folder/file.jpg/", //trailing and leading slash case dpr: 3, - effectSharpen: 10, - effectUSM: "2-2-0.8-0.024", - effectContrast: true, - effectGray: true, - effectShadow: 'bl-15_st-40_x-10_y-N5', - effectGradient: 'from-red_to-white', + sharpen: 10, + unsharpMask: "2-2-0.8-0.024", + contrastStretch: true, + grayscale: true, + shadow: 'bl-15_st-40_x-10_y-N5', + gradient: 'from-red_to-white', original: true, raw: "h-200,w-300,l-image,i-logo.png,l-end" }] From fc2440b545e2df8ae732682d74e42b1287c194fe Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:09:38 +0530 Subject: [PATCH 21/29] docs: remove Options Reference section from README --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 25b159d..b994879 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,6 @@ Lightweight JavaScript SDK for generating optimized URLs for images and videos, - [Promise-based Upload Example](#promise-based-upload-example) - [Test Examples](#test-examples) - [Changelog](#changelog) -- [Options Reference](#options-reference) ## Installation From 696105ad259384229b67d0f419efc789f5b6ff7b Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:20:08 +0530 Subject: [PATCH 22/29] chore: update CHANGELOG for version 4.0.0 with breaking changes and new features --- CHANGELOG.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03d7092..1033ef1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog +## Version 4.0.0 + +### Breaking Changes + +1. The default value for `transformationPosition` is now `query` instead of `path`. This change enables wildcard cache purging to remove CDN cache for all generated transformations. + + **Action Required:** + If you're using the `transformationPosition` parameter in the `url` method and want to apply transformations in the path, you must now explicitly set the value to `path`. The default is `query`. + +2. Removed the following deprecated parameters: + `effectSharpen`, `effectUSM`, `effectContrast`, `effectGray`, `effectShadow`, `effectGradient`, and `rotate`. + +### Other Changes + +1. Native support for overlays has been added. See the README for usage examples. +2. New AI-powered transformations are now supported: + `aiRemoveBackground`, `aiUpscale`, `aiVariation`, `aiDropShadow`, `aiChangeBackground`, and more. + *(Introduced in version 3.1.0)* + +--- + ## SDK Version 3.0.0 ### Breaking Changes From 64c537410cee02ba67053940c733f5a3d898c6ec Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:36:46 +0530 Subject: [PATCH 23/29] fix: update regex for overlay path and text to allow additional safe characters --- src/url/builder.ts | 4 ++-- test/url-generation/overlay.js | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 932c969..ceebc59 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -2,8 +2,8 @@ import { ImageKitOptions, UrlOptions } from "../interfaces"; import { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transformation, VideoOverlay } from "../interfaces/Transformation"; import transformationUtils, { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; -const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._,/ ]*$') -const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._, ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. +const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._/ ]*$') +const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._ ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. function removeTrailingSlash(str: string) { if (typeof str == "string" && str[str.length - 1] == "/") { diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 86eb13f..028a2df 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -318,17 +318,17 @@ describe("Overlay encoding test cases", function () { expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-Manu,l-end/medium_cafe_B1iTdD0C.jpg`); }); - it('Simple text overlay with spaces and comma, should use i instead of ie', function () { + it('Simple text overlay with spaces and other safe characters, should use i instead of ie', function () { const url = imagekit.url({ path: "/medium_cafe_B1iTdD0C.jpg", transformation: [{ overlay: { type: "text", - text: "alnum123-._, ", + text: "alnum123-._ ", } }] }); - expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123-._, ")},l-end/medium_cafe_B1iTdD0C.jpg`); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123-._ ")},l-end/medium_cafe_B1iTdD0C.jpg`); }); it('Non simple text overlay, should use ie instead of i', function () { From c48d189b5a7f07fc14c4ab1f622b151621282e1a Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:42:32 +0530 Subject: [PATCH 24/29] fix: update SIMPLE_OVERLAY_TEXT_REGEX to allow only safe characters in overlay text --- src/url/builder.ts | 2 +- test/url-generation/overlay.js | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index ceebc59..0c22dec 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -3,7 +3,7 @@ import { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transfor import transformationUtils, { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._/ ]*$') -const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._ ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. +const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9._ ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. function removeTrailingSlash(str: string) { if (typeof str == "string" && str[str.length - 1] == "/") { diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 028a2df..0ca07aa 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -324,11 +324,11 @@ describe("Overlay encoding test cases", function () { transformation: [{ overlay: { type: "text", - text: "alnum123-._ ", + text: "alnum123._ ", } }] }); - expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123-._ ")},l-end/medium_cafe_B1iTdD0C.jpg`); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123._ ")},l-end/medium_cafe_B1iTdD0C.jpg`); }); it('Non simple text overlay, should use ie instead of i', function () { From ffe7b1adcc7f10a97530ba078cd113bb6bd53e03 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 17:44:33 +0530 Subject: [PATCH 25/29] Revert "fix: update SIMPLE_OVERLAY_TEXT_REGEX to allow only safe characters in overlay text" This reverts commit c48d189b5a7f07fc14c4ab1f622b151621282e1a. --- src/url/builder.ts | 2 +- test/url-generation/overlay.js | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/url/builder.ts b/src/url/builder.ts index 0c22dec..ceebc59 100644 --- a/src/url/builder.ts +++ b/src/url/builder.ts @@ -3,7 +3,7 @@ import { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transfor import transformationUtils, { safeBtoa } from "../utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._/ ]*$') -const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9._ ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. +const SIMPLE_OVERLAY_TEXT_REGEX = new RegExp('^[a-zA-Z0-9-._ ]*$') // These characters are selected by testing actual URLs on both path and query parameters. If and when backend starts supporting wide range of characters, this regex should be updated to improve URL readability. function removeTrailingSlash(str: string) { if (typeof str == "string" && str[str.length - 1] == "/") { diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 0ca07aa..028a2df 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -324,11 +324,11 @@ describe("Overlay encoding test cases", function () { transformation: [{ overlay: { type: "text", - text: "alnum123._ ", + text: "alnum123-._ ", } }] }); - expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123._ ")},l-end/medium_cafe_B1iTdD0C.jpg`); + expect(url).equal(`https://ik.imagekit.io/demo/tr:l-text,i-${encodeURIComponent("alnum123-._ ")},l-end/medium_cafe_B1iTdD0C.jpg`); }); it('Non simple text overlay, should use ie instead of i', function () { From b47246e8a1edeb1f5dabf65d185ee5144415a199 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 18:03:15 +0530 Subject: [PATCH 26/29] update readme --- README.md | 148 +++++++++++++++++++++++++++--------------------------- 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index b994879..388a52f 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![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) -Lightweight JavaScript SDK for generating optimized URLs for images and videos, and for handling file uploads via ImageKit. +A lightweight JavaScript SDK for generating optimized URLs for images and videos, and for uploading files using ImageKit. ## Table of Contents - [Installation](#installation) @@ -65,26 +65,25 @@ And include it in your HTML: ``` ## Initialization - -Initialize the SDK by specifying your URL endpoint. Obtain your URL endpoint from [here](https://imagekit.io/dashboard/url-endpoints) and your public API key from [developer section](https://imagekit.io/dashboard/developer/api-keys). For URL generation: +To use the SDK, initialize it with your ImageKit URL endpoint. You can get the URL endpoint [here](https://imagekit.io/dashboard/url-endpoints) and your public API key from the [developer section](https://imagekit.io/dashboard/developer/api-keys): ```js var imagekit = new ImageKit({ urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", // Required - transformationPosition: "query", // Optional. Default is "query" - publicKey: "your_public_api_key", // Optional. Only needef for client-side file uploads. + transformationPosition: "query", // Optional, defaults to "query" + publicKey: "your_public_api_key", // Optional, required only for client-side file uploads }); ``` -> Note: Never include your private key in client-side code. If provided, the SDK throws an error. +> Note: Never include your private API key in client-side code. The SDK will throw an error if you do. ### Initialization Options -| Option | Description | Example | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| urlEndpoint | Required. It is always `https://ik.imagekit.io/your_imagekit_id` or configued custom domain name. | `urlEndpoint: "https://ik.imagekit.io/your_id"` | -| transformationPosition | Optional. Determines the position of the transformation string in the URL. Accepts `path` (as URL segment) or `query` (as query parameter). Default value is `query` so that it is possible for you to issue a wild card purge to remove all generated transformations from the CDN cache. | `transformationPosition: "query"` | -| publicKey | Optional. Your ImageKit public API key. Required for client-side file uploads. | `publicKey: "your_public_api_key"` | +| Option | Description | Example | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| urlEndpoint | Required. Your ImageKit URL endpoint or custom domain. | `urlEndpoint: "https://ik.imagekit.io/your_id"` | +| transformationPosition | Optional. Specifies whether transformations are added as URL path segments (`path`) or query parameters (`query`). The default is `query`, which allows you to perform wildcard purges and remove all generated transformations from the CDN cache. | `transformationPosition: "query"` | +| publicKey | Optional. Your public API key for client-side uploads. | `publicKey: "your_public_api_key"` | ## URL Generation @@ -93,14 +92,14 @@ The SDK’s `.url()` method enables you to generate optimized image and video UR The method accepts an object with the following parameters: -| Option | Description | Example | -| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -| path | The relative path of the image. Either `src` or `path` must be provided. | `"/path/to/image.jpg"` | -| src | The full URL of an image already mapped to ImageKit. Either `src` or `path` must be provided. | `"https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg"` | -| transformation | An array of objects specifying the transformations to be applied in the URL. Each object contains key-value pairs representing transformation parameters. | `[ { width: 300, height: 400 } ]` | -| queryParameters | Additional query parameters to be appended to the URL. | `{ v: 1 }` | +| Option | Description | Example | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| path | The relative path of the image. Either `src` or `path` must be provided. | `"/path/to/image.jpg"` | +| src | The full URL of an image already mapped to ImageKit. Either `src` or `path` must be provided. | `"https://ik.imagekit.io/your_imagekit_id/path/to/image.jpg"` | +| transformation | An array of objects specifying the transformations to be applied in the URL. Each object contains key-value pairs representing transformation parameters. See [supported transformations](#supported-transformations). | `[ { width: 300, height: 400 } ]` | +| queryParameters | Additional query parameters to be appended to the URL. | `{ v: 1 }` | -Optionally, you can include `transformationPosition` and `urlEndpoint` in the object to override the initialization settings on per `.url()` call basis. +Optionally, you can include `transformationPosition` and `urlEndpoint` in the object to override the initialization settings for a specific `.url()` call. ### Basic URL Generation @@ -116,6 +115,7 @@ Optionally, you can include `transformationPosition` and `urlEndpoint` in the ob }] }); ``` + *Result Example:* ``` https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300,w-400 @@ -375,59 +375,59 @@ If you want to generate transformations without any modifications, use the `raw` 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 | -| overlay | Generated correct layer syntax for image, video, text and subtitle overlays. | -| raw | The string provided in raw will be added in the URL as is. | +| 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 | +| overlay | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. | +| raw | The string provided in raw will be added in the URL as is. | ### Handling Unsupported Transformations @@ -532,9 +532,9 @@ imagekit.upload({ ## Test Examples -For a quick demonstration of the SDK features, refer to our test examples: -- URL Generation examples can be found in [basic](./test/url-generation/basic.js) and [overlay](./test/url-generation/overlay.js) -- File Upload examples can be found in [test/upload.js](./test/upload.js) +For a quick demonstration of the SDK features, check the test suite: +- URL generation examples can be found in [basic](./test/url-generation/basic.js) and [overlay](./test/url-generation/overlay.js) +- File upload examples can be found in [test/upload.js](./test/upload.js) ## Changelog From 58c087f538f6b784c887a05c953e39f4ea620fbb Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 18:06:29 +0530 Subject: [PATCH 27/29] docs: improve README formatting and clarify encoding options --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 388a52f..2111387 100644 --- a/README.md +++ b/README.md @@ -106,14 +106,14 @@ Optionally, you can include `transformationPosition` and `urlEndpoint` in the ob *A simple height and width transformation:* ```js - var imageURL = imagekit.url({ - path: "/default-image.jpg", - urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", - transformation: [{ - height: 300, - width: 400 - }] - }); +var imageURL = imagekit.url({ + path: "/default-image.jpg", + urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/", + transformation: [{ + height: 300, + width: 400 + }] +}); ``` *Result Example:* @@ -266,7 +266,7 @@ The table below outlines the available overlay configuration options: | text | (For text overlays) The text content to display. | `text: "ImageKit"` | | input | (For image, video, or subtitle overlays) Relative path to the overlay asset. | `input: "logo.png"` or `input: "overlay-video.mp4"` | | color | (For solidColor overlays) RGB/RGBA hex code or color name for the overlay color. | `color: "FF0000"` | -| encoding | Defines how the overlay input is encoded. Accepted values: `auto`, `plain`, `base64`. | `encoding: "auto"` | +| encoding | Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. | `encoding: "auto"` | | transformation | An array of transformation objects to style the overlay.
- [Text Overlay Transformations](#text-overlay-transformations)
- [Subtitle Overlay Transformations](#subtitle-overlay-transformations)
- Image and video overlays support most [transformations](#supported-transformations).
See [ImageKit docs](https://imagekit.io/docs/transformations#overlay-using-layers) for more details. | `transformation: [{ fontSize: 50 }]` | | position | Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. The `focus` value can be one of: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. | `position: { x: 10, y: 20 }` or `position: { focus: "center" }` | | timing | (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. | `timing: { start: 5, duration: 10 }` | From 7e5a1d758e4d88100837f4ec05bce8b2f4c389ce Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Mon, 31 Mar 2025 22:13:56 +0530 Subject: [PATCH 28/29] fix: update package.json to remove duplicate entries and add new keywords --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index bdfe653..2e5d45f 100644 --- a/package.json +++ b/package.json @@ -56,13 +56,13 @@ "javascript", "sdk", "js", - "sdk", "image", "optimization", - "image", "transformation", - "image", - "resize" + "resize", + "upload", + "video", + "overlay" ], "author": "ImageKit Developer", "license": "MIT", From 909cb8d9a4a857ef7c8f964e131fbeb7e229d0a3 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Tue, 1 Apr 2025 09:20:33 +0530 Subject: [PATCH 29/29] docs: enhance README description for clarity and browser usage --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2111387..c79c405 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![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) -A lightweight JavaScript SDK for generating optimized URLs for images and videos, and for uploading files using ImageKit. +A lightweight JavaScript SDK for generating image and video URLs with transformations, and for uploading files directly from the browser to ImageKit. This SDK is intended for use in the browser only. For Node.js, please refer to our official [Node.js SDK](https://github.com/imagekit-developer/imagekit-nodejs). ## Table of Contents - [Installation](#installation)