@talosjs/youtube 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Talos
+
+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,53 @@
+# @talosjs/youtube
+
+YouTube video downloader and metadata extraction library for fetching video information, thumbnails, and media streams.
+
+![Bun](https://img.shields.io/badge/Bun-Compatible-orange?style=flat-square&logo=bun)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)
+![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+
+## Features
+
+✅ **Transcript Fetching** - Retrieve timestamped transcripts and video metadata via `Youtube#transcript`
+
+✅ **ytdlp Integration** - Type definitions for ytdlp-nodejs including video/audio quality, format options, and download progress
+
+✅ **Quality Types** - `YoutubeVideoQualityType` (144p to 2160p) and `YoutubeAudioQualityType` for stream selection
+
+✅ **Error Handling** - Custom `YoutubeException` for YouTube-specific error scenarios
+
+✅ **Type-Safe** - Full TypeScript support with `IYoutube` interface and re-exported ytdlp types
+
+> For URL helpers like `getId`, `getEmbedUrl`, and `getWatchUrl`, see [`@talosjs/youtube-utils`](../youtube-utils).
+
+## Installation
+
+```bash
+bun add @talosjs/youtube
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `bun install`
+3. Run tests: `bun run test`
+4. Build the project: `bun run build`
+
+### Guidelines
+
+- Write tests for new features
+- Follow the existing code style
+- Update documentation for API changes
+- Ensure all tests pass before submitting PR
+
+---
+
+Made with ❤️ by the Talos team

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { ArgsOptions, FormatOptions, QualityOptions, VideoFormat, VideoProgress } from "ytdlp-nodejs";
+type YoutubeVideoFormatType = VideoFormat;
+type YoutubeVideoProgressType = VideoProgress;
+type YoutubeArgsOptionsType = ArgsOptions;
+type YoutubeFormatOptionsType<F extends YoutubeFormatKeyWordType> = FormatOptions<F>;
+type YoutubeQualityOptionsType = QualityOptions;
+type YoutubeFormatKeyWordType = keyof QualityOptions;
+type YoutubeVideoQualityType = "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p" | "144p" | "highest" | "lowest";
+type YoutubeAudioQualityType = "highest" | "lowest";
+type YoutubeTranscriptSegmentType = {
+	text: string;
+	start: number;
+	duration: number;
+};
+type YoutubeTranscriptAuthorType = {
+	name: string;
+	url: string;
+};
+type YoutubeTranscriptMetadataType = {
+	title: string;
+	author: YoutubeTranscriptAuthorType;
+	thumbnail: string;
+};
+type YoutubeTranscriptResponseType = {
+	id: string;
+	lang: string;
+	transcript: YoutubeTranscriptSegmentType[];
+	metadata: YoutubeTranscriptMetadataType;
+};
+interface IYoutube {
+	transcript(videoId: string): Promise<YoutubeTranscriptResponseType>;
+}
+declare class Youtube implements IYoutube {
+	private static readonly BASE_URL;
+	private readonly apiKey;
+	constructor(apiKey?: string);
+	transcript(videoId: string): Promise<YoutubeTranscriptResponseType>;
+}
+import { Exception } from "@talosjs/exception";
+declare class YoutubeException extends Exception {
+	constructor(message: string, key: string, data?: Record<string, unknown>);
+}
+export { YoutubeVideoQualityType, YoutubeVideoProgressType, YoutubeVideoFormatType, YoutubeTranscriptSegmentType, YoutubeTranscriptResponseType, YoutubeTranscriptMetadataType, YoutubeTranscriptAuthorType, YoutubeQualityOptionsType, YoutubeFormatOptionsType, YoutubeFormatKeyWordType, YoutubeException, YoutubeAudioQualityType, YoutubeArgsOptionsType, Youtube, IYoutube };

package/dist/index.js

@@ -0,0 +1,63 @@
+// @bun
+// src/YoutubeException.ts
+import { Exception } from "@talosjs/exception";
+import { HttpStatus } from "@talosjs/http-status";
+
+class YoutubeException extends Exception {
+  constructor(message, key, data = {}) {
+    super(message, {
+      key,
+      status: HttpStatus.Code.InternalServerError,
+      data
+    });
+    this.name = "YoutubeException";
+  }
+}
+
+// src/Youtube.ts
+class Youtube {
+  static BASE_URL = "https://transcriptapi.com/api/v2";
+  apiKey;
+  constructor(apiKey) {
+    this.apiKey = apiKey ?? Bun.env.YOUTUBE_TRANSCRIPT_API_KEY ?? "";
+    if (!this.apiKey) {
+      throw new YoutubeException("YouTube Transcript API key is required. Please set the YOUTUBE_TRANSCRIPT_API_KEY environment variable.", "API_KEY_REQUIRED");
+    }
+  }
+  async transcript(videoId) {
+    const params = new URLSearchParams({
+      video_url: videoId,
+      format: "json",
+      include_timestamp: "true",
+      send_metadata: "true"
+    });
+    const response = await fetch(`${Youtube.BASE_URL}/youtube/transcript?${params}`, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      }
+    });
+    if (!response.ok) {
+      throw new YoutubeException(`Transcript API error: ${response.status} ${response.statusText}`, "TRANSCRIPT_FAILED", { videoId, status: response.status });
+    }
+    const data = await response.json();
+    return {
+      id: data.video_id,
+      lang: data.language,
+      transcript: data.transcript,
+      metadata: {
+        title: data.metadata.title,
+        author: {
+          name: data.metadata.author_name,
+          url: data.metadata.author_url
+        },
+        thumbnail: data.metadata.thumbnail_url
+      }
+    };
+  }
+}
+export {
+  YoutubeException,
+  Youtube
+};
+
+//# debugId=025B276CE136CF8364756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["src/YoutubeException.ts", "src/Youtube.ts"],
+  "sourcesContent": [
+    "import { Exception } from \"@talosjs/exception\";\nimport { HttpStatus } from \"@talosjs/http-status\";\n\nexport class YoutubeException extends Exception {\n  constructor(message: string, key: string, data: Record<string, unknown> = {}) {\n    super(message, {\n      key,\n      status: HttpStatus.Code.InternalServerError,\n      data,\n    });\n    this.name = \"YoutubeException\";\n  }\n}\n",
+    "import type { IYoutube, YoutubeTranscriptResponseType } from \"./types\";\nimport { YoutubeException } from \"./YoutubeException\";\n\nexport class Youtube implements IYoutube {\n  private static readonly BASE_URL = \"https://transcriptapi.com/api/v2\";\n\n  private readonly apiKey: string;\n\n  constructor(apiKey?: string) {\n    this.apiKey = apiKey ?? Bun.env.YOUTUBE_TRANSCRIPT_API_KEY ?? \"\";\n\n    if (!this.apiKey) {\n      throw new YoutubeException(\n        \"YouTube Transcript API key is required. Please set the YOUTUBE_TRANSCRIPT_API_KEY environment variable.\",\n        \"API_KEY_REQUIRED\",\n      );\n    }\n  }\n\n  public async transcript(videoId: string): Promise<YoutubeTranscriptResponseType> {\n    const params = new URLSearchParams({\n      video_url: videoId,\n      format: \"json\",\n      include_timestamp: \"true\",\n      send_metadata: \"true\",\n    });\n\n    const response = await fetch(`${Youtube.BASE_URL}/youtube/transcript?${params}`, {\n      headers: {\n        Authorization: `Bearer ${this.apiKey}`,\n      },\n    });\n\n    if (!response.ok) {\n      throw new YoutubeException(\n        `Transcript API error: ${response.status} ${response.statusText}`,\n        \"TRANSCRIPT_FAILED\",\n        { videoId, status: response.status },\n      );\n    }\n\n    const data = await response.json();\n\n    return {\n      id: data.video_id,\n      lang: data.language,\n      transcript: data.transcript,\n      metadata: {\n        title: data.metadata.title,\n        author: {\n          name: data.metadata.author_name,\n          url: data.metadata.author_url,\n        },\n        thumbnail: data.metadata.thumbnail_url,\n      },\n    };\n  }\n}\n"
+  ],
+  "mappings": ";;AAAA;AACA;AAAA;AAEO,MAAM,yBAAyB,UAAU;AAAA,EAC9C,WAAW,CAAC,SAAiB,KAAa,OAAgC,CAAC,GAAG;AAAA,IAC5E,MAAM,SAAS;AAAA,MACb;AAAA,MACA,QAAQ,WAAW,KAAK;AAAA,MACxB;AAAA,IACF,CAAC;AAAA,IACD,KAAK,OAAO;AAAA;AAEhB;;;ACTO,MAAM,QAA4B;AAAA,SACf,WAAW;AAAA,EAElB;AAAA,EAEjB,WAAW,CAAC,QAAiB;AAAA,IAC3B,KAAK,SAAS,UAAU,IAAI,IAAI,8BAA8B;AAAA,IAE9D,IAAI,CAAC,KAAK,QAAQ;AAAA,MAChB,MAAM,IAAI,iBACR,2GACA,kBACF;AAAA,IACF;AAAA;AAAA,OAGW,WAAU,CAAC,SAAyD;AAAA,IAC/E,MAAM,SAAS,IAAI,gBAAgB;AAAA,MACjC,WAAW;AAAA,MACX,QAAQ;AAAA,MACR,mBAAmB;AAAA,MACnB,eAAe;AAAA,IACjB,CAAC;AAAA,IAED,MAAM,WAAW,MAAM,MAAM,GAAG,QAAQ,+BAA+B,UAAU;AAAA,MAC/E,SAAS;AAAA,QACP,eAAe,UAAU,KAAK;AAAA,MAChC;AAAA,IACF,CAAC;AAAA,IAED,IAAI,CAAC,SAAS,IAAI;AAAA,MAChB,MAAM,IAAI,iBACR,yBAAyB,SAAS,UAAU,SAAS,cACrD,qBACA,EAAE,SAAS,QAAQ,SAAS,OAAO,CACrC;AAAA,IACF;AAAA,IAEA,MAAM,OAAO,MAAM,SAAS,KAAK;AAAA,IAEjC,OAAO;AAAA,MACL,IAAI,KAAK;AAAA,MACT,MAAM,KAAK;AAAA,MACX,YAAY,KAAK;AAAA,MACjB,UAAU;AAAA,QACR,OAAO,KAAK,SAAS;AAAA,QACrB,QAAQ;AAAA,UACN,MAAM,KAAK,SAAS;AAAA,UACpB,KAAK,KAAK,SAAS;AAAA,QACrB;AAAA,QACA,WAAW,KAAK,SAAS;AAAA,MAC3B;AAAA,IACF;AAAA;AAEJ;",
+  "debugId": "025B276CE136CF8364756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@talosjs/youtube",
+  "description": "YouTube video downloader and metadata extraction library for fetching video information, thumbnails, and media streams",
+  "version": "1.0.0",
+  "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",
+    "npm:publish": "bun publish --tolerate-republish --force --production --access public"
+  },
+  "dependencies": {
+    "@talosjs/exception": "^1.2.10",
+    "@talosjs/http-status": "^1.1.11",
+    "ytdlp-nodejs": "^2.3.5"
+  },
+  "keywords": [
+    "api",
+    "bun",
+    "downloader",
+    "talos",
+    "transcript",
+    "typescript",
+    "video",
+    "youtube",
+    "ytdlp"
+  ]
+}