lavalink-client 2.1.2 → 2.1.4

package/dist/cjs/structures/LavalinkManager.d.ts

@@ -6,10 +6,6 @@ import { DestroyReasonsType, Player, PlayerJson, PlayerOptions } from "./Player"
 import { ManagerQueueOptions } from "./Queue";
 import { Track, UnresolvedTrack } from "./Track";
 import { ChannelDeletePacket, GuildShardPayload, ManagerUtils, MiniMap, SearchPlatform, SponsorBlockChaptersLoaded, SponsorBlockChapterStarted, SponsorBlockSegmentSkipped, SponsorBlockSegmentsLoaded, TrackEndEvent, TrackExceptionEvent, TrackStartEvent, TrackStuckEvent, VoicePacket, VoiceServer, VoiceState, WebSocketClosedEvent } from "./Utils";
-export interface LavalinkManager {
-    nodeManager: NodeManager;
-    utils: ManagerUtils;
-}
 export interface BotClientOptions {
     /** Bot Client Id */
     id: string;
@@ -168,31 +164,186 @@ interface LavalinkManagerEvents {
     "ChaptersLoaded": (player: Player, track: Track | UnresolvedTrack, payload: SponsorBlockChaptersLoaded) => void;
 }
 export interface LavalinkManager {
-    options: ManagerOptions;
+    /** @private */
     on<U extends keyof LavalinkManagerEvents>(event: U, listener: LavalinkManagerEvents[U]): this;
+    /** @private */
     emit<U extends keyof LavalinkManagerEvents>(event: U, ...args: Parameters<LavalinkManagerEvents[U]>): boolean;
 }
 export declare class LavalinkManager extends EventEmitter {
-    static DefaultSources: Record<SearchPlatform, import("./Utils").LavalinkSearchPlatform | import("./Utils").ClientCustomSearchPlatformUtils>;
-    static SourceLinksRegexes: Record<import("./Utils").SourcesRegex, RegExp>;
+    /** The Options of LavalinkManager (changeable) */
+    options: ManagerOptions;
+    /** LavalinkManager's NodeManager to manage all Nodes */
+    nodeManager: NodeManager;
+    /** LavalinkManager's Utils Class */
+    utils: ManagerUtils;
+    /** Wether the manager was initiated or not */
     initiated: boolean;
+    /** All Players stored in a MiniMap */
     readonly players: MiniMap<string, Player>;
+    /**
+     * Applies the options provided by the User
+     * @param options
+     * @returns
+     */
     private applyOptions;
+    /**
+     * Validates the current manager's options
+     * @param options
+     */
     private validateOptions;
+    /**
+     * Create the Lavalink Manager
+     * @param options
+     *
+     * @example
+     * ```ts
+     * //const client = new Client({...}); // create your BOT Client (e.g. via discord.js)
+     * client.lavalink = new LavalinkManager({
+     *   nodes: [
+     *     {
+     *       authorization: "yourverystrongpassword",
+     *       host: "localhost",
+     *       port: 2333,
+     *       id: "testnode"
+     *     },
+     *     sendToShard(guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+     *     client: {
+     *       id: process.env.CLIENT_ID,
+     *       username: "TESTBOT"
+     *     },
+     *     // optional Options:
+     *     autoSkip: true,
+     *     playerOptions: {
+     *       applyVolumeAsFilter: false,
+     *       clientBasedPositionUpdateInterval: 150,
+     *       defaultSearchPlatform: "ytmsearch",
+     *       volumeDecrementer: 0.75,
+     *       //requesterTransformer: YourRequesterTransformerFunction,
+     *       onDisconnect: {
+     *         autoReconnect: true,
+     *         destroyPlayer: false
+     *       },
+     *       onEmptyQueue: {
+     *         destroyAfterMs: 30_000,
+     *         //autoPlayFunction: YourAutoplayFunction,
+     *       },
+     *       useUnresolvedData: true
+     *     },
+     *     queueOptions: {
+     *       maxPreviousTracks: 25,
+     *       //queueStore: yourCustomQueueStoreManagerClass,
+     *       //queueChangesWatcher: yourCustomQueueChangesWatcherClass
+     *     },
+     *     linksBlacklist: [],
+     *     linksWhitelist: [],
+     *     advancedOptions: {
+     *       debugOptions: {
+     *         noAudio: false,
+     *         playerDestroy: {
+     *           dontThrowError: false,
+     *           debugLogs: false
+     *         }
+     *       }
+     *     }
+     *   ]
+     * })
+     * ```
+     */
     constructor(options: ManagerOptions);
-    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Get a Player from Lava
+     * @param guildId The guildId of the player
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.getPlayer(interaction.guildId);
+     * ```
+     * A quicker and easier way than doing:
+     * ```ts
+     * const player = client.lavalink.players.get(interaction.guildId);
+     * ```
+     * @returns
+     */
     getPlayer(guildId: string): Player;
+    /**
+     * Create a Music-Player. If a player exists, then it returns it before creating a new one
+     * @param options
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.createPlayer({
+     *   guildId: interaction.guildId,
+     *   voiceChannelId: interaction.member.voice.channelId,
+     *   // everything below is optional
+     *   textChannelId: interaction.channelId,
+     *   volume: 100,
+     *   selfDeaf: true,
+     *   selfMute: false,
+     *   instaUpdateFiltersFix: true,
+     *   applyVolumeAsFilter: false
+     *   //only needed if you want to autopick node by region (configured by you)
+     *   // vcRegion: interaction.member.voice.rtcRegion,
+     *   // provide a specific node
+     *   // node: client.lavalink.nodeManager.leastUsedNodes("memory")[0]
+     * });
+     * ```
+     */
+    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Destroy a player with optional destroy reason and disconnect it from the voice channel
+     * @param guildId
+     * @param destroyReason
+     * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.destroyPlayer(interaction.guildId, "forcefully destroyed the player");
+     * // recommend to do it on the player tho: player.destroy("forcefully destroyed the player");
+     * ```
+     */
     destroyPlayer(guildId: string, destroyReason?: string): Promise<Player>;
+    /**
+     * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
+     * @param guildId
+     * @returns
+     */
     deletePlayer(guildId: string): boolean;
+    /**
+     * Checks wether the the lib is useable based on if any node is connected
+     */
     get useable(): boolean;
     /**
-     * Initiates the Manager.
+     * Initiates the Manager, creates all nodes and connects all of them
      * @param clientData
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot ready event
+     * client.on("ready", () => {
+     *   client.lavalink.init({
+     *     id: client.user.id,
+     *     username: client.user.username
+     *   });
+     * });
+     * ```
      */
     init(clientData: BotClientOptions): Promise<this>;
     /**
      * Sends voice data to the Lavalink server.
+     * ! Without this the library won't work
      * @param data
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot "raw" event
+     * client.on("raw", (d) => {
+     *   // required in order to send audio updates and register channel deletion etc.
+     *   client.lavalink.sendRawData(d)
+     * })
+     * ```
      */
     sendRawData(data: VoicePacket | VoiceServer | VoiceState | ChannelDeletePacket): Promise<void>;
 }

package/dist/cjs/structures/LavalinkManager.js

@@ -2,16 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LavalinkManager = void 0;
 const events_1 = require("events");
-const LavalinkManagerStatics_1 = require("./LavalinkManagerStatics");
 const NodeManager_1 = require("./NodeManager");
 const Player_1 = require("./Player");
 const Queue_1 = require("./Queue");
 const Utils_1 = require("./Utils");
 class LavalinkManager extends events_1.EventEmitter {
-    static DefaultSources = LavalinkManagerStatics_1.DefaultSources;
-    static SourceLinksRegexes = LavalinkManagerStatics_1.SourceLinksRegexes;
+    /** The Options of LavalinkManager (changeable) */
+    options;
+    /** LavalinkManager's NodeManager to manage all Nodes */
+    nodeManager;
+    /** LavalinkManager's Utils Class */
+    utils;
+    /** Wether the manager was initiated or not */
     initiated = false;
+    /** All Players stored in a MiniMap */
     players = new Utils_1.MiniMap();
+    /**
+     * Applies the options provided by the User
+     * @param options
+     * @returns
+     */
     applyOptions(options) {
         this.options = {
             client: {
@@ -59,6 +69,10 @@ class LavalinkManager extends events_1.EventEmitter {
         };
         return;
     }
+    /**
+     * Validates the current manager's options
+     * @param options
+     */
     validateOptions(options) {
         if (typeof options?.sendToShard !== "function")
             throw new SyntaxError("ManagerOption.sendToShard was not provided, which is required!");
@@ -89,6 +103,64 @@ class LavalinkManager extends events_1.EventEmitter {
         if (typeof options?.queueOptions?.maxPreviousTracks !== "number" || options?.queueOptions?.maxPreviousTracks < 0)
             options.queueOptions.maxPreviousTracks = 25;
     }
+    /**
+     * Create the Lavalink Manager
+     * @param options
+     *
+     * @example
+     * ```ts
+     * //const client = new Client({...}); // create your BOT Client (e.g. via discord.js)
+     * client.lavalink = new LavalinkManager({
+     *   nodes: [
+     *     {
+     *       authorization: "yourverystrongpassword",
+     *       host: "localhost",
+     *       port: 2333,
+     *       id: "testnode"
+     *     },
+     *     sendToShard(guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+     *     client: {
+     *       id: process.env.CLIENT_ID,
+     *       username: "TESTBOT"
+     *     },
+     *     // optional Options:
+     *     autoSkip: true,
+     *     playerOptions: {
+     *       applyVolumeAsFilter: false,
+     *       clientBasedPositionUpdateInterval: 150,
+     *       defaultSearchPlatform: "ytmsearch",
+     *       volumeDecrementer: 0.75,
+     *       //requesterTransformer: YourRequesterTransformerFunction,
+     *       onDisconnect: {
+     *         autoReconnect: true,
+     *         destroyPlayer: false
+     *       },
+     *       onEmptyQueue: {
+     *         destroyAfterMs: 30_000,
+     *         //autoPlayFunction: YourAutoplayFunction,
+     *       },
+     *       useUnresolvedData: true
+     *     },
+     *     queueOptions: {
+     *       maxPreviousTracks: 25,
+     *       //queueStore: yourCustomQueueStoreManagerClass,
+     *       //queueChangesWatcher: yourCustomQueueChangesWatcherClass
+     *     },
+     *     linksBlacklist: [],
+     *     linksWhitelist: [],
+     *     advancedOptions: {
+     *       debugOptions: {
+     *         noAudio: false,
+     *         playerDestroy: {
+     *           dontThrowError: false,
+     *           debugLogs: false
+     *         }
+     *       }
+     *     }
+     *   ]
+     * })
+     * ```
+     */
     constructor(options) {
         super();
         if (!options)
@@ -100,6 +172,47 @@ class LavalinkManager extends events_1.EventEmitter {
         // create classes
         this.nodeManager = new NodeManager_1.NodeManager(this);
     }
+    /**
+     * Get a Player from Lava
+     * @param guildId The guildId of the player
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.getPlayer(interaction.guildId);
+     * ```
+     * A quicker and easier way than doing:
+     * ```ts
+     * const player = client.lavalink.players.get(interaction.guildId);
+     * ```
+     * @returns
+     */
+    getPlayer(guildId) {
+        return this.players.get(guildId);
+    }
+    /**
+     * Create a Music-Player. If a player exists, then it returns it before creating a new one
+     * @param options
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.createPlayer({
+     *   guildId: interaction.guildId,
+     *   voiceChannelId: interaction.member.voice.channelId,
+     *   // everything below is optional
+     *   textChannelId: interaction.channelId,
+     *   volume: 100,
+     *   selfDeaf: true,
+     *   selfMute: false,
+     *   instaUpdateFiltersFix: true,
+     *   applyVolumeAsFilter: false
+     *   //only needed if you want to autopick node by region (configured by you)
+     *   // vcRegion: interaction.member.voice.rtcRegion,
+     *   // provide a specific node
+     *   // node: client.lavalink.nodeManager.leastUsedNodes("memory")[0]
+     * });
+     * ```
+     */
     createPlayer(options) {
         const oldPlayer = this.getPlayer(options?.guildId);
         if (oldPlayer)
@@ -108,15 +221,29 @@ class LavalinkManager extends events_1.EventEmitter {
         this.players.set(newPlayer.guildId, newPlayer);
         return newPlayer;
     }
-    getPlayer(guildId) {
-        return this.players.get(guildId);
-    }
+    /**
+     * Destroy a player with optional destroy reason and disconnect it from the voice channel
+     * @param guildId
+     * @param destroyReason
+     * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.destroyPlayer(interaction.guildId, "forcefully destroyed the player");
+     * // recommend to do it on the player tho: player.destroy("forcefully destroyed the player");
+     * ```
+     */
     destroyPlayer(guildId, destroyReason) {
         const oldPlayer = this.getPlayer(guildId);
         if (!oldPlayer)
             return;
         return oldPlayer.destroy(destroyReason);
     }
+    /**
+     * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
+     * @param guildId
+     * @returns
+     */
     deletePlayer(guildId) {
         const oldPlayer = this.getPlayer(guildId);
         if (!oldPlayer)
@@ -130,12 +257,27 @@ class LavalinkManager extends events_1.EventEmitter {
         }
         return this.players.delete(guildId);
     }
+    /**
+     * Checks wether the the lib is useable based on if any node is connected
+     */
     get useable() {
         return this.nodeManager.nodes.filter(v => v.connected).size > 0;
     }
     /**
-     * Initiates the Manager.
+     * Initiates the Manager, creates all nodes and connects all of them
      * @param clientData
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot ready event
+     * client.on("ready", () => {
+     *   client.lavalink.init({
+     *     id: client.user.id,
+     *     username: client.user.username
+     *   });
+     * });
+     * ```
      */
     async init(clientData) {
         if (this.initiated)
@@ -165,7 +307,18 @@ class LavalinkManager extends events_1.EventEmitter {
     }
     /**
      * Sends voice data to the Lavalink server.
+     * ! Without this the library won't work
      * @param data
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot "raw" event
+     * client.on("raw", (d) => {
+     *   // required in order to send audio updates and register channel deletion etc.
+     *   client.lavalink.sendRawData(d)
+     * })
+     * ```
      */
     async sendRawData(data) {
         if (!this.initiated) {

package/dist/cjs/structures/Player.d.ts

@@ -172,7 +172,7 @@ export declare class Player {
      * @param query Query for your data
      * @param requestUser
      */
-    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").UnresolvedSearchResult | import("./Utils").SearchResult>;
+    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").SearchResult | import("./Utils").UnresolvedSearchResult>;
     /**
      * Pause the player
      */

package/dist/cjs/structures/Utils.js

@@ -243,7 +243,8 @@ class ManagerUtils {
             source: LavalinkManagerStatics_1.DefaultSources[(typeof query === "string" ? undefined : query.source?.trim?.()?.toLowerCase?.()) ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()] ?? (typeof query === "string" ? undefined : query.source?.trim?.()?.toLowerCase?.()) ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
         };
         const foundSource = Object.keys(LavalinkManagerStatics_1.DefaultSources).find(source => Query.query?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
-        if (foundSource && LavalinkManagerStatics_1.DefaultSources[foundSource]) {
+        // ignore links...
+        if (foundSource && !["https", "http"].includes(foundSource) && LavalinkManagerStatics_1.DefaultSources[foundSource]) {
             Query.source = LavalinkManagerStatics_1.DefaultSources[foundSource]; // set the source to ytsearch:
             Query.query = Query.query.slice(`${foundSource}:`.length, Query.query.length); // remove ytsearch: from the query
         }