ryanlink 1.0.1

package/src/types/core/Player.ts

@@ -0,0 +1,322 @@
+import type { CommonUserData, JsonObject, QueueContext, RequiredProp } from "../common";
+import type { Exception, PlayerState, TrackEndReason } from "../api/Websocket";
+import type { CreateNodeOptions, NodeEventMap } from "../lavalink";
+import type { CreateQueueOptions } from "../audio";
+import type { DefaultPlayerOptions } from "../../config";
+import type { Node } from "../../lavalink/LavalinkConnection";
+import type { VoiceState } from "../../voice/VoiceSession";
+import type { Playlist, Queue } from "../../audio";
+import type { Track } from "../../audio/AudioTrack";
+import type { Player } from "../../core/RyanlinkPlayer";
+import type { LyricsResult } from "../../extensions/LyricsExtension";
+import type { PlayerPlugin } from "../../core/PluginSystem";
+
+/**
+ * Helper type to exclude last element from tuple
+ */
+type ExcludeLast<T extends unknown[]> = T extends [...infer Items, unknown] ? Items : never;
+
+/**
+ * Player event map
+ */
+export interface PlayerEventMap {
+    /**
+     * Emitted when player is initialized
+     */
+    init: [];
+
+    /**
+     * Emitted when a node connects
+     */
+    nodeConnect: [node: Node, ...ExcludeLast<NodeEventMap["connect"]>];
+
+    /**
+     * Emitted when a node is ready
+     */
+    nodeReady: [node: Node, ...ExcludeLast<NodeEventMap["ready"]>];
+
+    /**
+     * Emitted when a node receives a dispatch
+     */
+    nodeDispatch: [node: Node, ...ExcludeLast<NodeEventMap["dispatch"]>];
+
+    /**
+     * Emitted when a node encounters an error
+     */
+    nodeError: [node: Node, ...ExcludeLast<NodeEventMap["error"]>];
+
+    /**
+     * Emitted when a node closes
+     */
+    nodeClose: [node: Node, ...ExcludeLast<NodeEventMap["close"]>];
+
+    /**
+     * Emitted when a node disconnects
+     */
+    nodeDisconnect: [node: Node, ...ExcludeLast<NodeEventMap["disconnect"]>];
+
+    /**
+     * Emitted when voice connection is established
+     */
+    voiceConnect: [voice: VoiceState];
+
+    /**
+     * Emitted when voice connection closes
+     */
+    voiceClose: [voice: VoiceState, code: number, reason: string, byRemote: boolean];
+
+    /**
+     * Emitted when voice connection changes nodes
+     */
+    voiceChange: [voice: VoiceState, previousNode: Node, wasPlaying: boolean];
+
+    /**
+     * Emitted when voice connection is destroyed
+     */
+    voiceDestroy: [voice: VoiceState, reason: string];
+
+    /**
+     * Emitted when a queue is created
+     */
+    queueCreate: [queue: Queue];
+
+    /**
+     * Emitted when queue state updates
+     */
+    queueUpdate: [queue: Queue, state: PlayerState];
+
+    /**
+     * Emitted when queue finishes
+     */
+    queueFinish: [queue: Queue];
+
+    /**
+     * Emitted when a queue is destroyed
+     */
+    queueDestroy: [queue: Queue, reason: string];
+
+    /**
+     * Emitted when a track starts playing
+     */
+    trackStart: [queue: Queue, track: Track];
+
+    /**
+     * Emitted when tracks are added to a queue
+     */
+    trackAdd: [player: Player, guildId: string, tracks: Track[]];
+
+    /**
+     * Emitted when a track gets stuck
+     */
+    trackStuck: [queue: Queue, track: Track, thresholdMs: number];
+
+    /**
+     * Emitted when a track encounters an error
+     */
+    trackError: [queue: Queue, track: Track, exception: Exception];
+
+    /**
+     * Emitted when a track finishes
+     */
+    trackFinish: [queue: Queue, track: Track, reason: TrackEndReason];
+
+    /**
+     * Emitted for debug logs
+     */
+    debug: [name: string, info: unknown];
+
+    /**
+     * Emitted when SponsorBlock segments are loaded
+     */
+    segmentsLoaded: [queue: Queue, track: Track, payload: unknown];
+
+    /**
+     * Emitted when a SponsorBlock segment is skipped
+     */
+    segmentSkipped: [queue: Queue, track: Track, payload: unknown];
+
+    /**
+     * Emitted when fair play algorithm is applied to a queue
+     */
+    fairPlayApplied: [player: Player, guildId: string, count: number];
+
+    /**
+     * Emitted when lyrics are found for a track
+     */
+    lyricsFound: [player: Player, track: Track, result: LyricsResult];
+
+    /**
+     * Emitted when lyrics are not found for a track
+     */
+    lyricsNotFound: [player: Player, track: Track];
+
+    /**
+     * Emitted when a queue is saved
+     */
+    queueSaved: [guildId: string];
+
+    /**
+     * Emitted when a queue is loaded
+     */
+    queueLoaded: [guildId: string, count: number];
+}
+
+/**
+ * Constructs a record type mapping plugins by their names
+ */
+export type PluginRecord<Plugins extends PlayerPlugin[]> = {
+    [Name in Plugins[number]["name"]]: Extract<Plugins[number], { name: Name }>;
+};
+
+/**
+ * Options for creating a Player
+ */
+export interface PlayerOptions<Plugins extends PlayerPlugin[] = PlayerPlugin[]> {
+    /**
+     * Options for creating node(s)
+     */
+    nodes: CreateNodeOptions[];
+
+    /**
+     * Plugins to initialize after creating nodes
+     */
+    plugins?: Plugins;
+
+    /**
+     * Whether to initialize automatically upon receiving the bot's ready event.
+     * @default true
+     */
+    autoInit?: boolean;
+
+    /**
+     * Whether to update players for nodes that couldn't resume.
+     * @default true
+     */
+    autoSync?: boolean;
+
+    /**
+     * The prefix to use for search queries (not URLs) by default.
+     * @default "ytsearch"
+     */
+    queryPrefix?: string;
+
+    /**
+     * Whether to relocate queues when a node closes/disconnects.
+     * @default true
+     */
+    relocateQueues?: boolean;
+
+    /**
+     * Forward voice state updates to your bot's gateway connection
+     * @param guildId Id of the guild this voice update is meant for
+     * @param payload The voice state update payload to be forwarded
+     */
+    forwardVoiceUpdate: (guildId: string, payload: VoiceUpdatePayload) => Promise<void>;
+
+    /**
+     * Return empty or populated array of related tracks
+     * @param queue The queue requesting track(s)
+     * @param track The track suggested for reference
+     */
+    fetchRelatedTracks?: (queue: Queue, track: Track) => Promise<Track[]>;
+}
+
+/**
+ * Player instance options (with defaults applied)
+ */
+export type PlayerInstanceOptions = Omit<
+    RequiredProp<PlayerOptions, keyof typeof DefaultPlayerOptions>,
+    "nodes" | "plugins"
+>;
+
+/**
+ * Voice state update payload
+ */
+export interface VoiceUpdatePayload {
+    op: 4;
+    d: {
+        guild_id: string;
+        channel_id: string | null;
+        self_deaf: boolean;
+        self_mute: boolean;
+    };
+}
+
+/**
+ * Options for customizing a 'search' operation
+ */
+export interface SearchOptions {
+    /**
+     * Node name to use for search
+     */
+    node?: string;
+
+    /**
+     * Search prefix (ytsearch, ytmsearch, scsearch, etc.)
+     */
+    prefix?: string;
+}
+
+/**
+ * Options for customizing a 'play' operation
+ */
+export interface PlayOptions<
+    Context extends Record<string, unknown> = QueueContext,
+    UserData extends JsonObject = CommonUserData,
+>
+    extends SearchOptions, CreateQueueOptions<Context> {
+    /**
+     * User data to attach to the track
+     */
+    userData?: UserData;
+}
+
+/**
+ * Track search result
+ */
+export interface TrackSearchResult {
+    type: "track";
+    data: Track;
+}
+
+/**
+ * Playlist search result
+ */
+export interface PlaylistSearchResult {
+    type: "playlist";
+    data: Playlist;
+}
+
+/**
+ * Query search result
+ */
+export interface QuerySearchResult {
+    type: "query";
+    data: Track[];
+}
+
+/**
+ * Empty search result
+ */
+export interface EmptySearchResult {
+    type: "empty";
+    data: [];
+}
+
+/**
+ * Error search result
+ */
+export interface ErrorSearchResult {
+    type: "error";
+    data: Exception;
+}
+
+/**
+ * Search result union type
+ */
+export type SearchResult =
+    | TrackSearchResult
+    | PlaylistSearchResult
+    | QuerySearchResult
+    | EmptySearchResult
+    | ErrorSearchResult;

package/src/types/core/index.ts

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

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from "./common";
+export * from "./api";
+export * from "./lavalink";
+export * from "./voice";
+export * from "./audio";
+export * from "./core";

package/src/types/lavalink/Node.ts

@@ -0,0 +1,173 @@
+import type { MessagePayload } from "../api";
+import type { RESTOptions } from "./REST";
+
+/**
+ * WebSocket close codes
+ * https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code
+ */
+export const enum CloseCodes {
+    /**
+     * The connection successfully completed the purpose for which it was created.
+     */
+    Normal = 1000,
+
+    /**
+     * The endpoint is going away, either because of a server failure or
+     * the browser navigating away from the page that opened the connection.
+     */
+    GoingAway,
+
+    /**
+     * The endpoint is terminating the connection due to a protocol error.
+     */
+    ProtocolError,
+
+    /**
+     * The connection is being terminated because the endpoint received data of a type it cannot accept.
+     * (For example, a text-only endpoint received binary data.)
+     */
+    UnsupportedData,
+
+    /**
+     * Reserved. A meaning might be defined in the future.
+     */
+    Reserved,
+
+    /**
+     * Reserved. Indicates that no status code was provided even though one was expected.
+     */
+    NoStatusReceived,
+
+    /**
+     * Reserved. Indicates that a connection was closed abnormally (that is, with no close frame being sent) when a status code is expected.
+     */
+    Abnormal,
+
+    /**
+     * The endpoint is terminating the connection because a message was received that contained inconsistent data (e.g., non-UTF-8 data within a text message).
+     */
+    InvalidFramePayloadData,
+
+    /**
+     * The endpoint is terminating the connection because it received a message that violates its policy. This is a generic status code, used when codes 1003 and 1009 are not suitable.
+     */
+    PolicyViolation,
+
+    /**
+     * The endpoint is terminating the connection because a data frame was received that is too large.
+     */
+    MessageTooBig,
+
+    /**
+     * The client is terminating the connection because it expected the server to negotiate one or more extension, but the server didn't.
+     */
+    MandatoryExtension,
+
+    /**
+     * The server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
+     */
+    InternalError,
+
+    /**
+     * The server is terminating the connection because it is restarting.
+     */
+    ServiceRestart,
+
+    /**
+     * The server is terminating the connection due to a temporary condition, e.g., it is overloaded and is casting off some of its clients.
+     */
+    TryAgainLater,
+
+    /**
+     * The server was acting as a gateway or proxy and received an invalid response from the upstream server. This is similar to 502 HTTP Status Code.
+     */
+    BadGateway,
+
+    /**
+     * Reserved. Indicates that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified).
+     */
+    TLSHandshake,
+}
+
+/**
+ * Node event map
+ */
+export interface NodeEventMap {
+    connect: [reconnects: number, name: string];
+    ready: [resumed: boolean, sessionId: string, name: string];
+    dispatch: [payload: MessagePayload, name: string];
+    error: [error: Error, name: string];
+    close: [code: number, reason: string, name: string];
+    disconnect: [code: number, reason: string, byLocal: boolean, name: string];
+}
+
+/**
+ * States of a node
+ */
+export type NodeState = "connecting" | "connected" | "ready" | "reconnecting" | "disconnected";
+
+/**
+ * Options for creating a node
+ */
+export interface NodeOptions extends RESTOptions {
+    /**
+     * Name of the node
+     */
+    name: string;
+
+    /**
+     * User Id of the bot
+     */
+    clientId: string;
+
+    /**
+     * Interval at which this node dispatches it's stats.
+     * Default: `60_000`
+     */
+    statsInterval?: number;
+
+    /**
+     * An assumption of this node's highest possible latency.
+     * Default: `2_000`
+     */
+    highestLatency?: number;
+
+    /**
+     * Number of milliseconds to wait between each reconnect.
+     * Default: `10_000`
+     */
+    reconnectDelay?: number;
+
+    /**
+     * Number of reconnects to attempt for unexpected disconnects.
+     * Negative for no limit, zero for no attempts.
+     * Default: `3`
+     */
+    reconnectLimit?: number;
+
+    /**
+     * Number of milliseconds to allow for initial handshake.
+     * Default: `5_000`
+     */
+    handshakeTimeout?: number;
+}
+
+/**
+ * SponsorBlock segment information
+ */
+export interface SponsorBlockSegment {
+    /**
+     * The category of the segment
+     */
+    category: string;
+
+    /**
+     * The start time of the segment in milliseconds
+     */
+    start: number;
+
+    /**
+     * The end time of the segment in milliseconds
+     */
+    end: number;
+}

package/src/types/lavalink/NodeManager.ts

@@ -0,0 +1,34 @@
+import type { NodeOptions } from "../../types/lavalink/Node";
+
+/**
+ * Options for creating a node via manager
+ */
+export type CreateNodeOptions = Omit<NodeOptions, "clientId">;
+
+/**
+ * Types of node features for support evaluation
+ */
+export type FeatureTypes = "filter" | "source" | "plugin";
+
+/**
+ * Simplified node stats for relevance evaluation.
+ *
+ * The value of each field lies within [0, 1]
+ * except `streaming`, where -1 reports insufficient data
+ */
+export interface NodeMetrics {
+    /**
+     * Memory usage (0-1 scale, 0 = no usage, 1 = full usage)
+     */
+    memory: number;
+
+    /**
+     * Workload (0-1 scale, 0 = no load, 1 = full load)
+     */
+    workload: number;
+
+    /**
+     * Streaming quality (0-1 scale, 0 = poor, 1 = excellent, -1 = insufficient data)
+     */
+    streaming: number;
+}

package/src/types/lavalink/REST.ts

@@ -0,0 +1,144 @@
+import type { JsonLike } from "../common";
+
+/**
+ * Options to create an instance of REST
+ */
+export interface RESTOptions {
+    /**
+     * URL of your lavalink server (e.g., "http://localhost:2333" or "https://lavalink.example.com")
+     * If provided, this takes precedence over host/port/secure
+     */
+    origin?: string;
+
+    /**
+     * Host of your lavalink server (e.g., "localhost" or "lavalink.example.com")
+     * Used only if origin is not provided
+     */
+    host?: string;
+
+    /**
+     * Port of your lavalink server
+     * Default: `2333`
+     * Used only if origin is not provided
+     */
+    port?: number;
+
+    /**
+     * Whether to use secure connection (https/wss)
+     * Default: `false`
+     * Used only if origin is not provided
+     */
+    secure?: boolean;
+
+    /**
+     * Password of your lavalink server
+     */
+    password: string;
+
+    /**
+     * The semver major of your lavalink server.
+     * Default: `4`
+     */
+    version?: number;
+
+    /**
+     * The value to set the `User-Agent` header to.
+     * Default: `$client/$version ($repository)`
+     */
+    userAgent?: string;
+
+    /**
+     * Id of the lavalink session you want to interact with (if any)
+     */
+    sessionId?: string;
+
+    /**
+     * Whether to include stack trace from lavalink server on error.
+     * Default: `false`
+     */
+    stackTrace?: boolean;
+
+    /**
+     * Number of milliseconds to allow per request.
+     * Default: `10_000`
+     */
+    requestTimeout?: number;
+}
+
+/**
+ * Options for customizing a request
+ */
+export interface RequestOptions {
+    /**
+     * The http method
+     */
+    method?: string;
+
+    /**
+     * The query params to `set` (not `append`)
+     */
+    params?: Record<string, Exclude<JsonLike, object>>;
+
+    /**
+     * The headers to send
+     */
+    headers?: Record<string, Exclude<JsonLike, object>>;
+
+    /**
+     * The json data to attach
+     */
+    data?: unknown;
+
+    /**
+     * The abort signal
+     */
+    signal?: AbortSignal;
+
+    /**
+     * The timeout for this request
+     */
+    timeout?: number;
+
+    /**
+     * Whether the base url should be versioned.
+     * Default: `true`
+     */
+    versioned?: boolean;
+}
+
+/**
+ * REST response wrapper
+ */
+export interface RestResponse<Data> extends Pick<Response, "status" | "statusText" | "ok" | "redirected" | "url"> {
+    /**
+     * Response headers as a plain object
+     */
+    headers: Record<string, string>;
+
+    /**
+     * Response data
+     */
+    data: Data;
+}
+
+/**
+ * HTTP status codes
+ */
+export const enum HttpStatusCode {
+    /**
+     * @deprecated
+     */
+    Processing = 102,
+    Ok = 200,
+    NoContent = 204,
+    BadRequest = 400,
+    Unauthorized,
+    Forbidden = 403,
+    NotFound,
+    MethodNotAllowed,
+    TooManyRequests = 429,
+    InternalServerError = 500,
+    BadGateway = 502,
+    ServiceUnavailable,
+    GatewayTimeout,
+}

package/src/types/lavalink/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Lavalink type definitions
+ */
+
+export * from "./REST";
+export type { LavalinkInfo } from "../api/Rest";
+export * from "./Node";
+export * from "./NodeManager";
+
+import type { StatsPayload } from "../api/Websocket";
+export * from "../api/Websocket";
+import type { Node } from "../../lavalink/LavalinkConnection";
+
+/**
+ * Node stats event data
+ */
+export interface BaseNodeStats extends StatsPayload {}
+
+/**
+ * Node manager events
+ */
+export interface NodeManagerEvents {
+    create: [node: Node];
+    destroy: [node: Node];
+    connect: [node: Node];
+    ready: [node: Node, resumed: boolean, sessionId: string];
+    disconnect: [node: Node, reason: { code: number; reason: string }];
+    reconnecting: [node: Node];
+    error: [node: Node, error: Error];
+    raw: [node: Node, payload: unknown];
+    nodeInfo: [node: Node, info: unknown];
+}