ryanlink 1.0.1

package/src/types/voice/VoiceManager.ts

@@ -0,0 +1,176 @@
+import type { NonNullableProp } from "../common";
+import type { CreateQueueOptions } from "../audio";
+
+/**
+ * Common info in Discord's 'dispatch' payload type
+ */
+export interface CommonDispatchPayloadInfo {
+    op: 0;
+    s: number;
+}
+
+/**
+ * Discord client ready payload (partial, essential only)
+ */
+export interface BotReadyPayload extends CommonDispatchPayloadInfo {
+    t: "READY";
+    d: {
+        user: {
+            id: string;
+        };
+    };
+}
+
+/**
+ * Discord voice state update payload
+ */
+export interface VoiceStateUpdatePayload extends CommonDispatchPayloadInfo {
+    t: "VOICE_STATE_UPDATE";
+    d: {
+        guild_id?: string;
+        channel_id: string | null;
+        user_id: string;
+        session_id: string;
+        deaf: boolean;
+        mute: boolean;
+        self_deaf: boolean;
+        self_mute: boolean;
+        suppress: boolean;
+    };
+}
+
+/**
+ * Discord voice server update payload
+ */
+export interface VoiceServerUpdatePayload extends CommonDispatchPayloadInfo {
+    t: "VOICE_SERVER_UPDATE";
+    d: {
+        token: string;
+        guild_id: string;
+        endpoint: string | null;
+    };
+}
+
+/**
+ * Discord dispatch payload
+ */
+export type DiscordDispatchPayload = BotReadyPayload | VoiceStateUpdatePayload | VoiceServerUpdatePayload;
+
+/**
+ * Internal ref representing client-side voice state
+ */
+export interface BotVoiceState
+    extends
+        Required<NonNullableProp<Omit<VoiceStateUpdatePayload["d"], "guild_id" | "user_id">, "channel_id">>,
+        NonNullableProp<Omit<VoiceServerUpdatePayload["d"], "guild_id">, "endpoint"> {
+    /**
+     * Whether the voice connection is established
+     */
+    connected: boolean;
+
+    /**
+     * The node session ID this voice state is connected to
+     */
+    node_session_id: string;
+
+    /**
+     * Whether the voice connection is reconnecting
+     */
+    reconnecting: boolean;
+
+    /**
+     * The voice region ID (extracted from endpoint)
+     */
+    region_id: string;
+}
+
+/**
+ * Options for customizing the player while connecting
+ */
+export interface ConnectOptions extends Pick<CreateQueueOptions, "context" | "filters" | "node" | "volume"> {}
+
+/**
+ * Discord voice close event codes
+ * https://discord.com/developers/docs/topics/opcodes-and-status-codes#voice-voice-close-event-codes
+ */
+export const enum VoiceCloseCodes {
+    /**
+     * You sent an invalid opcode.
+     */
+    UnknownOpcode = 4001,
+
+    /**
+     * You sent an invalid payload in your identifying to the Gateway.
+     */
+    FailedToDecodePayload,
+
+    /**
+     * You sent a payload before identifying with the Gateway.
+     */
+    NotAuthenticated,
+
+    /**
+     * The token you sent in your identify payload is incorrect.
+     */
+    AuthenticationFailed,
+
+    /**
+     * You sent more than one identify payload.
+     */
+    AlreadyAuthenticated,
+
+    /**
+     * Your session is no longer valid.
+     */
+    SessionNoLongerValid,
+
+    /**
+     * Your session has timed out.
+     */
+    SessionTimeout = 4009,
+
+    /**
+     * We can't find the server you're trying to connect to.
+     */
+    ServerNotFound = 4011,
+
+    /**
+     * We didn't recognize the protocol you sent.
+     */
+    UnknownProtocol,
+
+    /**
+     * Disconnect individual client (you were kicked, the main gateway session was dropped, etc.). Should not reconnect.
+     */
+    Disconnected = 4014,
+
+    /**
+     * The server crashed. Our bad! Try resuming.
+     */
+    VoiceServerCrashed,
+
+    /**
+     * We didn't recognize your encryption.
+     */
+    UnknownEncryptionMode,
+
+    /**
+     * This channel requires a client supporting E2EE via the DAVE Protocol
+     */
+    DAVEProtocolRequired,
+
+    /**
+     * You sent a malformed request.
+     */
+    BadRequest = 4020,
+
+    /**
+     * Disconnect due to rate limit exceeded. Should not reconnect.
+     */
+    DisconnectedRateLimited,
+
+    /**
+     * Disconnect all clients due to call terminated (channel deleted, voice server changed, etc.). Should not reconnect.
+     */
+    DisconnectedCallTerminated,
+}

package/src/types/voice/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Voice type definitions
+ */
+
+export * from "./VoiceManager";

package/src/utils/helpers.ts

@@ -0,0 +1,169 @@
+/**
+ * Utility functions for Ryanlink
+ */
+
+/**
+ * Do nothing, return nothing
+ * Useful for error handling and default callbacks
+ */
+export const noop = (): void => {};
+
+/**
+ * Format duration as a string
+ * @param ms Duration in milliseconds
+ * @returns Formatted string: `hh:mm:ss`, `mm:ss`, or `00:00` (default)
+ *
+ * @example
+ * formatDuration(0) // "00:00"
+ * formatDuration(90000) // "01:30"
+ * formatDuration(3661000) // "01:01:01"
+ */
+export const formatDuration = (ms: number): string => {
+    if (!Number.isSafeInteger(ms) || ms <= 0) {
+        return "00:00";
+    }
+
+    const s = Math.floor(ms / 1000);
+    const ss = `${s % 60}`.padStart(2, "0");
+    const mm = `${Math.floor(s / 60) % 60}`.padStart(2, "0");
+
+    if (s < 3600) {
+        return `${(s === 3600 ? "01:" : "") + mm}:${ss}`;
+    }
+
+    return `${`${Math.floor(s / 3600)}`.padStart(2, "0")}:${mm}:${ss}`;
+};
+
+/**
+ * Parse duration string to milliseconds
+ * @param duration Duration string (hh:mm:ss, mm:ss, or ss)
+ * @returns Duration in milliseconds
+ *
+ * @example
+ * parseDuration("01:30") // 90000
+ * parseDuration("1:01:01") // 3661000
+ */
+export const parseDuration = (duration: string): number => {
+    const parts = duration.split(":").map(Number);
+
+    if (parts.length === 1) {
+        return (parts[0] ?? 0) * 1000;
+    }
+
+    if (parts.length === 2) {
+        return ((parts[0] ?? 0) * 60 + (parts[1] ?? 0)) * 1000;
+    }
+
+    if (parts.length === 3) {
+        return ((parts[0] ?? 0) * 3600 + (parts[1] ?? 0) * 60 + (parts[2] ?? 0)) * 1000;
+    }
+
+    return 0;
+};
+
+/**
+ * Clamp a number between min and max
+ * @param value Value to clamp
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Clamped value
+ */
+export const clamp = (value: number, min: number, max: number): number => {
+    return Math.min(Math.max(value, min), max);
+};
+
+/**
+ * Sleep for a specified duration
+ * @param ms Duration in milliseconds
+ * @returns Promise that resolves after the duration
+ */
+export const sleep = (ms: number): Promise<void> => {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+/**
+ * Retry a function with exponential backoff
+ * @param fn Function to retry
+ * @param maxAttempts Maximum number of attempts
+ * @param baseDelay Base delay in milliseconds
+ * @returns Result of the function
+ */
+export const retry = async <T>(fn: () => Promise<T>, maxAttempts = 3, baseDelay = 1000): Promise<T> => {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        } catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+
+            if (attempt < maxAttempts - 1) {
+                const delay = baseDelay * Math.pow(2, attempt);
+                await sleep(delay);
+            }
+        }
+    }
+
+    throw lastError ?? new Error("Retry failed");
+};
+
+/**
+ * Shuffle an array in place using Fisher-Yates algorithm
+ * @param array Array to shuffle
+ * @returns The shuffled array
+ */
+export const shuffle = <T>(array: T[]): T[] => {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+};
+
+/**
+ * Get a random element from an array
+ * @param array Array to pick from
+ * @returns Random element or undefined if array is empty
+ */
+export const randomElement = <T>(array: T[]): T | undefined => {
+    if (array.length === 0) {
+        return undefined;
+    }
+    return array[Math.floor(Math.random() * array.length)];
+};
+
+/**
+ * Chunk an array into smaller arrays
+ * @param array Array to chunk
+ * @param size Size of each chunk
+ * @returns Array of chunks
+ */
+export const chunk = <T>(array: T[], size: number): T[][] => {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+};
+
+/**
+ * Remove duplicates from an array
+ * @param array Array to deduplicate
+ * @param key Optional key function for complex objects
+ * @returns Array without duplicates
+ */
+export const unique = <T>(array: T[], key?: (item: T) => unknown): T[] => {
+    if (!key) {
+        return [...new Set(array)];
+    }
+
+    const seen = new Set();
+    return array.filter((item) => {
+        const k = key(item);
+        if (seen.has(k)) {
+            return false;
+        }
+        seen.add(k);
+        return true;
+    });
+};

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility exports
+ */
+
+export * from "./helpers";
+export * from "./validators";

package/src/utils/validators.ts

@@ -0,0 +1,184 @@
+import { URL } from "node:url";
+import type { CreateNodeOptions, PlayerOptions } from "../types";
+
+/**
+ * Validation functions for Ryanlink
+ */
+
+/**
+ * Check if input is a finite number
+ * @param input Value to check
+ * @param check Optional check type: `integer`, `natural` (> 0), `whole` (>= 0)
+ * @returns `true` if the input passed, `false` otherwise
+ */
+export const isNumber = <T extends number>(
+    input: unknown,
+    check?: "integer" | "natural" | "whole" | "safe-int" | "positive",
+): input is T => {
+    if (check === undefined) {
+        return Number.isFinite(input);
+    }
+    if (check === "integer" || check === "safe-int") {
+        return Number.isSafeInteger(input);
+    }
+    if (check === "natural" || check === "positive") {
+        return Number.isSafeInteger(input) && (input as number) > 0;
+    }
+    if (check === "whole") {
+        return Number.isSafeInteger(input) && (input as number) >= 0;
+    }
+    return false;
+};
+
+/**
+ * Check if input is a string
+ * @param input Value to check
+ * @param check Optional check: {@linkcode RegExp}, `url` ({@linkcode URL.canParse}), `non-empty` (at least one non-whitespace character)
+ * @returns `true` if the input passed, `false` otherwise
+ */
+export const isString = <T extends string>(input: unknown, check?: "url" | "non-empty" | RegExp): input is T => {
+    if (typeof input !== "string") {
+        return false;
+    }
+    if (check === undefined) {
+        return true;
+    }
+    if (check === "url") {
+        return URL.canParse(input);
+    }
+    if (check === "non-empty") {
+        return input.trim().length > 0;
+    }
+    if (check instanceof RegExp) {
+        return check.test(input);
+    }
+    return false;
+};
+
+/**
+ * Check if input is a plain object
+ * @param input Value to check
+ * @param check Optional check: `non-empty` (at least one key)
+ * @returns `true` if the input passed, `false` otherwise
+ */
+export const isRecord = <T extends Record<string, unknown>>(input: unknown, check?: "non-empty"): input is T => {
+    if (!input || input.constructor !== Object) {
+        return false;
+    }
+    if (check === undefined) {
+        return true;
+    }
+    if (check === "non-empty") {
+        return Object.keys(input).length > 0;
+    }
+    return false;
+};
+
+/**
+ * Check if input is an array
+ * @param input Value to check
+ * @param check Optional check: `non-empty`, or a function (same as {@linkcode Array.prototype.every})
+ * @returns `true` if the input passed, `false` otherwise
+ */
+export const isArray = <T extends unknown[]>(
+    input: unknown,
+    check?: "non-empty" | Parameters<T["every"]>[0],
+): input is T => {
+    if (!Array.isArray(input)) {
+        return false;
+    }
+    if (check === undefined) {
+        return true;
+    }
+    if (check === "non-empty") {
+        return input.length !== 0;
+    }
+    if (typeof check === "function") {
+        return input.every(check);
+    }
+    return false;
+};
+
+/**
+ * Check if input is a boolean
+ * @param input Value to check
+ * @returns `true` if the input is a boolean, `false` otherwise
+ */
+export const isBoolean = (input: unknown): input is boolean => {
+    return typeof input === "boolean";
+};
+
+/**
+ * Check if input is a function
+ * @param input Value to check
+ * @returns `true` if the input is a function, `false` otherwise
+ */
+export const isFunction = (input: unknown): input is (...args: unknown[]) => unknown => {
+    return typeof input === "function";
+};
+
+/**
+ * Check if input is null or undefined
+ * @param input Value to check
+ * @returns `true` if the input is null or undefined, `false` otherwise
+ */
+export const isNullish = (input: unknown): input is null | undefined => {
+    return input === null || input === undefined;
+};
+
+/**
+ * Check if input is a valid snowflake (Discord ID)
+ * @param input Value to check
+ * @returns `true` if the input is a valid snowflake, `false` otherwise
+ */
+export const isSnowflake = (input: unknown): input is string => {
+    return isString(input) && /^\d{17,20}$/.test(input);
+};
+
+/**
+ * Check if input is a valid URL
+ * @param input Value to check
+ * @returns `true` if the input is a valid URL, `false` otherwise
+ */
+export const isUrl = (input: unknown): input is string => {
+    return isString(input, "url");
+};
+
+/**
+ * Type guard to check if error is an Error instance
+ * @param error Value to check
+ * @returns `true` if the value is an Error, `false` otherwise
+ */
+export const isError = (error: unknown): error is Error => {
+    return error instanceof Error;
+};
+
+/**
+ * Assert that a condition is true, throw error otherwise
+ */
+export function assert(condition: unknown, message: string): asserts condition {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+
+/**
+ * Validates node options
+ */
+export function validateNodeOptions(options: CreateNodeOptions): void {
+    assert(isString(options.name, "non-empty"), "Node name must be a non-empty string");
+    assert(isString(options.host, "non-empty"), "Node host must be a non-empty string");
+    assert(isNumber(options.port, "natural"), "Node port must be a positive number");
+    assert(isString(options.password, "non-empty"), "Node password must be a non-empty string");
+}
+
+/**
+ * Validates player options
+ */
+export function validatePlayerOptions(options: PlayerOptions): void {
+    assert(isArray(options.nodes, "non-empty"), "At least one node is required");
+    assert(isFunction(options.forwardVoiceUpdate), "forwardVoiceUpdate must be a function");
+    if (options.queryPrefix !== undefined) {
+        assert(isString(options.queryPrefix, "non-empty"), "queryPrefix must be a non-empty string");
+    }
+}