magmastream 2.9.3-dev.24 → 2.9.3-dev.26

package/dist/structures/Manager.d.ts

@@ -0,0 +1,259 @@
+import { Collection } from "@discordjs/collection";
+import { GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { EventEmitter } from "events";
+import { Node } from "./Node";
+import { Player } from "./Player";
+import { Redis as RedisClient } from "ioredis";
+import { AnyGuild, AnyUser, ManagerEvents, ManagerInitOptions, ManagerOptions, NodeOptions, PlayerOptions, SearchQuery, SearchResult, TrackData, VoicePacket, VoiceServer, VoiceState } from "./Types";
+/**
+ * The main hub for interacting with Lavalink and using Magmastream.
+ */
+export declare class Manager extends EventEmitter {
+    /** The map of players. */
+    readonly players: Collection<string, Player>;
+    /** The map of nodes. */
+    readonly nodes: Collection<string, Node>;
+    /** The options that were set. */
+    readonly options: ManagerOptions;
+    initiated: boolean;
+    redis?: RedisClient;
+    private _send;
+    private _getUser?;
+    private _getGuild?;
+    private loadedPlugins;
+    /**
+     * Initiates the Manager class.
+     * @param options
+     * @param options.enabledPlugins - An array of enabledPlugins to load.
+     * @param options.nodes - An array of node options to create nodes from.
+     * @param options.playNextOnEnd - Whether to automatically play the first track in the queue when the player is created.
+     * @param options.autoPlaySearchPlatforms - The search platform autoplay will use. Fallback to Youtube if not found.
+     * @param options.enablePriorityMode - Whether to use the priority when selecting a node to play on.
+     * @param options.clientName - The name of the client to send to Lavalink.
+     * @param options.defaultSearchPlatform - The default search platform to use when searching for tracks.
+     * @param options.useNode - The strategy to use when selecting a node to play on.
+     * @param options.trackPartial - The partial track search results to use when searching for tracks. This partials will always be presented on each track.
+     * @param options.eventBatchDuration - The duration to wait before processing the collected player state events.
+     * @param options.eventBatchInterval - The interval to wait before processing the collected player state events.
+     */
+    constructor(options: ManagerOptions);
+    /**
+     * Initiates the Manager.
+     * @param clientId - The Discord client ID (only required when not using any of the magmastream wrappers).
+     * @param clusterId - The cluster ID which runs the current process (required).
+     * @returns The manager instance.
+     */
+    init(options?: ManagerInitOptions): Promise<this>;
+    /**
+     * Searches the enabled sources based off the URL or the `source` property.
+     * @param query
+     * @param requester
+     * @returns The search result.
+     */
+    search<T = unknown>(query: string | SearchQuery, requester?: T): Promise<SearchResult>;
+    /**
+     * Returns a player or undefined if it does not exist.
+     * @param guildId The guild ID of the player to retrieve.
+     * @returns The player if it exists, undefined otherwise.
+     */
+    getPlayer(guildId: string): Player | undefined;
+    /**
+     * Creates a player or returns one if it already exists.
+     * @param options The options to create the player with.
+     * @returns The created player.
+     */
+    create(options: PlayerOptions): Player;
+    /**
+     * Destroys a player.
+     * @param guildId The guild ID of the player to destroy.
+     * @returns A promise that resolves when the player has been destroyed.
+     */
+    destroy(guildId: string): Promise<void>;
+    /**
+     * Creates a new node or returns an existing one if it already exists.
+     * @param options - The options to create the node with.
+     * @returns The created node.
+     */
+    createNode(options: NodeOptions): Node;
+    /**
+     * Destroys a node if it exists. Emits a debug event if the node is found and destroyed.
+     * @param identifier - The identifier of the node to destroy.
+     * @returns {void}
+     * @emits {debug} - Emits a debug message indicating the node is being destroyed.
+     */
+    destroyNode(identifier: string): Promise<void>;
+    /**
+     * Attaches an event listener to the manager.
+     * @param event The event to listen for.
+     * @param listener The function to call when the event is emitted.
+     * @returns The manager instance for chaining.
+     */
+    on<T extends keyof ManagerEvents>(event: T, listener: (...args: ManagerEvents[T]) => void): this;
+    /**
+     * Updates the voice state of a player based on the provided data.
+     * @param data - The data containing voice state information, which can be a VoicePacket, VoiceServer, or VoiceState.
+     * @returns A promise that resolves when the voice state update is handled.
+     * @emits {debug} - Emits a debug message indicating the voice state is being updated.
+     */
+    updateVoiceState(data: VoicePacket | VoiceServer | VoiceState): Promise<void>;
+    /**
+     * Decodes an array of base64 encoded tracks and returns an array of TrackData.
+     * Emits a debug event with the tracks being decoded.
+     * @param tracks - An array of base64 encoded track strings.
+     * @returns A promise that resolves to an array of TrackData objects.
+     * @throws Will throw an error if no nodes are available or if the API request fails.
+     */
+    decodeTracks(tracks: string[]): Promise<TrackData[]>;
+    /**
+     * Decodes a base64 encoded track and returns a TrackData.
+     * @param track - The base64 encoded track string.
+     * @returns A promise that resolves to a TrackData object.
+     * @throws Will throw an error if no nodes are available or if the API request fails.
+     */
+    decodeTrack(track: string): Promise<TrackData>;
+    /**
+     * Saves player states.
+     * @param {string} guildId - The guild ID of the player to save
+     */
+    savePlayerState(guildId: string): Promise<void>;
+    /**
+     * Sleeps for a specified amount of time.
+     * @param ms The amount of time to sleep in milliseconds.
+     * @returns A promise that resolves after the specified amount of time.
+     */
+    private sleep;
+    private restorePlayerFromState;
+    private restoreQueue;
+    private restorePreviousQueue;
+    private restoreRepeatState;
+    private restorePlayerData;
+    private restoreFilters;
+    /**
+     * Loads player states from the JSON file.
+     * @param nodeId The ID of the node to load player states from.
+     * @returns A promise that resolves when the player states have been loaded.
+     */
+    loadPlayerStates(nodeId: string): Promise<void>;
+    /**
+     * Returns the node to use based on the configured `useNode` and `enablePriorityMode` options.
+     * If `enablePriorityMode` is true, the node is chosen based on priority, otherwise it is chosen based on the `useNode` option.
+     * If `useNode` is "leastLoad", the node with the lowest load is chosen, if it is "leastPlayers", the node with the fewest players is chosen.
+     * If `enablePriorityMode` is false and `useNode` is not set, the node with the lowest load is chosen.
+     * @returns {Node} The node to use.
+     */
+    get useableNode(): Node;
+    /**
+     * Handles the shutdown of the process by saving all active players' states and optionally cleaning up inactive players.
+     * This function is called when the process is about to exit.
+     * It iterates through all players and calls {@link savePlayerState} to save their states.
+     * Optionally, it also calls {@link cleanupInactivePlayers} to remove any stale player state files.
+     * After saving and cleaning up, it exits the process.
+     */
+    handleShutdown(): Promise<void>;
+    /**
+     * Parses a YouTube title into a clean title and author.
+     * @param title - The original title of the YouTube video.
+     * @param originalAuthor - The original author of the YouTube video.
+     * @returns An object with the clean title and author.
+     */
+    private parseYouTubeTitle;
+    /**
+     * Balances brackets in a given string by ensuring all opened brackets are closed correctly.
+     * @param str - The input string that may contain unbalanced brackets.
+     * @returns A new string with balanced brackets.
+     */
+    private balanceBrackets;
+    /**
+     * Escapes a string by replacing special regex characters with their escaped counterparts.
+     * @param string - The string to escape.
+     * @returns The escaped string.
+     */
+    private escapeRegExp;
+    /**
+     * Checks if the given data is a voice update.
+     * @param data The data to check.
+     * @returns Whether the data is a voice update.
+     */
+    private isVoiceUpdate;
+    /**
+     * Determines if the provided update is a valid voice update.
+     * A valid update must contain either a token or a session_id.
+     *
+     * @param update - The voice update data to validate, which can be a VoicePacket, VoiceServer, or VoiceState.
+     * @returns {boolean} - True if the update is valid, otherwise false.
+     */
+    private isValidUpdate;
+    /**
+     * Handles a voice server update by updating the player's voice state and sending the voice state to the Lavalink node.
+     * @param player The player for which the voice state is being updated.
+     * @param update The voice server data received from Discord.
+     * @returns A promise that resolves when the voice state update is handled.
+     * @emits {debug} - Emits a debug message indicating the voice state is being updated.
+     */
+    private handleVoiceServerUpdate;
+    /**
+     * Handles a voice state update by updating the player's voice channel and session ID if provided, or by disconnecting and destroying the player if the channel ID is null.
+     * @param player The player for which the voice state is being updated.
+     * @param update The voice state data received from Discord.
+     * @emits {playerMove} - Emits a player move event if the channel ID is provided and the player is currently connected to a different voice channel.
+     * @emits {playerDisconnect} - Emits a player disconnect event if the channel ID is null.
+     */
+    private handleVoiceStateUpdate;
+    /**
+     * Cleans up an inactive player by removing its state data.
+     * This is done to prevent stale state data from accumulating.
+     * @param guildId The guild ID of the player to clean up.
+     */
+    cleanupInactivePlayer(guildId: string): Promise<void>;
+    /**
+     * Loads the enabled plugins.
+     */
+    private loadPlugins;
+    /**
+     * Unloads the enabled plugins.
+     */
+    private unloadPlugins;
+    /**
+     * Clears all player states from the file system.
+     * This is done to prevent stale state files from accumulating on the file system.
+     */
+    private clearAllStoredPlayers;
+    /**
+     * Returns the nodes that has the least load.
+     * The load is calculated by dividing the lavalink load by the number of cores.
+     * The result is multiplied by 100 to get a percentage.
+     * @returns {Collection<string, Node>}
+     */
+    private get leastLoadNode();
+    /**
+     * Returns the nodes that have the least amount of players.
+     * Filters out disconnected nodes and sorts the remaining nodes
+     * by the number of players in ascending order.
+     * @returns {Collection<string, Node>} A collection of nodes sorted by player count.
+     */
+    private get leastPlayersNode();
+    /**
+     * Returns a node based on priority.
+     * The nodes are sorted by priority in descending order, and then a random number
+     * between 0 and 1 is generated. The node that has a cumulative weight greater than or equal to the
+     * random number is returned.
+     * If no node has a cumulative weight greater than or equal to the random number, the node with the
+     * lowest load is returned.
+     * @returns {Node} The node to use.
+     */
+    private get priorityNode();
+    protected send(packet: GatewayVoiceStateUpdate): unknown;
+    protected getUserFromCache(id: string): AnyUser | undefined;
+    protected getGuildFromCache(id: string): AnyGuild | undefined;
+    sendPacket(packet: GatewayVoiceStateUpdate): unknown;
+    /**
+     * Resolves a PortableUser or ID to a real user object.
+     * Can be overridden by wrapper managers to return wrapper-specific User classes.
+     */
+    resolveUser(user: AnyUser | string): Promise<AnyUser>;
+    /**
+     * Resolves a Guild ID to a real guild object.
+     * Can be overridden by wrapper managers to return wrapper-specific Guild classes.
+     */
+    resolveGuild(guildId: string): AnyGuild;
+}