Merge pull request #56 from dev-saad07/sdk-improvements

imagekitio · web-flow · commit ce60c41f76ce · 2022-06-30T16:32:10.000+05:30
Sdk improvements
diff --git a/README.md b/README.md
@@ -287,7 +287,9 @@ Sample usage
     // Upload function internally uses the ImageKit.io javascript SDK
     function upload(data) {
         var file = document.getElementById("file1");
-        imagekit.upload({
+
+        // Using Callback Function
+        var xhr = imagekit.upload({
             file: file.files[0],
             fileName: "abc1.jpg",
             tags: ["tag1"],
@@ -305,10 +307,78 @@ Sample usage
                 transformation: [{ height: 300, width: 400}]
             }));
         })
+
+        xhr.upload.onprogress = (event) => {
+            console.log(`Uploaded ${event.loaded} of ${event.total} bytes`);
+        }
+
+        // Using Promises
+        imagekit.upload({
+            file: file.files[0],
+            fileName: "abc1.jpg",
+            tags: ["tag1"],
+            extensions: [
+                {
+                    name: "aws-auto-tagging",
+                    minConfidence: 80,
+                    maxTags: 10
+                }
+            ]
+        }).then(result => {
+            console.log(imagekit.url({
+                src: result.url,
+                transformation: [{ height: 300, width: 400}]
+            }));
+        }).then(error => {
+            console.log(error);
+        })
     }
 </script>
 ```
 
 If the upload succeeds, `err` will be `null`, and the `result` will be the same as what is received from ImageKit's servers.
 If the upload fails, `err` will be the same as what is received from ImageKit's servers, and the `result` will be null.
+Upload using callback functions returns the upload XHR, it can be used to monitor the progress of the upload.
+
+## Access request-id, other response headers and HTTP status code
+You can access `$ResponseMetadata` on success or error object to access the HTTP status code and response headers.
+
+```javascript
+// Success
+var response = await imagekit.upload({
+    file: file.files[0],
+    fileName: "abc1.jpg",
+    tags: ["tag1"],
+    extensions: [
+        {
+            name: "aws-auto-tagging",
+            minConfidence: 80,
+            maxTags: 10
+        }
+    ]
+});
+console.log(response.$ResponseMetadata.statusCode); // 200
+
+// { 'content-length': "300", 'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'}
+console.log(response.$ResponseMetadata.headers);
+
+// Error
+try {
+    await imagekit.upload({
+        file: file.files[0],
+        fileName: "abc1.jpg",
+        tags: ["tag1"],
+        extensions: [
+            {
+                name: "aws-auto-tagging",
+                minConfidence: 80,
+                maxTags: 10
+            }
+        ]
+    });
+} catch (ex) {
+    console.log(response.$ResponseMetadata.statusCode); // 400
 
+    // {'content-type': 'application/json', 'x-request-id': 'ee560df4-d44f-455e-a48e-29dfda49aec5'}
+    console.log(response.$ResponseMetadata.headers);
+}
diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts
@@ -281,6 +281,11 @@ const supportedTransforms: { [key: string]: string } = {
    * @link https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#original-image-orig
    */
   original: "orig",
+
+  /**
+   * @link https://docs.imagekit.io/features/image-transformations/conditional-transformations
+   */
+   raw: "raw",
 }
 
 
diff --git a/src/index.ts b/src/index.ts
@@ -1,6 +1,7 @@
 import { version } from "../package.json";
 import errorMessages from "./constants/errorMessages";
 import { ImageKitOptions, UploadOptions, UploadResponse, UrlOptions } from "./interfaces";
+import IKResponse from "./interfaces/IKResponse";
 import { upload } from "./upload/index";
 import { url } from "./url/index";
 import transformationUtils from "./utils/transformation";
@@ -13,6 +14,30 @@ function privateKeyPassed(options: ImageKitOptions) {
   return typeof (options as any).privateKey != "undefined";
 }
 
+const promisify = function <T = void>(thisContext: ImageKit, fn: Function) {
+  return function (...args: any[]): Promise<T> | void {
+    if (args.length === fn.length && typeof args[args.length - 1] !== "undefined") {
+      if (typeof args[args.length - 1] !== "function") {
+        throw new Error("Callback must be a function.");
+      }
+      fn.call(thisContext, ...args);
+    } else {
+      return new Promise<T>((resolve, reject) => {
+        const callback = function (err: Error, ...results: any[]) {
+          if (err) {
+            return reject(err);
+          } else {
+            resolve(results.length > 1 ? results : results[0]);
+          }
+        };
+        args.pop()
+        args.push(callback);
+        fn.call(thisContext, ...args);
+      });
+    }
+  };
+};
+
 class ImageKit {
   options: ImageKitOptions = {
     sdkVersion: `javascript-${version}`,
@@ -58,16 +83,26 @@ class ImageKit {
    *
    * @param uploadOptions
    */
-  upload(
-    uploadOptions: UploadOptions,
-    callback?: (err: Error | null, response: UploadResponse | null) => void,
-    options?: Partial<ImageKitOptions>,
-  ): void {
-    var mergedOptions = {
+  upload(uploadOptions: UploadOptions, options?: Partial<ImageKitOptions>): Promise<IKResponse<UploadResponse>>
+  upload(uploadOptions: UploadOptions, callback: (err: Error | null, response: IKResponse<UploadResponse> | null) => void, options?: Partial<ImageKitOptions>): XMLHttpRequest;
+  upload(uploadOptions: UploadOptions, callbackOrOptions?: ((err: Error | null, response: IKResponse<UploadResponse> | null) => void) | Partial<ImageKitOptions>, options?: Partial<ImageKitOptions>): XMLHttpRequest | Promise<IKResponse<UploadResponse>> {
+    let callback;
+    if (typeof callbackOrOptions === 'function') {
+      callback = callbackOrOptions;
+    } else {
+      options = callbackOrOptions || {};
+    }
+    var mergedOptions = { 
       ...this.options,
       ...options,
     };
-    return upload(uploadOptions, mergedOptions, callback);
+    const xhr = new XMLHttpRequest();
+    const promise = promisify<IKResponse<UploadResponse>>(this, upload)(xhr, uploadOptions, mergedOptions, callback);
+    if (typeof promise === "object" && typeof promise.then === "function") {
+      return promise
+    } else {
+      return xhr;
+    }
   }
 }
 
diff --git a/src/interfaces/IKResponse.ts b/src/interfaces/IKResponse.ts
@@ -0,0 +1,10 @@
+interface ResponseMetadata {
+  statusCode: number;
+  headers: Record<string, string | number | boolean>;
+}
+
+type IKResponse<T> = T extends Error
+  ? T & { $ResponseMetadata?: ResponseMetadata }
+  : T & { $ResponseMetadata: ResponseMetadata };
+
+export default IKResponse;
diff --git a/src/interfaces/UploadOptions.ts b/src/interfaces/UploadOptions.ts
@@ -75,4 +75,27 @@ export interface UploadOptions {
    * Final status of pending extensions will be sent to this URL. 
    */
   webhookUrl?: string
+  /*
+   * Default is true. If overwriteFile is set to false and useUniqueFileName is also false, and a file already exists at the exact location, upload API will return an error immediately.
+   */
+  overwriteFile?: boolean
+  /*
+   * Default is true. If set to true and a file already exists at the exact location, its AITags will be removed. Set overwriteAITags to false to preserve AITags.
+   */
+  overwriteAITags?: boolean
+  /*
+   * Default is true. If the request does not have tags , overwriteTags is set to true and a file already exists at the exact location, existing tags will be removed.
+   * In case the request body has tags, setting overwriteTags to false has no effect and request's tags are set on the asset.
+   */
+  overwriteTags?: boolean
+  /*
+   * Default is true. If the request does not have customMetadata , overwriteCustomMetadata is set to true and a file already exists at the exact location, exiting customMetadata will be removed.
+   * In case the request body has customMetadata, setting overwriteCustomMetadata to false has no effect and request's customMetadata is set on the asset.
+   */
+  overwriteCustomMetadata?: boolean
+  /*
+   * Stringified JSON key-value data to be associated with the asset. Checkout overwriteCustomMetadata parameter to understand default behaviour.
+   * Before setting any custom metadata on an asset you have to create the field using custom metadata fields API.
+   */
+  customMetadata?: string | Record<string, string | number | boolean | Array<string | number | boolean>>
 }
diff --git a/src/upload/index.ts b/src/upload/index.ts
@@ -4,6 +4,7 @@ import { request } from "../utils/request";
 import { ImageKitOptions, UploadOptions, UploadResponse } from "../interfaces";
 
 export const upload = (
+  xhr: XMLHttpRequest,
   uploadOptions: UploadOptions,
   options: ImageKitOptions,
   callback?: (err: Error | null, response: UploadResponse | null) => void,
@@ -39,23 +40,28 @@ export const upload = (
   }
   
   var formData = new FormData();
-  let i: keyof typeof uploadOptions;
-  for (i in uploadOptions) {
-    const param = uploadOptions[i];
-    if (typeof param !== "undefined") {
-      if (typeof param === "string" || typeof param === "boolean")  {
-        formData.append(i, String(param));
-      } 
-      else if(Array.isArray(param)) {
-        formData.append(i, JSON.stringify(param));
+  let key: keyof typeof uploadOptions;
+  for (key in uploadOptions) {
+    if (key) {
+      if (key == "file" && typeof uploadOptions.file != "string") {
+        formData.append('file', uploadOptions.file, String(uploadOptions.fileName));
+      } else if (key == "tags" && Array.isArray(uploadOptions.tags)) {
+        formData.append('tags', uploadOptions.tags.join(","));
+      } else if (key == "responseFields" && Array.isArray(uploadOptions.responseFields)) {
+        formData.append('responseFields', uploadOptions.responseFields.join(","));
+      } else if (key == "extensions" && Array.isArray(uploadOptions.extensions)) {
+        formData.append('extensions', JSON.stringify(uploadOptions.extensions));
+      } else if (key === "customMetadata" && typeof uploadOptions.customMetadata === "object" &&
+        !Array.isArray(uploadOptions.customMetadata) && uploadOptions.customMetadata !== null) {
+        formData.append('customMetadata', JSON.stringify(uploadOptions.customMetadata));
       }
       else {
-        formData.append(i, param);
+        formData.append(key, String(uploadOptions[key]));
       }
     }
   }
 
   formData.append("publicKey", options.publicKey);
 
-  request(formData, { ...options, authenticationEndpoint: options.authenticationEndpoint }, callback);
+  request(xhr, formData, { ...options, authenticationEndpoint: options.authenticationEndpoint }, callback);
 };
diff --git a/src/utils/request.ts b/src/utils/request.ts
@@ -1,14 +1,44 @@
 import respond from "../utils/respond";
 import errorMessages from "../constants/errorMessages"
 import { ImageKitOptions, UploadResponse } from "../interfaces";
+import IKResponse from "../interfaces/IKResponse";
 
 interface SignatureResponse {
     signature: string
     expire: number
     token: string
 }
 
-export const request = (formData: FormData, options: ImageKitOptions & { authenticationEndpoint: string }, callback?: (err: Error | null, response: UploadResponse | null) => void) => {
+function getResponseHeaderMap(xhr: XMLHttpRequest) {
+    const headers: Record<string, string | number | boolean> = {};
+    const responseHeaders = xhr.getAllResponseHeaders();
+    if (Object.keys(responseHeaders).length) {
+        responseHeaders
+        .trim()
+        .split(/[\r\n]+/)
+        .map(value => value.split(/: /))
+        .forEach(keyValue => {
+          headers[keyValue[0].trim()] = keyValue[1].trim();
+        });
+    }
+    return headers;
+}
+
+const addResponseHeadersAndBody = (body: any, xhr: XMLHttpRequest):IKResponse<UploadResponse> => {
+    let response = { ...body };
+    const responseMetadata = {
+        statusCode: xhr.status,
+        headers: getResponseHeaderMap(xhr)
+    }
+    Object.defineProperty(response, "$ResponseMetadata", {
+        value: responseMetadata,
+        enumerable: false,
+        writable: false
+    });
+    return response as IKResponse<UploadResponse>;
+}
+
+export const request = (uploadFileXHR: XMLHttpRequest,formData: FormData, options: ImageKitOptions & { authenticationEndpoint: string }, callback?: (err: Error | null, response: UploadResponse | null) => void) => {
     generateSignatureToken(options, (err, signaturObj) => {
         if (err) {
             return respond(true, err, callback)
@@ -17,25 +47,30 @@ export const request = (formData: FormData, options: ImageKitOptions & { authent
             formData.append("expire", String(signaturObj?.expire || 0));
             formData.append("token", signaturObj?.token || "");
 
-            uploadFile(formData, (err, responseSucessText) => {
+            uploadFile(uploadFileXHR, formData, (err, responseSucessText) => {
                 if (err) {
                     return respond(true, err, callback)
                 }
                 return respond(false, responseSucessText!, callback)
             });
         }
     });
+    return uploadFileXHR;
 }
 
 export const generateSignatureToken = (options: ImageKitOptions & { authenticationEndpoint: string }, callback: (err: Error | null, response: SignatureResponse | null) => void) => {
     var xhr = new XMLHttpRequest();
     xhr.timeout = 60000;
     xhr.open('GET', options.authenticationEndpoint);
     xhr.ontimeout = function (e) {
-        respond(true, errorMessages.AUTH_ENDPOINT_TIMEOUT, callback);
+        var body = errorMessages.AUTH_ENDPOINT_TIMEOUT;
+        var result = addResponseHeadersAndBody(body, xhr);
+        respond(true, result, callback);
     };
     xhr.onerror = function() {
-        respond(true, errorMessages.AUTH_ENDPOINT_NETWORK_ERROR, callback);
+        var body = errorMessages.AUTH_ENDPOINT_NETWORK_ERROR;
+        var result = addResponseHeadersAndBody(body, xhr);
+        respond(true, result, callback);
     }
     xhr.onload = function () {
         if (xhr.status === 200) {
@@ -46,14 +81,16 @@ export const generateSignatureToken = (options: ImageKitOptions & { authenticati
                     expire: body.expire,
                     token: body.token
                 }
-                respond(false, obj, callback)
+                var result = addResponseHeadersAndBody(obj, xhr);
+                respond(false, result, callback);
             } catch (ex) {
                 respond(true, ex, callback)
             }
         } else {
             try {
                 var error = JSON.parse(xhr.responseText);
-                respond(true, error, callback);
+                var result = addResponseHeadersAndBody(error, xhr);
+                respond(true, result, callback);
             } catch (ex) {
                 respond(true, ex, callback);
             }
@@ -63,27 +100,30 @@ export const generateSignatureToken = (options: ImageKitOptions & { authenticati
     return;
 }
 
-export const uploadFile = (formData: FormData, callback: (err: Error | null, response: UploadResponse | null) => void) => {
-    var uploadFileXHR = new XMLHttpRequest();
+export const uploadFile = (uploadFileXHR:XMLHttpRequest, formData: FormData, callback: (err: Error | IKResponse<UploadResponse> | null, response: UploadResponse | null) => void) => {
     uploadFileXHR.open('POST', 'https://upload.imagekit.io/api/v1/files/upload');
     uploadFileXHR.onerror = function() {
-        respond(true, errorMessages.UPLOAD_ENDPOINT_NETWORK_ERROR, callback);
+        var body = errorMessages.UPLOAD_ENDPOINT_NETWORK_ERROR;
+        var result = addResponseHeadersAndBody(body, uploadFileXHR);
+        respond(true, result, callback);
         return;
     }
     uploadFileXHR.onload = function () {
         if (uploadFileXHR.status === 200) {
-            var uploadResponse = JSON.parse(uploadFileXHR.responseText);
+            var body = JSON.parse(uploadFileXHR.responseText);
+            var uploadResponse = addResponseHeadersAndBody(body, uploadFileXHR);
             callback(null, uploadResponse);
         }
         else if (uploadFileXHR.status !== 200) {
             try {
-              callback(JSON.parse(uploadFileXHR.responseText), null);
+              var body = JSON.parse(uploadFileXHR.responseText);
+              var uploadResponse = addResponseHeadersAndBody(body, uploadFileXHR);
+              callback(uploadResponse, null);
             } catch (ex : any) {
               callback(ex, null);
             }
         }
     };
     uploadFileXHR.send(formData);
-    return
 }
 
diff --git a/test/upload.js b/test/upload.js
diff --git a/test/url-generation.js b/test/url-generation.js
