lavalink-client 1.2.5 → 2.0.0

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

@@ -1,7 +1,7 @@
 import { LavalinkFilterData } from "./Filters";
 import { LavalinkManager } from "./LavalinkManager";
 import { LavalinkNode, LavalinkNodeOptions, NodeStats } from "./Node";
-import { Player, PlayOptions } from "./Player";
+import { LavalinkPlayOptions, Player } from "./Player";
 import { LavalinkTrack, PluginInfo, Track, UnresolvedQuery, UnresolvedTrack } from "./Track";
 export declare const TrackSymbol: unique symbol;
 export declare const UnresolvedTrackSymbol: unique symbol;
@@ -247,17 +247,29 @@ export type State = "CONNECTED" | "CONNECTING" | "DISCONNECTED" | "DISCONNECTING
 export type PlayerEventType = "TrackStartEvent" | "TrackEndEvent" | "TrackExceptionEvent" | "TrackStuckEvent" | "WebSocketClosedEvent" | SponsorBlockSegmentEventType;
 export type TrackEndReason = "finished" | "loadFailed" | "stopped" | "replaced" | "cleanup";
 export interface InvalidLavalinkRestRequest {
+    /** Rest Request Data for when it was made */
     timestamp: number;
+    /** Status of the request */
     status: number;
+    /** Specific Errro which was sent */
     error: string;
+    /** Specific Message which was created */
     message?: string;
+    /** The specific error trace from the request */
+    trace?: unknown;
+    /** Path of where it's from */
     path: string;
 }
 export interface LavalinkPlayerVoice {
+    /** The Voice Token */
     token: string;
+    /** The Voice Server Endpoint  */
     endpoint: string;
+    /** The Voice SessionId */
     sessionId: string;
+    /** Wether or not the player is connected */
     connected?: boolean;
+    /** The Ping to the voice server */
     ping?: number;
 }
 export interface LavalinkPlayerVoiceOptions extends Omit<LavalinkPlayerVoice, 'connected' | 'ping'> {
@@ -296,84 +308,121 @@ export interface RoutePlanner {
     };
 }
 export interface Session {
+    /** Wether or not session is resuming or not */
     resuming: boolean;
+    /** For how long a session is lasting while not connected */
     timeout: number;
 }
 export interface GuildShardPayload {
     /** The OP code */
     op: number;
+    /** Data to send  */
     d: {
+        /** Guild id to apply voice settings */
         guild_id: string;
+        /** channel to move/connect to, or null to leave it */
         channel_id: string | null;
+        /** wether or not mute yourself */
         self_mute: boolean;
+        /** wether or not deafen yourself */
         self_deaf: boolean;
     };
 }
 export interface PlayerUpdateInfo {
+    /** guild id of the player */
     guildId: string;
-    playerOptions: PlayOptions;
+    /** Player options to provide to lavalink */
+    playerOptions: LavalinkPlayOptions;
+    /** Whether or not replace the current track with the new one (true is recommended) */
     noReplace?: boolean;
 }
 export interface LavalinkPlayer {
+    /** Guild Id of the player */
     guildId: string;
-    track?: {
-        encoded?: string;
-        info: {
-            identifier: string;
-            title: string;
-            author: string;
-            length: number;
-            artworkUrl: string | null;
-            uri: string;
-            sourceName: string;
-            isSeekable: boolean;
-            isStream: boolean;
-            isrc: string | null;
-            position?: number;
-        };
-    };
+    /** IF playing a track, all of the track information */
+    track?: LavalinkTrack;
+    /** Lavalink volume (mind volumedecrementer) */
     volume: number;
+    /** Wether it's paused or not */
     paused: boolean;
+    /** Voice Endpoint data */
     voice: LavalinkPlayerVoice;
+    /** All Audio Filters */
     filters: Partial<LavalinkFilterData>;
+    /** Lavalink-Voice-State Variables */
+    state: {
+        /** Time since connection established */
+        time: number;
+        /** Position of the track */
+        position: number;
+        /** COnnected or not */
+        connected: boolean;
+        /** Ping to voice server */
+        ping: number;
+    };
 }
 export interface ChannelDeletePacket {
+    /** Packet key for channel delete */
     t: "CHANNEL_DELETE";
+    /** data which is sent and relevant */
     d: {
+        /** guild id */
         guild_id: string;
+        /** Channel id */
         id: string;
     };
 }
 export interface VoiceState {
+    /** OP key from lavalink */
     op: "voiceUpdate";
+    /** GuildId provided by lavalink */
     guildId: string;
+    /** Event data */
     event: VoiceServer;
+    /** Session Id of the voice connection */
     sessionId?: string;
+    /** guild id of the voice channel */
     guild_id: string;
+    /** user id from the voice connection */
     user_id: string;
+    /** Session Id of the voice connection */
     session_id: string;
+    /** Voice Channel Id */
     channel_id: string;
 }
+/** The Base64 decodes tring by lavalink */
 export type Base64 = string;
 export interface VoiceServer {
+    /** Voice Token */
     token: string;
+    /** Guild Id of the voice server connection */
     guild_id: string;
+    /** Server Endpoint */
     endpoint: string;
 }
 export interface VoicePacket {
+    /** Voice Packet Keys to send */
     t?: "VOICE_SERVER_UPDATE" | "VOICE_STATE_UPDATE";
+    /** Voice Packets to send */
     d: VoiceState | VoiceServer;
 }
 export interface NodeMessage extends NodeStats {
+    /** The type of the event */
     type: PlayerEventType;
+    /** what ops are applying to that event */
     op: "stats" | "playerUpdate" | "event";
+    /** The specific guild id for that message */
     guildId: string;
 }
 export declare function queueTrackEnd(player: Player): Promise<Track>;
+/** Specific types to filter for lavasearch, will be filtered to correct types */
 export type LavaSearchType = "track" | "album" | "artist" | "playlist" | "text" | "tracks" | "albums" | "artists" | "playlists" | "texts";
 export interface LavaSearchFilteredResponse {
+    /** The Information of a playlist provided by lavasearch */
     info: PlaylistInfo;
+    /** additional plugin information */
     pluginInfo: PluginInfo;
+    /** List of tracks  */
     tracks: Track[];
 }
 export interface LavaSearchResponse {
@@ -393,13 +442,20 @@ export interface LavaSearchResponse {
     /** Addition result data provided by plugins */
     pluginInfo: PluginInfo;
 }
+/** SearchQuery Object for raw lavalink requests */
 export type SearchQuery = {
+    /** lavalink search Query / identifier string */
     query: string;
+    /** Source to append to the search query string */
     source?: SearchPlatform;
-} | string;
+} | /** Our just the search query / identifier string */ string;
+/** SearchQuery Object for Lavalink LavaSearch Plugin requests */
 export type LavaSearchQuery = {
+    /** lavalink search Query / identifier string */
     query: string;
+    /** Source to append to the search query string */
     source: LavaSrcSearchPlatformBase;
+    /** The Types to filter the search to */
     types?: LavaSearchType[];
 };
 export {};

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

@@ -56,6 +56,8 @@ export interface ManagerOptions {
     playerOptions?: ManagerPlayerOptions;
     /** If it should skip to the next Track on TrackEnd / TrackError etc. events */
     autoSkip?: boolean;
+    /** If it should skip to the next Track if track.resolve errors while trying to play a track. */
+    autoSkipOnResolveError?: boolean;
     /** If it should emit only new (unique) songs and not when a looping track (or similar) is plaid, default false */
     emitNewSongsOnly?: boolean;
     /** Only allow link requests with links either matching some of that regExp or including some of that string */

package/dist/esm/structures/LavalinkManager.js

@@ -37,6 +37,7 @@ export class LavalinkManager extends EventEmitter {
             linksWhitelist: options?.linksWhitelist ?? [],
             linksBlacklist: options?.linksBlacklist ?? [],
             autoSkip: options?.autoSkip ?? true,
+            autoSkipOnResolveError: options?.autoSkipOnResolveError ?? true,
             emitNewSongsOnly: options?.emitNewSongsOnly ?? false,
             queueOptions: {
                 maxPreviousTracks: options?.queueOptions?.maxPreviousTracks ?? 25,
@@ -62,6 +63,8 @@ export class LavalinkManager extends EventEmitter {
         // if(typeof options?.client !== "object" || typeof options?.client.id !== "string") throw new SyntaxError("ManagerOption.client = { id: string, username?:string } was not provided, which is required");
         if (options?.autoSkip && typeof options?.autoSkip !== "boolean")
             throw new SyntaxError("ManagerOption.autoSkip must be either false | true aka boolean");
+        if (options?.autoSkipOnResolveError && typeof options?.autoSkipOnResolveError !== "boolean")
+            throw new SyntaxError("ManagerOption.autoSkipOnResolveError must be either false | true aka boolean");
         if (options?.emitNewSongsOnly && typeof options?.emitNewSongsOnly !== "boolean")
             throw new SyntaxError("ManagerOption.emitNewSongsOnly must be either false | true aka boolean");
         if (!options?.nodes || !Array.isArray(options?.nodes) || !options?.nodes.every(node => this.utils.isNodeOptions(node)))

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

@@ -78,29 +78,49 @@ export interface NodeStats extends BaseNodeStats {
     frameStats: FrameStats;
 }
 export interface LavalinkInfo {
+    /** The version of this Lavalink server */
     version: VersionObject;
+    /** The millisecond unix timestamp when this Lavalink jar was built */
     buildTime: number;
+    /** The git information of this Lavalink server */
     git: GitObject;
+    /** The JVM version this Lavalink server runs on */
     jvm: string;
+    /** The Lavaplayer version being used by this server */
     lavaplayer: string;
+    /** The enabled source managers for this server */
     sourceManagers: string[];
+    /** The enabled filters for this server */
     filters: string[];
+    /** The enabled plugins for this server */
     plugins: PluginObject[];
 }
 export interface VersionObject {
+    /** The full version string of this Lavalink server */
     semver: string;
+    /** The major version of this Lavalink server */
     major: number;
+    /** The minor version of this Lavalink server */
     minor: number;
+    /** The patch version of this Lavalink server */
     patch: internal;
+    /** The pre-release version according to semver as a . separated list of identifiers */
     preRelease?: string;
+    /** The build metadata according to semver as a . separated list of identifiers */
+    build?: string;
 }
 export interface GitObject {
+    /** The branch this Lavalink server was built on */
     branch: string;
+    /** The commit this Lavalink server was built on */
     commit: string;
+    /** The millisecond unix timestamp for when the commit was created */
     commitTime: string;
 }
 export interface PluginObject {
+    /** The name of the plugin */
     name: string;
+    /** The version of the plugin */
     version: string;
 }
 export declare class LavalinkNode {
@@ -110,6 +130,11 @@ export declare class LavalinkNode {
     calls: number;
     stats: NodeStats;
     sessionId?: string | null;
+    /** Wether the node resuming is enabled or not */
+    resuming: {
+        enabled: boolean;
+        timeout: number | null;
+    };
     /** Actual Lavalink Information of the Node */
     info: LavalinkInfo | null;
     /** The Node Manager of this Node */
@@ -126,10 +151,17 @@ export declare class LavalinkNode {
     private version;
     /**
      * Create a new Node
-     * @param options
-     * @param manager
+     * @param options Lavalink Node Options
+     * @param manager Node Manager
      */
     constructor(options: LavalinkNodeOptions, manager: NodeManager);
+    /**
+     * Raw Request util function
+     * @param endpoint endpoint string
+     * @param modify modify the request
+     * @returns
+     */
+    private rawRequest;
     /**
      * Makes an API call to the Node
      * @param endpoint The endpoint that we will make the call to
@@ -137,8 +169,14 @@ export declare class LavalinkNode {
      * @returns The returned data
      */
     request(endpoint: string, modify?: ModifyRequest, parseAsText?: boolean): Promise<unknown>;
+    /**
+     * Search something raw on the node, please note only add tracks to players of that node
+     * @param query SearchQuery Object
+     * @param requestUser Request User for creating the player(s)
+     * @returns Searchresult
+     */
     search(query: SearchQuery, requestUser: unknown): Promise<SearchResult>;
-    lavaSearch(query: LavaSearchQuery, requestUser: unknown): Promise<SearchResult | LavaSearchResponse>;
+    lavaSearch(query: LavaSearchQuery, requestUser: unknown, throwOnEmpty?: boolean): Promise<SearchResult | LavaSearchResponse>;
     /**
      * Update the Player State on the Lavalink Server
      * @param data
@@ -179,7 +217,7 @@ export declare class LavalinkNode {
      * @param resuming Whether resuming is enabled for this session or not
      * @param timeout The timeout in seconds (default is 60s)
      */
-    updateSession(resuming?: boolean, timeout?: number): Promise<Session>;
+    updateSession(resuming?: boolean, timeout?: number): Promise<InvalidLavalinkRestRequest | Session>;
     /**
      * Decode Track or Tracks
      */

package/dist/esm/structures/Node.js

@@ -31,6 +31,8 @@ export class LavalinkNode {
         }
     };
     sessionId = null;
+    /** Wether the node resuming is enabled or not */
+    resuming = { enabled: true, timeout: null };
     /** Actual Lavalink Information of the Node */
     info = null;
     /** The Node Manager of this Node */
@@ -47,8 +49,8 @@ export class LavalinkNode {
     version = "v4";
     /**
      * Create a new Node
-     * @param options
-     * @param manager
+     * @param options Lavalink Node Options
+     * @param manager Node Manager
      */
     constructor(options, manager) {
         this.options = {
@@ -67,12 +69,12 @@ export class LavalinkNode {
         Object.defineProperty(this, NodeSymbol, { configurable: true, value: true });
     }
     /**
-     * Makes an API call to the Node
-     * @param endpoint The endpoint that we will make the call to
-     * @param modify Used to modify the request before being sent
-     * @returns The returned data
+     * Raw Request util function
+     * @param endpoint endpoint string
+     * @param modify modify the request
+     * @returns
      */
-    async request(endpoint, modify, parseAsText = false) {
+    async rawRequest(endpoint, modify) {
         const options = {
             path: `/${this.version}/${endpoint.replace(/^\//gm, "")}`,
             method: "GET",
@@ -87,12 +89,28 @@ export class LavalinkNode {
         options.path = url.pathname + url.search;
         const request = await this.rest.request(options);
         this.calls++;
+        return { request, options };
+    }
+    /**
+     * Makes an API call to the Node
+     * @param endpoint The endpoint that we will make the call to
+     * @param modify Used to modify the request before being sent
+     * @returns The returned data
+     */
+    async request(endpoint, modify, parseAsText = false) {
+        const { request, options } = await this.rawRequest(endpoint, modify);
         if (options.method === "DELETE")
             return;
         if (request.statusCode === 404)
-            throw new Error(`Node Request resulted into an error, request-URL: ${url} | headers: ${JSON.stringify(request.headers)}`);
+            throw new Error(`Node Request resulted into an error, request-PATH: ${options.path} | headers: ${JSON.stringify(request.headers)}`);
         return parseAsText ? await request.body.text() : await request.body.json();
     }
+    /**
+     * Search something raw on the node, please note only add tracks to players of that node
+     * @param query SearchQuery Object
+     * @param requestUser Request User for creating the player(s)
+     * @returns Searchresult
+     */
     async search(query, requestUser) {
         const Query = this.NodeManager.LavalinkManager.utils.transformQuery(query);
         this.NodeManager.LavalinkManager.utils.validateQueryString(this, Query.query, Query.source);
@@ -109,7 +127,7 @@ export class LavalinkNode {
         else
             uri += encodeURIComponent(decodeURIComponent(Query.query));
         const res = await this.request(uri);
-        // transform the data which can be Error, Track or Track[] to enfore [Track] 
+        // transform the data which can be Error, Track or Track[] to enfore [Track]
         const resTracks = res.loadType === "playlist" ? res.data?.tracks : res.loadType === "track" ? [res.data] : res.loadType === "search" ? Array.isArray(res.data) ? res.data : [res.data] : [];
         return {
             loadType: res.loadType,
@@ -126,7 +144,7 @@ export class LavalinkNode {
             tracks: (resTracks.length ? resTracks.map(t => this.NodeManager.LavalinkManager.utils.buildTrack(t, requestUser)) : [])
         };
     }
-    async lavaSearch(query, requestUser) {
+    async lavaSearch(query, requestUser, throwOnEmpty = false) {
         const Query = this.NodeManager.LavalinkManager.utils.transformLavaSearchQuery(query);
         if (Query.source)
             this.NodeManager.LavalinkManager.utils.validateSourceString(this, Query.source);
@@ -138,7 +156,10 @@ export class LavalinkNode {
             throw new RangeError(`there is no lavasearch-plugin available in the lavalink node: ${this.id}`);
         if (!this.info.plugins.find(v => v.name === "lavasrc-plugin"))
             throw new RangeError(`there is no lavasrc-plugin available in the lavalink node: ${this.id}`);
-        const res = await this.request(`/loadsearch?query=${Query.source ? `${Query.source}:` : ""}${encodeURIComponent(Query.query)}${Query.types?.length ? `&types=${Query.types.join(",")}` : ""}`);
+        const { request } = await this.rawRequest(`/loadsearch?query=${Query.source ? `${Query.source}:` : ""}${encodeURIComponent(Query.query)}${Query.types?.length ? `&types=${Query.types.join(",")}` : ""}`);
+        if (throwOnEmpty === true)
+            throw new Error("Nothing found");
+        const res = (request.statusCode === 204 ? {} : await request.body.json());
         return {
             tracks: res.tracks?.map(v => this.NodeManager.LavalinkManager.utils.buildTrack(v, requestUser)) || [],
             albums: res.albums?.map(v => ({ info: v.info, pluginInfo: v?.plugin || v.pluginInfo, tracks: v.tracks.map(v => this.NodeManager.LavalinkManager.utils.buildTrack(v, requestUser)) })) || [],
@@ -161,12 +182,10 @@ export class LavalinkNode {
             r.method = "PATCH";
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             r.headers["Content-Type"] = "application/json";
-            if (data.playerOptions.track)
-                delete data.playerOptions.track;
             r.body = JSON.stringify(data.playerOptions);
             if (data.noReplace) {
                 const url = new URL(`${this.poolAddress}${r.path}`);
-                url.searchParams.append("noReplace", data.noReplace?.toString() || "false");
+                url.searchParams.append("noReplace", data.noReplace === true && typeof data.noReplace === "boolean" ? "true" : "false");
                 r.path = url.pathname + url.search;
             }
         });
@@ -272,6 +291,10 @@ export class LavalinkNode {
             data.resuming = resuming;
         if (typeof timeout === "number" && timeout > 0)
             data.timeout = timeout;
+        this.resuming = {
+            enabled: typeof resuming === "boolean" ? resuming : false,
+            timeout: typeof resuming === "boolean" && resuming === true ? timeout : null,
+        };
         return await this.request(`/sessions/${this.sessionId}`, r => {
             r.method = "PATCH";
             r.headers = { Authorization: this.options.authorization, 'Content-Type': 'application/json' };
@@ -322,6 +345,7 @@ export class LavalinkNode {
      * @returns
      */
     async fetchVersion() {
+        // need to adjust path for no-prefix version info
         return await this.request(`/version`, r => { r.path = "/version"; }, true);
     }
     /**
@@ -556,6 +580,10 @@ export class LavalinkNode {
                 break;
             case "ready": // payload: { resumed: false, sessionId: 'ytva350aevn6n9n8', op: 'ready' }
                 this.sessionId = payload.sessionId;
+                this.resuming.enabled = payload.resumed;
+                if (payload.resumed === true) {
+                    this.NodeManager.emit("resumed", this, payload, await this.fetchAllPlayers());
+                }
                 break;
             default:
                 this.NodeManager.emit("error", this, new Error(`Unexpected op "${payload.op}" with data`), payload);

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

@@ -1,9 +1,9 @@
 /// <reference types="node" />
 import { EventEmitter } from "stream";
-import { LavalinkNode, LavalinkNodeOptions } from "./Node";
 import { LavalinkManager } from "./LavalinkManager";
-import { MiniMap } from "./Utils";
+import { LavalinkNode, LavalinkNodeOptions } from "./Node";
 import { DestroyReasonsType } from "./Player";
+import { LavalinkPlayer, MiniMap } from "./Utils";
 type LavalinkNodeIdentifier = string;
 interface NodeManagerEvents {
     /**
@@ -44,6 +44,16 @@ interface NodeManagerEvents {
      * @event Manager.nodeManager#raw
     */
     "raw": (node: LavalinkNode, payload: unknown) => void;
+    /**
+     * Emits when the node connects resumed. You then need to create all players within this event for your usecase.
+     * Aka for that you need to be able to save player data like vc channel + text channel in a db and then sync it again
+     * @event Manager.nodeManager#nodeResumed
+     */
+    "resumed": (node: LavalinkNode, paylaod: {
+        resumed: true;
+        sessionId: string;
+        op: "ready";
+    }, players: LavalinkPlayer[]) => void;
 }
 export declare interface NodeManager {
     on<U extends keyof NodeManagerEvents>(event: U, listener: NodeManagerEvents[U]): this;

package/dist/esm/structures/NodeManager.js

@@ -1,7 +1,7 @@
 import { EventEmitter } from "stream";
 import { LavalinkNode } from "./Node";
-import { MiniMap } from "./Utils";
 import { DestroyReasons } from "./Player";
+import { MiniMap } from "./Utils";
 export class NodeManager extends EventEmitter {
     nodes = new MiniMap();
     constructor(LavalinkManager) {

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

@@ -3,7 +3,7 @@ import { LavalinkManager } from "./LavalinkManager";
 import { LavalinkNode, SponsorBlockSegment } from "./Node";
 import { Queue } from "./Queue";
 import { Track, UnresolvedTrack } from "./Track";
-import { LavalinkPlayerVoiceOptions, LavaSearchQuery, SearchQuery } from "./Utils";
+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>;
@@ -51,27 +51,42 @@ export interface PlayerOptions {
     /** If a volume should be applied via filters instead of lavalink-volume */
     applyVolumeAsFilter?: boolean;
 }
-export interface PlayOptions {
-    /** Which Track to play | don't provide, if it should pick from the Queue */
-    track?: Track | UnresolvedTrack;
-    /** Encoded Track to use, instead of the queue system... */
-    encodedTrack?: string | null;
-    /** Encoded Track to use&search, instead of the queue system (yt only)... */
-    identifier?: string;
+export type anyObject = {
+    [key: string | number]: string | number | null | anyObject;
+};
+export interface BasePlayOptions {
     /** The position to start the track. */
     position?: number;
     /** The position to end the track. */
     endTime?: number;
-    /** Whether to not replace the track if a play payload is sent. */
-    noReplace?: boolean;
     /** If to start "paused" */
     paused?: boolean;
     /** The Volume to start with */
     volume?: number;
     /** The Lavalink Filters to use | only with the new REST API */
     filters?: Partial<LavalinkFilterData>;
+    /** Voice Update for Lavalink */
     voice?: LavalinkPlayerVoiceOptions;
 }
+export interface LavalinkPlayOptions extends BasePlayOptions {
+    /** Which Track to play | don't provide, if it should pick from the Queue */
+    track?: {
+        /** The track encoded base64 string to use instead of the one from the queue system */
+        encoded?: Base64 | null;
+        /** The identifier of the track to use */
+        identifier?: string;
+        /** Custom User Data for the track to provide, will then be on the userData object from the track */
+        userData?: anyObject;
+        /** The Track requester for when u provide encodedTrack / identifer */
+        requester?: unknown;
+    };
+}
+export interface PlayOptions extends LavalinkPlayOptions {
+    /** Whether to not replace the track if a play payload is sent. */
+    noReplace?: boolean;
+    /** Which Track to play | don't provide, if it should pick from the Queue */
+    clientTrack?: Track | UnresolvedTrack;
+}
 export interface Player {
     filterManager: FilterManager;
     LavalinkManager: LavalinkManager;