@imagekit/javascript 5.0.0-beta.7 → 5.1.0-beta.1

package/README.md

@@ -2,8 +2,6 @@
 
 # ImageKit.io JavaScript SDK
 
-![gzip size](https://img.badgesize.io/https://unpkg.com/@imagekit/javascript/dist/imagekit.min.js?compression=gzip&label=gzip)
-![brotli size](https://img.badgesize.io/https://unpkg.com/@imagekit/javascript/dist/imagekit.min.js?compression=brotli&label=brotli)
 ![Node CI](https://github.com/imagekit-developer/imagekit-javascript/workflows/Node%20CI/badge.svg)
 [![npm version](https://img.shields.io/npm/v/@imagekit/javascript)](https://www.npmjs.com/package/@imagekit/javascript) 
 [![codecov](https://codecov.io/gh/imagekit-developer/imagekit-javascript/branch/master/graph/badge.svg)](https://codecov.io/gh/imagekit-developer/imagekit-javascript)

package/dist/imagekit.cjs.js

@@ -579,10 +579,98 @@ const buildTransformationString = function (transformation) {
   return parsedTransforms.join(transformationUtils.getChainTransformDelimiter());
 };
 
+const DEFAULT_DEVICE_BREAKPOINTS = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const DEFAULT_IMAGE_BREAKPOINTS = [16, 32, 48, 64, 96, 128, 256, 384];
+function getResponsiveImageAttributes(opts) {
+  const {
+    src,
+    urlEndpoint,
+    transformation = [],
+    queryParameters,
+    transformationPosition,
+    sizes,
+    width,
+    deviceBreakpoints = DEFAULT_DEVICE_BREAKPOINTS,
+    imageBreakpoints = DEFAULT_IMAGE_BREAKPOINTS
+  } = opts;
+  const sortedDeviceBreakpoints = [...deviceBreakpoints].sort((a, b) => a - b);
+  const sortedImageBreakpoints = [...imageBreakpoints].sort((a, b) => a - b);
+  const allBreakpoints = [...sortedImageBreakpoints, ...sortedDeviceBreakpoints].sort((a, b) => a - b);
+  const {
+    candidates,
+    descriptorKind
+  } = computeCandidateWidths({
+    allBreakpoints,
+    deviceBreakpoints: sortedDeviceBreakpoints,
+    explicitWidth: width,
+    sizesAttr: sizes
+  });
+  const buildURL = w => buildSrc({
+    src,
+    urlEndpoint,
+    queryParameters,
+    transformationPosition,
+    transformation: [...transformation, {
+      width: w,
+      crop: 'at_max'
+    }
+    ]
+  });
+  const srcSet = candidates.map((w, i) => `${buildURL(w)} ${descriptorKind === 'w' ? w : i + 1}${descriptorKind}`).join(', ') || undefined;
+  const finalSizes = sizes ?? (descriptorKind === 'w' ? '100vw' : undefined);
+  return {
+    src: buildURL(candidates[candidates.length - 1]),
+    srcSet,
+    ...(finalSizes ? {
+      sizes: finalSizes
+    } : {}),
+    ...(width !== undefined ? {
+      width
+    } : {})
+  };
+}
+function computeCandidateWidths(params) {
+  const {
+    allBreakpoints,
+    deviceBreakpoints,
+    explicitWidth,
+    sizesAttr
+  } = params;
+  if (sizesAttr) {
+    const vwTokens = sizesAttr.match(/(^|\s)(1?\d{1,2})vw/g) || [];
+    const vwPercents = vwTokens.map(t => parseInt(t, 10));
+    if (vwPercents.length) {
+      const smallestRatio = Math.min(...vwPercents) / 100;
+      const minRequiredPx = deviceBreakpoints[0] * smallestRatio;
+      return {
+        candidates: allBreakpoints.filter(w => w >= minRequiredPx),
+        descriptorKind: 'w'
+      };
+    }
+    return {
+      candidates: allBreakpoints,
+      descriptorKind: 'w'
+    };
+  }
+  if (typeof explicitWidth !== 'number') {
+    return {
+      candidates: deviceBreakpoints,
+      descriptorKind: 'w'
+    };
+  }
+  const nearest = t => allBreakpoints.find(n => n >= t) || allBreakpoints[allBreakpoints.length - 1];
+  const unique = Array.from(new Set([nearest(explicitWidth), nearest(explicitWidth * 2)]));
+  return {
+    candidates: unique,
+    descriptorKind: 'x'
+  };
+}
+
 exports.ImageKitAbortError = ImageKitAbortError;
 exports.ImageKitInvalidRequestError = ImageKitInvalidRequestError;
 exports.ImageKitServerError = ImageKitServerError;
 exports.ImageKitUploadNetworkError = ImageKitUploadNetworkError;
 exports.buildSrc = buildSrc;
 exports.buildTransformationString = buildTransformationString;
+exports.getResponsiveImageAttributes = getResponsiveImageAttributes;
 exports.upload = upload;

package/dist/imagekit.esm.js

@@ -575,4 +575,91 @@ const buildTransformationString = function (transformation) {
   return parsedTransforms.join(transformationUtils.getChainTransformDelimiter());
 };
 
-export { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, buildSrc, buildTransformationString, upload };
+const DEFAULT_DEVICE_BREAKPOINTS = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const DEFAULT_IMAGE_BREAKPOINTS = [16, 32, 48, 64, 96, 128, 256, 384];
+function getResponsiveImageAttributes(opts) {
+  const {
+    src,
+    urlEndpoint,
+    transformation = [],
+    queryParameters,
+    transformationPosition,
+    sizes,
+    width,
+    deviceBreakpoints = DEFAULT_DEVICE_BREAKPOINTS,
+    imageBreakpoints = DEFAULT_IMAGE_BREAKPOINTS
+  } = opts;
+  const sortedDeviceBreakpoints = [...deviceBreakpoints].sort((a, b) => a - b);
+  const sortedImageBreakpoints = [...imageBreakpoints].sort((a, b) => a - b);
+  const allBreakpoints = [...sortedImageBreakpoints, ...sortedDeviceBreakpoints].sort((a, b) => a - b);
+  const {
+    candidates,
+    descriptorKind
+  } = computeCandidateWidths({
+    allBreakpoints,
+    deviceBreakpoints: sortedDeviceBreakpoints,
+    explicitWidth: width,
+    sizesAttr: sizes
+  });
+  const buildURL = w => buildSrc({
+    src,
+    urlEndpoint,
+    queryParameters,
+    transformationPosition,
+    transformation: [...transformation, {
+      width: w,
+      crop: 'at_max'
+    }
+    ]
+  });
+  const srcSet = candidates.map((w, i) => `${buildURL(w)} ${descriptorKind === 'w' ? w : i + 1}${descriptorKind}`).join(', ') || undefined;
+  const finalSizes = sizes ?? (descriptorKind === 'w' ? '100vw' : undefined);
+  return {
+    src: buildURL(candidates[candidates.length - 1]),
+    srcSet,
+    ...(finalSizes ? {
+      sizes: finalSizes
+    } : {}),
+    ...(width !== undefined ? {
+      width
+    } : {})
+  };
+}
+function computeCandidateWidths(params) {
+  const {
+    allBreakpoints,
+    deviceBreakpoints,
+    explicitWidth,
+    sizesAttr
+  } = params;
+  if (sizesAttr) {
+    const vwTokens = sizesAttr.match(/(^|\s)(1?\d{1,2})vw/g) || [];
+    const vwPercents = vwTokens.map(t => parseInt(t, 10));
+    if (vwPercents.length) {
+      const smallestRatio = Math.min(...vwPercents) / 100;
+      const minRequiredPx = deviceBreakpoints[0] * smallestRatio;
+      return {
+        candidates: allBreakpoints.filter(w => w >= minRequiredPx),
+        descriptorKind: 'w'
+      };
+    }
+    return {
+      candidates: allBreakpoints,
+      descriptorKind: 'w'
+    };
+  }
+  if (typeof explicitWidth !== 'number') {
+    return {
+      candidates: deviceBreakpoints,
+      descriptorKind: 'w'
+    };
+  }
+  const nearest = t => allBreakpoints.find(n => n >= t) || allBreakpoints[allBreakpoints.length - 1];
+  const unique = Array.from(new Set([nearest(explicitWidth), nearest(explicitWidth * 2)]));
+  return {
+    candidates: unique,
+    descriptorKind: 'x'
+  };
+}
+
+export { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, buildSrc, buildTransformationString, getResponsiveImageAttributes, upload };

package/dist/imagekit.min.js

@@ -1 +1 @@
-!function(e,r){"object"==typeof exports&&"undefined"!=typeof module?r(exports):"function"==typeof define&&define.amd?define(["exports"],r):r((e="undefined"!=typeof globalThis?globalThis:e||self).ImageKit={})}(this,(function(e){"use strict";var r={message:"Missing file parameter for upload"},t={message:"Missing fileName parameter for upload"},n={message:"Missing public key for upload"},s={message:"Request to ImageKit upload endpoint failed due to network error"},a={message:"Missing signature for upload. The SDK expects token, signature and expire for authentication."},o={message:"Missing token for upload. The SDK expects token, signature and expire for authentication."},i={message:"Missing expire for upload. The SDK expects token, signature and expire for authentication."},u={message:"Invalid transformation parameter. Please include at least pre, post, or both."},l={message:"Invalid pre transformation parameter."},p={message:"Invalid post transformation parameter."};class c extends Error{constructor(e,r){super(e),this.$ResponseMetadata=void 0,this.name="ImageKitInvalidRequestError",this.$ResponseMetadata=r}}class f extends Error{constructor(e,r){super(e),this.reason=void 0,this.name="ImageKitAbortError",this.reason=r}}class d extends Error{constructor(e){super(e),this.name="ImageKitUploadNetworkError"}}class g extends Error{constructor(e,r){super(e),this.$ResponseMetadata=void 0,this.name="ImageKitServerError",this.$ResponseMetadata=r}}const m=(e,r)=>{let t={...e};const n=h(r);return Object.defineProperty(t,"$ResponseMetadata",{value:n,enumerable:!1,writable:!1}),t},h=e=>{const r=function(e){const r={},t=e.getAllResponseHeaders();Object.keys(t).length&&t.trim().split(/[\r\n]+/).map(e=>e.split(/: /)).forEach(e=>{r[e[0].trim().toLowerCase()]=e[1].trim()});return r}(e);return{statusCode:e.status,headers:r,requestId:r["x-request-id"]}};const y={width:"w",height:"h",aspectRatio:"ar",background:"bg",border:"b",crop:"c",cropMode:"cm",dpr:"dpr",focus:"fo",quality:"q",x:"x",xCenter:"xc",y:"y",yCenter:"yc",format:"f",videoCodec:"vc",audioCodec:"ac",radius:"r",rotation:"rt",blur:"bl",named:"n",defaultImage:"di",flip:"fl",original:"orig",startOffset:"so",endOffset:"eo",duration:"du",streamingResolutions:"sr",grayscale:"e-grayscale",aiUpscale:"e-upscale",aiRetouch:"e-retouch",aiVariation:"e-genvar",aiDropShadow:"e-dropshadow",aiChangeBackground:"e-changebg",aiRemoveBackground:"e-bgremove",aiRemoveBackgroundExternal:"e-removedotbg",contrastStretch:"e-contrast",shadow:"e-shadow",sharpen:"e-sharpen",unsharpMask:"e-usm",gradient:"e-gradient",progressive:"pr",lossless:"lo",colorProfile:"cp",metadata:"md",opacity:"o",trim:"t",zoom:"z",page:"pg",fontSize:"fs",fontFamily:"ff",fontColor:"co",innerAlignment:"ia",padding:"pa",alpha:"al",typography:"tg",lineHeight:"lh",fontOutline:"fol",fontShadow:"fsh",raw:"raw"};var b=e=>"query"===e.transformationPosition,v=function(e){return e&&(y[e]||y[e.toLowerCase()])||""},w=function(){return":"},x=function(){return","},S=function(){return"-"};const k=function(e){return"undefined"!=typeof window?btoa(e):Buffer.from(e,"utf8").toString("base64")},R=new RegExp("^[a-zA-Z0-9-._/ ]*$"),I=new RegExp("^[a-zA-Z0-9-._ ]*$");function E(e){return"string"==typeof e&&"/"==e[e.length-1]&&(e=e.substring(0,e.length-1)),e}function M(e){return"string"==typeof e&&"/"==e[0]&&(e=e.slice(1)),e}function j(e,r){var t=r||"/",n=new RegExp(t+"{1,}","g");return e.join(t).replace(n,t)}function A(e,r){return e=E(M(e)),"plain"===r?"i-"+e.replace(/\//g,"@@"):"base64"===r?"ie-"+encodeURIComponent(k(e)):R.test(e)?"i-"+e.replace(/\//g,"@@"):"ie-"+encodeURIComponent(k(e))}function P(e){const r=[],{type:t,position:n={},timing:s={},transformation:a=[]}=e||{};if(!t)return;switch(t){case"text":{const t=e;if(!t.text)return;const n=t.encoding||"auto";r.push("l-text"),r.push(function(e,r){return"plain"===r?"i-"+encodeURIComponent(e):"base64"===r?"ie-"+encodeURIComponent(k(e)):I.test(e)?"i-"+encodeURIComponent(e):"ie-"+encodeURIComponent(k(e))}(t.text,n))}break;case"image":r.push("l-image");{const t=e,n=t.encoding||"auto";if(!t.input)return;r.push(A(t.input,n))}break;case"video":r.push("l-video");{const t=e,n=t.encoding||"auto";if(!t.input)return;r.push(A(t.input,n))}break;case"subtitle":r.push("l-subtitle");{const t=e,n=t.encoding||"auto";if(!t.input)return;r.push(A(t.input,n))}break;case"solidColor":r.push("l-image"),r.push("i-ik_canvas");{const t=e;if(!t.color)return;r.push("bg-"+t.color)}}const{x:o,y:i,focus:u}=n;o&&r.push("lx-"+o),i&&r.push("ly-"+i),u&&r.push("lfo-"+u);const{start:l,end:p,duration:c}=s;l&&r.push("lso-"+l),p&&r.push("leo-"+p),c&&r.push("ldu-"+c);const f=O(a);return f&&""!==f.trim()&&r.push(f),r.push("l-end"),r.join(x())}const O=function(e){if(!Array.isArray(e))return"";for(var r=[],t=0,n=e.length;t<n;t++){var s=[];for(var a in e[t]){let r=e[t][a];if(null!=r)if("overlay"!==a||"object"!=typeof r){var o=v(a);if(o||(o=a),""!==o)if(["e-grayscale","e-contrast","e-removedotbg","e-bgremove","e-upscale","e-retouch","e-genvar"].includes(o)){if(!0!==r&&"-"!==r&&"true"!==r)continue;s.push(o)}else!["e-sharpen","e-shadow","e-gradient","e-usm","e-dropshadow"].includes(o)||""!==r.toString().trim()&&!0!==r&&"true"!==r?"raw"===a?s.push(e[t][a]):("di"===o&&(r=E(M(r||"")),r=r.replace(/\//g,"@@")),"sr"===o&&Array.isArray(r)&&(r=r.join("_")),"t"===o&&""===r.toString().trim()&&(r="true"),s.push([o,r].join(S()))):s.push(o)}else{var i=P(r);i&&""!==i.trim()&&s.push(i)}}s.length&&r.push(s.join(x()))}return r.join(w())};e.ImageKitAbortError=f,e.ImageKitInvalidRequestError=c,e.ImageKitServerError=g,e.ImageKitUploadNetworkError=d,e.buildSrc=e=>{if(e.urlEndpoint=e.urlEndpoint||"",e.src=e.src||"",e.transformationPosition=e.transformationPosition||"query",!e.src)return"";const r=e.src.startsWith("http://")||e.src.startsWith("https://");var t,n,s;try{r?(t=new URL(e.src),n=!0):(s=new URL(e.urlEndpoint).pathname,t=new URL(j([e.urlEndpoint.replace(s,""),e.src])))}catch(e){return console.error(e),""}for(var a in e.queryParameters)t.searchParams.append(a,String(e.queryParameters[a]));var o=O(e.transformation);return o&&o.length&&(b(e)||n||(t.pathname=j(["tr"+w()+o,t.pathname]))),t.pathname=j(s?[s,t.pathname]:[t.pathname]),o&&o.length&&(b(e)||n)?""!==t.searchParams.toString()?`${t.href}&tr=${o}`:`${t.href}?tr=${o}`:t.href},e.buildTransformationString=O,e.upload=e=>e?new Promise((y,b)=>{const{xhr:v}=e||{};delete e.xhr;const w=v||new XMLHttpRequest;if(!e.file)return b(new c(r.message));if(!e.fileName)return b(new c(t.message));if(!e.publicKey||0===e.publicKey.length)return b(new c(n.message));if(!e.token)return b(new c(o.message));if(!e.signature)return b(new c(a.message));if(!e.expire)return b(new c(i.message));if(e.transformation){if(!Object.keys(e.transformation).includes("pre")&&!Object.keys(e.transformation).includes("post"))return b(new c(u.message));if(Object.keys(e.transformation).includes("pre")&&!e.transformation.pre)return b(new c(l.message));if(Object.keys(e.transformation).includes("post")){if(!Array.isArray(e.transformation.post))return b(new c(p.message));for(let r of e.transformation.post){if("abs"===r.type&&!r.protocol&&!r.value)return b(new c(p.message));if("transformation"===r.type&&!r.value)return b(new c(p.message))}}}var x=new FormData;let S;for(S in e)if(S)if("file"===S&&"string"!=typeof e.file)x.set("file",e.file,String(e.fileName));else if("tags"===S&&Array.isArray(e.tags))x.set("tags",e.tags.join(","));else if("signature"===S)x.set("signature",e.signature);else if("expire"===S)x.set("expire",String(e.expire));else if("token"===S)x.set("token",e.token);else if("responseFields"===S&&Array.isArray(e.responseFields))x.set("responseFields",e.responseFields.join(","));else if("extensions"===S&&Array.isArray(e.extensions))x.set("extensions",JSON.stringify(e.extensions));else if("customMetadata"!==S||"object"!=typeof e.customMetadata||Array.isArray(e.customMetadata)||null===e.customMetadata){if("transformation"===S&&"object"==typeof e.transformation&&null!==e.transformation)x.set(S,JSON.stringify(e.transformation));else if("checks"===S&&e.checks)x.set("checks",e.checks);else if(void 0!==e[S]){if(["onProgress","abortSignal"].includes(S))continue;x.set(S,String(e[S]))}}else x.set("customMetadata",JSON.stringify(e.customMetadata));function k(){var r;return w.abort(),b(new f("Upload aborted",null===(r=e.abortSignal)||void 0===r?void 0:r.reason))}if(e.onProgress&&(w.upload.onprogress=function(r){e.onProgress&&e.onProgress(r)}),e.abortSignal){var R;if(e.abortSignal.aborted)return b(new f("Upload aborted",null===(R=e.abortSignal)||void 0===R?void 0:R.reason));e.abortSignal.addEventListener("abort",k),w.addEventListener("loadend",()=>{e.abortSignal&&e.abortSignal.removeEventListener("abort",k)})}w.open("POST","https://upload.imagekit.io/api/v1/files/upload"),w.onerror=function(e){return b(new d(s.message))},w.onload=function(){if(w.status>=200&&w.status<300)try{var e=JSON.parse(w.responseText),r=m(e,w);return y(r)}catch(e){return b(e)}else if(w.status>=400&&w.status<500)try{e=JSON.parse(w.responseText);return b(new c(e.message??"Invalid request. Please check the parameters.",h(w)))}catch(e){return b(e)}else try{e=JSON.parse(w.responseText);return b(new g(e.message??"Server error occurred while uploading the file. This is rare and usually temporary.",h(w)))}catch(e){return b(new g("Server error occurred while uploading the file. This is rare and usually temporary.",h(w)))}},w.send(x)}):Promise.reject(new c("Invalid options provided for upload")),Object.defineProperty(e,"__esModule",{value:!0})}));
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).ImageKit={})}(this,(function(e){"use strict";var t={message:"Missing file parameter for upload"},r={message:"Missing fileName parameter for upload"},n={message:"Missing public key for upload"},s={message:"Request to ImageKit upload endpoint failed due to network error"},o={message:"Missing signature for upload. The SDK expects token, signature and expire for authentication."},a={message:"Missing token for upload. The SDK expects token, signature and expire for authentication."},i={message:"Missing expire for upload. The SDK expects token, signature and expire for authentication."},u={message:"Invalid transformation parameter. Please include at least pre, post, or both."},c={message:"Invalid pre transformation parameter."},p={message:"Invalid post transformation parameter."};class l extends Error{constructor(e,t){super(e),this.$ResponseMetadata=void 0,this.name="ImageKitInvalidRequestError",this.$ResponseMetadata=t}}class d extends Error{constructor(e,t){super(e),this.reason=void 0,this.name="ImageKitAbortError",this.reason=t}}class f extends Error{constructor(e){super(e),this.name="ImageKitUploadNetworkError"}}class g extends Error{constructor(e,t){super(e),this.$ResponseMetadata=void 0,this.name="ImageKitServerError",this.$ResponseMetadata=t}}const m=(e,t)=>{let r={...e};const n=h(t);return Object.defineProperty(r,"$ResponseMetadata",{value:n,enumerable:!1,writable:!1}),r},h=e=>{const t=function(e){const t={},r=e.getAllResponseHeaders();Object.keys(r).length&&r.trim().split(/[\r\n]+/).map(e=>e.split(/: /)).forEach(e=>{t[e[0].trim().toLowerCase()]=e[1].trim()});return t}(e);return{statusCode:e.status,headers:t,requestId:t["x-request-id"]}};const y={width:"w",height:"h",aspectRatio:"ar",background:"bg",border:"b",crop:"c",cropMode:"cm",dpr:"dpr",focus:"fo",quality:"q",x:"x",xCenter:"xc",y:"y",yCenter:"yc",format:"f",videoCodec:"vc",audioCodec:"ac",radius:"r",rotation:"rt",blur:"bl",named:"n",defaultImage:"di",flip:"fl",original:"orig",startOffset:"so",endOffset:"eo",duration:"du",streamingResolutions:"sr",grayscale:"e-grayscale",aiUpscale:"e-upscale",aiRetouch:"e-retouch",aiVariation:"e-genvar",aiDropShadow:"e-dropshadow",aiChangeBackground:"e-changebg",aiRemoveBackground:"e-bgremove",aiRemoveBackgroundExternal:"e-removedotbg",contrastStretch:"e-contrast",shadow:"e-shadow",sharpen:"e-sharpen",unsharpMask:"e-usm",gradient:"e-gradient",progressive:"pr",lossless:"lo",colorProfile:"cp",metadata:"md",opacity:"o",trim:"t",zoom:"z",page:"pg",fontSize:"fs",fontFamily:"ff",fontColor:"co",innerAlignment:"ia",padding:"pa",alpha:"al",typography:"tg",lineHeight:"lh",fontOutline:"fol",fontShadow:"fsh",raw:"raw"};var v=e=>"query"===e.transformationPosition,b=function(e){return e&&(y[e]||y[e.toLowerCase()])||""},w=function(){return":"},x=function(){return","},k=function(){return"-"};const S=function(e){return"undefined"!=typeof window?btoa(e):Buffer.from(e,"utf8").toString("base64")},R=new RegExp("^[a-zA-Z0-9-._/ ]*$"),I=new RegExp("^[a-zA-Z0-9-._ ]*$");function E(e){return"string"==typeof e&&"/"==e[e.length-1]&&(e=e.substring(0,e.length-1)),e}function A(e){return"string"==typeof e&&"/"==e[0]&&(e=e.slice(1)),e}function P(e,t){var r=t||"/",n=new RegExp(r+"{1,}","g");return e.join(r).replace(n,r)}const M=e=>{if(e.urlEndpoint=e.urlEndpoint||"",e.src=e.src||"",e.transformationPosition=e.transformationPosition||"query",!e.src)return"";const t=e.src.startsWith("http://")||e.src.startsWith("https://");var r,n,s;try{t?(r=new URL(e.src),n=!0):(s=new URL(e.urlEndpoint).pathname,r=new URL(P([e.urlEndpoint.replace(s,""),e.src])))}catch(e){return console.error(e),""}for(var o in e.queryParameters)r.searchParams.append(o,String(e.queryParameters[o]));var a=O(e.transformation);return a&&a.length&&(v(e)||n||(r.pathname=P(["tr"+w()+a,r.pathname]))),r.pathname=P(s?[s,r.pathname]:[r.pathname]),a&&a.length&&(v(e)||n)?""!==r.searchParams.toString()?`${r.href}&tr=${a}`:`${r.href}?tr=${a}`:r.href};function j(e,t){return e=E(A(e)),"plain"===t?"i-"+e.replace(/\//g,"@@"):"base64"===t?"ie-"+encodeURIComponent(S(e)):R.test(e)?"i-"+e.replace(/\//g,"@@"):"ie-"+encodeURIComponent(S(e))}function K(e){const t=[],{type:r,position:n={},timing:s={},transformation:o=[]}=e||{};if(!r)return;switch(r){case"text":{const r=e;if(!r.text)return;const n=r.encoding||"auto";t.push("l-text"),t.push(function(e,t){return"plain"===t?"i-"+encodeURIComponent(e):"base64"===t?"ie-"+encodeURIComponent(S(e)):I.test(e)?"i-"+encodeURIComponent(e):"ie-"+encodeURIComponent(S(e))}(r.text,n))}break;case"image":t.push("l-image");{const r=e,n=r.encoding||"auto";if(!r.input)return;t.push(j(r.input,n))}break;case"video":t.push("l-video");{const r=e,n=r.encoding||"auto";if(!r.input)return;t.push(j(r.input,n))}break;case"subtitle":t.push("l-subtitle");{const r=e,n=r.encoding||"auto";if(!r.input)return;t.push(j(r.input,n))}break;case"solidColor":t.push("l-image"),t.push("i-ik_canvas");{const r=e;if(!r.color)return;t.push("bg-"+r.color)}}const{x:a,y:i,focus:u}=n;a&&t.push("lx-"+a),i&&t.push("ly-"+i),u&&t.push("lfo-"+u);const{start:c,end:p,duration:l}=s;c&&t.push("lso-"+c),p&&t.push("leo-"+p),l&&t.push("ldu-"+l);const d=O(o);return d&&""!==d.trim()&&t.push(d),t.push("l-end"),t.join(x())}const O=function(e){if(!Array.isArray(e))return"";for(var t=[],r=0,n=e.length;r<n;r++){var s=[];for(var o in e[r]){let t=e[r][o];if(null!=t)if("overlay"!==o||"object"!=typeof t){var a=b(o);if(a||(a=o),""!==a)if(["e-grayscale","e-contrast","e-removedotbg","e-bgremove","e-upscale","e-retouch","e-genvar"].includes(a)){if(!0!==t&&"-"!==t&&"true"!==t)continue;s.push(a)}else!["e-sharpen","e-shadow","e-gradient","e-usm","e-dropshadow"].includes(a)||""!==t.toString().trim()&&!0!==t&&"true"!==t?"raw"===o?s.push(e[r][o]):("di"===a&&(t=E(A(t||"")),t=t.replace(/\//g,"@@")),"sr"===a&&Array.isArray(t)&&(t=t.join("_")),"t"===a&&""===t.toString().trim()&&(t="true"),s.push([a,t].join(k()))):s.push(a)}else{var i=K(t);i&&""!==i.trim()&&s.push(i)}}s.length&&t.push(s.join(x()))}return t.join(w())},C=[640,750,828,1080,1200,1920,2048,3840],q=[16,32,48,64,96,128,256,384];e.ImageKitAbortError=d,e.ImageKitInvalidRequestError=l,e.ImageKitServerError=g,e.ImageKitUploadNetworkError=f,e.buildSrc=M,e.buildTransformationString=O,e.getResponsiveImageAttributes=function(e){const{src:t,urlEndpoint:r,transformation:n=[],queryParameters:s,transformationPosition:o,sizes:a,width:i,deviceBreakpoints:u=C,imageBreakpoints:c=q}=e,p=[...u].sort((e,t)=>e-t),l=[...[...c].sort((e,t)=>e-t),...p].sort((e,t)=>e-t),{candidates:d,descriptorKind:f}=function(e){const{allBreakpoints:t,deviceBreakpoints:r,explicitWidth:n,sizesAttr:s}=e;if(s){const e=(s.match(/(^|\s)(1?\d{1,2})vw/g)||[]).map(e=>parseInt(e,10));if(e.length){const n=Math.min(...e)/100,s=r[0]*n;return{candidates:t.filter(e=>e>=s),descriptorKind:"w"}}return{candidates:t,descriptorKind:"w"}}if("number"!=typeof n)return{candidates:r,descriptorKind:"w"};const o=e=>t.find(t=>t>=e)||t[t.length-1];return{candidates:Array.from(new Set([o(n),o(2*n)])),descriptorKind:"x"}}({allBreakpoints:l,deviceBreakpoints:p,explicitWidth:i,sizesAttr:a}),g=e=>M({src:t,urlEndpoint:r,queryParameters:s,transformationPosition:o,transformation:[...n,{width:e,crop:"at_max"}]}),m=d.map((e,t)=>`${g(e)} ${"w"===f?e:t+1}${f}`).join(", ")||void 0,h=a??("w"===f?"100vw":void 0);return{src:g(d[d.length-1]),srcSet:m,...h?{sizes:h}:{},...void 0!==i?{width:i}:{}}},e.upload=e=>e?new Promise((y,v)=>{const{xhr:b}=e||{};delete e.xhr;const w=b||new XMLHttpRequest;if(!e.file)return v(new l(t.message));if(!e.fileName)return v(new l(r.message));if(!e.publicKey||0===e.publicKey.length)return v(new l(n.message));if(!e.token)return v(new l(a.message));if(!e.signature)return v(new l(o.message));if(!e.expire)return v(new l(i.message));if(e.transformation){if(!Object.keys(e.transformation).includes("pre")&&!Object.keys(e.transformation).includes("post"))return v(new l(u.message));if(Object.keys(e.transformation).includes("pre")&&!e.transformation.pre)return v(new l(c.message));if(Object.keys(e.transformation).includes("post")){if(!Array.isArray(e.transformation.post))return v(new l(p.message));for(let t of e.transformation.post){if("abs"===t.type&&!t.protocol&&!t.value)return v(new l(p.message));if("transformation"===t.type&&!t.value)return v(new l(p.message))}}}var x=new FormData;let k;for(k in e)if(k)if("file"===k&&"string"!=typeof e.file)x.set("file",e.file,String(e.fileName));else if("tags"===k&&Array.isArray(e.tags))x.set("tags",e.tags.join(","));else if("signature"===k)x.set("signature",e.signature);else if("expire"===k)x.set("expire",String(e.expire));else if("token"===k)x.set("token",e.token);else if("responseFields"===k&&Array.isArray(e.responseFields))x.set("responseFields",e.responseFields.join(","));else if("extensions"===k&&Array.isArray(e.extensions))x.set("extensions",JSON.stringify(e.extensions));else if("customMetadata"!==k||"object"!=typeof e.customMetadata||Array.isArray(e.customMetadata)||null===e.customMetadata){if("transformation"===k&&"object"==typeof e.transformation&&null!==e.transformation)x.set(k,JSON.stringify(e.transformation));else if("checks"===k&&e.checks)x.set("checks",e.checks);else if(void 0!==e[k]){if(["onProgress","abortSignal"].includes(k))continue;x.set(k,String(e[k]))}}else x.set("customMetadata",JSON.stringify(e.customMetadata));function S(){var t;return w.abort(),v(new d("Upload aborted",null===(t=e.abortSignal)||void 0===t?void 0:t.reason))}if(e.onProgress&&(w.upload.onprogress=function(t){e.onProgress&&e.onProgress(t)}),e.abortSignal){var R;if(e.abortSignal.aborted)return v(new d("Upload aborted",null===(R=e.abortSignal)||void 0===R?void 0:R.reason));e.abortSignal.addEventListener("abort",S),w.addEventListener("loadend",()=>{e.abortSignal&&e.abortSignal.removeEventListener("abort",S)})}w.open("POST","https://upload.imagekit.io/api/v1/files/upload"),w.onerror=function(e){return v(new f(s.message))},w.onload=function(){if(w.status>=200&&w.status<300)try{var e=JSON.parse(w.responseText),t=m(e,w);return y(t)}catch(e){return v(e)}else if(w.status>=400&&w.status<500)try{e=JSON.parse(w.responseText);return v(new l(e.message??"Invalid request. Please check the parameters.",h(w)))}catch(e){return v(e)}else try{e=JSON.parse(w.responseText);return v(new g(e.message??"Server error occurred while uploading the file. This is rare and usually temporary.",h(w)))}catch(e){return v(new g("Server error occurred while uploading the file. This is rare and usually temporary.",h(w)))}},w.send(x)}):Promise.reject(new l("Invalid options provided for upload")),Object.defineProperty(e,"__esModule",{value:!0})}));

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces";
+import type { SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces";
 import { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, upload } from "./upload";
 import { buildSrc, buildTransformationString } from "./url";
-export { buildSrc, buildTransformationString, upload, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitServerError, ImageKitUploadNetworkError };
-export type { Transformation, SrcOptions, UploadOptions, UploadResponse };
+import { getResponsiveImageAttributes } from "./responsive";
+import type { GetImageAttributesOptions, ResponsiveImageAttributes } from "./responsive";
+export { buildSrc, buildTransformationString, upload, getResponsiveImageAttributes, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitServerError, ImageKitUploadNetworkError };
+export type { Transformation, SrcOptions, UploadOptions, UploadResponse, GetImageAttributesOptions, ResponsiveImageAttributes };

package/dist/interfaces/Transformation.d.ts

@@ -621,4 +621,17 @@ export type SolidColorOverlayTransformation = Pick<Transformation, "width" | "he
      * Specifies the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`.
      */
     alpha?: number;
+    /**
+     * Specifies the background color of the solid color overlay.
+     * Accepts an RGB hex code, an RGBA code, or a color name.
+     */
+    background?: string;
+    /**
+     * Only works if base asset is an image.
+     *
+     * Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient.
+     *
+     * [Effects and Enhancements - Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient)
+     */
+    gradient?: Transformation["gradient"];
 };

package/dist/interfaces/UploadOptions.d.ts

@@ -16,6 +16,8 @@ interface Transformation {
     /**
      * Specifies pre-transformations to be applied. Must be a valid string of transformations like "w-300,h-300".
      * Refer to the docs for more details on transformations.
+     *
+     * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#pre-transformation}
      */
     pre?: string;
     /**
@@ -25,6 +27,8 @@ interface Transformation {
      *  - protocol: Used only when type is "abs". Can be "hls" or "dash".
      *
      * Refer to the docs for more details on transformations and usage in post.
+     *
+     * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#post-transformation}
      */
     post?: PostTransformation[];
 }

package/dist/responsive.d.ts

@@ -0,0 +1,58 @@
+import type { SrcOptions } from './interfaces';
+export interface GetImageAttributesOptions extends SrcOptions {
+    /**
+      * The intended display width of the image in pixels,
+      * used **only when the `sizes` attribute is not provided**.
+      *
+      * Triggers a DPR-based strategy (1x and 2x variants) and generates `x` descriptors in `srcSet`.
+      *
+      * Ignored if `sizes` is present.
+      */
+    width?: number;
+    /**
+     * The value for the HTML `sizes` attribute
+     * (e.g., `"100vw"` or `"(min-width:768px) 50vw, 100vw"`).
+     *
+     * - If it includes one or more `vw` units, breakpoints smaller than the corresponding percentage of the smallest device width are excluded.
+     * - If it contains no `vw` units, the full breakpoint list is used.
+     *
+     * Enables a width-based strategy and generates `w` descriptors in `srcSet`.
+     */
+    sizes?: string;
+    /**
+     * Custom list of **device-width breakpoints** in pixels.
+     * These define common screen widths for responsive image generation.
+     *
+     * Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.
+     * Sorted automatically.
+     */
+    deviceBreakpoints?: number[];
+    /**
+     * Custom list of **image-specific breakpoints** in pixels.
+     * Useful for generating small variants (e.g., placeholders or thumbnails).
+     *
+     * Merged with `deviceBreakpoints` before calculating `srcSet`.
+     * Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`.
+     * Sorted automatically.
+     */
+    imageBreakpoints?: number[];
+}
+/**
+ * Resulting set of attributes suitable for an HTML `<img>` element.
+ * Useful for enabling responsive image loading.
+ */
+export interface ResponsiveImageAttributes {
+    /** URL for the *largest* candidate (assigned to plain `src`). */
+    src: string;
+    /** Candidate set with `w` or `x` descriptors. */
+    srcSet?: string;
+    /** `sizes` returned (or synthesised as `100vw`). */
+    sizes?: string;
+    /** Width as a number (if `width` was provided). */
+    width?: number;
+}
+/**
+ * Generates a responsive image URL, `srcSet`, and `sizes` attributes
+ * based on the input options such as `width`, `sizes`, and breakpoints.
+ */
+export declare function getResponsiveImageAttributes(opts: GetImageAttributesOptions): ResponsiveImageAttributes;

package/dist/upload.d.ts

@@ -1,4 +1,4 @@
-import { ResponseMetadata, UploadOptions, UploadResponse } from "./interfaces";
+import type { ResponseMetadata, UploadOptions, UploadResponse } from "./interfaces";
 /**
  * Represents an error when a request to ImageKit is invalid.
  */

package/dist/url.d.ts

@@ -1,5 +1,5 @@
-import { SrcOptions } from "./interfaces";
-import { Transformation } from "./interfaces/Transformation";
+import type { SrcOptions } from "./interfaces";
+import type { Transformation } from "./interfaces/Transformation";
 /**
  * Builds a source URL with the given options.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@imagekit/javascript",
-    "version": "5.0.0-beta.7",
+    "version": "5.1.0-beta.1",
     "description": "ImageKit Javascript SDK",
     "main": "dist/imagekit.cjs.js",
     "module": "dist/imagekit.esm.js",
@@ -8,8 +8,7 @@
     "unpkg": "dist/imagekit.min.js",
     "types": "dist/index.d.ts",
     "files": [
-        "dist",
-        "src"
+        "dist"
     ],
     "devDependencies": {
         "@babel/cli": "^7.10.5",
@@ -49,7 +48,6 @@
         "startSampleApp": "yarn build && cd samples/sample-app/ && yarn install && node index.js"
     },
     "publishConfig": {
-        "tag": "beta",
         "access": "public"
     },
     "repository": {

package/src/constants/errorMessages.ts

@@ -1,14 +0,0 @@
-export default {
-  MISSING_UPLOAD_FILE_PARAMETER: { message: "Missing file parameter for upload" },
-  MISSING_UPLOAD_FILENAME_PARAMETER: { message: "Missing fileName parameter for upload" },
-  MISSING_PUBLIC_KEY: { message: "Missing public key for upload" },
-  UPLOAD_ENDPOINT_NETWORK_ERROR: {
-    message: "Request to ImageKit upload endpoint failed due to network error"
-  },
-  MISSING_SIGNATURE: { message: "Missing signature for upload. The SDK expects token, signature and expire for authentication." },
-  MISSING_TOKEN: { message: "Missing token for upload. The SDK expects token, signature and expire for authentication." },
-  MISSING_EXPIRE: { message: "Missing expire for upload. The SDK expects token, signature and expire for authentication." },
-  INVALID_TRANSFORMATION: { message: "Invalid transformation parameter. Please include at least pre, post, or both." },
-  INVALID_PRE_TRANSFORMATION: { message: "Invalid pre transformation parameter." },
-  INVALID_POST_TRANSFORMATION: { message: "Invalid post transformation parameter." }
-};

package/src/constants/supportedTransforms.ts

@@ -1,80 +0,0 @@
-/**
- * {@link https://imagekit.io/docs/transformations}
- */
-export const supportedTransforms: { [key: string]: string } = {
-  // Basic sizing & layout
-  width: "w",
-  height: "h",
-  aspectRatio: "ar",
-  background: "bg",
-  border: "b",
-  crop: "c",
-  cropMode: "cm",
-  dpr: "dpr",
-  focus: "fo",
-  quality: "q",
-  x: "x",
-  xCenter: "xc",
-  y: "y",
-  yCenter: "yc",
-  format: "f",
-  videoCodec: "vc",
-  audioCodec: "ac",
-  radius: "r",
-  rotation: "rt",
-  blur: "bl",
-  named: "n",
-  defaultImage: "di",
-  flip: "fl",
-  original: "orig",
-  startOffset: "so",
-  endOffset: "eo",
-  duration: "du",
-  streamingResolutions: "sr",
-
-  // AI & advanced effects
-  grayscale: "e-grayscale",
-  aiUpscale: "e-upscale",
-  aiRetouch: "e-retouch",
-  aiVariation: "e-genvar",
-  aiDropShadow: "e-dropshadow",
-  aiChangeBackground: "e-changebg",
-  aiRemoveBackground: "e-bgremove",
-  aiRemoveBackgroundExternal: "e-removedotbg",
-  contrastStretch: "e-contrast",
-  shadow: "e-shadow",
-  sharpen: "e-sharpen",
-  unsharpMask: "e-usm",
-  gradient: "e-gradient",
-
-  // Other flags & finishing
-  progressive: "pr",
-  lossless: "lo",
-  colorProfile: "cp",
-  metadata: "md",
-  opacity: "o",
-  trim: "t",
-  zoom: "z",
-  page: "pg",
-
-  // 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",
-};
-
-
-
-export default supportedTransforms

package/src/index.ts

@@ -1,13 +0,0 @@
-import { SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces";
-import { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, upload } from "./upload";
-import { buildSrc, buildTransformationString } from "./url";
-
-export { buildSrc, buildTransformationString, upload, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitServerError, ImageKitUploadNetworkError };
-export type {
-  Transformation,
-  SrcOptions,
-  UploadOptions,
-  UploadResponse
-};
-
-

package/src/interfaces/SrcOptions.ts

@@ -1,35 +0,0 @@
-import { Transformation } from "./Transformation";
-import { TransformationPosition } from ".";
-
-export interface SrcOptions {
-  /**
-   * Accepts a relative or absolute path of the resource. If a relative path is provided, it is appended to the `urlEndpoint`. 
-   * If an absolute path is provided, `urlEndpoint` is ignored.
-   */
-  src: string;
-
-  /**
-   * Get your urlEndpoint from the [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
-   */
-  urlEndpoint: string;
-
-  /**
-   * An array of objects specifying the transformations to be applied in the URL. If more than one transformation is specified, they are applied in the order they are specified as chained transformations.
-   * 
-   * {@link https://imagekit.io/docs/transformations#chained-transformations}
-   */
-  transformation?: Array<Transformation>;
-
-  /**
-   * These are additional query parameters that you want to add to the final URL.
-   * They can be any query parameters and not necessarily related to ImageKit.
-   * This is especially useful if you want to add a versioning parameter to your URLs.
-   */
-  queryParameters?: { [key: string]: string | number };
-
-  /**
-   * By default, the transformation string is added as a query parameter in the URL, e.g., `?tr=w-100,h-100`. 
-   * If you want to add the transformation string in the path of the URL, set this to `path`.
-   */
-  transformationPosition?: TransformationPosition;
-}