node-catbox/dist/index.d.mts

A library for interacting with Catbox.moe written in TypeScript.

import EventEmitter from "node:events";

//#region src/utils.d.ts
type ResponseSnapshot = Readonly<{
  url: string;
  ok: boolean;
  status: number;
  statusText: string;
  redirected: boolean;
  type: Response['type'];
  headers: Readonly<Record<string, string>>;
}>;
type RequestSnapshot = Readonly<{
  url: string;
  method: string;
  headers: Readonly<Record<string, string>>;
  hasBody: boolean;
}>;
//#endregion
//#region src/lib/Catbox.d.ts
type CatboxEvents = {
  uploadingURL: [url: string];
  uploadingFile: [filepath: string];
  uploadingStream: [filename: string];
  deletingFiles: [files: string[]];
  creatingAlbum: [title: string, description: string, files?: string[]];
  editingAlbum: [id: string, title: string, description: string, files?: string[]];
  addingFilesToAlbum: [id: string, files: string[]];
  removingFilesFromAlbum: [id: string, files: string[]];
  removingAlbum: [id: string];
  request: [request: RequestSnapshot];
  response: [response: ResponseSnapshot];
};
type UploadURLOptions = {
  /**
   * Direct URL of the file to upload
   */
  url: string;
};
type UploadFileOptions$1 = {
  /**
   * Path to the file to upload
   */
  path: string;
  /**
   * Maximum file size in bytes before throwing, defaults to 200 MB.
   */
  maxFileBytes?: number;
};
type UploadFileStreamOptions$1 = {
  stream: ReadableStream | AsyncIterable<any>;
  filename: string;
  /**
   * Maximum stream size in bytes before throwing, defaults to 200 MB.
   */
  maxStreamBytes?: number;
};
type DeleteFilesOptions = {
  /**
   * Array of existing file names (including extension) to delete
   */
  files: string[];
};
type CreateAlbumOptions = {
  /**
   * Title of the album
   */
  title: string;
  /**
   * Description of the album
   */
  description: string;
  /**
   * Names of existing files that the album should contain
   */
  files?: string[];
};
type EditAlbumOptions = CreateAlbumOptions & {
  /**
   * ID of the album
   */
  id: string;
};
type AddFilesToAlbumOptions = {
  /**
   * ID of the album
   */
  id: string;
  /**
   * Names of existing files to add to the album
   */
  files: string[];
};
type RemoveFilesFromAlbumOptions = {
  /**
   * ID of the album
   */
  id: string;
  /**
   * Names of existing files to remove from the album
   */
  files: string[];
};
type DeleteAlbumOptions = {
  /**
   * ID of the album
   */
  id: string;
};
declare class Catbox extends EventEmitter<CatboxEvents> {
  #private;
  /**
   * Creates a new {@link Catbox} instance
   * @param userHash Optional user hash
   */
  constructor(userHash?: string);
  /**
   * The user hash, if available
   */
  get userHash(): string | undefined;
  /**
   * Sets the user hash for this instance
   * @param userHash Your account's user hash
   * @see https://catbox.moe/user/manage.php
   */
  setUserHash(userHash: string): void;
  /**
   * Uploads a file via direct URL to Catbox.moe
   *
   * Files uploaded while a `userHash` is provided will be tied to your account.
   * @param options Options
   * @returns The uploaded file URL
   */
  uploadURL({
    url
  }: UploadURLOptions): Promise<string>;
  /**
   * Uploads a file via its path to Catbox.moe
   *
   * Files uploaded while a `userHash` is provided will be tied to your account.
   * @param options Options
   * @returns The uploaded file URL
   */
  uploadFile({
    path,
    maxFileBytes
  }: UploadFileOptions$1): Promise<string>;
  uploadFileStream({
    stream,
    filename,
    maxStreamBytes
  }: UploadFileStreamOptions$1): Promise<string>;
  /**
   * Deletes files from the user account
   * @param options Options
   * @returns `true` if files have been deleted successfully
   */
  deleteFiles({
    files
  }: DeleteFilesOptions): Promise<boolean>;
  /**
   * Creates an album
   * @param options Options
   * @returns The album URL
   */
  createAlbum({
    title,
    description,
    files
  }: CreateAlbumOptions): Promise<string>;
  /**
   * Edits an existing album
   *
   * Values are treated as direct input. For example omitting the description will remove the album's description and supplying a new array of files will change the album's files.
   *
   * Consider using the less-destructive {@link addFilesToAlbum} or {@link removeFilesFromAlbum} methods if you wish to only modify album contents.
   * @param options Options
   * @returns The album URL
   */
  editAlbum({
    id,
    title,
    description,
    files
  }: EditAlbumOptions): Promise<string>;
  /**
   * Adds existing files to an album
   * @param options Options
   * @returns The album URL
   */
  addFilesToAlbum({
    id,
    files
  }: AddFilesToAlbumOptions): Promise<string>;
  /**
   * Removes files from an album
   * @param options Options
   * @returns The album URL
   */
  removeFilesFromAlbum({
    id,
    files
  }: RemoveFilesFromAlbumOptions): Promise<string>;
  /**
   * Deletes an album
   * @param options Options
   * @returns `true` if the album was deleted or if the album doesn't exist
   */
  removeAlbum({
    id
  }: DeleteAlbumOptions): Promise<boolean>;
}
//#endregion
//#region src/lib/Litterbox.d.ts
type LitterboxEvents = {
  uploadingFile: [filepath: string, duration: typeof acceptedDurations[number] | FileLifetime];
  uploadingStream: [filename: string, duration: typeof acceptedDurations[number] | FileLifetime];
  request: [request: RequestSnapshot];
  response: [response: ResponseSnapshot];
};
type UploadFileOptions = {
  /**
   * Path to the file to upload.
   */
  path: string;
  /**
   * Duration before the file is deleted, defaults to `1h`.
   */
  duration?: typeof acceptedDurations[number] | FileLifetime;
  /**
   * The length of the randomized file name.
   */
  fileNameLength?: FileNameLength;
  /**
   * Maximum file size in bytes before throwing, defaults to 1 GB.
   */
  maxFileBytes?: number;
};
type UploadFileStreamOptions = {
  stream: ReadableStream | AsyncIterable<any>;
  filename: string;
  /**
   * Duration before the file is deleted, defaults to `1h`.
   */
  duration?: typeof acceptedDurations[number] | FileLifetime;
  /**
   * The length of the randomized file name.
   */
  fileNameLength?: FileNameLength;
  /**
   * Maximum stream size in bytes before throwing, defaults to 1 GB.
   */
  maxStreamBytes?: number;
};
declare const acceptedDurations: readonly ["1h", "12h", "24h", "72h"];
declare const enum FileLifetime {
  OneHour = "1h",
  TwelveHours = "12h",
  OneDay = "24h",
  ThreeDays = "72h"
}
declare const enum FileNameLength {
  Six = 6,
  Sixteen = 16
}
declare class Litterbox extends EventEmitter<LitterboxEvents> {
  #private;
  /**
   * Uploads a file temporarily to Litterbox
   * @param options Options
   * @returns The uploaded file URL
   */
  uploadFile({
    path,
    duration,
    fileNameLength,
    maxFileBytes
  }: UploadFileOptions): Promise<string>;
  uploadFileStream({
    stream,
    filename,
    duration,
    fileNameLength,
    maxStreamBytes
  }: UploadFileStreamOptions): Promise<string>;
}
//#endregion
export { Catbox, FileLifetime, FileNameLength, Litterbox, acceptedDurations };