refactor: update export types and remove unused ImageKitOptions interface

Author: manu4543

README.md

@@ -75,8 +75,6 @@ var imagekit = new ImageKit({
 });
 ```
 
-> 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                                         |

rollup.config.js

@@ -33,8 +33,8 @@ export default [
   {
     input: "src/index.ts",
     output: [
-      { file: pkg.main, format: "cjs", exports: "default" },
-      { file: pkg.module, format: "es", exports: "default" },
+      { file: pkg.main, format: "cjs", exports: "named" },
+      { file: pkg.module, format: "es", exports: "named" },
     ],
     plugins: [
       nodeResolve({ extensions: [".ts"] }),

src/constants/errorMessages.ts

@@ -1,25 +1,24 @@
 export default {
-  MANDATORY_INITIALIZATION_MISSING: { message: "Missing urlEndpoint during SDK initialization", help: "" },
-  INVALID_TRANSFORMATION_POSITION: { message: "Invalid transformationPosition parameter", help: "" },
-  PRIVATE_KEY_CLIENT_SIDE: { message: "privateKey should not be passed on the client side", help: "" },
-  MISSING_UPLOAD_DATA: { message: "Missing data for upload", help: "" },
-  MISSING_UPLOAD_FILE_PARAMETER: { message: "Missing file parameter for upload", help: "" },
-  MISSING_UPLOAD_FILENAME_PARAMETER: { message: "Missing fileName parameter for upload", help: "" },
-  MISSING_AUTHENTICATION_ENDPOINT: { message: "Missing authentication endpoint for upload", help: "" },
-  MISSING_PUBLIC_KEY: { message: "Missing public key for upload", help: "" },
-  AUTH_ENDPOINT_TIMEOUT: { message: "The authenticationEndpoint you provided timed out in 60 seconds", help: "" },
-  AUTH_ENDPOINT_NETWORK_ERROR: { message: "Request to authenticationEndpoint failed due to network error", help: "" },
-  AUTH_INVALID_RESPONSE: { message: "Invalid response from authenticationEndpoint. The SDK expects a JSON response with three fields i.e. signature, token and expire.", help: "" },
+  MANDATORY_INITIALIZATION_MISSING: { message: "Missing urlEndpoint during SDK initialization" },
+  INVALID_TRANSFORMATION_POSITION: { message: "Invalid transformationPosition parameter" },
+  PRIVATE_KEY_CLIENT_SIDE: { message: "privateKey should not be passed on the client side" },
+  MISSING_UPLOAD_DATA: { message: "Missing data for upload" },
+  MISSING_UPLOAD_FILE_PARAMETER: { message: "Missing file parameter for upload" },
+  MISSING_UPLOAD_FILENAME_PARAMETER: { message: "Missing fileName parameter for upload" },
+  MISSING_AUTHENTICATION_ENDPOINT: { message: "Missing authentication endpoint for upload" },
+  MISSING_PUBLIC_KEY: { message: "Missing public key for upload" },
+  AUTH_ENDPOINT_TIMEOUT: { message: "The authenticationEndpoint you provided timed out in 60 seconds" },
+  AUTH_ENDPOINT_NETWORK_ERROR: { message: "Request to authenticationEndpoint failed due to network error" },
+  AUTH_INVALID_RESPONSE: { message: "Invalid response from authenticationEndpoint. The SDK expects a JSON response with three fields i.e. signature, token and expire." },
   UPLOAD_ENDPOINT_NETWORK_ERROR: {
-    message: "Request to ImageKit upload endpoint failed due to network error",
-    help: "",
+    message: "Request to ImageKit upload endpoint failed due to network error"
   },
-  INVALID_UPLOAD_OPTIONS: { message: "Invalid uploadOptions parameter", help: "" },
-  MISSING_SIGNATURE: { message: "Missing signature for upload. The SDK expects token, signature and expire for authentication.", help: "" },
-  MISSING_TOKEN: { message: "Missing token for upload. The SDK expects token, signature and expire for authentication.", help: "" },
-  MISSING_EXPIRE: { message: "Missing expire for upload. The SDK expects token, signature and expire for authentication.", help: "" },
-  INVALID_TRANSFORMATION: { message: "Invalid transformation parameter. Please include at least pre, post, or both.", help: "" },
-  INVALID_PRE_TRANSFORMATION: { message: "Invalid pre transformation parameter.", help: "" },
-  INVALID_POST_TRANSFORMATION: { message: "Invalid post transformation parameter.", help: "" },
-  UPLOAD_ABORTED: { message: "Request aborted by the user", help: "" },
+  INVALID_UPLOAD_OPTIONS: { message: "Invalid uploadOptions parameter" },
+  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." },
+  UPLOAD_ABORTED: { message: "Request aborted by the user" },
 };

src/index.ts

@@ -1,88 +1,11 @@
-import errorMessages from "./constants/errorMessages";
-import { ImageKitOptions, UploadOptions, UploadResponse, UrlOptions } from "./interfaces";
-import IKResponse from "./interfaces/IKResponse";
+import { UploadOptions, UploadResponse, UrlOptions } from "./interfaces";
 import { upload } from "./upload";
-import { buildURL } from "./url/builder";
-import transformationUtils from "./utils/transformation";
-type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+import { buildURL, generateTransformationString } from "./url";
 
+export { buildURL, generateTransformationString, upload };
 
-function mandatoryParametersAvailable(options: ImageKitOptions) {
-  return options.urlEndpoint;
-}
-
-class ImageKit {
-  options: MakeRequired<ImageKitOptions, "urlEndpoint"> = {
-    publicKey: "",
-    urlEndpoint: "",
-    transformationPosition: transformationUtils.getDefault(),
-  };
-
-  constructor(opts: MakeRequired<ImageKitOptions, "urlEndpoint">) {
-    this.options = { ...this.options, ...(opts || {}) };
-    if (!mandatoryParametersAvailable(this.options)) {
-      throw errorMessages.MANDATORY_INITIALIZATION_MISSING;
-    }
-
-    if (!transformationUtils.validParameters(this.options)) {
-      throw errorMessages.INVALID_TRANSFORMATION_POSITION;
-    }
-  }
-
-  /**
-   * An instance method to generate URL for the given transformation parameters. This method is useful when you want to generate URL using the instance of the SDK without passing common parameters like `urlEndpoint` and `transformationPosition` every time.
-   */
-  url(urlOptions: UrlOptions & Partial<Pick<ImageKitOptions, "urlEndpoint" | "transformationPosition">>): string {
-    // Merge the options with the instance options
-    const options = {
-      ...this.options,
-      ...urlOptions,
-    };
-    return ImageKit.url(options);
-  }
-
-  /**
-   * A static method to generate URL for the given transformation parameters. This method is useful when you want to generate URL without creating an instance of the SDK.
-   */
-  static url(urlOptions: UrlOptions & Required<Pick<ImageKitOptions, "urlEndpoint">> & Pick<ImageKitOptions, "transformationPosition">): string {
-    return buildURL(urlOptions);
-  }
-
-  /**
-   * An instance method to upload file to ImageKit.io. This method is useful when you want to upload file using the instance of the SDK without passing common parameters like `urlEndpoint` and `publicKey` every time.
-   */
-  upload(uploadOptions: UploadOptions & Partial<Pick<ImageKitOptions, "publicKey">>): Promise<IKResponse<UploadResponse>> {
-    // Merge the options with the instance options
-    const options = {
-      ...this.options,
-      ...uploadOptions,
-    };
-
-    return ImageKit.upload(options as UploadOptions & Required<Pick<ImageKitOptions, "publicKey">>);
-  }
-
-  /**
-   * A static method to upload file to ImageKit.io. This method is useful when you want to upload file without creating an instance of the SDK.
-   */
-  static upload(uploadOptions: UploadOptions & Required<Pick<ImageKitOptions, "publicKey">>): Promise<IKResponse<UploadResponse>> {
-    if (!uploadOptions.publicKey || uploadOptions.publicKey.length === 0) {
-      throw errorMessages.MISSING_PUBLIC_KEY;
-    }
-
-    const { xhr: userProvidedXHR } = uploadOptions || {};
-    delete uploadOptions.xhr;
-    const xhr = userProvidedXHR || new XMLHttpRequest();
-
-    // Extract publicKey from uploadOptions
-    const { publicKey, ...rest } = uploadOptions;
-    return upload(
-      xhr,
-      rest,
-      {
-        publicKey,
-      }
-    )
-  }
-}
-
-export default ImageKit;
+export type {
+  UrlOptions,
+  UploadOptions,
+  UploadResponse
+};

src/interfaces/ImageKitOptions.ts

@@ -16,7 +16,7 @@ interface AbsObject {
 
 type PostTransformation = TransformationObject | GifToVideoOrThumbnailObject | AbsObject;
 
-interface Transformation{
+interface Transformation {
   pre?: string
   post?: PostTransformation[]
 }
@@ -35,28 +35,38 @@ export interface UploadOptions {
    *      Pass the full URL, for example - https://www.example.com/rest-of-the-image-path.jpg.
    */
   file: string | Blob | File;
+
+  /**
+  * The name with which the file has to be uploaded.
+  * The file name can contain:
+  * - Alphanumeric Characters: a-z , A-Z , 0-9 (including unicode letters, marks, and numerals in other languages)
+  * - Special Characters: . _ and -
+  * Any other character including space will be replaced by _
+  */
+  fileName: string;
+
   /**
    * HMAC-SHA1 digest of the token+expire using your ImageKit.io private API key as a key. This should be in lowercase.
    * Warning: Signature must be calculated on the server-side. This field is required for authentication when uploading a file from the client-side.
    */
   signature: string;
+
   /**
    * A unique value generated by the client, which will be used by the ImageKit.io server to recognize and prevent subsequent retries for the same request. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
    * Note: Sending a value that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new value for this field.
    */
   token: string;
+
   /**
    * The time until your signature is valid. It must be a Unix time in less than 1 hour into the future. It should be in seconds.
    */
   expire: number;
+
   /**
-   * The name with which the file has to be uploaded.
-   * The file name can contain:
-   * - Alphanumeric Characters: a-z , A-Z , 0-9 (including unicode letters, marks, and numerals in other languages)
-   * - Special Characters: . _ and -
-   * Any other character including space will be replaced by _
+   * The public API key of your ImageKit account. You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
    */
-  fileName: string;
+  publicKey: string;
+
   /**
    * Whether to use a unique filename for this file or not.
    * - Accepts true or false.

src/interfaces/UploadOptions.ts

@@ -94,60 +94,66 @@ export interface Metadata {
   };
 }
 
+export interface ResponseMetadata {
+  statusCode: number;
+  requestId: string;
+  headers: Record<string, string | number | boolean>;
+}
+
 /**
- * Response from uploading a file
+ * Response from server when file is uploaded successfully.
  *
  * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Responses}
  */
 export interface UploadResponse {
   /**
    * Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file.
    */
-  fileId: string;
+  fileId?: string;
   /**
    * The name of the uploaded file.
    */
-  name: string;
+  name?: string;
   /**
    * The URL of the file.
    */
-  url: string;
+  url?: string;
   /**
    * In case of an image, a small thumbnail URL.
    */
-  thumbnailUrl: string;
+  thumbnailUrl?: string;
   /**
    * Height of the uploaded image file. Only applicable when file type is image.
    */
-  height: number;
+  height?: number;
   /**
    * Width of the uploaded image file. Only applicable when file type is image.
    */
-  width: number;
+  width?: number;
   /**
    * Size of the uploaded file in bytes.
    */
-  size: number;
+  size?: number;
   /**
    * Type of file. It can either be image or non-image.
    */
-  fileType: FileType;
+  fileType?: FileType;
   /**
    * The path of the file uploaded. It includes any folder that you specified while uploading.
    */
-  filePath: string;
+  filePath?: string;
   /**
    * Array of tags associated with the image.
    */
   tags?: string[];
   /**
    * Is the file marked as private. It can be either true or false.
    */
-  isPrivateFile: boolean;
+  isPrivateFile?: boolean;
   /**
    * Value of custom coordinates associated with the image in format x,y,width,height.
    */
-  customCoordinates: string | null;
+  customCoordinates?: string | null;
   /**
    * The metadata of the upload file. Use responseFields property in request to get the metadata returned in response of upload API.
    */
@@ -156,8 +162,21 @@ export interface UploadResponse {
    * AITags field is populated only because the google-auto-tagging extension was executed synchronously and it received a successresponse.
    */
   AITags?: object[];
+
   /*
    * Field object which will contain the status of each extension at the time of completion of the update/upload request.
    */ 
   extensionStatus?: { [key: string]: string }
+
+  /**
+   * Message indicating that the file upload is accepted. This field is only present when the upload is accepted but not yet processed.
+   * This can happen when the file is being processed for pre-transformation for video.
+   * The upload will be completed once the pre-transformation is done.
+   */
+  message?: string
+
+  /**
+   * Response metadata for debugging purposes.
+   */
+  readonly $ResponseMetadata: ResponseMetadata;
 }

src/interfaces/UploadResponse.ts

@@ -1,11 +1,17 @@
 import { Transformation } from "./Transformation";
+import { TransformationPosition } from ".";
 
 export interface UrlOptions {
   /**
    * Accepts relative or absolute path of the resource. If relative path is provided, it is appended to the `urlEndpoint`. If 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.
    * 
@@ -19,4 +25,9 @@ export interface UrlOptions {
    * Especially useful, if you want to add some 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;
 }

src/interfaces/UrlOptions.ts

@@ -1,7 +1,7 @@
-import { ImageKitOptions } from "./ImageKitOptions";
 import { TransformationPosition } from "./Transformation";
 import { UploadOptions } from "./UploadOptions";
-import { UploadResponse, FileType } from "./UploadResponse";
+import { FileType, UploadResponse } from "./UploadResponse";
 import { UrlOptions } from "./UrlOptions";
 
-export type { ImageKitOptions, TransformationPosition, UploadOptions, UploadResponse, FileType, UrlOptions };
+export type { FileType, TransformationPosition, UploadOptions, UploadResponse, UrlOptions };
+