lavalink-client 2.2.0 → 2.2.1

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

@@ -4,28 +4,58 @@ import { LavalinkNode, SponsorBlockSegment } from "./Node";
 import { Queue } from "./Queue";
 import { Track, UnresolvedTrack } from "./Track";
 import { Base64, LavalinkPlayerVoiceOptions, LavaSearchQuery, SearchQuery } from "./Utils";
-type PlayerDestroyReasons = "QueueEmpty" | "NodeDestroy" | "NodeDeleted" | "LavalinkNoVoice" | "NodeReconnectFail" | "PlayerReconnectFail" | "Disconnected" | "ChannelDeleted" | "ReconnectAllNodes" | "DisconnectAllNodes";
-export type DestroyReasonsType = PlayerDestroyReasons | string;
-export declare const DestroyReasons: Record<PlayerDestroyReasons, PlayerDestroyReasons>;
+export declare enum DestroyReasons {
+    QueueEmpty = "QueueEmpty",
+    NodeDestroy = "NodeDestroy",
+    NodeDeleted = "NodeDeleted",
+    LavalinkNoVoice = "LavalinkNoVoice",
+    NodeReconnectFail = "NodeReconnectFail",
+    Disconnected = "Disconnected",
+    PlayerReconnectFail = "PlayerReconnectFail",
+    ChannelDeleted = "ChannelDeleted",
+    DisconnectAllNodes = "DisconnectAllNodes",
+    ReconnectAllNodes = "ReconnectAllNodes"
+}
+export type DestroyReasonsType = keyof typeof DestroyReasons | string;
 export interface PlayerJson {
+    /** Guild Id where the player was playing in */
     guildId: string;
+    /** Options provided to the player */
     options: PlayerOptions;
+    /** Voice Channel Id the player was playing in */
     voiceChannelId: string;
+    /** Text Channel Id the player was synced to */
     textChannelId?: string;
+    /** Position the player was at */
     position: number;
+    /** Lavalink's position the player was at */
     lastPosition: number;
+    /** Last time the position was sent from lavalink */
+    lastPositionChange: number;
+    /** Volume in % from the player (without volumeDecrementer) */
     volume: number;
+    /** Real Volume used in lavalink (with the volumeDecrementer) */
     lavalinkVolume: number;
+    /** The repeatmode from the player */
     repeatMode: RepeatMode;
+    /** Pause state */
     paused: boolean;
+    /** Wether the player was playing or not */
     playing: boolean;
+    /** When the player was created */
     createdTimeStamp?: number;
+    /** All current used fitlers Data */
     filters: FilterData;
+    /** The player's ping object */
     ping: {
+        /** Ping to the voice websocket server */
         ws: number;
+        /** Avg. calc. Ping to the lavalink server */
         lavalink: number;
     };
+    /** Equalizer Bands used in lavalink */
     equalizer: EQBand[];
+    /** The Id of the last used node */
     nodeId?: string;
 }
 export type RepeatMode = "queue" | "track" | "off";
@@ -88,10 +118,15 @@ export interface PlayOptions extends LavalinkPlayOptions {
     clientTrack?: Track | UnresolvedTrack;
 }
 export interface Player {
+    /** Filter Manager per player */
     filterManager: FilterManager;
+    /** circular reference to the lavalink Manager from the Player for easier use */
     LavalinkManager: LavalinkManager;
+    /** Player options currently used, mutation doesn't affect player's state */
     options: PlayerOptions;
+    /** The lavalink node assigned the the player, don't change it manually */
     node: LavalinkNode;
+    /** The queue from the player */
     queue: Queue;
 }
 export declare class Player {
@@ -117,7 +152,9 @@ export declare class Player {
     /** The Volume Lavalink actually is outputting */
     lavalinkVolume: number;
     /** The current Positin of the player (Calculated) */
-    position: number;
+    get position(): number;
+    /** The timestamp when the last position change update happened */
+    lastPositionChange: number;
     /** The current Positin of the player (from Lavalink) */
     lastPosition: number;
     /** When the player was created [Timestamp in Ms] (from lavalink) */
@@ -163,7 +200,7 @@ export declare class Player {
      * @param ignoreVolumeDecrementer If it should ignore the volumedecrementer option
      */
     setVolume(volume: number, ignoreVolumeDecrementer?: boolean): Promise<this>;
-    lavaSearch(query: LavaSearchQuery, requestUser: unknown): Promise<import("./Utils").SearchResult | import("./Utils").LavaSearchResponse>;
+    lavaSearch(query: LavaSearchQuery, requestUser: unknown, throwOnEmpty?: boolean): Promise<import("./Utils").SearchResult | import("./Utils").LavaSearchResponse>;
     setSponsorBlock(segments?: SponsorBlockSegment[]): Promise<void>;
     getSponsorBlock(): Promise<SponsorBlockSegment[]>;
     deleteSponsorBlock(): Promise<void>;
@@ -172,7 +209,7 @@ export declare class Player {
      * @param query Query for your data
      * @param requestUser
      */
-    search(query: SearchQuery, requestUser: unknown): Promise<import("./Utils").SearchResult | import("./Utils").UnresolvedSearchResult>;
+    search(query: SearchQuery, requestUser: unknown, throwOnEmpty?: boolean): Promise<import("./Utils").SearchResult | import("./Utils").UnresolvedSearchResult>;
     /**
      * Pause the player
      */
@@ -220,7 +257,7 @@ export declare class Player {
     /**
      * Destroy the player and disconnect from the voice channel
      */
-    destroy(reason?: string, disconnect?: boolean): Promise<this>;
+    destroy(reason?: DestroyReasons | string, disconnect?: boolean): Promise<this>;
     /**
      * Move the player on a different Audio-Node
      * @param newNode New Node / New Node Id
@@ -229,4 +266,3 @@ export declare class Player {
     /** Converts the Player including Queue to a Json state */
     toJSON(): PlayerJson;
 }
-export {};

package/dist/cjs/structures/Player.js

@@ -5,18 +5,20 @@ const BandCampSearch_1 = require("./CustomSearches/BandCampSearch");
 const Filters_1 = require("./Filters");
 const Queue_1 = require("./Queue");
 const Utils_1 = require("./Utils");
-exports.DestroyReasons = {
-    QueueEmpty: "QueueEmpty",
-    NodeDestroy: "NodeDestroy",
-    NodeDeleted: "NodeDeleted",
-    LavalinkNoVoice: "LavalinkNoVoice",
-    NodeReconnectFail: "NodeReconnectFail",
-    Disconnected: "Disconnected",
-    PlayerReconnectFail: "PlayerReconnectFail",
-    ChannelDeleted: "ChannelDeleted",
-    DisconnectAllNodes: "DisconnectAllNodes",
-    ReconnectAllNodes: "ReconnectAllNodes"
-};
+var DestroyReasons;
+(function (DestroyReasons) {
+    DestroyReasons["QueueEmpty"] = "QueueEmpty";
+    DestroyReasons["NodeDestroy"] = "NodeDestroy";
+    DestroyReasons["NodeDeleted"] = "NodeDeleted";
+    DestroyReasons["LavalinkNoVoice"] = "LavalinkNoVoice";
+    DestroyReasons["NodeReconnectFail"] = "NodeReconnectFail";
+    DestroyReasons["Disconnected"] = "Disconnected";
+    DestroyReasons["PlayerReconnectFail"] = "PlayerReconnectFail";
+    DestroyReasons["ChannelDeleted"] = "ChannelDeleted";
+    DestroyReasons["DisconnectAllNodes"] = "DisconnectAllNodes";
+    DestroyReasons["ReconnectAllNodes"] = "ReconnectAllNodes";
+})(DestroyReasons || (exports.DestroyReasons = DestroyReasons = {}));
+;
 class Player {
     /** The Guild Id of the Player */
     guildId;
@@ -42,7 +44,11 @@ class Player {
     /** The Volume Lavalink actually is outputting */
     lavalinkVolume = 100;
     /** The current Positin of the player (Calculated) */
-    position = 0;
+    get position() {
+        return this.lastPosition + (this.lastPositionChange ? Date.now() - this.lastPositionChange : 0);
+    }
+    /** The timestamp when the last position change update happened */
+    lastPositionChange = null;
     /** The current Positin of the player (from Lavalink) */
     lastPosition = 0;
     /** When the player was created [Timestamp in Ms] (from lavalink) */
@@ -245,8 +251,8 @@ class Player {
         this.ping.lavalink = Math.round((performance.now() - now) / 10) / 100;
         return this;
     }
-    async lavaSearch(query, requestUser) {
-        return this.node.lavaSearch(query, requestUser);
+    async lavaSearch(query, requestUser, throwOnEmpty = false) {
+        return this.node.lavaSearch(query, requestUser, throwOnEmpty);
     }
     async setSponsorBlock(segments = ["sponsor", "selfpromo"]) {
         return this.node.setSponsorBlock(this, segments);
@@ -262,11 +268,11 @@ class Player {
      * @param query Query for your data
      * @param requestUser
      */
-    async search(query, requestUser) {
+    async search(query, requestUser, throwOnEmpty = false) {
         const Query = this.LavalinkManager.utils.transformQuery(query);
         if (["bcsearch", "bandcamp"].includes(Query.source) && !this.node.info.sourceManagers.includes("bandcamp"))
             return await (0, BandCampSearch_1.bandCampSearch)(this, Query.query, requestUser);
-        return this.node.search(Query, requestUser);
+        return this.node.search(Query, requestUser, throwOnEmpty);
     }
     /**
      * Pause the player
@@ -306,7 +312,7 @@ class Player {
             throw new RangeError("Current Track is not seekable / a stream");
         if (position < 0 || position > this.queue.current.info.duration)
             position = Math.max(Math.min(position, this.queue.current.info.duration), 0);
-        this.position = position;
+        this.lastPositionChange = Date.now();
         this.lastPosition = position;
         const now = performance.now();
         await this.node.updatePlayer({ guildId: this.guildId, playerOptions: { position } });
@@ -488,6 +494,7 @@ class Player {
             textChannelId: this.textChannelId,
             position: this.position,
             lastPosition: this.lastPosition,
+            lastPositionChange: this.lastPositionChange,
             volume: this.volume,
             lavalinkVolume: this.lavalinkVolume,
             repeatMode: this.repeatMode,
@@ -498,6 +505,7 @@ class Player {
             equalizer: this.filterManager?.equalizerBands || [],
             nodeId: this.node?.id,
             ping: this.ping,
+            queue: this.queue.utils.toJSON(),
         };
     }
 }

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

@@ -105,6 +105,7 @@ export declare class ManagerUtils {
     validateQueryString(node: LavalinkNode, queryString: string, sourceString?: LavalinkSearchPlatform): void;
     transformQuery(query: SearchQuery): {
         query: string;
+        extraQueryUrlParams: URLSearchParams;
         source: any;
     };
     transformLavaSearchQuery(query: LavaSearchQuery): {
@@ -453,6 +454,8 @@ export interface LavaSearchResponse {
 export type SearchQuery = {
     /** lavalink search Query / identifier string */
     query: string;
+    /** Extra url query params to use, e.g. for flowertts */
+    extraQueryUrlParams?: URLSearchParams;
     /** Source to append to the search query string */
     source?: SearchPlatform;
 } | /** Our just the search query / identifier string */ string;

package/dist/cjs/structures/Utils.js

@@ -241,6 +241,7 @@ class ManagerUtils {
         const sourceOfQuery = typeof query === "string" ? undefined : (LavalinkManagerStatics_1.DefaultSources[(query.source?.trim?.()?.toLowerCase?.()) ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()] ?? (query.source?.trim?.()?.toLowerCase?.()));
         const Query = {
             query: typeof query === "string" ? query : query.query,
+            extraQueryUrlParams: typeof query !== "string" ? query.extraQueryUrlParams : undefined,
             source: sourceOfQuery ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
         };
         const foundSource = Object.keys(LavalinkManagerStatics_1.DefaultSources).find(source => Query.query?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();

package/dist/esm/structures/Filters.d.ts

@@ -7,7 +7,7 @@ export declare class FilterManager {
     /** The Equalizer bands currently applied to the Lavalink Server */
     equalizerBands: EQBand[];
     /** Private Util for the instaFix Filters option */
-    filterUpdatedState: number;
+    filterUpdatedState: boolean;
     /** All "Active" / "disabled" Player Filters */
     filters: PlayerFilters;
     /** The Filter Data sent to Lavalink, only if the filter is enabled (ofc.) */

package/dist/esm/structures/Filters.js

@@ -5,7 +5,7 @@ export class FilterManager {
     /** The Equalizer bands currently applied to the Lavalink Server */
     equalizerBands = [];
     /** Private Util for the instaFix Filters option */
-    filterUpdatedState = 0;
+    filterUpdatedState = false;
     /** All "Active" / "disabled" Player Filters */
     filters = {
         volume: false,
@@ -157,6 +157,8 @@ export class FilterManager {
                 delete sendData[key];
         }
         const now = performance.now();
+        if (this.player.options.instaUpdateFiltersFix === true)
+            this.filterUpdatedState = true;
         await this.player.node.updatePlayer({
             guildId: this.player.guildId,
             playerOptions: {
@@ -164,8 +166,6 @@ export class FilterManager {
             }
         });
         this.player.ping.lavalink = Math.round((performance.now() - now) / 10) / 100;
-        if (this.player.options.instaUpdateFiltersFix === true)
-            this.filterUpdatedState = 1;
         return;
     }
     /**
@@ -651,6 +651,8 @@ export class FilterManager {
         if (!this.player.node.sessionId)
             throw new Error("The Lavalink-Node is either not ready or not up to date");
         const now = performance.now();
+        if (this.player.options.instaUpdateFiltersFix === true)
+            this.filterUpdatedState = true;
         await this.player.node.updatePlayer({
             guildId: this.player.guildId,
             playerOptions: {
@@ -658,8 +660,6 @@ export class FilterManager {
             }
         });
         this.player.ping.lavalink = Math.round((performance.now() - now) / 10) / 100;
-        if (this.player.options.instaUpdateFiltersFix === true)
-            this.filterUpdatedState = 1;
         return this;
     }
     /** Clears the equalizer bands. */

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

@@ -6,6 +6,7 @@ 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";
+/** How the botclient is allowed to be structured */
 export interface BotClientOptions {
     /** Bot Client Id */
     id: string;
@@ -14,6 +15,7 @@ export interface BotClientOptions {
     /** So users can pass entire objects / classes */
     [x: string | number | symbol]: unknown;
 }
+/** Sub Manager Options, for player specific things */
 export interface ManagerPlayerOptions {
     /** If the Lavalink Volume should be decremented by x number */
     volumeDecrementer?: number;
@@ -39,6 +41,7 @@ export interface ManagerPlayerOptions {
     };
     useUnresolvedData?: boolean;
 }
+/** Manager Options used to create the manager */
 export interface ManagerOptions {
     /** The Node Options, for all Nodes! (on init) */
     nodes: LavalinkNodeOptions[];
@@ -64,6 +67,8 @@ export interface ManagerOptions {
     linksAllowed?: boolean;
     /** Advanced Options for the Library, which may or may not be "library breaking" */
     advancedOptions?: {
+        /** Max duration for that the filter fix duration works (in ms) - default is 8mins */
+        maxFilterFixDuration?: number;
         /** optional */
         debugOptions?: {
             /** For logging custom searches */
@@ -239,6 +244,7 @@ export declare class LavalinkManager extends EventEmitter {
      *     linksBlacklist: [],
      *     linksWhitelist: [],
      *     advancedOptions: {
+     *       maxFilterFixDuration: 600_000,
      *       debugOptions: {
      *         noAudio: false,
      *         playerDestroy: {
@@ -309,10 +315,22 @@ export declare class LavalinkManager extends EventEmitter {
      * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
      * @param guildId
      * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.deletePlayer(interaction.guildId);
+     * // shouldn't be used except you know what you are doing.
+     * ```
      */
     deletePlayer(guildId: string): boolean;
     /**
      * Checks wether the the lib is useable based on if any node is connected
+     *
+     * @example
+     * ```ts
+     * if(!client.lavalink.useable) return console.error("can'T search yet, because there is no useable lavalink node.")
+     * // continue with code e.g. createing a player and searching
+     * ```
      */
     get useable(): boolean;
     /**
@@ -320,7 +338,6 @@ export declare class LavalinkManager extends EventEmitter {
      * @param clientData
      *
      * @example
-     *
      * ```ts
      * // on the bot ready event
      * client.on("ready", () => {

package/dist/esm/structures/LavalinkManager.js

@@ -55,6 +55,7 @@ export class LavalinkManager extends EventEmitter {
                 queueStore: options?.queueOptions?.queueStore ?? new DefaultQueueStore(),
             },
             advancedOptions: {
+                maxFilterFixDuration: options?.advancedOptions?.maxFilterFixDuration ?? 600000,
                 debugOptions: {
                     logCustomSearches: options?.advancedOptions?.debugOptions?.logCustomSearches ?? false,
                     noAudio: options?.advancedOptions?.debugOptions?.noAudio ?? false,
@@ -147,6 +148,7 @@ export class LavalinkManager extends EventEmitter {
      *     linksBlacklist: [],
      *     linksWhitelist: [],
      *     advancedOptions: {
+     *       maxFilterFixDuration: 600_000,
      *       debugOptions: {
      *         noAudio: false,
      *         playerDestroy: {
@@ -241,6 +243,12 @@ export class LavalinkManager extends EventEmitter {
      * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
      * @param guildId
      * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.deletePlayer(interaction.guildId);
+     * // shouldn't be used except you know what you are doing.
+     * ```
      */
     deletePlayer(guildId) {
         const oldPlayer = this.getPlayer(guildId);
@@ -257,6 +265,12 @@ export class LavalinkManager extends EventEmitter {
     }
     /**
      * Checks wether the the lib is useable based on if any node is connected
+     *
+     * @example
+     * ```ts
+     * if(!client.lavalink.useable) return console.error("can'T search yet, because there is no useable lavalink node.")
+     * // continue with code e.g. createing a player and searching
+     * ```
      */
     get useable() {
         return this.nodeManager.nodes.filter(v => v.connected).size > 0;
@@ -266,7 +280,6 @@ export class LavalinkManager extends EventEmitter {
      * @param clientData
      *
      * @example
-     *
      * ```ts
      * // on the bot ready event
      * client.on("ready", () => {

package/dist/esm/structures/LavalinkManagerStatics.d.ts

@@ -1,5 +1,7 @@
 import { ClientCustomSearchPlatformUtils, LavalinkSearchPlatform, SearchPlatform, SourcesRegex } from "./Utils";
+/** Default Sources Record, to allow source parsing with multiple inputs. */
 export declare const DefaultSources: Record<SearchPlatform, LavalinkSearchPlatform | ClientCustomSearchPlatformUtils>;
+/** Lavalink Plugins definiton */
 export declare const LavalinkPlugins: {
     DuncteBot_Plugin: string;
     LavaSrc: string;
@@ -7,4 +9,5 @@ export declare const LavalinkPlugins: {
     LavaSearch: string;
     LavalinkFilterPlugin: string;
 };
+/** Lavalink Sources regexes for url validations */
 export declare const SourceLinksRegexes: Record<SourcesRegex, RegExp>;

package/dist/esm/structures/LavalinkManagerStatics.js

@@ -1,3 +1,4 @@
+/** Default Sources Record, to allow source parsing with multiple inputs. */
 export const DefaultSources = {
     // youtubemusic
     "youtube music": "ytmsearch",
@@ -63,6 +64,7 @@ export const DefaultSources = {
     "link": "link",
     "uri": "uri"
 };
+/** Lavalink Plugins definiton */
 export const LavalinkPlugins = {
     DuncteBot_Plugin: "DuncteBot-plugin",
     LavaSrc: "lavasrc-plugin",
@@ -70,6 +72,7 @@ export const LavalinkPlugins = {
     LavaSearch: "lavasearch-plugin",
     LavalinkFilterPlugin: "lavalink-filter-plugin"
 };
+/** Lavalink Sources regexes for url validations */
 export const SourceLinksRegexes = {
     /** DEFAULT SUPPORTED BY LAVALINK */
     YoutubeRegex: /https?:\/\/?(?:www\.)?(?:(m|www)\.)?(?:youtu\.be\/|youtube\.com\/(?:embed\/|v\/|shorts|playlist\?|watch\?v=|watch\?.+(?:&|&);v=))([a-zA-Z0-9\-_]{11})?(?:(?:\?|&|&)index=((?:\d){1,3}))?(?:(?:\?|&|&)?list=([a-zA-Z\-_0-9]{34}))?(?:\S+)?/,