yukimu 1.0.0

package/src/Resolver.ts

@@ -0,0 +1,127 @@
+import { SearchResult, SearchSource, SourcePrefixes, SpotifyOptions } from "./types";
+import type { Yukimu } from "./Yukimu";
+
+// ─── URL Patterns ─────────────────────────────────────────────────────────────
+
+const URL_PATTERNS: Record<string, RegExp[]> = {
+  youtube: [
+    /^https?:\/\/(www\.)?(youtube\.com|youtu\.be)\/.+/,
+    /^https?:\/\/music\.youtube\.com\/.+/,
+  ],
+  spotify: [
+    /^https?:\/\/open\.spotify\.com\/(track|album|playlist|artist)\/.+/,
+  ],
+  soundcloud: [
+    /^https?:\/\/(www\.)?soundcloud\.com\/.+/,
+  ],
+  deezer: [
+    /^https?:\/\/(www\.)?deezer\.com\/(track|album|playlist)\/.+/,
+  ],
+  applemusic: [
+    /^https?:\/\/music\.apple\.com\/.+/,
+  ],
+  tidal: [
+    /^https?:\/\/(www\.)?tidal\.com\/(browse\/)?(track|album|playlist)\/.+/,
+  ],
+  jiosaavn: [
+    /^https?:\/\/(www\.)?jiosaavn\.com\/.+/,
+  ],
+  yandexmusic: [
+    /^https?:\/\/music\.yandex\.(ru|com)\/.+/,
+  ],
+};
+
+export class Resolver {
+  private manager: Yukimu;
+  private spotifyToken: string | null = null;
+  private spotifyExpiry: number = 0;
+
+  constructor(manager: Yukimu) {
+    this.manager = manager;
+  }
+
+  /**
+   * Resolve a query or URL to Lavalink tracks
+   */
+  public async resolve(query: string, source: SearchSource): Promise<SearchResult> {
+    const node = this.manager.getBestNode();
+
+    // Check if query is a direct URL
+    const detectedSource = this.detectSource(query);
+
+    if (detectedSource) {
+      // It's a URL — pass directly to Lavalink (LavaSrc handles platform resolution)
+      return node.loadTracks(query);
+    }
+
+    // It's a search query — use source prefix
+    const prefix = SourcePrefixes[source];
+    return node.loadTracks(`${prefix}:${query}`);
+  }
+
+  /**
+   * Detect what platform a URL belongs to
+   */
+  public detectSource(url: string): SearchSource | null {
+    for (const [source, patterns] of Object.entries(URL_PATTERNS)) {
+      if (patterns.some(p => p.test(url))) {
+        return source as SearchSource;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get Spotify API token (for resolving Spotify metadata without LavaSrc)
+   * Only needed if you're NOT using the LavaSrc Lavalink plugin
+   */
+  public async getSpotifyToken(): Promise<string | null> {
+    const opts = this.manager.options.spotify;
+    if (!opts) return null;
+    if (this.spotifyToken && Date.now() < this.spotifyExpiry) return this.spotifyToken;
+
+    try {
+      const res = await fetch("https://accounts.spotify.com/api/token", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Authorization: `Basic ${Buffer.from(`${opts.clientId}:${opts.clientSecret}`).toString("base64")}`,
+        },
+        body: "grant_type=client_credentials",
+      });
+
+      const data = await res.json() as { access_token: string; expires_in: number };
+      this.spotifyToken = data.access_token;
+      this.spotifyExpiry = Date.now() + data.expires_in * 1000 - 5000;
+      return this.spotifyToken;
+    } catch (err) {
+      console.error("[Yukimu] Failed to fetch Spotify token:", err);
+      return null;
+    }
+  }
+
+  /**
+   * Resolve a Spotify URL to track metadata (title + artist for YouTube fallback search)
+   * Used when LavaSrc plugin is NOT installed
+   */
+  public async resolveSpotifyFallback(url: string): Promise<{ title: string; artist: string } | null> {
+    const token = await this.getSpotifyToken();
+    if (!token) return null;
+
+    const match = url.match(/spotify\.com\/track\/([a-zA-Z0-9]+)/);
+    if (!match) return null;
+
+    try {
+      const res = await fetch(`https://api.spotify.com/v1/tracks/${match[1]}`, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      const data = await res.json() as { name: string; artists: { name: string }[] };
+      return {
+        title: data.name,
+        artist: data.artists[0]?.name ?? "Unknown",
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/Yukimu.ts

@@ -0,0 +1,177 @@
+import { EventEmitter } from "events";
+import { Node } from "./Node";
+import { Player } from "./Player";
+import { Resolver } from "./Resolver";
+import {
+  YukimuOptions,
+  PlayerOptions,
+  YukimuEvents,
+  SearchSource,
+  SearchResult,
+} from "./types";
+
+/**
+ * Yukimu - A powerful Lavalink v4 wrapper for Discord bots
+ * Supports: YouTube, YouTube Music, Spotify, Deezer, Apple Music,
+ *           JioSaavn, Tidal, SoundCloud, Yandex Music
+ */
+export class Yukimu extends EventEmitter {
+  public readonly options: YukimuOptions;
+  public readonly nodes: Map<string, Node> = new Map();
+  public readonly players: Map<string, Player> = new Map();
+  public readonly resolver: Resolver;
+
+  /** Send function — you must set this to send voice payloads to Discord */
+  public sendPayload!: (guildId: string, payload: unknown) => void;
+
+  constructor(options: YukimuOptions) {
+    super();
+    this.options = options;
+    this.resolver = new Resolver(this);
+
+    // Initialize all nodes
+    for (const nodeOpts of options.nodes) {
+      this.addNode(nodeOpts);
+    }
+  }
+
+  // ─── Node Management ────────────────────────────────────────────
+
+  /** Add a new Lavalink node */
+  public addNode(options: import("./types").NodeOptions): Node {
+    const node = new Node(this, options);
+    this.nodes.set(options.name, node);
+    node.connect();
+    return node;
+  }
+
+  /** Remove a node by name */
+  public removeNode(name: string): void {
+    const node = this.nodes.get(name);
+    if (!node) throw new Error(`Node "${name}" not found`);
+    node.destroy();
+    this.nodes.delete(name);
+  }
+
+  /** Get the best available node (least load) */
+  public getBestNode(): Node {
+    const connected = [...this.nodes.values()].filter(n => n.connected);
+    if (!connected.length) throw new Error("No connected Lavalink nodes available");
+
+    return connected.sort((a, b) => {
+      const aLoad = a.stats?.cpu?.lavalinkLoad ?? 0;
+      const bLoad = b.stats?.cpu?.lavalinkLoad ?? 0;
+      return aLoad - bLoad;
+    })[0];
+  }
+
+  // ─── Player Management ───────────────────────────────────────────
+
+  /** Create a new player for a guild */
+  public createPlayer(options: PlayerOptions): Player {
+    const existing = this.players.get(options.guildId);
+    if (existing) return existing;
+
+    const node = options.nodeName
+      ? this.nodes.get(options.nodeName) ?? this.getBestNode()
+      : this.getBestNode();
+
+    const player = new Player(this, node, options);
+    this.players.set(options.guildId, player);
+    this.emit("playerCreate", player);
+    return player;
+  }
+
+  /** Get an existing player */
+  public getPlayer(guildId: string): Player | undefined {
+    return this.players.get(guildId);
+  }
+
+  /** Destroy a player */
+  public destroyPlayer(guildId: string): void {
+    const player = this.players.get(guildId);
+    if (!player) return;
+    player.destroy();
+    this.players.delete(guildId);
+    this.emit("playerDestroy", player);
+  }
+
+  // ─── Search ──────────────────────────────────────────────────────
+
+  /**
+   * Search for tracks across any supported source
+   * @param query - Search query or direct URL
+   * @param source - Where to search (youtube, spotify, deezer, etc.)
+   */
+  public async search(
+    query: string,
+    source: SearchSource = this.options.defaultSource ?? "youtube"
+  ): Promise<SearchResult> {
+    return this.resolver.resolve(query, source);
+  }
+
+  // ─── Discord Voice Gateway Handlers ──────────────────────────────
+
+  /**
+   * Handle Discord voice state updates — call this in your bot's
+   * voiceStateUpdate event handler
+   */
+  public handleVoiceStateUpdate(data: {
+    guild_id?: string;
+    user_id: string;
+    session_id: string;
+    channel_id?: string | null;
+  }): void {
+    if (data.user_id !== this.options.clientId) return;
+    if (!data.guild_id) return;
+
+    const player = this.players.get(data.guild_id);
+    if (!player) return;
+
+    if (!data.channel_id) {
+      // Bot was disconnected from voice
+      player.voiceChannelId = null;
+      player.connected = false;
+      return;
+    }
+
+    player.voiceChannelId = data.channel_id;
+    player.sessionId = data.session_id;
+    player.connected = true;
+    player.checkVoiceReady();
+  }
+
+  /**
+   * Handle Discord voice server updates — call this in your bot's
+   * voiceServerUpdate event handler
+   */
+  public handleVoiceServerUpdate(data: {
+    guild_id: string;
+    token: string;
+    endpoint?: string | null;
+  }): void {
+    const player = this.players.get(data.guild_id);
+    if (!player) return;
+    if (!data.endpoint) return;
+
+    player.voiceToken = data.token;
+    player.voiceEndpoint = data.endpoint;
+    player.checkVoiceReady();
+  }
+
+  // ─── EventEmitter typing ─────────────────────────────────────────
+
+  public on<K extends keyof YukimuEvents>(
+    event: K,
+    listener: (...args: YukimuEvents[K]) => void
+  ): this {
+    return super.on(event, listener as (...args: unknown[]) => void);
+  }
+
+  public emit<K extends keyof YukimuEvents>(
+    event: K,
+    ...args: YukimuEvents[K]
+  ): boolean {
+    return super.emit(event, ...args);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { Yukimu } from "./Yukimu";
+export { Node } from "./Node";
+export { Player } from "./Player";
+export { Queue } from "./Queue";
+export { Resolver } from "./Resolver";
+export * from "./types";

package/src/types.ts

@@ -0,0 +1,178 @@
+export interface YukimuOptions {
+  /** Your Discord bot token */
+  token: string;
+  /** Client ID of your bot */
+  clientId: string;
+  /** Lavalink nodes to connect to */
+  nodes: NodeOptions[];
+  /** Default search source */
+  defaultSource?: SearchSource;
+  /** Spotify credentials (for Spotify support) */
+  spotify?: SpotifyOptions;
+  /** Deezer options */
+  deezer?: DeezerOptions;
+  /** Apple Music options */
+  appleMusic?: AppleMusicOptions;
+}
+
+export interface NodeOptions {
+  /** Node identifier */
+  name: string;
+  /** Lavalink server host */
+  host: string;
+  /** Lavalink server port */
+  port: number;
+  /** Lavalink server password */
+  password: string;
+  /** Use SSL/TLS */
+  secure?: boolean;
+  /** Number of retries on disconnect */
+  retries?: number;
+  /** Lavalink version — 3 or 4 (default: 4) */
+  version?: 3 | 4;
+}
+
+export interface SpotifyOptions {
+  clientId: string;
+  clientSecret: string;
+}
+
+export interface DeezerOptions {
+  /** Deezer master decryption key (from LavaSrc plugin) */
+  masterKey?: string;
+}
+
+export interface AppleMusicOptions {
+  /** Apple Music media API token */
+  mediaAPIToken?: string;
+  countryCode?: string;
+}
+
+export type SearchSource =
+  | "youtube"
+  | "youtubemusic"
+  | "spotify"
+  | "deezer"
+  | "applemusic"
+  | "soundcloud"
+  | "tidal"
+  | "jiosaavn"
+  | "yandexmusic";
+
+export const SourcePrefixes: Record<SearchSource, string> = {
+  youtube: "ytsearch",
+  youtubemusic: "ytmsearch",
+  spotify: "spsearch",
+  deezer: "dzsearch",
+  applemusic: "amsearch",
+  soundcloud: "scsearch",
+  tidal: "tdsearch",
+  jiosaavn: "jssearch",
+  yandexmusic: "ymsearch",
+};
+
+export interface Track {
+  encoded: string;
+  info: TrackInfo;
+  pluginInfo?: Record<string, unknown>;
+}
+
+export interface TrackInfo {
+  identifier: string;
+  isSeekable: boolean;
+  author: string;
+  length: number;
+  isStream: boolean;
+  position: number;
+  title: string;
+  uri?: string;
+  artworkUrl?: string;
+  isrc?: string;
+  sourceName: string;
+}
+
+export interface SearchResult {
+  loadType: LoadType;
+  tracks: Track[];
+  playlistInfo?: PlaylistInfo;
+  exception?: LavalinkException;
+}
+
+export type LoadType =
+  | "track"
+  | "playlist"
+  | "search"
+  | "empty"
+  | "error";
+
+export interface PlaylistInfo {
+  name: string;
+  selectedTrack: number;
+}
+
+export interface LavalinkException {
+  message?: string;
+  severity: "common" | "suspicious" | "fault";
+  cause: string;
+}
+
+export interface PlayerOptions {
+  /** Guild ID to create player for */
+  guildId: string;
+  /** Voice channel ID */
+  voiceChannelId: string;
+  /** Text channel ID (for sending messages) */
+  textChannelId?: string;
+  /** Whether to self-deaf */
+  selfDeaf?: boolean;
+  /** Whether to self-mute */
+  selfMute?: boolean;
+  /** Node name to use (optional, auto-selected if not set) */
+  nodeName?: string;
+  /** Default volume 0-100 */
+  volume?: number;
+}
+
+export interface VoiceState {
+  token: string;
+  endpoint: string;
+  sessionId: string;
+}
+
+export interface NodeStats {
+  players: number;
+  playingPlayers: number;
+  uptime: number;
+  memory: {
+    free: number;
+    used: number;
+    allocated: number;
+    reservable: number;
+  };
+  cpu: {
+    cores: number;
+    systemLoad: number;
+    lavalinkLoad: number;
+  };
+  frameStats?: {
+    sent: number;
+    nulled: number;
+    deficit: number;
+  };
+}
+
+export type YukimuEvents = {
+  nodeConnect: [node: import("./Node").Node];
+  nodeDisconnect: [node: import("./Node").Node, code: number, reason: string];
+  nodeError: [node: import("./Node").Node, error: Error];
+  nodeReady: [node: import("./Node").Node];
+  trackStart: [player: import("./Player").Player, track: Track];
+  trackEnd: [player: import("./Player").Player, track: Track, reason: string];
+  trackError: [player: import("./Player").Player, track: Track, exception: LavalinkException];
+  trackStuck: [player: import("./Player").Player, track: Track, threshold: number];
+  playerCreate: [player: import("./Player").Player];
+  playerDestroy: [player: import("./Player").Player];
+  playerUpdate: [player: import("./Player").Player];
+  queueEnd: [player: import("./Player").Player];
+  socketClosed: [player: import("./Player").Player, code: number, reason: string];
+};

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "example"]
+}