magmastream 2.9.3-dev.25 → 2.9.3-dev.27

package/dist/structures/Utils.d.ts

@@ -0,0 +1,169 @@
+import { AutoPlayPlatform, TrackPartial } from "./Enums";
+import { Manager } from "./Manager";
+import { AnyUser, ErrorOrEmptySearchResult, Extendable, LavalinkResponse, SearchResult, SerializedPlayerState, Track, TrackData } from "./Types";
+import { Player } from "./Player";
+export declare abstract class TrackUtils {
+    static trackPartial: TrackPartial[] | null;
+    private static manager;
+    /**
+     * Initializes the TrackUtils class with the given manager.
+     * @param manager The manager instance to use.
+     * @hidden
+     */
+    static init(manager: Manager): void;
+    /**
+     * Sets the partial properties for the Track class. If a Track has some of its properties removed by the partial,
+     * it will be considered a partial Track.
+     * @param {TrackPartial} partial The array of string property names to remove from the Track class.
+     */
+    static setTrackPartial(partial: TrackPartial[]): void;
+    /**
+     * Checks if the provided argument is a valid Track.
+     * @param value The value to check.
+     * @returns {boolean} Whether the provided argument is a valid Track.
+     */
+    static isTrack(track: unknown): track is Track;
+    /**
+     * Checks if the provided argument is a valid Track array.
+     * @param value The value to check.
+     * @returns {boolean} Whether the provided argument is a valid Track array.
+     */
+    static isTrackArray(value: unknown): value is Track[];
+    /**
+     * Checks if the provided argument is a valid Track or Track array.
+     * @param value The value to check.
+     * @returns {boolean} Whether the provided argument is a valid Track or Track array.
+     */
+    static validate(value: unknown): value is Track | Track[];
+    /**
+     * Builds a Track from the raw data from Lavalink and a optional requester.
+     * @param data The raw data from Lavalink to build the Track from.
+     * @param requester The user who requested the track, if any.
+     * @param isAutoPlay Whether the track is autoplayed. Defaults to false.
+     * @returns The built Track.
+     */
+    static build<T = AnyUser>(data: TrackData, requester?: T, isAutoplay?: boolean): Track;
+    /**
+     * Validates a search result.
+     * @param result The search result to validate.
+     * @returns Whether the search result is valid.
+     */
+    static isErrorOrEmptySearchResult(result: SearchResult): result is ErrorOrEmptySearchResult;
+    /**
+     * Revives a track.
+     * @param track The track to revive.
+     * @returns The revived track.
+     */
+    static revive(track: Track): Track;
+}
+export declare abstract class AutoPlayUtils {
+    private static manager;
+    /**
+     * Initializes the AutoPlayUtils class with the given manager.
+     * @param manager The manager instance to use.
+     * @hidden
+     */
+    static init(manager: Manager): Promise<void>;
+    /**
+     * Gets recommended tracks for the given track.
+     * @param track The track to get recommended tracks for.
+     * @returns An array of recommended tracks.
+     */
+    static getRecommendedTracks(track: Track): Promise<Track[]>;
+    /**
+     * Gets recommended tracks from Last.fm for the given track.
+     * @param track The track to get recommended tracks for.
+     * @param apiKey The API key for Last.fm.
+     * @returns An array of recommended tracks.
+     */
+    static getRecommendedTracksFromLastFm(track: Track, apiKey: string): Promise<Track[]>;
+    /**
+     * Gets recommended tracks from the given source.
+     * @param track The track to get recommended tracks for.
+     * @param platform The source to get recommended tracks from.
+     * @returns An array of recommended tracks.
+     */
+    static getRecommendedTracksFromSource(track: Track, platform: AutoPlayPlatform): Promise<Track[]>;
+    /**
+     * Searches for a track using the manager and returns resolved tracks.
+     * @param query The search query (artist - title).
+     * @param requester The requester who initiated the search.
+     * @returns An array of resolved tracks, or an empty array if not found or error occurred.
+     */
+    private static resolveTracksFromQuery;
+    /**
+     * Resolves the first available track from a search query using the specified source.
+     * Useful for normalizing tracks that lack platform-specific metadata or URIs.
+     *
+     * @param query - The search query string (usually "Artist - Title").
+     * @param source - The search platform to use (e.g., Spotify, Deezer, YouTube).
+     * @param requester - The requester object, used for context or attribution.
+     * @returns A single resolved {@link Track} object if found, or `null` if the search fails or returns no results.
+     */
+    private static resolveFirstTrackFromQuery;
+    private static isPlaylistRawData;
+    private static isTrackData;
+    private static isTrackDataArray;
+    static buildTracksFromResponse<T>(recommendedResult: LavalinkResponse, requester?: T): Track[];
+}
+export declare abstract class PlayerUtils {
+    private static manager;
+    /**
+     * Initializes the PlayerUtils class with the given manager.
+     * @param manager The manager instance to use.
+     * @hidden
+     */
+    static init(manager: Manager): void;
+    /**
+     * Serializes a Player instance to avoid circular references.
+     * @param player The Player instance to serialize
+     * @returns The serialized Player instance
+     */
+    static serializePlayer(player: Player): Promise<SerializedPlayerState> | null;
+    /**
+     * Gets the base directory for player data.
+     */
+    static getPlayersBaseDir(): string;
+    /**
+     * Gets the path to the player's directory.
+     */
+    static getGuildDir(guildId: string): string;
+    /**
+     * Gets the path to the player's state file.
+     */
+    static getPlayerStatePath(guildId: string): string;
+    /**
+     * Gets the path to the player's current track file.
+     */
+    static getPlayerCurrentPath(guildId: string): string;
+    /**
+     * Gets the path to the player's queue file.
+     */
+    static getPlayerQueuePath(guildId: string): string;
+    /**
+     * Gets the path to the player's previous tracks file.
+     */
+    static getPlayerPreviousPath(guildId: string): string;
+    /**
+     * Gets the Redis key for player storage.
+     */
+    static getRedisKey(): string;
+}
+/** Gets or extends structures to extend the built in, or already extended, classes to add more functionality. */
+export declare abstract class Structure {
+    /**
+     * Extends a class.
+     * @param name
+     * @param extender
+     */
+    static extend<K extends keyof Extendable, T extends Extendable[K]>(name: K, extender: (target: Extendable[K]) => T): T;
+    /**
+     * Get a structure from available structures by name.
+     * @param name
+     */
+    static get<K extends keyof Extendable>(name: K): Extendable[K];
+}
+export declare abstract class JSONUtils {
+    static safe<T>(obj: T, space?: number): string;
+    static serializeTrack(track: Track): string;
+}

package/dist/structures/Utils.js

@@ -653,10 +653,13 @@ class PlayerUtils {
         try {
             const [current, tracks, previous] = await Promise.all([player.queue.getCurrent(), player.queue.getTracks(), player.queue.getPrevious()]);
             const serializeTrack = (track) => {
+                if (!track || !track.identifier)
+                    return null;
                 try {
                     return {
                         ...track,
                         requester: track.requester ? { id: track.requester.id, username: track.requester.username } : null,
+                        displayThumbnail: undefined,
                     };
                 }
                 catch {
@@ -681,7 +684,11 @@ class PlayerUtils {
                     safeNode = null;
                 }
             }
+            const serializableData = player.getSerializableData();
+            const nowPlayingMessage = serializableData.nowPlayingMessage;
+            delete serializableData.nowPlayingMessage;
             const snapshot = {
+                clusterId: player.clusterId,
                 options: player.options,
                 voiceState: player.voiceState,
                 guildId: player.guildId,
@@ -714,7 +721,16 @@ class PlayerUtils {
                         filterStatus: { ...player.filters.filtersStatus },
                     }
                     : null,
-                data: safeSerialize(player.getSerializableData()),
+                data: {
+                    ...safeSerialize(serializableData),
+                    nowPlayingMessage: nowPlayingMessage
+                        ? {
+                            id: String(nowPlayingMessage.id),
+                            channelId: nowPlayingMessage.channelId,
+                            guildId: nowPlayingMessage.guildId,
+                        }
+                        : null,
+                },
             };
             // Sanity check
             JSON.stringify(snapshot);

package/dist/utils/filtersEqualizers.d.ts

@@ -0,0 +1,16 @@
+/** Represents an equalizer band. */
+export interface Band {
+    /** The index of the equalizer band (0-12). */
+    band: number;
+    /** The gain value of the equalizer band (in decibels). */
+    gain: number;
+}
+export declare const bassBoostEqualizer: Band[];
+export declare const softEqualizer: Band[];
+export declare const tvEqualizer: Band[];
+export declare const trebleBassEqualizer: Band[];
+export declare const vaporwaveEqualizer: Band[];
+export declare const popEqualizer: Band[];
+export declare const electronicEqualizer: Band[];
+export declare const radioEqualizer: Band[];
+export declare const demonEqualizer: Band[];

package/dist/utils/managerCheck.d.ts

@@ -0,0 +1,7 @@
+import { ManagerOptions } from "../structures/Types";
+/**
+ * Validates the provided ManagerOptions object.
+ * @param options - The options to validate.
+ * @throws {MagmaStreamError} Throws if any required option is missing or invalid.
+ */
+export default function managerCheck(options: ManagerOptions): void;

package/dist/utils/nodeCheck.d.ts

@@ -0,0 +1,7 @@
+import { NodeOptions } from "../structures/Types";
+/**
+ * Validates the provided NodeOptions object.
+ * @param options - The options to validate.
+ * @throws {MagmaStreamError} Throws if any required option is missing or invalid.
+ */
+export default function nodeCheck(options: NodeOptions): void;

package/dist/utils/playerCheck.d.ts

@@ -0,0 +1,7 @@
+import { PlayerOptions } from "../structures/Types";
+/**
+ * Validates the provided PlayerOptions object.
+ * @param options - The options to validate.
+ * @throws {MagmaStreamError} Throws if any required option is missing or invalid.
+ */
+export default function playerCheck(options: PlayerOptions): void;

package/dist/wrappers/discord.js.d.ts

@@ -0,0 +1,15 @@
+import { Manager as BaseManager } from "../structures/Manager";
+import type { GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { Client, Guild, User } from "discord.js";
+import { AnyUser, ManagerOptions } from "../structures/Types";
+export * from "../index";
+/**
+ * Discord.js wrapper for Magmastream.
+ */
+export declare class DiscordJSManager extends BaseManager {
+    readonly client: Client;
+    constructor(client: Client, options?: ManagerOptions);
+    protected send(packet: GatewayVoiceStateUpdate): void;
+    resolveUser(user: AnyUser | string): Promise<User | AnyUser>;
+    resolveGuild(guildId: string): Guild | null;
+}

package/dist/wrappers/discordeno.d.ts

@@ -0,0 +1,19 @@
+import { GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { Manager as BaseManager } from "../structures/Manager";
+import { Bot, User } from "@discordeno/bot";
+import { AnyGuild, AnyUser, ManagerOptions } from "../structures/Types";
+export * from "../index";
+/**
+ * Discordeno wrapper for Magmastream.
+ */
+export declare class DiscordenoManager extends BaseManager {
+    readonly client: Bot;
+    constructor(client: Bot, options?: ManagerOptions);
+    protected send(packet: GatewayVoiceStateUpdate): void;
+    /**
+     * Resolve a user by ID or partial info.
+     * Uses user-provided cache getter if available, otherwise falls back to minimal info.
+     */
+    resolveUser(user: AnyUser | string): Promise<User | AnyUser>;
+    resolveGuild(guildId: string): AnyGuild;
+}

package/dist/wrappers/eris.d.ts

@@ -0,0 +1,15 @@
+import { GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { Manager as BaseManager } from "../structures/Manager";
+import type { Client, Guild, User } from "eris";
+import { AnyUser, ManagerOptions } from "../structures/Types";
+export * from "../index";
+/**
+ * Eris wrapper for Magmastream.
+ */
+export declare class ErisManager extends BaseManager {
+    readonly client: Client;
+    constructor(client: Client, options?: ManagerOptions);
+    protected send(packet: GatewayVoiceStateUpdate): void;
+    resolveUser(user: AnyUser | string): Promise<User | AnyUser>;
+    resolveGuild(guildId: string): Guild;
+}

package/dist/wrappers/oceanic.d.ts

@@ -0,0 +1,15 @@
+import { GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { Manager as BaseManager } from "../structures/Manager";
+import { AnyUser, ManagerOptions } from "../structures/Types";
+import { Client, Guild, User } from "oceanic.js";
+export * from "../index";
+/**
+ * Oceanic wrapper for Magmastream.
+ */
+export declare class OceanicManager extends BaseManager {
+    readonly client: Client;
+    constructor(client: Client, options?: ManagerOptions);
+    protected send(packet: GatewayVoiceStateUpdate): void;
+    resolveUser(user: AnyUser | string): Promise<User | AnyUser>;
+    resolveGuild(guildId: string): Guild;
+}

package/dist/wrappers/seyfert.d.ts

@@ -0,0 +1,37 @@
+import { Manager as BaseManager } from "../structures/Manager";
+import { type GatewayVoiceStateUpdate } from "discord-api-types/v10";
+import { Client, Guild, User, WorkerClient } from "seyfert";
+import { AnyUser, ManagerOptions } from "../structures/Types";
+export * from "../index";
+/**
+ * Seyfert wrapper for Magmastream.
+ *
+ * @note This wrapper does require the manual implementation of the "raw" and "ready" events, to call the `updateVoiceState` and `init` methods respectively.
+ *
+ * @example
+ * ```typescript
+ * const client = new Client();
+ * const manager = new SeyfertManager(client, options);
+ *
+ * client.events.values.RAW = {
+ *     data: { name: "raw" },
+ *     run: async (data) => {
+ *         await manager.updateVoiceState(data);
+ *     }
+ * }
+ *
+ * client.events.values.READY = {
+ *     data: { name: "ready" },
+ *     run: async (user, client) => {
+ *         await manager.init({ clientId: client.botId });
+ *     }
+ * }
+ * ```
+ */
+export declare class SeyfertManager extends BaseManager {
+    readonly client: Client | WorkerClient;
+    constructor(client: Client | WorkerClient, options?: ManagerOptions);
+    protected send(packet: GatewayVoiceStateUpdate): void;
+    resolveUser(user: AnyUser | string): Promise<User | AnyUser>;
+    resolveGuild(guildId: string): Guild<"cached">;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "magmastream",
-    "version": "2.9.3-dev.25",
+    "version": "2.9.3-dev.27",
     "description": "A user-friendly Lavalink client designed for NodeJS.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -8,6 +8,7 @@
         "dist"
     ],
     "scripts": {
+        "prepare": "npm run build",
         "build": "tsc",
         "types": "rtb --dist dist",
         "format": "prettier --write .",