feat: add encoding options for overlay input paths and texts

Author: manu4543

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.
      * 

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;
         }

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

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`);
+    });
+});