@ooneex/youtube 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ooneex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# @ooneex/youtube

package/dist/index.d.ts

@@ -0,0 +1,439 @@
+import { ArgsOptions, FormatOptions, PlaylistInfo, QualityOptions, VideoFormat, VideoInfo, VideoProgress } from "ytdlp-nodejs";
+/**
+* Video information returned from YouTube.
+* Contains metadata such as title, description, duration, view count, etc.
+*
+* @example
+* ```typescript
+* const info: YoutubeVideoInfoType = await youtube.getVideoInfo(url);
+* console.log(info.title, info.duration, info.view_count);
+* ```
+*/
+type YoutubeVideoInfoType = VideoInfo;
+/**
+* Playlist information returned from YouTube.
+* Contains playlist metadata and list of videos in the playlist.
+*
+* @example
+* ```typescript
+* const playlist: YoutubePlaylistInfoType = await youtube.getPlaylistInfo(url);
+* console.log(playlist.title, playlist.entries.length);
+* ```
+*/
+type YoutubePlaylistInfoType = PlaylistInfo;
+/**
+* Video format information including codec, resolution, and bitrate details.
+*
+* @example
+* ```typescript
+* const info = await youtube.getVideoInfo(url);
+* const formats: YoutubeVideoFormatType[] = info.formats;
+* formats.forEach(f => console.log(f.format_id, f.ext, f.resolution));
+* ```
+*/
+type YoutubeVideoFormatType = VideoFormat;
+/**
+* Download progress information for tracking video download status.
+*
+* @example
+* ```typescript
+* const progress: YoutubeVideoProgressType = {
+*   percent: 50,
+*   totalSize: "100MB",
+*   currentSpeed: "5MB/s",
+*   eta: "10s",
+* };
+* ```
+*/
+type YoutubeVideoProgressType = VideoProgress;
+/**
+* Additional arguments options for yt-dlp commands.
+*
+* @example
+* ```typescript
+* const args: YoutubeArgsOptionsType = {
+*   noPlaylist: true,
+*   extractAudio: true,
+* };
+* ```
+*/
+type YoutubeArgsOptionsType = ArgsOptions;
+/**
+* Format options for downloading videos with specific quality settings.
+*
+* @typeParam F - The format keyword type (e.g., "video", "audio", "videoandaudio")
+*
+* @example
+* ```typescript
+* const options: YoutubeFormatOptionsType<"video"> = {
+*   format: { quality: "1080p" },
+* };
+* ```
+*/
+type YoutubeFormatOptionsType<F extends YoutubeFormatKeyWordType> = FormatOptions<F>;
+/**
+* Quality options for specifying video/audio quality preferences.
+*
+* @example
+* ```typescript
+* const quality: YoutubeQualityOptionsType = {
+*   video: "1080p",
+*   audio: "highest",
+* };
+* ```
+*/
+type YoutubeQualityOptionsType = QualityOptions;
+/**
+* Format keyword type for specifying download format categories.
+* Can be "video", "audio", or "videoandaudio".
+*
+* @example
+* ```typescript
+* const format: YoutubeFormatKeyWordType = "videoandaudio";
+* ```
+*/
+type YoutubeFormatKeyWordType = keyof QualityOptions;
+/**
+* Video quality presets for download operations.
+*
+* @example
+* ```typescript
+* const quality: YoutubeVideoQualityType = "1080p";
+*
+* // Available options:
+* // - "2160p" (4K)
+* // - "1440p" (2K)
+* // - "1080p" (Full HD)
+* // - "720p" (HD)
+* // - "480p" (SD)
+* // - "360p", "240p", "144p" (Low quality)
+* // - "highest" (Best available)
+* // - "lowest" (Smallest file size)
+* ```
+*/
+type YoutubeVideoQualityType = "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p" | "144p" | "highest" | "lowest";
+/**
+* Audio quality presets for audio download operations.
+*
+* @example
+* ```typescript
+* const quality: YoutubeAudioQualityType = "highest";
+*
+* // Available options:
+* // - "highest" (Best available audio quality)
+* // - "lowest" (Smallest file size)
+* ```
+*/
+type YoutubeAudioQualityType = "highest" | "lowest";
+/**
+* Configuration options for the YouTube client.
+*
+* @example
+* ```typescript
+* const options: YoutubeOptionsType = {
+*   binaryPath: "/usr/local/bin/yt-dlp",
+*   ffmpegPath: "/usr/local/bin/ffmpeg",
+* };
+* const youtube = new Youtube(options);
+* ```
+*/
+type YoutubeOptionsType = {
+	/**
+	* Path to the yt-dlp binary.
+	* Falls back to YOUTUBE_YTDLP_PATH environment variable if not provided.
+	*/
+	binaryPath?: string;
+	/**
+	* Path to the ffmpeg binary.
+	* Falls back to YOUTUBE_FFMPEG_PATH environment variable if not provided.
+	*/
+	ffmpegPath?: string;
+};
+/**
+* Interface defining the YouTube client API.
+* Provides methods for fetching video info, downloading, and managing media.
+*
+* @example
+* ```typescript
+* class MyYoutubeClient implements IYoutube {
+*   async getVideoInfo(url: string) { ... }
+*   async getPlaylistInfo(url: string) { ... }
+*   // ... implement all methods
+* }
+* ```
+*/
+interface IYoutube {
+	/**
+	* Retrieves detailed information about a YouTube video.
+	* @param url - The YouTube video URL
+	* @returns Promise resolving to video metadata
+	*/
+	getVideoInfo(url: string): Promise<YoutubeVideoInfoType>;
+	/**
+	* Retrieves information about a YouTube playlist.
+	* @param url - The YouTube playlist URL
+	* @returns Promise resolving to playlist metadata
+	*/
+	getPlaylistInfo(url: string): Promise<YoutubePlaylistInfoType>;
+	/**
+	* Downloads a video to the local filesystem.
+	* @param url - The YouTube video URL
+	* @param destination - The destination path for the downloaded file
+	* @returns Promise resolving to the downloaded file path
+	*/
+	download(url: string, destination: string): Promise<string>;
+	/**
+	* Downloads a video and returns it as a File object.
+	* @param url - The YouTube video URL
+	* @param options - Optional filename and format settings
+	* @returns Promise resolving to a File object
+	*/
+	getFile<F extends YoutubeFormatKeyWordType>(url: string, options?: {
+		filename?: string;
+		format?: YoutubeFormatOptionsType<F>["format"];
+	}): Promise<File>;
+	/**
+	* Extracts the video ID (watch ID) from a YouTube URL.
+	* @param url - The YouTube video URL
+	* @returns The video ID or null if not found
+	*/
+	getWatchId(url: string): string | null;
+	/**
+	* Generates an embed URL for a YouTube video.
+	* @param urlOrId - The YouTube video URL or video ID
+	* @returns The embed URL or null if the video ID cannot be extracted
+	*/
+	getEmbedUrl(urlOrId: string): string | null;
+	/**
+	* Generates a standard watch URL for a YouTube video.
+	* @param urlOrId - The YouTube video URL or video ID
+	* @returns The watch URL or null if the video ID cannot be extracted
+	*/
+	getWatchUrl(urlOrId: string): string | null;
+	/**
+	* Downloads only the audio from a YouTube video.
+	* @param url - The YouTube video URL
+	* @param destination - The destination path for the downloaded audio file
+	* @returns Promise resolving to the downloaded audio file path
+	*/
+	downloadAudio(url: string, destination: string): Promise<string>;
+}
+/**
+* YouTube client for downloading and extracting information from YouTube videos and playlists.
+* Wraps yt-dlp functionality with a clean async API and proper error handling.
+*
+* @example Basic Usage
+* ```typescript
+* import { Youtube } from "@ooneex/youtube";
+*
+* const youtube = new Youtube();
+*
+* // Get video information
+* const info = await youtube.getVideoInfo("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+* console.log(info.title, info.duration);
+*
+* // Download a video
+* const filePath = await youtube.download("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+* console.log(`Downloaded to: ${filePath}`);
+* ```
+*
+* @example Download with Quality Options
+* ```typescript
+* const youtube = new Youtube();
+*
+* // Download video in 1080p
+* const path = await youtube.download(url, {
+*   format: { video: "1080p" },
+* });
+*
+* // Download audio only
+* const audioPath = await youtube.download(url, {
+*   format: { audio: "highest" },
+* });
+* ```
+*/
+declare class Youtube implements IYoutube {
+	private readonly ytdlp;
+	/**
+	* Creates a new YouTube client instance.
+	*
+	* @param options - Optional configuration for binary paths
+	* @throws {YoutubeException} If required binary paths are not configured
+	*
+	* @example
+	* ```typescript
+	* const youtube = new Youtube();
+	* ```
+	*
+	* @example With Custom Paths
+	* ```typescript
+	* const youtube = new Youtube({
+	*   binaryPath: "/custom/path/to/yt-dlp",
+	*   ffmpegPath: "/custom/path/to/ffmpeg",
+	* });
+	* ```
+	*/
+	constructor(options?: YoutubeOptionsType);
+	/**
+	* Retrieves detailed metadata for a YouTube video.
+	*
+	* @param url - The YouTube video URL
+	* @returns Promise resolving to video information including title, description,
+	*          duration, view count, available formats, and more
+	* @throws {YoutubeException} If the video cannot be accessed or URL is invalid
+	*
+	* @example
+	* ```typescript
+	* const youtube = new Youtube();
+	* const info = await youtube.getVideoInfo("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+	*
+	* console.log("Title:", info.title);
+	* console.log("Duration:", info.duration, "seconds");
+	* console.log("Views:", info.view_count);
+	* console.log("Description:", info.description);
+	* console.log("Available formats:", info.formats.length);
+	* ```
+	*/
+	getVideoInfo(url: string): Promise<YoutubeVideoInfoType>;
+	/**
+	* Retrieves information about a YouTube playlist including all videos.
+	*
+	* @param url - The YouTube playlist URL
+	* @returns Promise resolving to playlist metadata and video entries
+	* @throws {YoutubeException} If the playlist cannot be accessed or URL is invalid
+	*
+	* @example
+	* ```typescript
+	* const youtube = new Youtube();
+	* const playlist = await youtube.getPlaylistInfo(
+	*   "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
+	* );
+	*
+	* console.log("Playlist:", playlist.title);
+	* console.log("Video count:", playlist.entries.length);
+	*
+	* // Iterate over videos in the playlist
+	* for (const video of playlist.entries) {
+	*   console.log(`- ${video.title} (${video.duration}s)`);
+	* }
+	* ```
+	*/
+	getPlaylistInfo(url: string): Promise<YoutubePlaylistInfoType>;
+	/**
+	* Downloads a video to the local filesystem.
+	*
+	* @typeParam F - The format keyword type (video, audio, or videoandaudio)
+	* @param url - The YouTube video URL
+	* @param options - Optional format and quality settings
+	* @returns Promise resolving to the path of the downloaded file
+	* @throws {YoutubeException} If download fails
+	*
+	* @example Download with Default Settings
+	* ```typescript
+	* const youtube = new Youtube();
+	* const filePath = await youtube.download("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+	* console.log("Downloaded to:", filePath);
+	* ```
+	*
+	* @example Download with Specific Quality
+	* ```typescript
+	* const youtube = new Youtube();
+	*
+	* // Download 1080p video
+	* const videoPath = await youtube.download(url, {
+	*   format: { video: "1080p" },
+	* });
+	*
+	* // Download 720p video with audio
+	* const hdPath = await youtube.download(url, {
+	*   format: { videoandaudio: "720p" },
+	* });
+	* ```
+	*
+	* @example Download Audio Only
+	* ```typescript
+	* const youtube = new Youtube();
+	* const audioPath = await youtube.download(url, {
+	*   format: { audio: "highest" },
+	* });
+	* ```
+	*/
+	download(url: string, destination: string): Promise<string>;
+	/**
+	* Downloads only the audio from a YouTube video.
+	* Convenience method that wraps download with audio-only format settings.
+	*
+	* @param url - The YouTube video URL
+	* @param quality - Audio quality preference (defaults to "highest")
+	* @returns Promise resolving to the path of the downloaded audio file
+	* @throws {YoutubeException} If download fails
+	*
+	* @example Basic Usage
+	* ```typescript
+	* const youtube = new Youtube();
+	* const audioPath = await youtube.downloadAudio("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+	* console.log("Audio downloaded to:", audioPath);
+	* ```
+	*
+	* @example With Quality Option
+	* ```typescript
+	* const youtube = new Youtube();
+	*
+	* // Download highest quality audio
+	* const hqPath = await youtube.downloadAudio(url, "highest");
+	*
+	* // Download lowest quality (smaller file)
+	* const lqPath = await youtube.downloadAudio(url, "lowest");
+	* ```
+	*/
+	downloadAudio(url: string, destination: string): Promise<string>;
+	/**
+	* Downloads a video and returns it as a File object.
+	* Useful for in-memory processing or streaming without saving to disk.
+	*
+	* @typeParam F - The format keyword type (video, audio, or videoandaudio)
+	* @param url - The YouTube video URL
+	* @param options - Optional filename and format settings
+	* @returns Promise resolving to a File object containing the video data
+	* @throws {YoutubeException} If download fails
+	*
+	* @example Basic Usage
+	* ```typescript
+	* const youtube = new Youtube();
+	* const file = await youtube.getFile("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+	*
+	* console.log("File name:", file.name);
+	* console.log("File size:", file.size, "bytes");
+	* console.log("MIME type:", file.type);
+	* ```
+	*
+	* @example With Custom Filename
+	* ```typescript
+	* const youtube = new Youtube();
+	* const file = await youtube.getFile(url, {
+	*   filename: "my-video.mp4",
+	* });
+	* ```
+	*
+	* @example With Format Options
+	* ```typescript
+	* const youtube = new Youtube();
+	* const audioFile = await youtube.getFile(url, {
+	*   filename: "audio.mp3",
+	*   format: { audio: "highest" },
+	* });
+	* ```
+	*/
+	getFile<F extends YoutubeFormatKeyWordType>(url: string, options?: {
+		filename?: string;
+		format?: YoutubeFormatOptionsType<F>["format"] | undefined;
+	}): Promise<File>;
+	getWatchId(url: string): string | null;
+	getEmbedUrl(urlOrId: string): string | null;
+	getWatchUrl(urlOrId: string): string | null;
+}
+import { Exception } from "@ooneex/exception";
+declare class YoutubeException extends Exception {
+	constructor(message: string, data?: Record<string, unknown>);
+}
+export { YoutubeVideoQualityType, YoutubeVideoProgressType, YoutubeVideoInfoType, YoutubeVideoFormatType, YoutubeQualityOptionsType, YoutubePlaylistInfoType, YoutubeOptionsType, YoutubeFormatOptionsType, YoutubeFormatKeyWordType, YoutubeException, YoutubeAudioQualityType, YoutubeArgsOptionsType, Youtube, IYoutube };

package/dist/index.js

@@ -0,0 +1,4 @@
+// @bun
+import{YtDlp as B}from"ytdlp-nodejs";import{Exception as z}from"@ooneex/exception";import{HttpStatus as A}from"@ooneex/http-status";class q extends z{constructor(S,C={}){super(S,{status:A.Code.InternalServerError,data:C});this.name="YoutubeException"}}class F{ytdlp;constructor(S={}){let C=S.binaryPath||Bun.env.YOUTUBE_YTDLP_PATH,H=S.ffmpegPath||Bun.env.YOUTUBE_FFMPEG_PATH;if(!C)throw new q("yt-dlp binary path is required. Please provide it through the constructor options or set the YOUTUBE_YTDLP_PATH environment variable.");if(!H)throw new q("ffmpeg binary path is required. Please provide it through the constructor options or set the YOUTUBE_FFMPEG_PATH environment variable.");this.ytdlp=new B({binaryPath:C,ffmpegPath:H})}async getVideoInfo(S){try{return await this.ytdlp.getInfoAsync(S)}catch(C){throw new q(`Failed to get video info: ${C.message}`,{data:{url:S}})}}async getPlaylistInfo(S){try{return await this.ytdlp.getInfoAsync(S)}catch(C){throw new q(`Failed to get playlist info: ${C.message}`,{data:{url:S}})}}async download(S,C){try{return await this.ytdlp.downloadAsync(this.getWatchId(S)||"",{format:{filter:"audioandvideo",type:"mp4"},output:C})}catch(H){throw new q(`Failed to download video: ${H.message}`,{data:{url:S}})}}async downloadAudio(S,C){try{return await this.ytdlp.downloadAsync(this.getWatchId(S)||"",{format:{filter:"audioonly",type:"mp3"},output:C})}catch(H){throw new q(`Failed to download audio: ${H.message}`,{data:{url:S}})}}async getFile(S,C){try{let H=C?{filename:C.filename,format:C.format}:void 0;return await this.ytdlp.getFileAsync(this.getWatchId(S)||"",H)}catch(H){throw new q(`Failed to get file: ${H.message}`,{data:{url:S}})}}getWatchId(S){let C=[/(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/v\/|youtube\.com\/watch\?.*&v=)([^&\n?#]+)/,/youtube\.com\/shorts\/([^&\n?#]+)/];for(let H of C){let x=S.match(H);if(x?.[1])return x[1]}return null}getEmbedUrl(S){let C=this.getWatchId(S)??S;if(!/^[\w-]{10,12}$/.test(C))return null;return`https://www.youtube.com/embed/${C}`}getWatchUrl(S){let C=this.getWatchId(S)??S;if(!/^[\w-]{10,12}$/.test(C))return null;return`https://www.youtube.com/watch?v=${C}`}}export{q as YoutubeException,F as Youtube};
+
+//# debugId=D8DC7E8F8C92550864756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["src/Youtube.ts", "src/YoutubeException.ts"],
+  "sourcesContent": [
+    "import { YtDlp } from \"ytdlp-nodejs\";\nimport type {\n  IYoutube,\n  YoutubeFormatKeyWordType,\n  YoutubeFormatOptionsType,\n  YoutubeOptionsType,\n  YoutubePlaylistInfoType,\n  YoutubeVideoInfoType,\n} from \"./types\";\nimport { YoutubeException } from \"./YoutubeException\";\n\n/**\n * YouTube client for downloading and extracting information from YouTube videos and playlists.\n * Wraps yt-dlp functionality with a clean async API and proper error handling.\n *\n * @example Basic Usage\n * ```typescript\n * import { Youtube } from \"@ooneex/youtube\";\n *\n * const youtube = new Youtube();\n *\n * // Get video information\n * const info = await youtube.getVideoInfo(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n * console.log(info.title, info.duration);\n *\n * // Download a video\n * const filePath = await youtube.download(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n * console.log(`Downloaded to: ${filePath}`);\n * ```\n *\n * @example Download with Quality Options\n * ```typescript\n * const youtube = new Youtube();\n *\n * // Download video in 1080p\n * const path = await youtube.download(url, {\n *   format: { video: \"1080p\" },\n * });\n *\n * // Download audio only\n * const audioPath = await youtube.download(url, {\n *   format: { audio: \"highest\" },\n * });\n * ```\n */\nexport class Youtube implements IYoutube {\n  private readonly ytdlp: YtDlp;\n\n  /**\n   * Creates a new YouTube client instance.\n   *\n   * @param options - Optional configuration for binary paths\n   * @throws {YoutubeException} If required binary paths are not configured\n   *\n   * @example\n   * ```typescript\n   * const youtube = new Youtube();\n   * ```\n   *\n   * @example With Custom Paths\n   * ```typescript\n   * const youtube = new Youtube({\n   *   binaryPath: \"/custom/path/to/yt-dlp\",\n   *   ffmpegPath: \"/custom/path/to/ffmpeg\",\n   * });\n   * ```\n   */\n  constructor(options: YoutubeOptionsType = {}) {\n    const binaryPath = options.binaryPath || Bun.env.YOUTUBE_YTDLP_PATH;\n    const ffmpegPath = options.ffmpegPath || Bun.env.YOUTUBE_FFMPEG_PATH;\n\n    if (!binaryPath) {\n      throw new YoutubeException(\n        \"yt-dlp binary path is required. Please provide it through the constructor options or set the YOUTUBE_YTDLP_PATH environment variable.\",\n      );\n    }\n\n    if (!ffmpegPath) {\n      throw new YoutubeException(\n        \"ffmpeg binary path is required. Please provide it through the constructor options or set the YOUTUBE_FFMPEG_PATH environment variable.\",\n      );\n    }\n\n    this.ytdlp = new YtDlp({\n      binaryPath,\n      ffmpegPath,\n    });\n  }\n\n  /**\n   * Retrieves detailed metadata for a YouTube video.\n   *\n   * @param url - The YouTube video URL\n   * @returns Promise resolving to video information including title, description,\n   *          duration, view count, available formats, and more\n   * @throws {YoutubeException} If the video cannot be accessed or URL is invalid\n   *\n   * @example\n   * ```typescript\n   * const youtube = new Youtube();\n   * const info = await youtube.getVideoInfo(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n   *\n   * console.log(\"Title:\", info.title);\n   * console.log(\"Duration:\", info.duration, \"seconds\");\n   * console.log(\"Views:\", info.view_count);\n   * console.log(\"Description:\", info.description);\n   * console.log(\"Available formats:\", info.formats.length);\n   * ```\n   */\n  public async getVideoInfo(url: string): Promise<YoutubeVideoInfoType> {\n    try {\n      return await this.ytdlp.getInfoAsync<\"video\">(url);\n    } catch (error) {\n      throw new YoutubeException(`Failed to get video info: ${(error as Error).message}`, {\n        data: { url },\n      });\n    }\n  }\n\n  /**\n   * Retrieves information about a YouTube playlist including all videos.\n   *\n   * @param url - The YouTube playlist URL\n   * @returns Promise resolving to playlist metadata and video entries\n   * @throws {YoutubeException} If the playlist cannot be accessed or URL is invalid\n   *\n   * @example\n   * ```typescript\n   * const youtube = new Youtube();\n   * const playlist = await youtube.getPlaylistInfo(\n   *   \"https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf\"\n   * );\n   *\n   * console.log(\"Playlist:\", playlist.title);\n   * console.log(\"Video count:\", playlist.entries.length);\n   *\n   * // Iterate over videos in the playlist\n   * for (const video of playlist.entries) {\n   *   console.log(`- ${video.title} (${video.duration}s)`);\n   * }\n   * ```\n   */\n  public async getPlaylistInfo(url: string): Promise<YoutubePlaylistInfoType> {\n    try {\n      return await this.ytdlp.getInfoAsync<\"playlist\">(url);\n    } catch (error) {\n      throw new YoutubeException(`Failed to get playlist info: ${(error as Error).message}`, {\n        data: { url },\n      });\n    }\n  }\n\n  /**\n   * Downloads a video to the local filesystem.\n   *\n   * @typeParam F - The format keyword type (video, audio, or videoandaudio)\n   * @param url - The YouTube video URL\n   * @param options - Optional format and quality settings\n   * @returns Promise resolving to the path of the downloaded file\n   * @throws {YoutubeException} If download fails\n   *\n   * @example Download with Default Settings\n   * ```typescript\n   * const youtube = new Youtube();\n   * const filePath = await youtube.download(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n   * console.log(\"Downloaded to:\", filePath);\n   * ```\n   *\n   * @example Download with Specific Quality\n   * ```typescript\n   * const youtube = new Youtube();\n   *\n   * // Download 1080p video\n   * const videoPath = await youtube.download(url, {\n   *   format: { video: \"1080p\" },\n   * });\n   *\n   * // Download 720p video with audio\n   * const hdPath = await youtube.download(url, {\n   *   format: { videoandaudio: \"720p\" },\n   * });\n   * ```\n   *\n   * @example Download Audio Only\n   * ```typescript\n   * const youtube = new Youtube();\n   * const audioPath = await youtube.download(url, {\n   *   format: { audio: \"highest\" },\n   * });\n   * ```\n   */\n  public async download(url: string, destination: string): Promise<string> {\n    try {\n      return await this.ytdlp.downloadAsync(this.getWatchId(url) || \"\", {\n        format: { filter: \"audioandvideo\", type: \"mp4\" },\n        output: destination,\n      });\n    } catch (error) {\n      throw new YoutubeException(`Failed to download video: ${(error as Error).message}`, {\n        data: { url },\n      });\n    }\n  }\n\n  /**\n   * Downloads only the audio from a YouTube video.\n   * Convenience method that wraps download with audio-only format settings.\n   *\n   * @param url - The YouTube video URL\n   * @param quality - Audio quality preference (defaults to \"highest\")\n   * @returns Promise resolving to the path of the downloaded audio file\n   * @throws {YoutubeException} If download fails\n   *\n   * @example Basic Usage\n   * ```typescript\n   * const youtube = new Youtube();\n   * const audioPath = await youtube.downloadAudio(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n   * console.log(\"Audio downloaded to:\", audioPath);\n   * ```\n   *\n   * @example With Quality Option\n   * ```typescript\n   * const youtube = new Youtube();\n   *\n   * // Download highest quality audio\n   * const hqPath = await youtube.downloadAudio(url, \"highest\");\n   *\n   * // Download lowest quality (smaller file)\n   * const lqPath = await youtube.downloadAudio(url, \"lowest\");\n   * ```\n   */\n  public async downloadAudio(url: string, destination: string): Promise<string> {\n    try {\n      return await this.ytdlp.downloadAsync(this.getWatchId(url) || \"\", {\n        format: { filter: \"audioonly\", type: \"mp3\" },\n        output: destination,\n      });\n    } catch (error) {\n      throw new YoutubeException(`Failed to download audio: ${(error as Error).message}`, {\n        data: { url },\n      });\n    }\n  }\n\n  /**\n   * Downloads a video and returns it as a File object.\n   * Useful for in-memory processing or streaming without saving to disk.\n   *\n   * @typeParam F - The format keyword type (video, audio, or videoandaudio)\n   * @param url - The YouTube video URL\n   * @param options - Optional filename and format settings\n   * @returns Promise resolving to a File object containing the video data\n   * @throws {YoutubeException} If download fails\n   *\n   * @example Basic Usage\n   * ```typescript\n   * const youtube = new Youtube();\n   * const file = await youtube.getFile(\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\");\n   *\n   * console.log(\"File name:\", file.name);\n   * console.log(\"File size:\", file.size, \"bytes\");\n   * console.log(\"MIME type:\", file.type);\n   * ```\n   *\n   * @example With Custom Filename\n   * ```typescript\n   * const youtube = new Youtube();\n   * const file = await youtube.getFile(url, {\n   *   filename: \"my-video.mp4\",\n   * });\n   * ```\n   *\n   * @example With Format Options\n   * ```typescript\n   * const youtube = new Youtube();\n   * const audioFile = await youtube.getFile(url, {\n   *   filename: \"audio.mp3\",\n   *   format: { audio: \"highest\" },\n   * });\n   * ```\n   */\n  public async getFile<F extends YoutubeFormatKeyWordType>(\n    url: string,\n    options?: { filename?: string; format?: YoutubeFormatOptionsType<F>[\"format\"] | undefined },\n  ): Promise<File> {\n    try {\n      const fileOptions = options ? { filename: options.filename, format: options.format } : undefined;\n      return await this.ytdlp.getFileAsync(\n        this.getWatchId(url) || \"\",\n        fileOptions as Parameters<typeof this.ytdlp.getFileAsync<F>>[1],\n      );\n    } catch (error) {\n      throw new YoutubeException(`Failed to get file: ${(error as Error).message}`, {\n        data: { url },\n      });\n    }\n  }\n\n  public getWatchId(url: string): string | null {\n    const patterns = [\n      /(?:youtube\\.com\\/watch\\?v=|youtu\\.be\\/|youtube\\.com\\/embed\\/|youtube\\.com\\/v\\/|youtube\\.com\\/watch\\?.*&v=)([^&\\n?#]+)/,\n      /youtube\\.com\\/shorts\\/([^&\\n?#]+)/,\n    ];\n\n    for (const pattern of patterns) {\n      const match = url.match(pattern);\n      if (match?.[1]) {\n        return match[1];\n      }\n    }\n\n    return null;\n  }\n\n  public getEmbedUrl(urlOrId: string): string | null {\n    const videoId = this.getWatchId(urlOrId) ?? urlOrId;\n\n    // Validate that it looks like a YouTube video ID (typically 11 characters, alphanumeric with - and _)\n    if (!/^[\\w-]{10,12}$/.test(videoId)) {\n      return null;\n    }\n\n    return `https://www.youtube.com/embed/${videoId}`;\n  }\n\n  public getWatchUrl(urlOrId: string): string | null {\n    const videoId = this.getWatchId(urlOrId) ?? urlOrId;\n\n    // Validate that it looks like a YouTube video ID (typically 11 characters, alphanumeric with - and _)\n    if (!/^[\\w-]{10,12}$/.test(videoId)) {\n      return null;\n    }\n\n    return `https://www.youtube.com/watch?v=${videoId}`;\n  }\n}\n",
+    "import { Exception } from \"@ooneex/exception\";\nimport { HttpStatus } from \"@ooneex/http-status\";\n\nexport class YoutubeException extends Exception {\n  constructor(message: string, data: Record<string, unknown> = {}) {\n    super(message, {\n      status: HttpStatus.Code.InternalServerError,\n      data,\n    });\n    this.name = \"YoutubeException\";\n  }\n}\n"
+  ],
+  "mappings": ";AAAA,gBAAS,qBCAT,oBAAS,0BACT,qBAAS,4BAEF,MAAM,UAAyB,CAAU,CAC9C,WAAW,CAAC,EAAiB,EAAgC,CAAC,EAAG,CAC/D,MAAM,EAAS,CACb,OAAQ,EAAW,KAAK,oBACxB,MACF,CAAC,EACD,KAAK,KAAO,mBAEhB,CDkCO,MAAM,CAA4B,CACtB,MAqBjB,WAAW,CAAC,EAA8B,CAAC,EAAG,CAC5C,IAAM,EAAa,EAAQ,YAAc,IAAI,IAAI,mBAC3C,EAAa,EAAQ,YAAc,IAAI,IAAI,oBAEjD,GAAI,CAAC,EACH,MAAM,IAAI,EACR,uIACF,EAGF,GAAI,CAAC,EACH,MAAM,IAAI,EACR,wIACF,EAGF,KAAK,MAAQ,IAAI,EAAM,CACrB,aACA,YACF,CAAC,OAuBU,aAAY,CAAC,EAA4C,CACpE,GAAI,CACF,OAAO,MAAM,KAAK,MAAM,aAAsB,CAAG,EACjD,MAAO,EAAO,CACd,MAAM,IAAI,EAAiB,6BAA8B,EAAgB,UAAW,CAClF,KAAM,CAAE,KAAI,CACd,CAAC,QA2BQ,gBAAe,CAAC,EAA+C,CAC1E,GAAI,CACF,OAAO,MAAM,KAAK,MAAM,aAAyB,CAAG,EACpD,MAAO,EAAO,CACd,MAAM,IAAI,EAAiB,gCAAiC,EAAgB,UAAW,CACrF,KAAM,CAAE,KAAI,CACd,CAAC,QA2CQ,SAAQ,CAAC,EAAa,EAAsC,CACvE,GAAI,CACF,OAAO,MAAM,KAAK,MAAM,cAAc,KAAK,WAAW,CAAG,GAAK,GAAI,CAChE,OAAQ,CAAE,OAAQ,gBAAiB,KAAM,KAAM,EAC/C,OAAQ,CACV,CAAC,EACD,MAAO,EAAO,CACd,MAAM,IAAI,EAAiB,6BAA8B,EAAgB,UAAW,CAClF,KAAM,CAAE,KAAI,CACd,CAAC,QA+BQ,cAAa,CAAC,EAAa,EAAsC,CAC5E,GAAI,CACF,OAAO,MAAM,KAAK,MAAM,cAAc,KAAK,WAAW,CAAG,GAAK,GAAI,CAChE,OAAQ,CAAE,OAAQ,YAAa,KAAM,KAAM,EAC3C,OAAQ,CACV,CAAC,EACD,MAAO,EAAO,CACd,MAAM,IAAI,EAAiB,6BAA8B,EAAgB,UAAW,CAClF,KAAM,CAAE,KAAI,CACd,CAAC,QAyCQ,QAA2C,CACtD,EACA,EACe,CACf,GAAI,CACF,IAAM,EAAc,EAAU,CAAE,SAAU,EAAQ,SAAU,OAAQ,EAAQ,MAAO,EAAI,OACvF,OAAO,MAAM,KAAK,MAAM,aACtB,KAAK,WAAW,CAAG,GAAK,GACxB,CACF,EACA,MAAO,EAAO,CACd,MAAM,IAAI,EAAiB,uBAAwB,EAAgB,UAAW,CAC5E,KAAM,CAAE,KAAI,CACd,CAAC,GAIE,UAAU,CAAC,EAA4B,CAC5C,IAAM,EAAW,CACf,wHACA,mCACF,EAEA,QAAW,KAAW,EAAU,CAC9B,IAAM,EAAQ,EAAI,MAAM,CAAO,EAC/B,GAAI,IAAQ,GACV,OAAO,EAAM,GAIjB,OAAO,KAGF,WAAW,CAAC,EAAgC,CACjD,IAAM,EAAU,KAAK,WAAW,CAAO,GAAK,EAG5C,GAAI,CAAC,iBAAiB,KAAK,CAAO,EAChC,OAAO,KAGT,MAAO,iCAAiC,IAGnC,WAAW,CAAC,EAAgC,CACjD,IAAM,EAAU,KAAK,WAAW,CAAO,GAAK,EAG5C,GAAI,CAAC,iBAAiB,KAAK,CAAO,EAChC,OAAO,KAGT,MAAO,mCAAmC,IAE9C",
+  "debugId": "D8DC7E8F8C92550864756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ooneex/youtube",
+  "description": "A YouTube video downloader and utility library",
+  "version": "0.0.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test tests",
+    "build": "bunup",
+    "lint": "tsgo --noEmit && bunx biome lint",
+    "publish": "bun publish --access public || true"
+  },
+  "dependencies": {
+    "@ooneex/exception": "0.0.1",
+    "@ooneex/http-status": "0.0.1",
+    "ytdlp-nodejs": "^2.3.5"
+  },
+  "keywords": [
+    "api",
+    "bun",
+    "downloader",
+    "embed",
+    "ooneex",
+    "typescript",
+    "video",
+    "youtube",
+    "ytdlp"
+  ]
+}