@imagekit/javascript 5.0.0-beta.6 → 5.0.0

package/src/interfaces/UploadOptions.ts

@@ -1,192 +0,0 @@
-interface TransformationObject {
-  type: "transformation";
-  value: string;
-}
-
-interface GifToVideoOrThumbnailObject {
-  type: "gif-to-video" | "thumbnail";
-  value?: string;
-}
-
-interface AbsObject {
-  type: "abs";
-  value: string;
-  protocol: "hls" | "dash";
-}
-
-type PostTransformation = TransformationObject | GifToVideoOrThumbnailObject | AbsObject;
-
-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.
-   */
-  pre?: string;
-
-  /**
-   * Specifies post-transformations to be applied. This is an array of transformation objects, each with:
-   *  - type: One of "transformation", "gif-to-video", "thumbnail", or "abs".
-   *  - value: A valid transformation string required if "type" is "transformation" or "abs". Optional if "type" is "gif-to-video" or "thumbnail".
-   *  - 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.
-   */
-  post?: PostTransformation[];
-}
-
-/**
- * Options used when uploading a file using the V1 API.
- * Check out the official documentation:
- * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file}
- */
-export interface UploadOptions {
-  /**
-   * This field accepts three main input formats for the file content:
-   * - "binary": Directly pass the binary data. Typically used when uploading via the browser using a File or Blob.
-   * - "base64": A base64-encoded string of the file content.
-   * - "url": A direct URL from which ImageKit server will download the file and upload.
-   */
-  file: string | Blob | File;
-
-  /**
-   * The name with which the file should be uploaded.
-   * - Valid characters: alphanumeric (a-z, A-Z, 0-9, including Unicode letters and numerals) and the special chars ". _ -"
-   * - Any other character (including space) is replaced with "_"
-   *
-   * Example: "company_logo.png"
-   */
-  fileName: string;
-
-  /**
-   * The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key.
-   * Required for client-side authentication. Must be computed on the server side.
-   * Calculate this signature in your secure server and pass it to the client.
-   */
-  signature: string;
-
-  /**
-   * A unique value to identify and prevent replays. Typically a UUID (e.g., version 4).
-   * Each request must carry a fresh token. The server rejects reused tokens, even if the original request failed.
-   */
-  token: string;
-
-  /**
-   * A Unix timestamp in seconds, less than 1 hour in the future.
-   */
-  expire: number;
-
-  /**
-   * The public API key of your ImageKit account. You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).
-   */
-  publicKey: string;
-
-  /**
-   * Whether to use a unique filename for this file or not.
-   * - Accepts true or false.
-   * - If set true, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename.
-   * - If set false, then the image is uploaded with the provided filename parameter and any existing file with the same name is replaced.
-   * Default value - true
-   */
-  useUniqueFileName?: boolean;
-
-  /**
-   * Optionally set tags on the uploaded file.
-   * If passing an array, the SDK automatically joins them into a comma-separated string when sending to the server.
-   * Example: ["t-shirt", "round-neck", "men"] => "t-shirt,round-neck,men"
-   */
-  tags?: string | string[];
-
-  /**
-   * The folder path where the file will be stored, e.g., "/images/folder/".
-   * - If the path doesn't exist, it is created on-the-fly.
-   * - Nested folders are supported by using multiple "/".
-   * - Default: "/"
-   */
-  folder?: string;
-
-  /**
-   * Whether to mark the file as private (only relevant for image uploads).
-   * A private file requires signed URLs or named transformations for access.
-   * Default: false
-   */
-  isPrivateFile?: boolean;
-
-  /**
-   * A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size).
-   * Example: "10,10,100,100".
-   */
-  customCoordinates?: string;
-
-  /**
-   * A comma-separated or array-based set of fields to return in the upload response.
-   * Example: "tags,customCoordinates,isPrivateFile,metadata"
-   */
-  responseFields?: string | string[];
-
-  /**
-   * An array of extension objects to apply to the image, e.g. background removal, auto-tagging, etc.
-   * The SDK will JSON-stringify this array automatically before sending.
-   */
-  extensions?: object[];
-
-  /**
-   * A webhook URL to receive the final status of any pending extensions once they've completed processing.
-   */
-  webhookUrl?: string;
-
-  /**
-   * Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists.
-   */
-  overwriteFile?: boolean;
-
-  /**
-   * Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags.
-   */
-  overwriteAITags?: boolean;
-
-  /**
-   * Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags.
-   */
-  overwriteTags?: boolean;
-
-  /**
-   * Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata.
-   */
-  overwriteCustomMetadata?: boolean;
-
-  /**
-   * A stringified JSON or an object containing custom metadata fields to store with the file.
-   * Custom metadata fields must be pre-defined in your ImageKit configuration.
-   */
-  customMetadata?: string | Record<string, string | number | boolean | Array<string | number | boolean>>;
-
-  /**
-   * Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations.
-   * For details, see:
-   * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload}
-   */
-  transformation?: Transformation;
-
-  /**
-   * An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc.
-   * You can listen to `progress` or other events on this object for custom logic.
-   */
-  xhr?: XMLHttpRequest;
-
-  /**
-   * A string specifying the checks to be performed server-side before uploading to the media library, e.g. size or mime type checks.
-   * For format details, see: {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#upload-api-checks}
-   */
-  checks?: string;
-
-  /**
-   * Optional callback function that will be called with the progress event when the file is being uploaded.
-   */
-  onProgress?: (event: ProgressEvent) => void;
-
-  /**
-   * An AbortSignal instance that can be used to cancel the request if needed.
-   * When aborted, the request fails with an ImageKitAbortError.
-   */
-  abortSignal?: AbortSignal;
-}

package/src/interfaces/UploadResponse.ts

@@ -1,182 +0,0 @@
-/**
- * Type of files to include in result set. Accepts three values:
- * all - include all types of files in result set
- * image - only search in image type files
- * non-image - only search in files which are not image, e.g., JS or CSS or video files.
- *
- * {@link https://imagekit.io/docs/api-reference/digital-asset-management-dam/list-and-search-assets}
- */
-type FileType = "all" | "image" | "non-image";
-
-/**
- * Metadata object structure
- * 
- * {@link https://imagekit.io/docs/api-reference/file-metadata/get-uploaded-file-metadata#Responses}
- * 
- * Contents of Object
- * 
- * - Exif
- * 
- * For more information about the Exif standard, please refer to the specification found on http://www.exif.org. A comprehensive list of available Exif attributes and their meaning can be found on http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/.
- * 
- * - Perceptual Hash (pHash)
- * 
- * Perceptual hashing allows you to construct a hash value that uniquely identifies an input image based on the image's contents. It is different from cryptographic hash functions like MD5 and SHA1. pHash provides similar hash value after minor distortions, like small rotations, blurring, and compression in the image.
- */
-interface Metadata {
-  height: number;
-  width: number;
-  size: number;
-  format: string;
-  hasColorProfile: boolean;
-  quality: number;
-  density: number;
-  hasTransparency: boolean;
-  pHash: string;
-  exif: {
-    image: {
-      Make: string;
-      Model: string;
-      Orientation: number;
-      XResolution: number;
-      YResolution: number;
-      ResolutionUnit: number;
-      Software: string;
-      ModifyDate: string;
-      YCbCrPositioning: number;
-      ExifOffset: number;
-      GPSInfo: number;
-    };
-    thumbnail: {
-      Compression: number;
-      XResolution: number;
-      YResolution: number;
-      ResolutionUnit: number;
-      ThumbnailOffset: number;
-      ThumbnailLength: number;
-    };
-    exif: {
-      ExposureTime: number;
-      FNumber: number;
-      ExposureProgram: number;
-      ISO: number;
-      ExifVersion: string;
-      DateTimeOriginal: string;
-      CreateDate: string;
-      ShutterSpeedValue: number;
-      ApertureValue: number;
-      ExposureCompensation: number;
-      MeteringMode: number;
-      Flash: number;
-      FocalLength: number;
-      SubSecTime: string;
-      SubSecTimeOriginal: string;
-      SubSecTimeDigitized: string;
-      FlashpixVersion: string;
-      ColorSpace: number;
-      ExifImageWidth: number;
-      ExifImageHeight: number;
-      InteropOffset: number;
-      FocalPlaneXResolution: number;
-      FocalPlaneYResolution: number;
-      FocalPlaneResolutionUnit: number;
-      CustomRendered: number;
-      ExposureMode: number;
-      WhiteBalance: number;
-      SceneCaptureType: number;
-    };
-    gps: { GPSVersionID: number[] };
-    interoperability: {
-      InteropIndex: string;
-      InteropVersion: string;
-    };
-    makernote: any;
-  };
-}
-
-export interface ResponseMetadata {
-  statusCode: number;
-  requestId: string;
-  headers: Record<string, string | number | boolean>;
-}
-
-/**
- * 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;
-  /**
-   * The name of the uploaded file.
-   */
-  name?: string;
-  /**
-   * The URL of the file.
-   */
-  url?: string;
-  /**
-   * In case of an image, a small thumbnail URL.
-   */
-  thumbnailUrl?: string;
-  /**
-   * Height of the uploaded image file. Only applicable when file type is image.
-   */
-  height?: number;
-  /**
-   * Width of the uploaded image file. Only applicable when file type is image.
-   */
-  width?: number;
-  /**
-   * Size of the uploaded file in bytes.
-   */
-  size?: number;
-  /**
-   * Type of file. It can either be image or non-image.
-   */
-  fileType?: FileType;
-  /**
-   * The path of the file uploaded. It includes any folder that you specified while uploading.
-   */
-  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;
-  /**
-   * Value of custom coordinates associated with the image in format x,y,width,height.
-   */
-  customCoordinates?: string | null;
-  /**
-   * The metadata of the upload file. Use responseFields property in request to get the metadata returned in response of upload API.
-   */
-  metadata?: Metadata;
-  /*
-   * 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;
-}

package/src/interfaces/index.ts

@@ -1,7 +0,0 @@
-// src/interfaces/index.ts
-// Re-export all interfaces so that TypeDoc includes referenced types in the documentation
-
-export * from './UploadResponse';
-export * from './UploadOptions';
-export * from './Transformation';
-export * from './SrcOptions';

package/src/upload.ts

@@ -1,274 +0,0 @@
-import errorMessages from "./constants/errorMessages";
-import { ResponseMetadata, UploadOptions, UploadResponse } from "./interfaces";
-
-/**
- * Represents an error when a request to ImageKit is invalid.
- */
-export class ImageKitInvalidRequestError extends Error {
-  /**
-   * Optional metadata about the response. It is only available if server returns a response.
-   */
-  readonly $ResponseMetadata?: ResponseMetadata;
-  constructor(message: string, responseMetadata?: ResponseMetadata) {
-    super(message);
-    this.name = "ImageKitInvalidRequestError";
-    this.$ResponseMetadata = responseMetadata;
-  }
-}
-
-/**
- * Represents an error when an upload operation is aborted.
- */
-export class ImageKitAbortError extends Error {
-  /**
-   * The reason why the operation was aborted, which can be any JavaScript value. If not specified, the reason is set to "AbortError" DOMException.
-   */
-  reason?: unknown;
-  constructor(message: string, reason?: unknown) {
-    super(message);
-    this.name = "ImageKitAbortError";
-    this.reason = reason;
-  }
-}
-
-/**
- * Represents a network error during an upload operation to ImageKit.
- */
-export class ImageKitUploadNetworkError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ImageKitUploadNetworkError";
-  }
-}
-
-/**
- * Represents a server error from ImageKit during an upload operation.
- */
-export class ImageKitServerError extends Error {
-  /**
-   * Optional metadata about the response. It is only available if server returns a response.
-   */
-  readonly $ResponseMetadata?: ResponseMetadata;
-  constructor(message: string, responseMetadata?: ResponseMetadata) {
-    super(message);
-    this.name = "ImageKitServerError";
-    this.$ResponseMetadata = responseMetadata;
-  }
-}
-
-/**
- * Uploads a file to ImageKit with the given upload options. This function uses V1 API, check the [API docs](https://imagekit.io/docs/api-reference/upload-file/upload-file) for more details.
- *
- * @throws {ImageKitInvalidRequestError} If the request is invalid.
- * @throws {ImageKitAbortError} If the request is aborted.
- * @throws {ImageKitUploadNetworkError} If there is a network error.
- * @throws {ImageKitServerError} If there is a server error.
- *
- * @param {UploadOptions} uploadOptions - The options for uploading the file.
- * @returns {Promise<UploadResponse>} A Promise resolving to a successful UploadResponse.
- */
-export const upload = (uploadOptions: UploadOptions): Promise<UploadResponse> => {
-  if(!uploadOptions) {
-    return Promise.reject(new ImageKitInvalidRequestError("Invalid options provided for upload"));
-  }
-  return new Promise((resolve, reject) => {
-    const { xhr: userProvidedXHR } = uploadOptions || {};
-    delete uploadOptions.xhr;
-    const xhr = userProvidedXHR || new XMLHttpRequest();
-
-    if (!uploadOptions.file) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILE_PARAMETER.message));
-    }
-
-    if (!uploadOptions.fileName) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_UPLOAD_FILENAME_PARAMETER.message));
-    }
-
-    if (!uploadOptions.publicKey || uploadOptions.publicKey.length === 0) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_PUBLIC_KEY.message));
-    }
-
-    if (!uploadOptions.token) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_TOKEN.message));
-    }
-
-    if (!uploadOptions.signature) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_SIGNATURE.message));
-    }
-
-    if (!uploadOptions.expire) {
-      return reject(new ImageKitInvalidRequestError(errorMessages.MISSING_EXPIRE.message));
-    }
-
-    if (uploadOptions.transformation) {
-      if (!(Object.keys(uploadOptions.transformation).includes("pre") || Object.keys(uploadOptions.transformation).includes("post"))) {
-        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_TRANSFORMATION.message));
-      }
-      if (Object.keys(uploadOptions.transformation).includes("pre") && !uploadOptions.transformation.pre) {
-        return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_PRE_TRANSFORMATION.message));
-      }
-      if (Object.keys(uploadOptions.transformation).includes("post")) {
-        if (Array.isArray(uploadOptions.transformation.post)) {
-          for (let transformation of uploadOptions.transformation.post) {
-            if (transformation.type === "abs" && !(transformation.protocol || transformation.value)) {
-              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-            } else if (transformation.type === "transformation" && !transformation.value) {
-              return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-            }
-          }
-        } else {
-          return reject(new ImageKitInvalidRequestError(errorMessages.INVALID_POST_TRANSFORMATION.message));
-        }
-      }
-    }
-
-    var formData = new FormData();
-    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 === 'signature') {
-          formData.append("signature", uploadOptions.signature);
-        } else if (key === 'expire') {
-          formData.append("expire", String(uploadOptions.expire));
-        } else if (key === 'token') {
-          formData.append("token", uploadOptions.token);
-        } 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 if (key === "transformation" && typeof uploadOptions.transformation === "object" &&
-          uploadOptions.transformation !== null) {
-          formData.append(key, JSON.stringify(uploadOptions.transformation));
-        } else if (key === 'checks' && uploadOptions.checks) {
-          formData.append("checks", uploadOptions.checks);
-        } else if (uploadOptions[key] !== undefined) {
-          if (["onProgress", "abortSignal"].includes(key)) continue;
-          formData.append(key, String(uploadOptions[key]));
-        }
-      }
-    }
-
-    formData.append("publicKey", uploadOptions.publicKey);
-
-    if (uploadOptions.onProgress) {
-      xhr.upload.onprogress = function (event: ProgressEvent) {
-        if (uploadOptions.onProgress) uploadOptions.onProgress(event)
-      };
-    }
-
-    function onAbortHandler() {
-      xhr.abort();
-      return reject(new ImageKitAbortError(
-        "Upload aborted",
-        uploadOptions.abortSignal?.reason
-      ));
-    }
-
-    if (uploadOptions.abortSignal) {
-      if (uploadOptions.abortSignal.aborted) {
-        // If the signal is already aborted, return immediately with the reason
-
-        return reject(new ImageKitAbortError(
-          "Upload aborted",
-          uploadOptions.abortSignal?.reason
-        ));
-      }
-
-      // If the signal is not already aborted, add an event listener to abort the request when the signal is aborted
-      uploadOptions.abortSignal.addEventListener("abort", onAbortHandler);
-
-      // On XHR completion (success, fail, or abort), remove just this abort handler
-      xhr.addEventListener("loadend", () => {
-        if (uploadOptions.abortSignal) {
-          uploadOptions.abortSignal.removeEventListener("abort", onAbortHandler);
-        }
-      });
-    }
-
-    xhr.open('POST', 'https://upload.imagekit.io/api/v1/files/upload');
-    xhr.onerror = function (e) {
-      return reject(new ImageKitUploadNetworkError(errorMessages.UPLOAD_ENDPOINT_NETWORK_ERROR.message));
-    }
-    xhr.onload = function () {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        try {
-          var body = JSON.parse(xhr.responseText);
-          var uploadResponse = addResponseHeadersAndBody(body, xhr);
-          return resolve(uploadResponse);
-        } catch (ex: any) {
-          return reject(ex);
-        }
-      } else if (xhr.status >= 400 && xhr.status < 500) {
-        // Send ImageKitInvalidRequestError
-        try {
-          var body = JSON.parse(xhr.responseText);
-          return reject(new ImageKitInvalidRequestError(
-            body.message ?? "Invalid request. Please check the parameters.",
-            getResponseMetadata(xhr)
-          ));
-        } catch (ex: any) {
-          return reject(ex);
-        }
-      } else {
-        // Send ImageKitServerError
-        try {
-          var body = JSON.parse(xhr.responseText);
-          return reject(new ImageKitServerError(
-            body.message ?? "Server error occurred while uploading the file. This is rare and usually temporary.",
-            getResponseMetadata(xhr)
-          ));
-        } catch (ex: any) {
-          return reject(new ImageKitServerError(
-            "Server error occurred while uploading the file. This is rare and usually temporary.",
-            getResponseMetadata(xhr)
-          ));
-        }
-      }
-    };
-    xhr.send(formData);
-  });
-};
-
-
-const addResponseHeadersAndBody = (body: any, xhr: XMLHttpRequest) => {
-  let response = { ...body };
-  const responseMetadata = getResponseMetadata(xhr);
-  Object.defineProperty(response, "$ResponseMetadata", {
-    value: responseMetadata,
-    enumerable: false,
-    writable: false
-  });
-  return response;
-}
-
-const getResponseMetadata = (xhr: XMLHttpRequest): ResponseMetadata => {
-  const headers = getResponseHeaderMap(xhr);
-  const responseMetadata = {
-    statusCode: xhr.status,
-    headers: headers,
-    requestId: headers["x-request-id"]
-  }
-  return responseMetadata;
-}
-
-function getResponseHeaderMap(xhr: XMLHttpRequest): Record<string, string> {
-  const headers: Record<string, string> = {};
-  const responseHeaders = xhr.getAllResponseHeaders();
-  if (Object.keys(responseHeaders).length) {
-    responseHeaders
-      .trim()
-      .split(/[\r\n]+/)
-      .map(value => value.split(/: /))
-      .forEach(keyValue => {
-        headers[keyValue[0].trim().toLowerCase()] = keyValue[1].trim();
-      });
-  }
-  return headers;
-}