corde/lib/src/api/botAPI.d.ts

A simple library for Discord bot tests

import {
  CategoryChannel,
  DMChannel,
  Guild,
  Message,
  NewsChannel,
  Role,
  TextChannel,
  VoiceChannel,
} from "discord.js";
import {
  IChannelIdentifier,
  ICordeBot,
  ICreateChannelOptions,
  ICreateChannelOptionsSimple,
  IGuildCreateOptions,
  IGuildIdentifier,
  IMessageEmbed,
  IRoleData,
  IRoleIdentifier,
} from "../types";
export declare class BotAPI {
  private _bot;
  /**
   * Gets the voice channel state that corde's bot is connected in, If it's connected.
   * This property is filled when `joinVoiceChannel()` connects to a channel
   * and is cleared when `leaveVoiceChannal()` is called.
   */
  get voiceState(): import("../types").IVoiceChannelState | undefined;
  /**
   * Client of Discord.js
   */
  get client(): import("discord.js").Client;
  /**
   * Same of `this.getChannel()`
   * @throws Error if corde bot is not connected.
   */
  get channel(): TextChannel;
  /**
   * Get all channels in **cache** of the bot.
   * @throws Error if corde bot is not connected.
   */
  get channels(): import("discord.js").Channel[];
  /**
   * Same of `this.getGuild()`
   * @throws Error if corde bot is not connected.
   */
  get guild(): Guild;
  /**
   * Members of the guild defined in configs
   * @throws Error if corde bot is not connected.
   */
  get guildMembers(): import("discord.js").GuildMember[];
  /**
   * Get all guilds in **cache** of the bot.
   * @throws Error if corde bot is not connected.
   */
  get guilds(): Guild[];
  /**
   * Get all roles in **cache** of the guild
   * defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.getGuild().roles.cache.array()
   * ```
   * @throws Error if corde bot is not connected.
   */
  get roles(): Role[];
  /**
   * Checks if corde's bot is connected and ready.
   */
  get isLoggedIn(): boolean;
  constructor(bot: ICordeBot);
  /**
   * Checks if a given message was sent by corde's bot
   * @param message Sent message
   * @returns If corde's bot is the author of the message
   */
  isMessageAuthor(message: Message): boolean;
  /**
   * Joins corde's bot to a voice channel.
   * @param channelId Voice channel to corde's bot connect
   * @throws Error if corde bot is not connected.
   * @returns Voice connection state. This property can be get from `bot.voiceState`
   */
  joinVoiceChannel(channelId: string): Promise<import("../types").IVoiceChannelState>;
  /**
   * Leaves a voice channel.
   * @throws Error if corde bot is not connected.
   */
  leaveVoiceChannel(): void;
  /**
   * From all channels in **cache**, get all that are of type text
   * @throws Error if corde bot is not connected.
   */
  getOnlyTextChannels(): (TextChannel | DMChannel | NewsChannel)[];
  /**
   * Checks if corde's bot is in a voice channel
   */
  isInVoiceChannel(): boolean;
  /**
   * Makes a fetch of a channel based on it's `id`.
   * @param id Id of the channel.
   * @throws Error if corde bot is not connected.
   * @returns Channel if it's found
   */
  fetchChannel(id: string): Promise<import("discord.js").Channel | undefined>;
  /**
   * Makes a fetch of a guild based on it's `id`.
   * @param id Id of the guild
   * @throws Error if corde bot is not connected.
   * @returns Guild if it's found
   */
  fetchGuild(id: string): Promise<Guild | undefined>;
  /**
   * Fetch for a role based on it's id, caching it after that.
   * @param roleId Id of the role.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Fetched Role or undefined.
   */
  fetchRole(roleId: string): Promise<Role | undefined>;
  /**
   * Fetch for a role based on it's id, and it's guild's id, caching it after that.
   *
   * @param roleId Id of the role.
   * @param guildId Id of the guild.
   * @param fetchGuild Define if the guild should be fetched or searched in cache.
   *
   * @throws Error if corde's bot isn't connected yet.
   *
   * @returns Fetched Role or undefined.
   */
  fetchRole(roleId: string, guildId: string, fetchGuild?: boolean): Promise<Role | undefined>;
  private _getOrFetchGuild;
  /**
   * Gets the channel defined in `configs`
   * @throws Error if corde bot is not connected.
   */
  getChannel(): TextChannel;
  /**
   * Gets a channel from `client.channels.cache` based on the channel's id
   *
   * @param id Channel Id
   * @throws Error if corde bot is not connected.
   * @return Channel searched by it's id or undefined.
   */
  getChannel(id: string): TextChannel | undefined;
  /**
   * Gets a channel from `client.channels.cache` based on the channel's id or name
   *
   * @param identifier Channel's identifier
   * @throws Error if corde bot is not connected.
   * @return Channel searched or undefined.
   */
  getChannel(identifier: IChannelIdentifier): TextChannel | undefined;
  /**
   * Gets the guild defined in `configs`
   * @throws Error if corde bot is not connected.
   */
  getGuild(): Guild;
  /**
   * Gets a guild from `client.channels.guild` based on the guild's id
   * @param id Guild Id
   * @throws Error if corde bot is not connected.
   * @return Guild searched by it's id or undefined.
   */
  getGuild(id: string): Guild | undefined;
  /**
   * Gets a guild from `client.guild.cache` based on the guild's id or name
   *
   * @param identifier Guild's identifier
   * @throws Error if corde bot is not connected.
   * @return Guild searched or undefined.
   */
  getGuild(identifier: IGuildIdentifier): Guild | undefined;
  /**
   * Sends a message to the connected textChannel.
   *
   * **This function does not work without a test case**
   *
   * @param message Message to send
   *
   * @example
   *
   * // Works
   * test("test 1", () => {
   *    const message = await corde.bot.send("msg");
   *    expect(`editMessage ${message.id}`).toEditMessage({ id: message.id }, "newValue");
   * });
   *
   * // Do not Works
   * group("test 1", () => {
   *    const message = await corde.bot.send("msg");
   * });
   *
   * @throws Error if corde bot is not connected.
   * @throws Error If message is invalid.
   *
   * @returns null if message is empty, null or undefined.
   * Message if **message** is not empty and it was send to Discord.
   *
   * @since 2.0
   */
  send(message: string | number | boolean | bigint): Promise<Message>;
  send(message: IMessageEmbed): Promise<Message>;
  /**
   * Creates a new role inside the guild provided in configs.
   *
   * @param name Name of the role.
   * @throws CordeClientError if corde has not yet connect it's bot.
   * @returns A promise that return the created role.
   *
   * @since 2.1
   */
  createRole(name?: string): Promise<Role>;
  /**
   * Creates a new role inside the guild provided in configs.
   *
   * @param data Basic informations about the role.
   * @throws CordeClientError if corde has not yet connect it's bot.
   * @returns A promise that return the created role.
   *
   * @since 2.1
   */
  createRole(data: IRoleData): Promise<Role>;
  private _throwErrorIfInvalidName;
  /**
   * Creates a new `guild` in defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.guilds.create("nameExample");
   * ```
   *
   * @param name Name of the new guild.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created guild.
   */
  createGuild(name: string): Promise<Guild>;
  /**
   * Creates a new `guild` in defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.guilds.create("exampleName", { ... });
   * ```
   *
   * @param options Informations about the guild.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created guild.
   */
  createGuild(options: IGuildCreateOptions): Promise<Guild>;
  /**
   * Creates a new channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName");
   * ```
   *
   * @param name Name of the new channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createChannel(name: string): Promise<TextChannel>;
  /**
   * Creates a new channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { ... });
   * ```
   *
   * @param options Informations about the channel, including it's type.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createChannel(
    channelOptions: ICreateChannelOptions,
  ): Promise<TextChannel | VoiceChannel | CategoryChannel>;
  /**
   * Creates a new **voice** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { type: "voice" });
   * ```
   *
   * @param name Name of the new channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createVoiceChannel(name: string): Promise<VoiceChannel>;
  /**
   * Creates a new **voice** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { ..., type: "voice" });
   * ```
   *
   * @param options Informations about the channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createVoiceChannel(options: ICreateChannelOptionsSimple): Promise<VoiceChannel>;
  /**
   * Creates a new **text** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { type: "text" });
   * ```
   *
   * @param name Name of the new channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createTextChannel(name: string): Promise<TextChannel>;
  /**
   * Creates a new **text** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { ..., type: "text" });
   * ```
   *
   * @param options Informations about the channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createTextChannel(options: ICreateChannelOptionsSimple): Promise<TextChannel>;
  /**
   * Creates a new **category** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { type: "category" });
   * ```
   *
   * @param name Name of the new channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createCategoryChannel(name: string): Promise<CategoryChannel>;
  /**
   * Creates a new **category** channel in guild defined in configs.
   *
   * Shortcut for:
   *
   * ```typescript
   * this.client.channels.create("exampleName", { ..., type: "category" });
   * ```
   *
   * @param options Informations about the channel.
   * @throws Error if corde's bot isn't connected yet.
   * @returns Created channel.
   */
  createCategoryChannel(options: ICreateChannelOptionsSimple): Promise<CategoryChannel>;
  /**
   * Finds a role in config guild's cache, basing on it's **id**
   *
   * @param id Id of the role.
   * @throws CordeClientError if corde's bot is not connected.
   * @returns Role that matches the provided **id** or **name**
   */
  getRole(id: string): Role | undefined;
  /**
   * Finds a role in config guild's cache, basing on it's **id** or **name**.
   *
   * @param data Data of the role. It can be it's **name** or **id**.
   *
   * if both informations be provided, and they are from two differents
   * roles, the result will correspond to the role that matchs with the parameter
   * **id**.
   *
   * @throws CordeClientError if corde's bot is not connected.
   * @returns Role that matches the provided **id** or **name**
   */
  getRole(data: IRoleIdentifier): Role | undefined;
  private _fetchRole;
  private _getRole;
  private _createChannel;
  private _throwErrorIfNotLogged;
}