youtube-transcript-plus 1.1.1 → 1.2.0

package/README.md

@@ -169,7 +169,7 @@ fetchTranscript('videoId_or_URL', {
 
 ### Error Handling
 
-The library throws specific errors for different failure scenarios. Make sure to handle them appropriately.
+The library throws specific errors for different failure scenarios. Each error includes a `videoId` property for programmatic handling.
 
 ```javascript
 import {
@@ -183,13 +183,13 @@ fetchTranscript('videoId_or_URL')
   .then(console.log)
   .catch((error) => {
     if (error instanceof YoutubeTranscriptVideoUnavailableError) {
-      console.error('Video is unavailable:', error.message);
+      console.error('Video is unavailable:', error.videoId);
     } else if (error instanceof YoutubeTranscriptDisabledError) {
-      console.error('Transcripts are disabled for this video:', error.message);
+      console.error('Transcripts are disabled:', error.videoId);
     } else if (error instanceof YoutubeTranscriptNotAvailableError) {
-      console.error('No transcript available:', error.message);
+      console.error('No transcript available:', error.videoId);
     } else if (error instanceof YoutubeTranscriptNotAvailableLanguageError) {
-      console.error('Transcript not available in the specified language:', error.message);
+      console.error('Language not available:', error.lang, error.availableLangs);
     } else {
       console.error('An unexpected error occurred:', error.message);
     }
@@ -209,6 +209,14 @@ The repository includes several example files in the `example/` directory to dem
 
 These examples can be found in the `example/` directory of the repository.
 
+### TypeScript Types
+
+All types are exported for TypeScript consumers:
+
+```typescript
+import type { TranscriptConfig, TranscriptResponse, FetchParams, CacheStrategy } from 'youtube-transcript-plus';
+```
+
 ### API
 
 ### `fetchTranscript(videoId: string, config?: TranscriptConfig)`
@@ -237,10 +245,11 @@ Returns a `Promise<TranscriptResponse[]>` where each item in the array represent
 
 The library throws the following errors:
 
-- **`YoutubeTranscriptVideoUnavailableError`**: The video is unavailable or has been removed.
-- **`YoutubeTranscriptDisabledError`**: Transcripts are disabled for the video.
-- **`YoutubeTranscriptNotAvailableError`**: No transcript is available for the video.
-- **`YoutubeTranscriptNotAvailableLanguageError`**: The transcript is not available in the specified language.
+- **`YoutubeTranscriptVideoUnavailableError`**: The video is unavailable or has been removed. Properties: `videoId`.
+- **`YoutubeTranscriptDisabledError`**: Transcripts are disabled for the video. Properties: `videoId`.
+- **`YoutubeTranscriptNotAvailableError`**: No transcript is available for the video. Properties: `videoId`.
+- **`YoutubeTranscriptNotAvailableLanguageError`**: The transcript is not available in the specified language. Properties: `videoId`, `lang`, `availableLangs`.
+- **`YoutubeTranscriptTooManyRequestError`**: YouTube is rate-limiting requests from your IP.
 - **`YoutubeTranscriptInvalidVideoIdError`**: The provided video ID or URL is invalid.
 
 ## License

package/dist/__tests__/cache/fs-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/cache/in-memory-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache/fs-cache.d.ts

@@ -2,6 +2,7 @@ import { CacheStrategy } from '../types';
 export declare class FsCache implements CacheStrategy {
     private cacheDir;
     private defaultTTL;
+    private ready;
     constructor(cacheDir?: string, defaultTTL?: number);
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ttl?: number): Promise<void>;

package/dist/errors.d.ts

@@ -2,15 +2,21 @@ export declare class YoutubeTranscriptTooManyRequestError extends Error {
     constructor();
 }
 export declare class YoutubeTranscriptVideoUnavailableError extends Error {
+    readonly videoId: string;
     constructor(videoId: string);
 }
 export declare class YoutubeTranscriptDisabledError extends Error {
+    readonly videoId: string;
     constructor(videoId: string);
 }
 export declare class YoutubeTranscriptNotAvailableError extends Error {
+    readonly videoId: string;
     constructor(videoId: string);
 }
 export declare class YoutubeTranscriptNotAvailableLanguageError extends Error {
+    readonly videoId: string;
+    readonly lang: string;
+    readonly availableLangs: string[];
     constructor(lang: string, availableLangs: string[], videoId: string);
 }
 export declare class YoutubeTranscriptInvalidVideoIdError extends Error {

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export declare class YoutubeTranscript {
     fetchTranscript(videoId: string): Promise<TranscriptResponse[]>;
     static fetchTranscript(videoId: string, config?: TranscriptConfig): Promise<TranscriptResponse[]>;
 }
-export type { CacheStrategy } from './types';
+export type { CacheStrategy, TranscriptConfig, TranscriptResponse, FetchParams } from './types';
 export { InMemoryCache, FsCache } from './cache';
 export * from './errors';
 export declare const fetchTranscript: typeof YoutubeTranscript.fetchTranscript;

package/dist/types.d.ts

@@ -24,5 +24,5 @@ export interface TranscriptResponse {
     text: string;
     duration: number;
     offset: number;
-    lang?: string;
+    lang: string;
 }

package/dist/utils.d.ts

@@ -1,3 +1,4 @@
 import { FetchParams } from './types';
+export declare function decodeXmlEntities(text: string): string;
 export declare function retrieveVideoId(videoId: string): string;
 export declare function defaultFetch(params: FetchParams): Promise<Response>;

package/dist/youtube-transcript-plus.js

@@ -48,24 +48,30 @@ class YoutubeTranscriptVideoUnavailableError extends Error {
     constructor(videoId) {
         super(`The video with ID "${videoId}" is no longer available or has been removed. Please check the video URL or ID and try again.`);
         this.name = 'YoutubeTranscriptVideoUnavailableError';
+        this.videoId = videoId;
     }
 }
 class YoutubeTranscriptDisabledError extends Error {
     constructor(videoId) {
         super(`Transcripts are disabled for the video with ID "${videoId}". This may be due to the video owner disabling captions or the video not supporting transcripts.`);
         this.name = 'YoutubeTranscriptDisabledError';
+        this.videoId = videoId;
     }
 }
 class YoutubeTranscriptNotAvailableError extends Error {
     constructor(videoId) {
         super(`No transcripts are available for the video with ID "${videoId}". This may be because the video does not have captions or the captions are not accessible.`);
         this.name = 'YoutubeTranscriptNotAvailableError';
+        this.videoId = videoId;
     }
 }
 class YoutubeTranscriptNotAvailableLanguageError extends Error {
     constructor(lang, availableLangs, videoId) {
         super(`No transcripts are available in "${lang}" for the video with ID "${videoId}". Available languages: ${availableLangs.join(', ')}. Please try a different language.`);
         this.name = 'YoutubeTranscriptNotAvailableLanguageError';
+        this.videoId = videoId;
+        this.lang = lang;
+        this.availableLangs = availableLangs;
     }
 }
 class YoutubeTranscriptInvalidVideoIdError extends Error {
@@ -75,8 +81,21 @@ class YoutubeTranscriptInvalidVideoIdError extends Error {
     }
 }
 
+const RE_VIDEO_ID = /^[a-zA-Z0-9_-]{11}$/;
+const XML_ENTITIES = {
+    '&': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&#39;': "'",
+    '&apos;': "'",
+};
+const RE_XML_ENTITY = /&(?:amp|lt|gt|quot|apos|#39);/g;
+function decodeXmlEntities(text) {
+    return text.replace(RE_XML_ENTITY, (match) => { var _a; return (_a = XML_ENTITIES[match]) !== null && _a !== void 0 ? _a : match; });
+}
 function retrieveVideoId(videoId) {
-    if (videoId.length === 11) {
+    if (RE_VIDEO_ID.test(videoId)) {
         return videoId;
     }
     const matchId = videoId.match(RE_YOUTUBE);
@@ -100,15 +119,19 @@ function defaultFetch(params) {
     });
 }
 
+function sanitizeKey(key) {
+    return key.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
 class FsCache {
     constructor(cacheDir = './cache', defaultTTL = DEFAULT_CACHE_TTL) {
         this.cacheDir = cacheDir;
         this.defaultTTL = defaultTTL;
-        fs.mkdir(cacheDir, { recursive: true }).catch(() => { });
+        this.ready = fs.mkdir(cacheDir, { recursive: true }).then(() => { });
     }
     get(key) {
         return __awaiter(this, void 0, void 0, function* () {
-            const filePath = path.join(this.cacheDir, key);
+            yield this.ready;
+            const filePath = path.join(this.cacheDir, sanitizeKey(key));
             try {
                 const data = yield fs.readFile(filePath, 'utf-8');
                 const { value, expires } = JSON.parse(data);
@@ -117,13 +140,14 @@ class FsCache {
                 }
                 yield fs.unlink(filePath);
             }
-            catch (error) { }
+            catch (_error) { }
             return null;
         });
     }
     set(key, value, ttl) {
         return __awaiter(this, void 0, void 0, function* () {
-            const filePath = path.join(this.cacheDir, key);
+            yield this.ready;
+            const filePath = path.join(this.cacheDir, sanitizeKey(key));
             const expires = Date.now() + (ttl !== null && ttl !== void 0 ? ttl : this.defaultTTL);
             yield fs.writeFile(filePath, JSON.stringify({ value, expires }), 'utf-8');
         });
@@ -209,7 +233,7 @@ class YoutubeTranscript {
             }
             const apiKey = apiKeyMatch[1];
             // 3) Call Innertube player as ANDROID client to retrieve captionTracks
-            const playerEndpoint = `https://www.youtube.com/youtubei/v1/player?key=${apiKey}`;
+            const playerEndpoint = `${protocol}://www.youtube.com/youtubei/v1/player?key=${apiKey}`;
             const playerBody = {
                 context: {
                     client: {
@@ -262,7 +286,7 @@ class YoutubeTranscript {
             if (!transcriptURL) {
                 throw new YoutubeTranscriptNotAvailableError(identifier);
             }
-            transcriptURL = transcriptURL.replace(/&fmt=[^&]+$/, '');
+            transcriptURL = transcriptURL.replace(/&fmt=[^&]+/, '');
             if ((_m = this.config) === null || _m === void 0 ? void 0 : _m.disableHttps) {
                 transcriptURL = transcriptURL.replace(/^https:\/\//, 'http://');
             }
@@ -281,7 +305,7 @@ class YoutubeTranscript {
             // 6) Parse XML into the existing TranscriptResponse shape
             const results = [...transcriptBody.matchAll(RE_XML_TRANSCRIPT)];
             const transcript = results.map((m) => ({
-                text: m[3],
+                text: decodeXmlEntities(m[3]),
                 duration: parseFloat(m[2]),
                 offset: parseFloat(m[1]),
                 lang: lang !== null && lang !== void 0 ? lang : selectedTrack.languageCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youtube-transcript-plus",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Fetch transcript from a YouTube video",
   "type": "module",
   "main": "dist/youtube-transcript-plus.js",
@@ -9,8 +9,10 @@
   "scripts": {
     "build": "rollup -c",
     "format": "prettier --write 'src/**/*.ts'",
+    "lint": "eslint .",
     "test": "jest",
     "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit",
     "prepare": "husky"
   },
   "author": "ericmmartin",
@@ -29,18 +31,23 @@
     ]
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@types/jest": "^30.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.5.0",
     "https-proxy-agent": "^7.0.6",
     "husky": "^9.1.7",
     "jest": "^30.0.5",
     "lint-staged": "^16.1.5",
+    "nock": "^14.0.10",
     "prettier": "^3.6.2",
     "rollup": "^4.46.4",
-    "rollup-plugin-typescript": "^1.0.1",
     "rollup-plugin-typescript2": "^0.36.0",
     "ts-jest": "^29.4.1",
     "tslib": "^2.8.1",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.50.0"
   },
   "files": [
     "dist/*"