lavalink-client 2.9.0 → 2.9.1

package/dist/index.d.mts

@@ -417,7 +417,19 @@ declare function parseLavalinkConnUrl(connectionUrl: string): {
 declare class ManagerUtils {
     LavalinkManager: LavalinkManager | undefined;
     constructor(LavalinkManager?: LavalinkManager);
+    /**
+     * Builds a pluginInfo object based on the provided data, extracting relevant information from the data and clientData parameters. This function is used to construct the pluginInfo property for tracks, allowing for consistent handling of plugin-related information across different track sources and formats.
+     * @param data
+     * @param clientData
+     * @returns
+     */
     buildPluginInfo(data: any, clientData?: any): any;
+    /**
+     * Builds a Track object from the provided data and requester information. It validates the presence of required properties in the data, transforms the requester using a custom transformer function if provided, and constructs a Track object with the appropriate properties and plugin information. The function also includes error handling to ensure that the input data is valid and provides debug information if track building fails.
+     * @param data
+     * @param requester
+     * @returns
+     */
     buildTrack(data: LavalinkTrack | Track, requester: unknown): Track;
     /**
      * Builds a UnresolvedTrack to be resolved before being played  .
@@ -430,6 +442,11 @@ declare class ManagerUtils {
      * @param data
      */
     isNode(data: LavalinkNode): boolean;
+    /**
+     * Gets the transformed requester based on the LavalinkManager options. If a custom requester transformer function is provided in the player options, it applies that function to the requester; otherwise, it returns the requester as is. The function also includes error handling to catch any exceptions that may occur during the transformation process and emits a debug event if the transformation fails.
+     * @param requester
+     * @returns
+     */
     getTransformedRequester(requester: unknown): unknown;
     /**
      * Validate if a data is equal to node options
@@ -470,18 +487,73 @@ declare class ManagerUtils {
      * @param track
      */
     isUnresolvedTrackQuery(data: UnresolvedQuery): boolean;
+    /**
+     * Gets the closest track by resolving the provided UnresolvedTrack using the getClosestTrack function. It includes error handling to catch any exceptions that may occur during the resolution process and emits a debug event if the resolution fails. The function returns a Promise that resolves to a Track object if successful, or undefined if no closest track is found.
+     * @param data
+     * @param player
+     * @returns
+     */
     getClosestTrack(data: UnresolvedTrack, player: Player): Promise<Track | undefined>;
-    validateQueryString(node: LavalinkNode, queryString: string, sourceString?: LavalinkSearchPlatform): void;
+    /**
+     * Validates the query string against various criteria, including checking for empty strings, length limits for specific sources, blacklisted links or words, and ensuring that the Lavalink node has the necessary source managers enabled for the provided query. The function also includes debug event emissions to assist with troubleshooting and understanding the validation process.
+     * @param node
+     * @param queryString
+     * @param sourceString
+     * @returns
+     */
+    validateQueryString(node: LavalinkNode, queryString: string, sourceString?: SearchPlatform): void;
+    /**
+     * Finds the source of a query string by checking if it starts with a valid source prefix defined in the DefaultSources object. If a valid source prefix is found, it returns the corresponding SearchPlatform; otherwise, it returns null. This function is useful for determining the intended search platform for a given query string, allowing for more accurate search results when the user specifies a source (e.g., "ytsearch:Never Gonna Give You Up" would indicate that the search should be performed on YouTube).
+     * @param queryString
+     * @returns
+     */
+    findSourceOfQuery(queryString: string): SearchPlatform;
+    /**
+     * Extracts the source from the query if it starts with a valid source prefix (e.g., "ytsearch:") and updates the searchQuery object accordingly.
+     * @param searchQuery
+     * @returns The updated searchQuery object with the extracted source and modified query string.
+     */
+    extractSourceOfQuery<T extends {
+        query: string;
+        source?: string;
+    }>(searchQuery: T): T;
+    /**
+     * Converts a string to lowercase if the input is a string, otherwise returns the input as is. This is useful for ensuring that search platform identifiers are case-insensitive while allowing other types of input to pass through unchanged.
+     * @param input
+     * @returns
+     */
+    typedLowerCase<T extends unknown>(input: T): T;
+    /**
+     * Transforms a search query by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, and the determined search platform to be used for the search operation.
+     * @param query
+     * @returns
+     */
     transformQuery(query: SearchQuery): {
         query: string;
-        extraQueryUrlParams: URLSearchParams;
-        source: any;
+        extraQueryUrlParams: any;
+        source: SearchPlatform;
     };
+    /**
+     * Transforms a LavaSearchQuery by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, the determined search platform to be used for the search operation, and the types of search (track, playlist, artist, album, text) to be performed.
+     * @param query
+     * @returns
+     */
     transformLavaSearchQuery(query: LavaSearchQuery): {
+        query: never;
+        types: any[];
+        extraQueryUrlParams: any;
+        source: SearchPlatform;
+    } | {
         query: string;
         types: string[];
-        source: any;
+        source: "ytsearch" | "ytmsearch" | "scsearch" | "bcsearch" | "spsearch" | "sprec" | "amsearch" | "dzsearch" | "dzisrc" | "dzrec" | "ymsearch" | "ymrec" | "vksearch" | "vkrec" | "tdsearch" | "tdrec" | "qbsearch" | "qbisrc" | "qbrec" | "pdsearch" | "pdisrc" | "pdrec" | "ftts" | "speak" | "phsearch" | "pornhub" | "porn" | "tts" | "jssearch" | "jsrec" | "local" | "http" | "https" | "link" | "uri" | "youtube" | "yt" | "youtube music" | "youtubemusic" | "ytm" | "musicyoutube" | "music youtube" | "soundcloud" | "sc" | "am" | "apple music" | "applemusic" | "apple" | "musicapple" | "music apple" | "sp" | "spsuggestion" | "spotify" | "spotify.com" | "spotifycom" | "dz" | "deezer" | "yandex" | "yandex music" | "yandexmusic" | "vk" | "vk music" | "vkmusic" | "tidal" | "tidal music" | "qobuz" | "pandora" | "pd" | "pandora music" | "pandoramusic" | "flowerytts" | "flowery" | "flowery.tts" | "bandcamp" | "bc" | "js" | "jiosaavn" | "td";
     };
+    /**
+     * Validates the provided source string against the capabilities of the Lavalink node. It checks if the source string is supported by the node's enabled source managers and plugins, throwing errors if any required sources or plugins are missing for the specified search platform. This ensures that search queries are only executed with compatible sources based on the node's configuration.
+     * @param node
+     * @param sourceString
+     * @returns
+     */
     validateSourceString(node: LavalinkNode, sourceString: SearchPlatform): void;
 }
 /**
@@ -3842,6 +3914,8 @@ interface ManagerPlayerOptions<CustomPlayerT extends Player = Player> {
     clientBasedPositionUpdateInterval?: number;
     /** What should be used as a searchPlatform, if no source was provided during the query */
     defaultSearchPlatform?: SearchPlatform;
+    /** Allow custom sources which lavalink-client does not support (yet) */
+    allowCustomSources?: boolean;
     /** Applies the volume via a filter, not via the lavalink volume transformer */
     applyVolumeAsFilter?: boolean;
     /** Transforms the saved data of a requested user */
@@ -4016,6 +4090,7 @@ declare class LavalinkManager<CustomPlayerT extends Player = Player> extends Eve
      *       applyVolumeAsFilter: false,
      *       clientBasedPositionUpdateInterval: 150,
      *       defaultSearchPlatform: "ytmsearch",
+     *       allowCustomSources: false,
      *       volumeDecrementer: 0.75,
      *       //requesterTransformer: YourRequesterTransformerFunction,
      *       onDisconnect: {

package/dist/index.d.ts

@@ -417,7 +417,19 @@ declare function parseLavalinkConnUrl(connectionUrl: string): {
 declare class ManagerUtils {
     LavalinkManager: LavalinkManager | undefined;
     constructor(LavalinkManager?: LavalinkManager);
+    /**
+     * Builds a pluginInfo object based on the provided data, extracting relevant information from the data and clientData parameters. This function is used to construct the pluginInfo property for tracks, allowing for consistent handling of plugin-related information across different track sources and formats.
+     * @param data
+     * @param clientData
+     * @returns
+     */
     buildPluginInfo(data: any, clientData?: any): any;
+    /**
+     * Builds a Track object from the provided data and requester information. It validates the presence of required properties in the data, transforms the requester using a custom transformer function if provided, and constructs a Track object with the appropriate properties and plugin information. The function also includes error handling to ensure that the input data is valid and provides debug information if track building fails.
+     * @param data
+     * @param requester
+     * @returns
+     */
     buildTrack(data: LavalinkTrack | Track, requester: unknown): Track;
     /**
      * Builds a UnresolvedTrack to be resolved before being played  .
@@ -430,6 +442,11 @@ declare class ManagerUtils {
      * @param data
      */
     isNode(data: LavalinkNode): boolean;
+    /**
+     * Gets the transformed requester based on the LavalinkManager options. If a custom requester transformer function is provided in the player options, it applies that function to the requester; otherwise, it returns the requester as is. The function also includes error handling to catch any exceptions that may occur during the transformation process and emits a debug event if the transformation fails.
+     * @param requester
+     * @returns
+     */
     getTransformedRequester(requester: unknown): unknown;
     /**
      * Validate if a data is equal to node options
@@ -470,18 +487,73 @@ declare class ManagerUtils {
      * @param track
      */
     isUnresolvedTrackQuery(data: UnresolvedQuery): boolean;
+    /**
+     * Gets the closest track by resolving the provided UnresolvedTrack using the getClosestTrack function. It includes error handling to catch any exceptions that may occur during the resolution process and emits a debug event if the resolution fails. The function returns a Promise that resolves to a Track object if successful, or undefined if no closest track is found.
+     * @param data
+     * @param player
+     * @returns
+     */
     getClosestTrack(data: UnresolvedTrack, player: Player): Promise<Track | undefined>;
-    validateQueryString(node: LavalinkNode, queryString: string, sourceString?: LavalinkSearchPlatform): void;
+    /**
+     * Validates the query string against various criteria, including checking for empty strings, length limits for specific sources, blacklisted links or words, and ensuring that the Lavalink node has the necessary source managers enabled for the provided query. The function also includes debug event emissions to assist with troubleshooting and understanding the validation process.
+     * @param node
+     * @param queryString
+     * @param sourceString
+     * @returns
+     */
+    validateQueryString(node: LavalinkNode, queryString: string, sourceString?: SearchPlatform): void;
+    /**
+     * Finds the source of a query string by checking if it starts with a valid source prefix defined in the DefaultSources object. If a valid source prefix is found, it returns the corresponding SearchPlatform; otherwise, it returns null. This function is useful for determining the intended search platform for a given query string, allowing for more accurate search results when the user specifies a source (e.g., "ytsearch:Never Gonna Give You Up" would indicate that the search should be performed on YouTube).
+     * @param queryString
+     * @returns
+     */
+    findSourceOfQuery(queryString: string): SearchPlatform;
+    /**
+     * Extracts the source from the query if it starts with a valid source prefix (e.g., "ytsearch:") and updates the searchQuery object accordingly.
+     * @param searchQuery
+     * @returns The updated searchQuery object with the extracted source and modified query string.
+     */
+    extractSourceOfQuery<T extends {
+        query: string;
+        source?: string;
+    }>(searchQuery: T): T;
+    /**
+     * Converts a string to lowercase if the input is a string, otherwise returns the input as is. This is useful for ensuring that search platform identifiers are case-insensitive while allowing other types of input to pass through unchanged.
+     * @param input
+     * @returns
+     */
+    typedLowerCase<T extends unknown>(input: T): T;
+    /**
+     * Transforms a search query by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, and the determined search platform to be used for the search operation.
+     * @param query
+     * @returns
+     */
     transformQuery(query: SearchQuery): {
         query: string;
-        extraQueryUrlParams: URLSearchParams;
-        source: any;
+        extraQueryUrlParams: any;
+        source: SearchPlatform;
     };
+    /**
+     * Transforms a LavaSearchQuery by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, the determined search platform to be used for the search operation, and the types of search (track, playlist, artist, album, text) to be performed.
+     * @param query
+     * @returns
+     */
     transformLavaSearchQuery(query: LavaSearchQuery): {
+        query: never;
+        types: any[];
+        extraQueryUrlParams: any;
+        source: SearchPlatform;
+    } | {
         query: string;
         types: string[];
-        source: any;
+        source: "ytsearch" | "ytmsearch" | "scsearch" | "bcsearch" | "spsearch" | "sprec" | "amsearch" | "dzsearch" | "dzisrc" | "dzrec" | "ymsearch" | "ymrec" | "vksearch" | "vkrec" | "tdsearch" | "tdrec" | "qbsearch" | "qbisrc" | "qbrec" | "pdsearch" | "pdisrc" | "pdrec" | "ftts" | "speak" | "phsearch" | "pornhub" | "porn" | "tts" | "jssearch" | "jsrec" | "local" | "http" | "https" | "link" | "uri" | "youtube" | "yt" | "youtube music" | "youtubemusic" | "ytm" | "musicyoutube" | "music youtube" | "soundcloud" | "sc" | "am" | "apple music" | "applemusic" | "apple" | "musicapple" | "music apple" | "sp" | "spsuggestion" | "spotify" | "spotify.com" | "spotifycom" | "dz" | "deezer" | "yandex" | "yandex music" | "yandexmusic" | "vk" | "vk music" | "vkmusic" | "tidal" | "tidal music" | "qobuz" | "pandora" | "pd" | "pandora music" | "pandoramusic" | "flowerytts" | "flowery" | "flowery.tts" | "bandcamp" | "bc" | "js" | "jiosaavn" | "td";
     };
+    /**
+     * Validates the provided source string against the capabilities of the Lavalink node. It checks if the source string is supported by the node's enabled source managers and plugins, throwing errors if any required sources or plugins are missing for the specified search platform. This ensures that search queries are only executed with compatible sources based on the node's configuration.
+     * @param node
+     * @param sourceString
+     * @returns
+     */
     validateSourceString(node: LavalinkNode, sourceString: SearchPlatform): void;
 }
 /**
@@ -3842,6 +3914,8 @@ interface ManagerPlayerOptions<CustomPlayerT extends Player = Player> {
     clientBasedPositionUpdateInterval?: number;
     /** What should be used as a searchPlatform, if no source was provided during the query */
     defaultSearchPlatform?: SearchPlatform;
+    /** Allow custom sources which lavalink-client does not support (yet) */
+    allowCustomSources?: boolean;
     /** Applies the volume via a filter, not via the lavalink volume transformer */
     applyVolumeAsFilter?: boolean;
     /** Transforms the saved data of a requested user */
@@ -4016,6 +4090,7 @@ declare class LavalinkManager<CustomPlayerT extends Player = Player> extends Eve
      *       applyVolumeAsFilter: false,
      *       clientBasedPositionUpdateInterval: 150,
      *       defaultSearchPlatform: "ytmsearch",
+     *       allowCustomSources: false,
      *       volumeDecrementer: 0.75,
      *       //requesterTransformer: YourRequesterTransformerFunction,
      *       onDisconnect: {

package/dist/index.js

@@ -604,12 +604,24 @@ var ManagerUtils = class {
   constructor(LavalinkManager2) {
     this.LavalinkManager = LavalinkManager2;
   }
+  /**
+   * Builds a pluginInfo object based on the provided data, extracting relevant information from the data and clientData parameters. This function is used to construct the pluginInfo property for tracks, allowing for consistent handling of plugin-related information across different track sources and formats.
+   * @param data
+   * @param clientData
+   * @returns
+   */
   buildPluginInfo(data, clientData = {}) {
     return {
       clientData,
       ...data.pluginInfo || data.plugin
     };
   }
+  /**
+   * Builds a Track object from the provided data and requester information. It validates the presence of required properties in the data, transforms the requester using a custom transformer function if provided, and constructs a Track object with the appropriate properties and plugin information. The function also includes error handling to ensure that the input data is valid and provides debug information if track building fails.
+   * @param data
+   * @param requester
+   * @returns
+   */
   buildTrack(data, requester) {
     if (!data?.encoded || typeof data.encoded !== "string")
       throw new RangeError("Argument 'data.encoded' must be present.");
@@ -707,6 +719,11 @@ var ManagerUtils = class {
       return false;
     return true;
   }
+  /**
+   * Gets the transformed requester based on the LavalinkManager options. If a custom requester transformer function is provided in the player options, it applies that function to the requester; otherwise, it returns the requester as is. The function also includes error handling to catch any exceptions that may occur during the transformation process and emits a debug event if the transformation fails.
+   * @param requester
+   * @returns
+   */
   getTransformedRequester(requester) {
     try {
       return typeof this.LavalinkManager?.options?.playerOptions?.requesterTransformer === "function" ? this.LavalinkManager?.options?.playerOptions?.requesterTransformer(requester) : requester;
@@ -795,6 +812,12 @@ var ManagerUtils = class {
   isUnresolvedTrackQuery(data) {
     return typeof data === "object" && !("info" in data) && typeof data.title === "string";
   }
+  /**
+   * Gets the closest track by resolving the provided UnresolvedTrack using the getClosestTrack function. It includes error handling to catch any exceptions that may occur during the resolution process and emits a debug event if the resolution fails. The function returns a Promise that resolves to a Track object if successful, or undefined if no closest track is found.
+   * @param data
+   * @param player
+   * @returns
+   */
   async getClosestTrack(data, player) {
     try {
       return getClosestTrack(data, player);
@@ -810,6 +833,13 @@ var ManagerUtils = class {
       throw e;
     }
   }
+  /**
+   * Validates the query string against various criteria, including checking for empty strings, length limits for specific sources, blacklisted links or words, and ensuring that the Lavalink node has the necessary source managers enabled for the provided query. The function also includes debug event emissions to assist with troubleshooting and understanding the validation process.
+   * @param node
+   * @param queryString
+   * @param sourceString
+   * @returns
+   */
   validateQueryString(node, queryString, sourceString) {
     if (!node.info) throw new Error("No Lavalink Node was provided");
     if (node._checkForSources && !node.info.sourceManagers?.length)
@@ -897,24 +927,84 @@ var ManagerUtils = class {
     }
     return;
   }
-  transformQuery(query) {
-    const sourceOfQuery = typeof query === "string" ? void 0 : 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 : void 0,
-      source: sourceOfQuery ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
-    };
-    const foundSource = Object.keys(DefaultSources).find((source) => Query.query?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
+  /**
+   * Finds the source of a query string by checking if it starts with a valid source prefix defined in the DefaultSources object. If a valid source prefix is found, it returns the corresponding SearchPlatform; otherwise, it returns null. This function is useful for determining the intended search platform for a given query string, allowing for more accurate search results when the user specifies a source (e.g., "ytsearch:Never Gonna Give You Up" would indicate that the search should be performed on YouTube).
+   * @param queryString
+   * @returns
+   */
+  findSourceOfQuery(queryString) {
+    const foundSource = Object.keys(DefaultSources).find((source) => queryString?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
     if (foundSource && !["https", "http"].includes(foundSource) && DefaultSources[foundSource]) {
-      Query.source = DefaultSources[foundSource];
-      Query.query = Query.query.slice(`${foundSource}:`.length, Query.query.length);
+      return foundSource;
     }
-    return Query;
+    return null;
   }
+  /**
+   * Extracts the source from the query if it starts with a valid source prefix (e.g., "ytsearch:") and updates the searchQuery object accordingly.
+   * @param searchQuery
+   * @returns The updated searchQuery object with the extracted source and modified query string.
+   */
+  extractSourceOfQuery(searchQuery) {
+    const foundSource = this.findSourceOfQuery(searchQuery.query);
+    if (foundSource) {
+      searchQuery.source = DefaultSources[foundSource];
+      searchQuery.query = searchQuery.query.slice(`${foundSource}:`.length, searchQuery.query.length);
+    }
+    return searchQuery;
+  }
+  /**
+   * Converts a string to lowercase if the input is a string, otherwise returns the input as is. This is useful for ensuring that search platform identifiers are case-insensitive while allowing other types of input to pass through unchanged.
+   * @param input
+   * @returns
+   */
+  typedLowerCase(input) {
+    if (!input) return input;
+    if (typeof input === "string") return input.toLowerCase();
+    return input;
+  }
+  /**
+   * Transforms a search query by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, and the determined search platform to be used for the search operation.
+   * @param query
+   * @returns
+   */
+  transformQuery(query) {
+    const typedDefault = this.typedLowerCase(this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform);
+    if (typeof query === "string") {
+      const Query = {
+        query,
+        extraQueryUrlParams: void 0,
+        source: typedDefault
+      };
+      return this.extractSourceOfQuery(Query);
+    }
+    const providedSource = query?.source?.trim?.()?.toLowerCase?.();
+    const validSourceExtracted = DefaultSources[providedSource ?? typedDefault];
+    return this.extractSourceOfQuery({
+      query: query.query,
+      extraQueryUrlParams: query.extraQueryUrlParams,
+      source: validSourceExtracted ?? providedSource ?? typedDefault
+    });
+  }
+  /**
+   * Transforms a LavaSearchQuery by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, the determined search platform to be used for the search operation, and the types of search (track, playlist, artist, album, text) to be performed.
+   * @param query
+   * @returns
+   */
   transformLavaSearchQuery(query) {
-    const sourceOfQuery = typeof query === "string" ? void 0 : DefaultSources[query.source?.trim?.()?.toLowerCase?.() ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()] ?? query.source?.trim?.()?.toLowerCase?.();
+    const typedDefault = this.typedLowerCase(this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform);
+    if (typeof query === "string") {
+      const Query2 = {
+        query,
+        types: [],
+        extraQueryUrlParams: void 0,
+        source: typedDefault
+      };
+      return this.extractSourceOfQuery(Query2);
+    }
+    const providedSource = query?.source?.trim?.()?.toLowerCase?.();
+    const validSourceExtracted = DefaultSources[providedSource ?? typedDefault];
     const Query = {
-      query: typeof query === "string" ? query : query.query,
+      query: query.query,
       types: query.types ? ["track", "playlist", "artist", "album", "text"].filter(
         (v) => query.types?.find((x) => x.toLowerCase().startsWith(v))
       ) : [
@@ -924,19 +1014,23 @@ var ManagerUtils = class {
         "album"
         /*"text"*/
       ],
-      source: sourceOfQuery ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
+      source: validSourceExtracted ?? providedSource ?? typedDefault
     };
-    const foundSource = Object.keys(DefaultSources).find((source) => Query.query.toLowerCase().startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
-    if (foundSource && DefaultSources[foundSource]) {
-      Query.source = DefaultSources[foundSource];
-      Query.query = Query.query.slice(`${foundSource}:`.length, Query.query.length);
-    }
-    return Query;
+    return this.extractSourceOfQuery(Query);
   }
+  /**
+   * Validates the provided source string against the capabilities of the Lavalink node. It checks if the source string is supported by the node's enabled source managers and plugins, throwing errors if any required sources or plugins are missing for the specified search platform. This ensures that search queries are only executed with compatible sources based on the node's configuration.
+   * @param node
+   * @param sourceString
+   * @returns
+   */
   validateSourceString(node, sourceString) {
     if (!sourceString) throw new Error(`No SourceString was provided`);
     const source = DefaultSources[sourceString.toLowerCase().trim()];
-    if (!source) throw new Error(`Lavalink Node SearchQuerySource: '${sourceString}' is not available`);
+    if (!source && !!this.LavalinkManager.options.playerOptions.allowCustomSources)
+      throw new Error(
+        `Lavalink-Client does not support SearchQuerySource: '${sourceString}'. You can disable this check by setting 'ManagerOptions.PlayerOptions.allowCustomSources' to true`
+      );
     if (!node.info) throw new Error("Lavalink Node does not have any info cached yet, not ready yet!");
     if (!node._checkForSources) return;
     if (source === "amsearch" && !node.info?.sourceManagers?.includes("applemusic")) {
@@ -6072,6 +6166,7 @@ var LavalinkManager = class extends import_events2.EventEmitter {
         applyVolumeAsFilter: options?.playerOptions?.applyVolumeAsFilter ?? false,
         clientBasedPositionUpdateInterval: options?.playerOptions?.clientBasedPositionUpdateInterval ?? 100,
         defaultSearchPlatform: options?.playerOptions?.defaultSearchPlatform ?? "ytsearch",
+        allowCustomSources: options?.playerOptions?.allowCustomSources ?? false,
         onDisconnect: {
           destroyPlayer: options?.playerOptions?.onDisconnect?.destroyPlayer ?? true,
           autoReconnect: options?.playerOptions?.onDisconnect?.autoReconnect ?? false,
@@ -6188,6 +6283,7 @@ var LavalinkManager = class extends import_events2.EventEmitter {
    *       applyVolumeAsFilter: false,
    *       clientBasedPositionUpdateInterval: 150,
    *       defaultSearchPlatform: "ytmsearch",
+   *       allowCustomSources: false,
    *       volumeDecrementer: 0.75,
    *       //requesterTransformer: YourRequesterTransformerFunction,
    *       onDisconnect: {

package/dist/index.mjs

@@ -540,12 +540,24 @@ var ManagerUtils = class {
   constructor(LavalinkManager2) {
     this.LavalinkManager = LavalinkManager2;
   }
+  /**
+   * Builds a pluginInfo object based on the provided data, extracting relevant information from the data and clientData parameters. This function is used to construct the pluginInfo property for tracks, allowing for consistent handling of plugin-related information across different track sources and formats.
+   * @param data
+   * @param clientData
+   * @returns
+   */
   buildPluginInfo(data, clientData = {}) {
     return {
       clientData,
       ...data.pluginInfo || data.plugin
     };
   }
+  /**
+   * Builds a Track object from the provided data and requester information. It validates the presence of required properties in the data, transforms the requester using a custom transformer function if provided, and constructs a Track object with the appropriate properties and plugin information. The function also includes error handling to ensure that the input data is valid and provides debug information if track building fails.
+   * @param data
+   * @param requester
+   * @returns
+   */
   buildTrack(data, requester) {
     if (!data?.encoded || typeof data.encoded !== "string")
       throw new RangeError("Argument 'data.encoded' must be present.");
@@ -643,6 +655,11 @@ var ManagerUtils = class {
       return false;
     return true;
   }
+  /**
+   * Gets the transformed requester based on the LavalinkManager options. If a custom requester transformer function is provided in the player options, it applies that function to the requester; otherwise, it returns the requester as is. The function also includes error handling to catch any exceptions that may occur during the transformation process and emits a debug event if the transformation fails.
+   * @param requester
+   * @returns
+   */
   getTransformedRequester(requester) {
     try {
       return typeof this.LavalinkManager?.options?.playerOptions?.requesterTransformer === "function" ? this.LavalinkManager?.options?.playerOptions?.requesterTransformer(requester) : requester;
@@ -731,6 +748,12 @@ var ManagerUtils = class {
   isUnresolvedTrackQuery(data) {
     return typeof data === "object" && !("info" in data) && typeof data.title === "string";
   }
+  /**
+   * Gets the closest track by resolving the provided UnresolvedTrack using the getClosestTrack function. It includes error handling to catch any exceptions that may occur during the resolution process and emits a debug event if the resolution fails. The function returns a Promise that resolves to a Track object if successful, or undefined if no closest track is found.
+   * @param data
+   * @param player
+   * @returns
+   */
   async getClosestTrack(data, player) {
     try {
       return getClosestTrack(data, player);
@@ -746,6 +769,13 @@ var ManagerUtils = class {
       throw e;
     }
   }
+  /**
+   * Validates the query string against various criteria, including checking for empty strings, length limits for specific sources, blacklisted links or words, and ensuring that the Lavalink node has the necessary source managers enabled for the provided query. The function also includes debug event emissions to assist with troubleshooting and understanding the validation process.
+   * @param node
+   * @param queryString
+   * @param sourceString
+   * @returns
+   */
   validateQueryString(node, queryString, sourceString) {
     if (!node.info) throw new Error("No Lavalink Node was provided");
     if (node._checkForSources && !node.info.sourceManagers?.length)
@@ -833,24 +863,84 @@ var ManagerUtils = class {
     }
     return;
   }
-  transformQuery(query) {
-    const sourceOfQuery = typeof query === "string" ? void 0 : 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 : void 0,
-      source: sourceOfQuery ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
-    };
-    const foundSource = Object.keys(DefaultSources).find((source) => Query.query?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
+  /**
+   * Finds the source of a query string by checking if it starts with a valid source prefix defined in the DefaultSources object. If a valid source prefix is found, it returns the corresponding SearchPlatform; otherwise, it returns null. This function is useful for determining the intended search platform for a given query string, allowing for more accurate search results when the user specifies a source (e.g., "ytsearch:Never Gonna Give You Up" would indicate that the search should be performed on YouTube).
+   * @param queryString
+   * @returns
+   */
+  findSourceOfQuery(queryString) {
+    const foundSource = Object.keys(DefaultSources).find((source) => queryString?.toLowerCase?.()?.startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
     if (foundSource && !["https", "http"].includes(foundSource) && DefaultSources[foundSource]) {
-      Query.source = DefaultSources[foundSource];
-      Query.query = Query.query.slice(`${foundSource}:`.length, Query.query.length);
+      return foundSource;
     }
-    return Query;
+    return null;
   }
+  /**
+   * Extracts the source from the query if it starts with a valid source prefix (e.g., "ytsearch:") and updates the searchQuery object accordingly.
+   * @param searchQuery
+   * @returns The updated searchQuery object with the extracted source and modified query string.
+   */
+  extractSourceOfQuery(searchQuery) {
+    const foundSource = this.findSourceOfQuery(searchQuery.query);
+    if (foundSource) {
+      searchQuery.source = DefaultSources[foundSource];
+      searchQuery.query = searchQuery.query.slice(`${foundSource}:`.length, searchQuery.query.length);
+    }
+    return searchQuery;
+  }
+  /**
+   * Converts a string to lowercase if the input is a string, otherwise returns the input as is. This is useful for ensuring that search platform identifiers are case-insensitive while allowing other types of input to pass through unchanged.
+   * @param input
+   * @returns
+   */
+  typedLowerCase(input) {
+    if (!input) return input;
+    if (typeof input === "string") return input.toLowerCase();
+    return input;
+  }
+  /**
+   * Transforms a search query by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, and the determined search platform to be used for the search operation.
+   * @param query
+   * @returns
+   */
+  transformQuery(query) {
+    const typedDefault = this.typedLowerCase(this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform);
+    if (typeof query === "string") {
+      const Query = {
+        query,
+        extraQueryUrlParams: void 0,
+        source: typedDefault
+      };
+      return this.extractSourceOfQuery(Query);
+    }
+    const providedSource = query?.source?.trim?.()?.toLowerCase?.();
+    const validSourceExtracted = DefaultSources[providedSource ?? typedDefault];
+    return this.extractSourceOfQuery({
+      query: query.query,
+      extraQueryUrlParams: query.extraQueryUrlParams,
+      source: validSourceExtracted ?? providedSource ?? typedDefault
+    });
+  }
+  /**
+   * Transforms a LavaSearchQuery by determining the appropriate search platform based on the query string and the default search platform specified in the LavalinkManager options. It checks if the query string starts with a valid source prefix and extracts it if present. The function returns an object containing the modified query string, any extra URL parameters, the determined search platform to be used for the search operation, and the types of search (track, playlist, artist, album, text) to be performed.
+   * @param query
+   * @returns
+   */
   transformLavaSearchQuery(query) {
-    const sourceOfQuery = typeof query === "string" ? void 0 : DefaultSources[query.source?.trim?.()?.toLowerCase?.() ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()] ?? query.source?.trim?.()?.toLowerCase?.();
+    const typedDefault = this.typedLowerCase(this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform);
+    if (typeof query === "string") {
+      const Query2 = {
+        query,
+        types: [],
+        extraQueryUrlParams: void 0,
+        source: typedDefault
+      };
+      return this.extractSourceOfQuery(Query2);
+    }
+    const providedSource = query?.source?.trim?.()?.toLowerCase?.();
+    const validSourceExtracted = DefaultSources[providedSource ?? typedDefault];
     const Query = {
-      query: typeof query === "string" ? query : query.query,
+      query: query.query,
       types: query.types ? ["track", "playlist", "artist", "album", "text"].filter(
         (v) => query.types?.find((x) => x.toLowerCase().startsWith(v))
       ) : [
@@ -860,19 +950,23 @@ var ManagerUtils = class {
         "album"
         /*"text"*/
       ],
-      source: sourceOfQuery ?? this.LavalinkManager?.options?.playerOptions?.defaultSearchPlatform?.toLowerCase?.()
+      source: validSourceExtracted ?? providedSource ?? typedDefault
     };
-    const foundSource = Object.keys(DefaultSources).find((source) => Query.query.toLowerCase().startsWith(`${source}:`.toLowerCase()))?.trim?.()?.toLowerCase?.();
-    if (foundSource && DefaultSources[foundSource]) {
-      Query.source = DefaultSources[foundSource];
-      Query.query = Query.query.slice(`${foundSource}:`.length, Query.query.length);
-    }
-    return Query;
+    return this.extractSourceOfQuery(Query);
   }
+  /**
+   * Validates the provided source string against the capabilities of the Lavalink node. It checks if the source string is supported by the node's enabled source managers and plugins, throwing errors if any required sources or plugins are missing for the specified search platform. This ensures that search queries are only executed with compatible sources based on the node's configuration.
+   * @param node
+   * @param sourceString
+   * @returns
+   */
   validateSourceString(node, sourceString) {
     if (!sourceString) throw new Error(`No SourceString was provided`);
     const source = DefaultSources[sourceString.toLowerCase().trim()];
-    if (!source) throw new Error(`Lavalink Node SearchQuerySource: '${sourceString}' is not available`);
+    if (!source && !!this.LavalinkManager.options.playerOptions.allowCustomSources)
+      throw new Error(
+        `Lavalink-Client does not support SearchQuerySource: '${sourceString}'. You can disable this check by setting 'ManagerOptions.PlayerOptions.allowCustomSources' to true`
+      );
     if (!node.info) throw new Error("Lavalink Node does not have any info cached yet, not ready yet!");
     if (!node._checkForSources) return;
     if (source === "amsearch" && !node.info?.sourceManagers?.includes("applemusic")) {
@@ -6008,6 +6102,7 @@ var LavalinkManager = class extends EventEmitter2 {
         applyVolumeAsFilter: options?.playerOptions?.applyVolumeAsFilter ?? false,
         clientBasedPositionUpdateInterval: options?.playerOptions?.clientBasedPositionUpdateInterval ?? 100,
         defaultSearchPlatform: options?.playerOptions?.defaultSearchPlatform ?? "ytsearch",
+        allowCustomSources: options?.playerOptions?.allowCustomSources ?? false,
         onDisconnect: {
           destroyPlayer: options?.playerOptions?.onDisconnect?.destroyPlayer ?? true,
           autoReconnect: options?.playerOptions?.onDisconnect?.autoReconnect ?? false,
@@ -6124,6 +6219,7 @@ var LavalinkManager = class extends EventEmitter2 {
    *       applyVolumeAsFilter: false,
    *       clientBasedPositionUpdateInterval: 150,
    *       defaultSearchPlatform: "ytmsearch",
+   *       allowCustomSources: false,
    *       volumeDecrementer: 0.75,
    *       //requesterTransformer: YourRequesterTransformerFunction,
    *       onDisconnect: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lavalink-client",
-    "version": "2.9.0",
+    "version": "2.9.1",
     "description": "Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Proficients. - Supports NodeLink@v3 too.",
     "keywords": [
         "advanced",