aqualink 2.19.1 → 2.20.0

package/build/handlers/autoplay.js

@@ -1,4 +1,4 @@
-const https = require('https')
+const https = require('node:https')
 
 // Default agent config (used only if shared agent not provided)
 const AGENT_CONFIG = {
@@ -11,7 +11,12 @@ const AGENT_CONFIG = {
 
 // Shared agent reference - can be set from Rest module
 let sharedAgent = null
-const getAgent = () => sharedAgent || (sharedAgent = new https.Agent(AGENT_CONFIG))
+const getAgent = () => {
+  if (!sharedAgent) {
+    sharedAgent = new https.Agent(AGENT_CONFIG)
+  }
+  return sharedAgent
+}
 
 // Allow Rest module to inject its agent
 const setSharedAgent = (agent) => {
@@ -20,7 +25,6 @@ const setSharedAgent = (agent) => {
   }
 }
 
-
 const SC_LINK_RE = /<a\s+itemprop="url"\s+href="(\/[^"]+)"/g
 const MAX_REDIRECTS = 3
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024 // 5 MB

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<
@@ -139,12 +140,26 @@ declare module 'aqualink' {
     // 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
@@ -191,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 }
@@ -211,7 +228,7 @@ declare module 'aqualink' {
     auth: string
     ssl: boolean
     sessionId: string | null
-    regions: string[]
+    regions: DiscordVoiceRegion[]
     wsUrl: string
     rest: Rest
     resumeTimeout: number
@@ -334,7 +351,10 @@ declare module 'aqualink' {
      * await player.play(track);
      * ```
      */
-    play(track?: Track | null, options?: { paused?: boolean; startTime?: number; noReplace?: boolean }): Promise<Player>
+    play(
+      track?: Track | null,
+      options?: { paused?: boolean; startTime?: number; noReplace?: boolean }
+    ): Promise<Player>
 
     /**
      * Connects the player to a voice channel
@@ -746,6 +766,7 @@ declare module 'aqualink' {
     _lastSentVoiceKey: string
     _lastVoiceDataUpdate: number
     _stateFlags: number
+    _regionMigrationAttempted: boolean
 
     // Methods
     setServerUpdate(data: VoiceServerUpdate['d']): void
@@ -762,6 +783,7 @@ declare module 'aqualink' {
     _sendUpdate(payload: any): Promise<void>
     _handleDisconnect(): void
     _clearPendingUpdate(): void
+    _checkRegionMigration(): void
   }
 
   export class Plugin {
@@ -813,6 +835,9 @@ declare module 'aqualink' {
     loadBalancer?: LoadBalancerStrategy
     failoverOptions?: FailoverOptions
     useHttp2?: boolean
+    autoRegionMigrate?: boolean
+    debugTrace?: boolean
+    traceMaxEntries?: number
   }
 
   export interface FailoverOptions {
@@ -832,7 +857,7 @@ declare module 'aqualink' {
     auth?: string
     ssl?: boolean
     sessionId?: string
-    regions?: string[]
+    regions?: DiscordVoiceRegion[]
   }
 
   export interface NodeAdditionalOptions {
@@ -863,7 +888,7 @@ declare module 'aqualink' {
     deaf?: boolean
     mute?: boolean
     defaultVolume?: number
-    region?: string
+    region?: DiscordVoiceRegion
   }
 
   export interface ResolveOptions {
@@ -1160,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
 }