aqualink 2.19.0 → 2.20.0

package/build/handlers/autoplay.js

@@ -1,14 +1,29 @@
-const https = require('https')
+const https = require('node:https')
 
+// Default agent config (used only if shared agent not provided)
 const AGENT_CONFIG = {
   keepAlive: true,
-  maxSockets: 5,
-  maxFreeSockets: 2,
+  maxSockets: 64,
+  maxFreeSockets: 32,
   timeout: 8000,
   freeSocketTimeout: 4000
 }
 
-const agent = new https.Agent(AGENT_CONFIG)
+// Shared agent reference - can be set from Rest module
+let sharedAgent = null
+const getAgent = () => {
+  if (!sharedAgent) {
+    sharedAgent = new https.Agent(AGENT_CONFIG)
+  }
+  return sharedAgent
+}
+
+// Allow Rest module to inject its agent
+const setSharedAgent = (agent) => {
+  if (agent && typeof agent.request === 'function') {
+    sharedAgent = agent
+  }
+}
 
 const SC_LINK_RE = /<a\s+itemprop="url"\s+href="(\/[^"]+)"/g
 const MAX_REDIRECTS = 3
@@ -23,7 +38,7 @@ const fastFetch = (url, depth = 0) =>
 
     const req = https.get(
       url,
-      { agent, timeout: DEFAULT_TIMEOUT_MS },
+      { agent: getAgent(), timeout: DEFAULT_TIMEOUT_MS },
       (res) => {
         const { statusCode, headers } = res
 
@@ -132,5 +147,6 @@ const spAutoPlay = async (seed, player, requester, excludedIds = []) => {
 
 module.exports = {
   scAutoPlay,
-  spAutoPlay
+  spAutoPlay,
+  setSharedAgent
 }

package/build/handlers/fetchImage.js

@@ -1,4 +1,4 @@
-const https = require('https')
+const https = require('node:https')
 
 const sourceHandlers = {
   spotify: fetchSpotifyThumbnail,
@@ -80,9 +80,7 @@ async function fetchYouTubeThumbnail(identifier) {
     try {
       const exists = await checkImageExists(url)
       if (exists) return url
-    } catch (error) {
-      continue
-    }
+    } catch (_error) {}
   }
 
   return null

package/build/index.d.ts

@@ -29,6 +29,7 @@ declare module 'aqualink' {
     allowedDomains: string[]
     loadBalancer: LoadBalancerStrategy
     send: (payload: any) => void
+    autoRegionMigrate: boolean
 
     // Internal State Management
     _nodeStates: Map<
@@ -50,16 +51,81 @@ declare module 'aqualink' {
     get leastUsedNodes(): Node[]
 
     // Core Methods
+    /**
+     * Initializes the specific client id and connects to all nodes
+     * @param clientId Client ID
+     * @example
+     * ```ts
+     * await aqua.init(client.user.id);
+     * ```
+     */
     init(clientId: string): Promise<Aqua>
+
+    /**
+     * Creates a new node connection
+     * @param options Modified node options
+     */
     createNode(options: NodeOptions): Promise<Node>
+
+    /**
+     * Destroys a node by identifier
+     * @param identifier Node identifier (name or host)
+     */
     destroyNode(identifier: string): void
+
+    /**
+     * Updates the voice state of a player
+     * @param data Voice state update packet
+     */
     updateVoiceState(data: VoiceStateUpdate | VoiceServerUpdate): void
+
+    /**
+     * Fetches nodes in a specific region
+     * @param region Region name
+     */
     fetchRegion(region: string): Node[]
+
+    /**
+     * Creates a connection for a player
+     * @param options Connection options
+     */
     createConnection(options: ConnectionOptions): Player
+
+    /**
+     * Creates a player on a specific node
+     * @param node Node to create player on
+     * @param options Player options
+     */
     createPlayer(node: Node, options: PlayerOptions): Player
+
+    /**
+     * Destroys a player
+     * @param guildId Guild ID
+     */
     destroyPlayer(guildId: string): Promise<void>
+
+    /**
+     * Resolves a track or playlist
+     * @param options Resolution options
+     * @example
+     * ```ts
+     * const result = await aqua.resolve({ query: 'https://...', requester: user });
+     * ```
+     */
     resolve(options: ResolveOptions): Promise<ResolveResponse>
+
+    /**
+     * Gets an existing player
+     * @param guildId Guild ID
+     */
     get(guildId: string): Player
+
+    /**
+     * Searches for tracks
+     * @param query Search query
+     * @param requester Requester object
+     * @param source Search source (ytsearch, scsearch, etc)
+     */
     search(
       query: string,
       requester: any,
@@ -68,14 +134,32 @@ declare module 'aqualink' {
 
     // Save/Load Methods
     savePlayer(filePath?: string): Promise<void>
+    savePlayerSync(filePath?: string): void
     loadPlayers(filePath?: string): Promise<void>
 
     // Failover and Migration Methods
     handleNodeFailover(failedNode: Node): Promise<void>
 
+    /**
+     * Moves a player to a different node
+     * @param guildId Guild ID of the player
+     * @param targetNode Target node to move to
+     * @param reason Reason for migration (default: 'region')
+     */
+    movePlayerToNode(
+      guildId: string,
+      targetNode: Node,
+      reason?: string
+    ): Promise<Player>
+
     // Utility Methods
+    /**
+     * Destroys the Aqua instance and all players
+     */
     destroy(): Promise<void>
 
+    getTrace(limit?: number): TraceEntry[]
+
     // Internal Methods
     _invalidateCache(): void
     _getCachedNodeLoad(node: Node): number
@@ -122,6 +206,8 @@ declare module 'aqualink' {
     _bindEventHandlers(): void
     _startCleanupTimer(): void
     _onNodeReady(node: Node, data: { resumed: boolean }): void
+    _regionMatches(configuredRegion: string, extractedRegion: string): boolean
+    _findBestNodeForRegion(region: string): Node | null
 
     // Optional bypass checks
     bypassChecks?: { nodeFetchInfo?: boolean }
@@ -142,7 +228,7 @@ declare module 'aqualink' {
     auth: string
     ssl: boolean
     sessionId: string | null
-    regions: string[]
+    regions: DiscordVoiceRegion[]
     wsUrl: string
     rest: Rest
     resumeTimeout: number
@@ -168,7 +254,7 @@ declare module 'aqualink' {
     _isConnecting: boolean
     _debugEnabled: boolean
     _headers: Record<string, string>
-    _boundHandlers: Record<string, Function>
+    _boundHandlers: Record<string, ReturnType<typeof this._boundHandlers>>
 
     // Methods
     connect(): Promise<void>
@@ -244,29 +330,122 @@ declare module 'aqualink' {
     _boundPlayerUpdate: (packet: any) => void
     _boundEvent: (payload: any) => void
     _boundAquaPlayerMove: (oldChannel: string, newChannel: string) => void
+    _lastVoiceChannel: string | null
+    _lastTextChannel: string | null
 
     // Getters
     get previous(): Track | null
     get currenttrack(): Track | null
 
     // Core Methods
-    play(): Promise<Player>
+    /**
+     * Plays a track. If no track is provided, plays the next track in the queue.
+     * @param track The track to play
+     * @param options Options for playback
+     * @example
+     * ```ts
+     * // Play the next track in the queue
+     * await player.play();
+     *
+     * // Play a specific track
+     * await player.play(track);
+     * ```
+     */
+    play(
+      track?: Track | null,
+      options?: { paused?: boolean; startTime?: number; noReplace?: boolean }
+    ): Promise<Player>
+
+    /**
+     * Connects the player to a voice channel
+     * @param options Connection options
+     * @example
+     * ```ts
+     * player.connect({
+     *   guildId: '...',
+     *   voiceChannel: '...',
+     *   deaf: true
+     * });
+     * ```
+     */
     connect(options?: ConnectionOptions): Player
+
+    /**
+     * Destroys the player and optionally cleans up resources
+     * @param options Destruction options
+     */
     destroy(options?: {
       preserveClient?: boolean
       skipRemote?: boolean
+      preserveMessage?: boolean
+      preserveReconnecting?: boolean
+      preserveTracks?: boolean
     }): Player
+
+    /**
+     * Pauses or resumes the player
+     * @param paused Whether to pause
+     */
     pause(paused: boolean): Player
+
+    /**
+     * Seeks to a position in the current track
+     * @param position Position in milliseconds
+     */
     seek(position: number): Player
+
+    /**
+     * Stops the playback
+     */
     stop(): Player
+
+    /**
+     * Sets the player volume
+     * @param volume Volume (0-1000)
+     */
     setVolume(volume: number): Player
+
+    /**
+     * Sets the loop mode
+     * @param mode Loop mode (off, track, queue)
+     */
     setLoop(mode: LoopMode | LoopModeName): Player
+
+    /**
+     * Sets the text channel for the player
+     * @param channel Channel ID
+     */
     setTextChannel(channel: string): Player
+
+    /**
+     * Sets the voice channel and moves the player
+     * @param channel Channel ID
+     */
     setVoiceChannel(channel: string): Player
+
+    /**
+     * Disconnects the player from voice
+     */
     disconnect(): Player
+
+    /**
+     * Shuffles the queue
+     */
     shuffle(): Player
+
+    /**
+     * Gets the player queue
+     */
     getQueue(): Queue
+
+    /**
+     * Replays the current track from the beginning
+     */
     replay(): Player
+
+    /**
+     * Skips the current track
+     */
     skip(): Player
 
     // Advanced Methods
@@ -355,9 +534,24 @@ declare module 'aqualink' {
     get thumbnail(): string
 
     // Methods
+    /**
+     * Resolves local artwork/thumbnail
+     */
     resolveThumbnail(url?: string): string | null
+
+    /**
+     * Resolves the track if it needs (re)resolution
+     */
     resolve(aqua: Aqua, opts?: TrackResolutionOptions): Promise<Track | null>
+
+    /**
+     * Checks if the track is valid
+     */
     isValid(): boolean
+
+    /**
+     * Disposes the track and frees resources
+     */
     dispose(): void
 
     // Internal Methods
@@ -380,13 +574,54 @@ declare module 'aqualink' {
     useHttp2: boolean
 
     // Core Methods
+    /**
+     * Sets the session ID for the REST connection
+     * @param sessionId The session ID
+     */
     setSessionId(sessionId: string): void
+
+    /**
+     * Makes a generic request to the Lavalink REST API
+     * @param method HTTP method
+     * @param endpoint API endpoint
+     * @param body Request body
+     */
     makeRequest(method: HttpMethod, endpoint: string, body?: any): Promise<any>
+
+    /**
+     * Updates a player via REST
+     * @param options Update options
+     */
     updatePlayer(options: UpdatePlayerOptions): Promise<any>
+
+    /**
+     * Destroys a player via REST
+     * @param guildId Guild ID
+     */
     destroyPlayer(guildId: string): Promise<any>
+
+    /**
+     * Gets lyrics for a track
+     * @param options Lyrics options
+     */
     getLyrics(options: GetLyricsOptions): Promise<LyricsResponse>
+
+    /**
+     * Subscribes to live lyrics events
+     * @param guildId Guild ID
+     * @param sync Whether to sync with playback
+     */
     subscribeLiveLyrics(guildId: string, sync?: boolean): Promise<any>
+
+    /**
+     * Unsubscribes from live lyrics
+     * @param guildId Guild ID
+     */
     unsubscribeLiveLyrics(guildId: string): Promise<any>
+
+    /**
+     * Gets node statistics
+     */
     getStats(): Promise<NodeStats>
 
     // Additional REST Methods
@@ -421,14 +656,33 @@ declare module 'aqualink' {
     readonly last: Track | null
 
     // Methods
+    /**
+     * Adds a track to the queue
+     * @param track Track to add
+     */
     add(track: Track): Queue
+
+    /**
+     * Adds multiple tracks to the queue
+     * @param tracks Tracks to add
+     */
     add(...tracks: Track[]): Queue
+
     push(track: Track): number
     unshift(track: Track): number
     shift(): Track | undefined
     remove(track: Track): boolean
+
+    /**
+     * Clears the queue
+     */
     clear(): void
+
+    /**
+     * Shuffles the queue
+     */
     shuffle(): Queue
+
     peek(): Track | null
     isEmpty(): boolean
     toArray(): Track[]
@@ -509,6 +763,10 @@ declare module 'aqualink' {
     _updateTimer: NodeJS.Timeout | null
     _hasDebugListeners: boolean
     _hasMoveListeners: boolean
+    _lastSentVoiceKey: string
+    _lastVoiceDataUpdate: number
+    _stateFlags: number
+    _regionMigrationAttempted: boolean
 
     // Methods
     setServerUpdate(data: VoiceServerUpdate['d']): void
@@ -525,6 +783,7 @@ declare module 'aqualink' {
     _sendUpdate(payload: any): Promise<void>
     _handleDisconnect(): void
     _clearPendingUpdate(): void
+    _checkRegionMigration(): void
   }
 
   export class Plugin {
@@ -576,6 +835,9 @@ declare module 'aqualink' {
     loadBalancer?: LoadBalancerStrategy
     failoverOptions?: FailoverOptions
     useHttp2?: boolean
+    autoRegionMigrate?: boolean
+    debugTrace?: boolean
+    traceMaxEntries?: number
   }
 
   export interface FailoverOptions {
@@ -595,7 +857,7 @@ declare module 'aqualink' {
     auth?: string
     ssl?: boolean
     sessionId?: string
-    regions?: string[]
+    regions?: DiscordVoiceRegion[]
   }
 
   export interface NodeAdditionalOptions {
@@ -626,7 +888,7 @@ declare module 'aqualink' {
     deaf?: boolean
     mute?: boolean
     defaultVolume?: number
-    region?: string
+    region?: DiscordVoiceRegion
   }
 
   export interface ResolveOptions {
@@ -923,6 +1185,122 @@ declare module 'aqualink' {
     toFront?: boolean
   }
 
+  /**
+   * A map of Discord voice region codes to their string values.
+   * Each entry shows the country and airport name in IntelliSense.
+   *
+   * Use `VoiceRegion.bom`, `VoiceRegion.gru`, etc. for full autocomplete descriptions,
+   * or pass raw strings like `'bom'` directly — both are accepted by `NodeOptions.regions`.
+   *
+   * @example
+   * ```ts
+   * // With descriptions in IntelliSense
+   * { host: '...', regions: [VoiceRegion.gru, VoiceRegion.eze] }
+   *
+   * // Raw strings also work
+   * { host: '...', regions: ['gru', 'eze'] }
+   * ```
+   */
+  export const VoiceRegion: {
+    // ─── Asia Pacific ─────────────────────────────────────────────────────────
+
+    /** 🇮🇳 Mumbai Chhatrapati Shivaji Maharaj International */
+    readonly India: 'bom'
+    /** 🇸🇬 Changi Airport */
+    readonly Singapore: 'sin'
+    /** 🇯🇵 Tokyo Narita International */
+    readonly Japan: 'nrt'
+    /** 🇰🇷 Seoul Incheon International */
+    readonly SouthKorea: 'icn'
+    /** 🇭🇰 Hong Kong International */
+    readonly HongKong: 'hkg'
+    /** 🇦🇺 Sydney Kingsford Smith */
+    readonly Australia: 'syd'
+    /** 🇮🇩 Jakarta Soekarno-Hatta International */
+    readonly Indonesia: 'cgk'
+
+    // ─── Europe ───────────────────────────────────────────────────────────────
+
+    /** 🇩🇪 Frankfurt Airport */
+    readonly Germany: 'fra'
+    /** 🇳🇱 Amsterdam Schiphol */
+    readonly Netherlands: 'ams'
+    /** 🇬🇧 London Heathrow */
+    readonly UnitedKingdom: 'lhr'
+    /** 🇫🇷 Paris Charles de Gaulle */
+    readonly France: 'cdg'
+    /** 🇪🇸 Madrid Barajas */
+    readonly Spain: 'mad'
+    /** 🇮🇹 Milan Malpensa */
+    readonly Italy: 'mxp'
+    /** 🇸🇪 Stockholm Arlanda */
+    readonly Sweden: 'arn'
+    /** 🇫🇮 Helsinki Vantaa */
+    readonly Finland: 'hel'
+    /** 🇵🇱 Warsaw Chopin */
+    readonly Poland: 'waw'
+    /** 🇷🇴 Bucharest Henri Coanda */
+    readonly Romania: 'buh'
+    /** 🇷🇺 St. Petersburg Pulkovo */
+    readonly RussiaSTP: 'led'
+    /** 🇷🇺 Moscow Sheremetyevo */
+    readonly RussiaMoscow: 'svo'
+
+    // ─── Middle East & Africa ─────────────────────────────────────────────────
+
+    /** 🇮🇱 Tel Aviv Ben Gurion */
+    readonly Israel: 'tlv'
+    /** 🇦🇪 Dubai International */
+    readonly UAE: 'dxb'
+    /** 🇸🇦 Dammam King Fahd International */
+    readonly SaudiArabia: 'dmm'
+    /** 🇿🇦 Johannesburg O.R. Tambo International */
+    readonly SouthAfrica: 'jnb'
+
+    // ─── North America ────────────────────────────────────────────────────────
+
+    /** 🇺🇸 Newark / New York */
+    readonly USANewark: 'ewr'
+    /** 🇺🇸 Washington D.C. Dulles */
+    readonly USAWashington: 'iad'
+    /** 🇺🇸 Atlanta Hartsfield-Jackson */
+    readonly USAAtlanta: 'atl'
+    /** 🇺🇸 Miami International */
+    readonly USAMiami: 'mia'
+    /** 🇺🇸 Chicago O'Hare */
+    readonly USAChicago: 'ord'
+    /** 🇺🇸 Dallas/Fort Worth */
+    readonly USADallas: 'dfw'
+    /** 🇺🇸 Seattle-Tacoma / Oregon */
+    readonly USASeattle: 'sea'
+    /** 🇺🇸 Los Angeles International */
+    readonly USALosAngeles: 'lax'
+    /** 🇨🇦 Toronto Pearson International */
+    readonly CanadaToronto: 'yyz'
+    /** 🇨🇦 Montreal Pierre Elliott Trudeau */
+    readonly CanadaMontreal: 'ymq'
+
+    // ─── South America ────────────────────────────────────────────────────────
+
+    /** 🇧🇷 Sao Paulo Guarulhos International */
+    readonly Brazil: 'gru'
+    /** 🇨🇱 Santiago Arturo Merino Benitez */
+    readonly Chile: 'scl'
+    /** 🇦🇷 Buenos Aires Ministro Pistarini */
+    readonly Argentina: 'eze'
+  }
+
+  /**
+   * Discord voice server region prefix (derived from IATA airport codes).
+   * Used in `NodeOptions.regions` to match players to the best Lavalink node
+   * based on Discord's voice endpoint (e.g. `c-bom06-xxxx.discord.media` -> `'bom'`).
+   *
+   * For descriptions on each value, use the `VoiceRegion` object in your IDE.
+   */
+  export type DiscordVoiceRegion =
+    | (typeof VoiceRegion)[keyof typeof VoiceRegion]
+    | (string & {})
+
   // Type Unions and Enums
   export type SearchSource =
     | 'ytsearch'

package/build/index.js

@@ -9,6 +9,53 @@ const Rest = require('./structures/Rest')
 const Track = require('./structures/Track')
 const { AqualinkEvents } = require('./structures/AqualinkEvents')
 
+const VoiceRegion = Object.freeze({
+  // ─── Asia Pacific ─────────────────────────────────────────────────────────
+  India: 'bom',
+  Singapore: 'sin',
+  Japan: 'nrt',
+  SouthKorea: 'icn',
+  HongKong: 'hkg',
+  Australia: 'syd',
+  Indonesia: 'cgk',
+
+  // ─── Europe ───────────────────────────────────────────────────────────────
+  Germany: 'fra',
+  Netherlands: 'ams',
+  UnitedKingdom: 'lhr',
+  France: 'cdg',
+  Spain: 'mad',
+  Italy: 'mxp',
+  Sweden: 'arn',
+  Finland: 'hel',
+  Poland: 'waw',
+  Romania: 'buh',
+  RussiaSTP: 'led',
+  RussiaMoscow: 'svo',
+
+  // ─── Middle East & Africa ─────────────────────────────────────────────────
+  Israel: 'tlv',
+  UAE: 'dxb',
+  SaudiArabia: 'dmm',
+  SouthAfrica: 'jnb',
+
+  // ─── North America ────────────────────────────────────────────────────────
+  USANewark: 'ewr',
+  USAWashington: 'iad',
+  USAAtlanta: 'atl',
+  USAMiami: 'mia',
+  USAChicago: 'ord',
+  USADallas: 'dfw',
+  USASeattle: 'sea',
+  USALosAngeles: 'lax',
+  CanadaToronto: 'yyz',
+  CanadaMontreal: 'ymq',
+
+  Brazil: 'gru' || 'brazil', // i only know this endpoint lol.
+  Chile: 'scl' || 'chile',
+  Argentina: 'eze' || 'argentina'
+})
+
 module.exports = {
   Connection,
   Filters,
@@ -19,5 +66,6 @@ module.exports = {
   Queue,
   Rest,
   Track,
+  VoiceRegion,
   AqualinkEvents
 }