youtube-transcript-plus 1.1.0 → 1.1.2

package/README.md

@@ -58,19 +58,37 @@ fetchTranscript('videoId_or_URL', {
 
 ### Custom Fetch Functions
 
-You can inject custom `videoFetch` and `transcriptFetch` functions to modify the fetch behavior, such as using a proxy or custom headers.
+You can inject custom `videoFetch`, `playerFetch`, and `transcriptFetch` functions to modify the fetch behavior, such as using a proxy or custom headers. The library makes three types of HTTP requests:
+
+1. **`videoFetch`**: Fetches the YouTube video page (GET request)
+2. **`playerFetch`**: Calls YouTube's Innertube API to get caption tracks (POST request)
+3. **`transcriptFetch`**: Downloads the actual transcript data (GET request)
 
 ```javascript
 fetchTranscript('videoId_or_URL', {
   videoFetch: async ({ url, lang, userAgent }) => {
+    // Custom logic for video page fetch (GET)
+    return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
+      headers: {
+        ...(lang && { 'Accept-Language': lang }),
+        'User-Agent': userAgent,
+      },
+    });
+  },
+  playerFetch: async ({ url, method, body, headers, lang, userAgent }) => {
+    // Custom logic for Innertube API call (POST)
     return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
+      method,
       headers: {
         ...(lang && { 'Accept-Language': lang }),
         'User-Agent': userAgent,
+        ...headers,
       },
+      body,
     });
   },
   transcriptFetch: async ({ url, lang, userAgent }) => {
+    // Custom logic for transcript data fetch (GET)
     return fetch(`https://my-proxy-server.com/?url=${encodeURIComponent(url)}`, {
       headers: {
         ...(lang && { 'Accept-Language': lang }),
@@ -187,6 +205,7 @@ The repository includes several example files in the `example/` directory to dem
 3. **`fs-caching-usage.js`**: Demonstrates how to use the `FsCache` to cache transcripts on the file system with a 1-day TTL.
 4. **`language-usage.js`**: Shows how to fetch a transcript in a specific language (e.g., French).
 5. **`proxy-usage.js`**: Demonstrates how to use a proxy server to fetch transcripts, which can be useful for bypassing rate limits or accessing restricted content.
+6. **`custom-fetch-usage.js`**: Shows how to use all three custom fetch functions (`videoFetch`, `playerFetch`, `transcriptFetch`) with logging and custom headers.
 
 These examples can be found in the `example/` directory of the repository.
 
@@ -203,8 +222,9 @@ Fetches the transcript for a YouTube video.
   - **`cache`**: Custom caching strategy.
   - **`cacheTTL`**: Time-to-live for cache entries in milliseconds.
   - **`disableHttps`**: Set to `true` to use HTTP instead of HTTPS for YouTube requests.
-  - **`videoFetch`**: Custom fetch function for the video page request.
-  - **`transcriptFetch`**: Custom fetch function for the transcript request.
+  - **`videoFetch`**: Custom fetch function for the video page request (GET).
+  - **`playerFetch`**: Custom fetch function for the YouTube Innertube API request (POST).
+  - **`transcriptFetch`**: Custom fetch function for the transcript data request (GET).
 
 Returns a `Promise<TranscriptResponse[]>` where each item in the array represents a transcript segment with the following properties:
 

package/dist/constants.d.ts

@@ -1,3 +1,4 @@
 export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 export declare const RE_YOUTUBE: RegExp;
 export declare const RE_XML_TRANSCRIPT: RegExp;
+export declare const DEFAULT_CACHE_TTL = 3600000;

package/dist/index.d.ts

@@ -7,9 +7,7 @@ import { TranscriptConfig, TranscriptResponse } from './types';
  */
 export declare class YoutubeTranscript {
     private config?;
-    constructor(config?: TranscriptConfig & {
-        cacheTTL?: number;
-    });
+    constructor(config?: TranscriptConfig);
     fetchTranscript(videoId: string): Promise<TranscriptResponse[]>;
     static fetchTranscript(videoId: string, config?: TranscriptConfig): Promise<TranscriptResponse[]>;
 }

package/dist/types.d.ts

@@ -2,22 +2,23 @@ export interface CacheStrategy {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ttl?: number): Promise<void>;
 }
+export interface FetchParams {
+    url: string;
+    lang?: string;
+    userAgent?: string;
+    method?: 'GET' | 'POST';
+    body?: string;
+    headers?: Record<string, string>;
+}
 export interface TranscriptConfig {
     lang?: string;
     userAgent?: string;
     cache?: CacheStrategy;
     cacheTTL?: number;
     disableHttps?: boolean;
-    videoFetch?: (params: {
-        url: string;
-        lang?: string;
-        userAgent?: string;
-    }) => Promise<Response>;
-    transcriptFetch?: (params: {
-        url: string;
-        lang?: string;
-        userAgent?: string;
-    }) => Promise<Response>;
+    videoFetch?: (params: FetchParams) => Promise<Response>;
+    transcriptFetch?: (params: FetchParams) => Promise<Response>;
+    playerFetch?: (params: FetchParams) => Promise<Response>;
 }
 export interface TranscriptResponse {
     text: string;

package/dist/utils.d.ts

@@ -1,6 +1,3 @@
+import { FetchParams } from './types';
 export declare function retrieveVideoId(videoId: string): string;
-export declare function defaultFetch({ url, lang, userAgent, }: {
-    url: string;
-    lang?: string;
-    userAgent?: string;
-}): Promise<Response>;
+export declare function defaultFetch(params: FetchParams): Promise<Response>;

package/dist/youtube-transcript-plus.js

@@ -36,6 +36,7 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
 const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
 const RE_YOUTUBE = /(?:v=|\/|v\/|embed\/|watch\?.*v=|youtu\.be\/|\/v\/|e\/|watch\?.*vi?=|\/embed\/|\/v\/|vi?\/|watch\?.*vi?=|youtu\.be\/|\/vi?\/|\/e\/)([a-zA-Z0-9_-]{11})/i;
 const RE_XML_TRANSCRIPT = /<text start="([^"]*)" dur="([^"]*)">([^<]*)<\/text>/g;
+const DEFAULT_CACHE_TTL = 3600000; // 1 hour in milliseconds
 
 class YoutubeTranscriptTooManyRequestError extends Error {
     constructor() {
@@ -84,16 +85,23 @@ function retrieveVideoId(videoId) {
     }
     throw new YoutubeTranscriptInvalidVideoIdError();
 }
-function defaultFetch(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ url, lang, userAgent, }) {
-        return fetch(url, {
-            headers: Object.assign(Object.assign({}, (lang && { 'Accept-Language': lang })), { 'User-Agent': userAgent || DEFAULT_USER_AGENT }),
-        });
+function defaultFetch(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { url, lang, userAgent, method = 'GET', body, headers = {} } = params;
+        const fetchHeaders = Object.assign(Object.assign({ 'User-Agent': userAgent || DEFAULT_USER_AGENT }, (lang && { 'Accept-Language': lang })), headers);
+        const fetchOptions = {
+            method,
+            headers: fetchHeaders,
+        };
+        if (body && method === 'POST') {
+            fetchOptions.body = body;
+        }
+        return fetch(url, fetchOptions);
     });
 }
 
 class FsCache {
-    constructor(cacheDir = './cache', defaultTTL = 3600000) {
+    constructor(cacheDir = './cache', defaultTTL = DEFAULT_CACHE_TTL) {
         this.cacheDir = cacheDir;
         this.defaultTTL = defaultTTL;
         fs.mkdir(cacheDir, { recursive: true }).catch(() => { });
@@ -109,7 +117,7 @@ class FsCache {
                 }
                 yield fs.unlink(filePath);
             }
-            catch (error) { }
+            catch (_error) { }
             return null;
         });
     }
@@ -123,9 +131,8 @@ class FsCache {
 }
 
 class InMemoryCache {
-    constructor(defaultTTL = 3600000) {
+    constructor(defaultTTL = DEFAULT_CACHE_TTL) {
         this.cache = new Map();
-        // 1 hour default TTL
         this.defaultTTL = defaultTTL;
     }
     get(key) {
@@ -158,7 +165,7 @@ class YoutubeTranscript {
     }
     fetchTranscript(videoId) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
             const identifier = retrieveVideoId(videoId);
             const lang = (_a = this.config) === null || _a === void 0 ? void 0 : _a.lang;
             const userAgent = (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.userAgent) !== null && _c !== void 0 ? _c : DEFAULT_USER_AGENT;
@@ -172,7 +179,7 @@ class YoutubeTranscript {
                     try {
                         return JSON.parse(cached);
                     }
-                    catch (_o) {
+                    catch (_p) {
                         // ignore parse errors and continue
                     }
                 }
@@ -212,19 +219,25 @@ class YoutubeTranscript {
                 },
                 videoId: identifier,
             };
-            // Use global fetch for the POST. No public interface change.
-            const playerRes = yield fetch(playerEndpoint, {
+            // Use configurable playerFetch for the POST to allow custom fetch logic.
+            const playerFetchParams = {
+                url: playerEndpoint,
                 method: 'POST',
-                headers: Object.assign({ 'Content-Type': 'application/json', 'User-Agent': userAgent }, (lang ? { 'Accept-Language': lang } : {})),
+                lang,
+                userAgent,
+                headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(playerBody),
-            });
+            };
+            const playerRes = ((_h = this.config) === null || _h === void 0 ? void 0 : _h.playerFetch)
+                ? yield this.config.playerFetch(playerFetchParams)
+                : yield defaultFetch(playerFetchParams);
             if (!playerRes.ok) {
                 throw new YoutubeTranscriptVideoUnavailableError(identifier);
             }
             const playerJson = yield playerRes.json();
-            const tracklist = (_j = (_h = playerJson === null || playerJson === void 0 ? void 0 : playerJson.captions) === null || _h === void 0 ? void 0 : _h.playerCaptionsTracklistRenderer) !== null && _j !== void 0 ? _j : playerJson === null || playerJson === void 0 ? void 0 : playerJson.playerCaptionsTracklistRenderer;
+            const tracklist = (_k = (_j = playerJson === null || playerJson === void 0 ? void 0 : playerJson.captions) === null || _j === void 0 ? void 0 : _j.playerCaptionsTracklistRenderer) !== null && _k !== void 0 ? _k : playerJson === null || playerJson === void 0 ? void 0 : playerJson.playerCaptionsTracklistRenderer;
             const tracks = tracklist === null || tracklist === void 0 ? void 0 : tracklist.captionTracks;
-            const isPlayableOk = ((_k = playerJson === null || playerJson === void 0 ? void 0 : playerJson.playabilityStatus) === null || _k === void 0 ? void 0 : _k.status) === 'OK';
+            const isPlayableOk = ((_l = playerJson === null || playerJson === void 0 ? void 0 : playerJson.playabilityStatus) === null || _l === void 0 ? void 0 : _l.status) === 'OK';
             // If `captions` is entirely missing, treat as "not available"
             if (!(playerJson === null || playerJson === void 0 ? void 0 : playerJson.captions) || !tracklist) {
                 // If video is playable but captions aren’t provided, treat as "disabled"
@@ -250,11 +263,11 @@ class YoutubeTranscript {
                 throw new YoutubeTranscriptNotAvailableError(identifier);
             }
             transcriptURL = transcriptURL.replace(/&fmt=[^&]+$/, '');
-            if ((_l = this.config) === null || _l === void 0 ? void 0 : _l.disableHttps) {
+            if ((_m = this.config) === null || _m === void 0 ? void 0 : _m.disableHttps) {
                 transcriptURL = transcriptURL.replace(/^https:\/\//, 'http://');
             }
             // 5) Fetch transcript XML using the same hook surface as before
-            const transcriptResponse = ((_m = this.config) === null || _m === void 0 ? void 0 : _m.transcriptFetch)
+            const transcriptResponse = ((_o = this.config) === null || _o === void 0 ? void 0 : _o.transcriptFetch)
                 ? yield this.config.transcriptFetch({ url: transcriptURL, lang, userAgent })
                 : yield defaultFetch({ url: transcriptURL, lang, userAgent });
             if (!transcriptResponse.ok) {
@@ -281,7 +294,7 @@ class YoutubeTranscript {
                 try {
                     yield cache.set(cacheKey, JSON.stringify(transcript), cacheTTL);
                 }
-                catch (_p) {
+                catch (_q) {
                     // non-fatal
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youtube-transcript-plus",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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,24 @@
     ]
   },
   "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/*"