youtube-transcript-nodejs 0.1.0

package/dist/esm/potoken/AutoPoTokenProvider.js

@@ -0,0 +1,166 @@
+import { BotDetected } from '../errors/index.js';
+import { isTokenFresh } from './types.js';
+/**
+ * Self-contained PoToken provider.
+ *
+ * Uses `bgutils-js` (an optional dependency) to drive YouTube's BotGuard
+ * VM and mint PoTokens locally. No external service required.
+ *
+ * The visitorData is derived from the video id by default; pass a real
+ * one via `setVisitorData()` for stronger session-bound guarantees.
+ *
+ * Note: this provider requires the optional `bgutils-js` dependency. If
+ * it is not installed, generation throws `BotDetected`.
+ */
+const WAA_API_KEY = 'AIzaSyDyT5W0Jh49F30Pqqtyfdf7pDLFKLJoAnw';
+const REQUEST_KEY = 'O43z0dpjhgX20SCx4KAo';
+const CHALLENGE_URL = 'https://jnn-pa.googleapis.com/$rpc/google.internal.waa.v1.Waa/Create';
+/**
+ * Lazy import of bgutils-js. Throws if the package is not installed.
+ */
+async function importBg() {
+    try {
+        const mod = (await import('bgutils-js'));
+        return mod.BG ?? mod;
+    }
+    catch {
+        return null;
+    }
+}
+export class AutoPoTokenProvider {
+    fetchImpl;
+    ttlMs;
+    challengeTtlMs;
+    visitorData;
+    cache = null;
+    constructor(opts = {}) {
+        const f = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        if (!f) {
+            throw new Error('No fetch implementation available');
+        }
+        this.fetchImpl = f;
+        this.ttlMs = opts.ttlMs ?? 12 * 60 * 60 * 1000;
+        this.challengeTtlMs = opts.challengeTtlMs ?? 5 * 60 * 1000;
+        this.visitorData = opts.visitorData;
+    }
+    setVisitorData(visitorData) {
+        this.visitorData = visitorData;
+    }
+    /**
+     * Whether bgutils-js is installed and the provider is usable.
+     */
+    isAvailable() {
+        // Synchronous check via require cache is unreliable; the real check
+        // happens lazily in generateForVideo().
+        try {
+            require.resolve('bgutils-js');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async generateForVideo(videoId) {
+        if (this.cache?.lastVideoId === videoId &&
+            this.cache.lastTokenResult &&
+            isTokenFresh(this.cache.lastTokenResult, 60_000)) {
+            return this.cache.lastTokenResult;
+        }
+        const bg = await importBg();
+        if (!bg) {
+            throw new BotDetected(videoId);
+        }
+        const visitorData = this.visitorData ?? videoId;
+        try {
+            const challengeEntry = await this.getOrLoadChallenge(bg);
+            const botguard = await bg.BotGuardClient.create({
+                program: challengeEntry.challenge.program,
+                globalName: challengeEntry.challenge.globalName,
+                globalObj: challengeEntry.globalObj,
+            });
+            const result = await bg.PoToken.generate({
+                program: challengeEntry.challenge.program,
+                globalName: challengeEntry.challenge.globalName,
+                bgConfig: {
+                    fetch: this.fetchImpl.bind(globalThis),
+                    globalObj: challengeEntry.globalObj,
+                    identifier: visitorData,
+                    requestKey: REQUEST_KEY,
+                },
+            });
+            const tokenResult = {
+                poToken: result.poToken,
+                visitorData,
+                expiresAt: new Date(Date.now() + this.ttlMs),
+            };
+            this.cache = {
+                ...challengeEntry,
+                botguard,
+                lastVideoId: videoId,
+                lastTokenResult: tokenResult,
+            };
+            return tokenResult;
+        }
+        catch (err) {
+            if (err instanceof BotDetected)
+                throw err;
+            throw new BotDetected(videoId);
+        }
+    }
+    async dispose() {
+        if (this.cache?.botguard?.shutdown) {
+            try {
+                await this.cache.botguard.shutdown();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.cache = null;
+    }
+    async getOrLoadChallenge(bg) {
+        if (this.cache && Date.now() - this.cache.fetchedAt < this.challengeTtlMs) {
+            return this.cache;
+        }
+        const response = await this.fetchImpl(CHALLENGE_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json+protobuf',
+                'x-goog-api-key': WAA_API_KEY,
+                'x-user-agent': 'grpc-web-javascript/0.1',
+            },
+            body: JSON.stringify([REQUEST_KEY]),
+        });
+        if (!response.ok) {
+            throw new BotDetected('__challenge__');
+        }
+        const rawData = (await response.json());
+        const parsed = bg.Challenge.parseChallengeData
+            ? bg.Challenge.parseChallengeData(rawData)
+            : rawData;
+        const challenge = parsed;
+        if (!challenge?.program || !challenge?.globalName) {
+            throw new BotDetected('__challenge__');
+        }
+        // Execute interpreter script to populate globalObj[globalName].
+        const globalObj = globalThis ?? {};
+        const script = challenge.interpreterJavascript.privateDoNotAccessOrElseSafeScriptWrappedValue;
+        if (typeof script === 'string' && script.length > 0 && !globalObj[challenge.globalName]) {
+            try {
+                new Function(script)();
+            }
+            catch {
+                throw new BotDetected('__challenge__');
+            }
+        }
+        const entry = {
+            challenge,
+            globalObj,
+            botguard: null,
+            fetchedAt: Date.now(),
+        };
+        this.cache = entry;
+        return entry;
+    }
+}
+//# sourceMappingURL=AutoPoTokenProvider.js.map

package/dist/esm/potoken/AutoPoTokenProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutoPoTokenProvider.js","sourceRoot":"","sources":["../../../src/potoken/AutoPoTokenProvider.ts"],"names":[],"mappings":"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"}

package/dist/esm/potoken/HttpPoTokenProvider.d.ts

@@ -0,0 +1,41 @@
+import { type PoTokenProvider, type TokenResult } from './types.js';
+/**
+ * Configuration for {@link HttpPoTokenProvider}.
+ */
+export interface HttpPoTokenProviderOptions {
+    /** Base URL of the pot provider (e.g. http://localhost:4416). */
+    baseUrl: string;
+    /** Request timeout in ms. */
+    timeoutMs?: number;
+    /** Custom fetch implementation. */
+    fetchImpl?: typeof fetch;
+    /** Token TTL — how long we treat a returned token as fresh. */
+    ttlMs?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Talks to a `bgutil-ytdlp-pot-provider`-compatible HTTP endpoint to fetch
+ * PoTokens. Useful for users who already run the provider as a sidecar.
+ *
+ * Protocol (compatible with bgutil-ytdlp-pot-provider):
+ *
+ *   POST {baseUrl}/get_pot
+ *   Content-Type: application/json
+ *   Body: { video_id, visitor_data? }
+ *   → 200 { po_token, visitor_data, expiration? }
+ *
+ * If the server returns no token, throws `BotDetected`.
+ */
+export declare class HttpPoTokenProvider implements PoTokenProvider {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly ttlMs;
+    private cache;
+    private readonly signal?;
+    constructor(opts: HttpPoTokenProviderOptions);
+    generateForVideo(videoId: string): Promise<TokenResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=HttpPoTokenProvider.d.ts.map

package/dist/esm/potoken/HttpPoTokenProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpPoTokenProvider.d.ts","sourceRoot":"","sources":["../../../src/potoken/HttpPoTokenProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAyD;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;gBAE1B,IAAI,EAAE,0BAA0B;IAetC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAqDvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/esm/potoken/HttpPoTokenProvider.js

@@ -0,0 +1,101 @@
+import { BotDetected } from '../errors/index.js';
+import { isTokenFresh } from './types.js';
+/**
+ * Talks to a `bgutil-ytdlp-pot-provider`-compatible HTTP endpoint to fetch
+ * PoTokens. Useful for users who already run the provider as a sidecar.
+ *
+ * Protocol (compatible with bgutil-ytdlp-pot-provider):
+ *
+ *   POST {baseUrl}/get_pot
+ *   Content-Type: application/json
+ *   Body: { video_id, visitor_data? }
+ *   → 200 { po_token, visitor_data, expiration? }
+ *
+ * If the server returns no token, throws `BotDetected`.
+ */
+export class HttpPoTokenProvider {
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    ttlMs;
+    cache = null;
+    signal;
+    constructor(opts) {
+        if (!opts.baseUrl) {
+            throw new Error('HttpPoTokenProvider requires baseUrl');
+        }
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        const f = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        if (!f) {
+            throw new Error('No fetch implementation available');
+        }
+        this.fetchImpl = f;
+        this.ttlMs = opts.ttlMs ?? 12 * 60 * 60 * 1000; // 12h default
+        this.signal = opts.signal;
+    }
+    async generateForVideo(videoId) {
+        if (this.cache && this.cache.videoId === videoId && isTokenFresh(this.cache.result)) {
+            return this.cache.result;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        this.signal?.addEventListener('abort', () => controller.abort(), { once: true });
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}/get_pot`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ video_id: videoId }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new BotDetected(videoId);
+            }
+            const data = (await response.json());
+            if (!data.po_token || !data.visitor_data) {
+                throw new BotDetected(videoId);
+            }
+            const expiresAt = parseExpiration(data.expiration, this.ttlMs);
+            const result = {
+                poToken: data.po_token,
+                visitorData: data.visitor_data,
+                expiresAt,
+            };
+            this.cache = { videoId, result };
+            return result;
+        }
+        catch (err) {
+            if (err instanceof BotDetected)
+                throw err;
+            // Re-throw AbortError directly so tests / callers can distinguish
+            // timeout from other failures.
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`PoToken request timed out for video "${videoId}"`);
+            }
+            // Wrap network errors as BotDetected since they likely indicate the
+            // provider is down or unreachable.
+            if (process.env['DEBUG_POT']) {
+                console.error('[HttpPoTokenProvider] fetch failed:', err);
+            }
+            throw new BotDetected(videoId);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async dispose() {
+        this.cache = null;
+    }
+}
+function parseExpiration(value, fallbackMs) {
+    if (typeof value === 'number') {
+        return new Date(value > 1e12 ? value : Date.now() + value);
+    }
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return new Date(parsed);
+    }
+    return new Date(Date.now() + fallbackMs);
+}
+//# sourceMappingURL=HttpPoTokenProvider.js.map

package/dist/esm/potoken/HttpPoTokenProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpPoTokenProvider.js","sourceRoot":"","sources":["../../../src/potoken/HttpPoTokenProvider.ts"],"names":[],"mappings":"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"}

package/dist/esm/potoken/NoopPoTokenProvider.d.ts

@@ -0,0 +1,12 @@
+import type { PoTokenProvider, TokenResult } from './types.js';
+/**
+ * Default PoToken provider — always throws.
+ *
+ * This preserves Python-library behavior: ANDROID InnerTube is used as
+ * the primary path, and PoToken is only required if the user explicitly
+ * opts in via a real provider.
+ */
+export declare class NoopPoTokenProvider implements PoTokenProvider {
+    generateForVideo(_videoId: string): Promise<TokenResult>;
+}
+//# sourceMappingURL=NoopPoTokenProvider.d.ts.map

package/dist/esm/potoken/NoopPoTokenProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoopPoTokenProvider.d.ts","sourceRoot":"","sources":["../../../src/potoken/NoopPoTokenProvider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACnD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAG/D"}

package/dist/esm/potoken/NoopPoTokenProvider.js

@@ -0,0 +1,14 @@
+import { PoTokenRequired } from '../errors/index.js';
+/**
+ * Default PoToken provider — always throws.
+ *
+ * This preserves Python-library behavior: ANDROID InnerTube is used as
+ * the primary path, and PoToken is only required if the user explicitly
+ * opts in via a real provider.
+ */
+export class NoopPoTokenProvider {
+    async generateForVideo(_videoId) {
+        throw new PoTokenRequired(_videoId);
+    }
+}
+//# sourceMappingURL=NoopPoTokenProvider.js.map

package/dist/esm/potoken/NoopPoTokenProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoopPoTokenProvider.js","sourceRoot":"","sources":["../../../src/potoken/NoopPoTokenProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IAC9B,KAAK,CAAC,gBAAgB,CAAC,QAAgB;QACrC,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/esm/potoken/baseScriptCache.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Simple in-memory cache for YouTube's base.js player script.
+ *
+ * base.js (~2.5MB minified) changes occasionally; we cache it for
+ * `ttlMs` (default 5 minutes) to avoid repeated downloads. The AutoPoTokenProvider
+ * owns the cache.
+ */
+export interface BaseScriptCacheOptions {
+    /** Time-to-live in ms (default 5 minutes). */
+    ttlMs?: number;
+    /** Custom fetch implementation. */
+    fetchImpl?: typeof fetch;
+}
+export declare class BaseScriptCache {
+    private readonly ttlMs;
+    private readonly fetchImpl;
+    private cached;
+    constructor(opts?: BaseScriptCacheOptions);
+    /**
+     * Get base.js content. Re-downloads when cache is stale or missing.
+     */
+    get(baseJsUrl: string): Promise<string>;
+    /** Force the next `get()` to re-download. */
+    invalidate(): void;
+    /** Inspect cache state (for tests). */
+    isFresh(): boolean;
+}
+//# sourceMappingURL=baseScriptCache.d.ts.map

package/dist/esm/potoken/baseScriptCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseScriptCache.d.ts","sourceRoot":"","sources":["../../../src/potoken/baseScriptCache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,MAAM,CAAuD;gBAEzD,IAAI,GAAE,sBAA2B;IAS7C;;OAEG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAa7C,6CAA6C;IAC7C,UAAU,IAAI,IAAI;IAIlB,uCAAuC;IACvC,OAAO,IAAI,OAAO;CAGnB"}

package/dist/esm/potoken/baseScriptCache.js

@@ -0,0 +1,37 @@
+export class BaseScriptCache {
+    ttlMs;
+    fetchImpl;
+    cached = null;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? 5 * 60 * 1000;
+        const f = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        if (!f) {
+            throw new Error('No fetch implementation available');
+        }
+        this.fetchImpl = f;
+    }
+    /**
+     * Get base.js content. Re-downloads when cache is stale or missing.
+     */
+    async get(baseJsUrl) {
+        if (this.cached && Date.now() - this.cached.fetchedAt < this.ttlMs) {
+            return this.cached.content;
+        }
+        const response = await this.fetchImpl(baseJsUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch base.js: ${response.status} ${response.statusText}`);
+        }
+        const content = await response.text();
+        this.cached = { content, fetchedAt: Date.now() };
+        return content;
+    }
+    /** Force the next `get()` to re-download. */
+    invalidate() {
+        this.cached = null;
+    }
+    /** Inspect cache state (for tests). */
+    isFresh() {
+        return this.cached !== null && Date.now() - this.cached.fetchedAt < this.ttlMs;
+    }
+}
+//# sourceMappingURL=baseScriptCache.js.map

package/dist/esm/potoken/baseScriptCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseScriptCache.js","sourceRoot":"","sources":["../../../src/potoken/baseScriptCache.ts"],"names":[],"mappings":"AAcA,MAAM,OAAO,eAAe;IACT,KAAK,CAAS;IACd,SAAS,CAAe;IACjC,MAAM,GAAkD,IAAI,CAAC;IAErE,YAAY,OAA+B,EAAE;QAC3C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACzC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC9D,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,SAAiB;QACzB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACnE,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QAC7B,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACjD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,6CAA6C;IAC7C,UAAU;QACR,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,uCAAuC;IACvC,OAAO;QACL,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC;IACjF,CAAC;CACF"}

package/dist/esm/potoken/index.d.ts

@@ -0,0 +1,10 @@
+export { NoopPoTokenProvider } from './NoopPoTokenProvider.js';
+export { HttpPoTokenProvider } from './HttpPoTokenProvider.js';
+export type { HttpPoTokenProviderOptions } from './HttpPoTokenProvider.js';
+export { AutoPoTokenProvider } from './AutoPoTokenProvider.js';
+export type { AutoPoTokenProviderOptions } from './AutoPoTokenProvider.js';
+export { BaseScriptCache } from './baseScriptCache.js';
+export type { BaseScriptCacheOptions } from './baseScriptCache.js';
+export { isTokenFresh } from './types.js';
+export type { PoTokenProvider, TokenResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/potoken/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/potoken/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/potoken/index.js

@@ -0,0 +1,6 @@
+export { NoopPoTokenProvider } from './NoopPoTokenProvider.js';
+export { HttpPoTokenProvider } from './HttpPoTokenProvider.js';
+export { AutoPoTokenProvider } from './AutoPoTokenProvider.js';
+export { BaseScriptCache } from './baseScriptCache.js';
+export { isTokenFresh } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/potoken/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/potoken/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/potoken/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A successful PoToken generation result.
+ */
+export interface TokenResult {
+    /** The PoToken (`identityToken`) string. */
+    readonly poToken: string;
+    /** The visitorData (`VISITOR_DATA` cookie value). */
+    readonly visitorData: string;
+    /**
+     * Wall-clock time after which this token should be considered expired.
+     * Providers may set this conservatively (e.g. 12h).
+     */
+    readonly expiresAt: Date;
+}
+/**
+ * A pluggable PoToken provider.
+ *
+ * Implementations include:
+ *  - {@link NoopPoTokenProvider} (default; throws PoTokenRequired)
+ *  - {@link HttpPoTokenProvider} (calls an external HTTP endpoint)
+ *  - {@link AutoPoTokenProvider} (self-contained via bgutils-js)
+ */
+export interface PoTokenProvider {
+    /**
+     * Generate (or return a cached) PoToken for the given video.
+     *
+     * Providers are responsible for caching; the facade does not cache
+     * results across calls.
+     *
+     * @throws if generation fails irrecoverably
+     */
+    generateForVideo(videoId: string): Promise<TokenResult>;
+    /** Optional cleanup (e.g. close HTTP clients, release timers). */
+    dispose?(): Promise<void> | void;
+}
+/**
+ * Internal: returns true if a token is still fresh (with a safety margin).
+ */
+export declare function isTokenFresh(result: TokenResult, safetyMarginMs?: number): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/potoken/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/potoken/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAExD,kEAAkE;IAClE,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,GAAE,MAAe,GAAG,OAAO,CAE1F"}

package/dist/esm/potoken/types.js

@@ -0,0 +1,7 @@
+/**
+ * Internal: returns true if a token is still fresh (with a safety margin).
+ */
+export function isTokenFresh(result, safetyMarginMs = 60_000) {
+    return result.expiresAt.getTime() - safetyMarginMs > Date.now();
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/potoken/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/potoken/types.ts"],"names":[],"mappings":"AAsCA;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB,EAAE,iBAAyB,MAAM;IAC/E,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAClE,CAAC"}

package/dist/esm/util/htmlSanitizer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sanitize a piece of HTML-formatted transcript text into plain text
+ * with HTML entities decoded.
+ *
+ * YouTube occasionally double-encodes entities (`'` instead of `'`),
+ * so we decode repeatedly until the string stabilises (capped at 5 passes
+ * to defend against pathological cases).
+ *
+ * @param raw  raw `<text>` inner content from the timedtext XML
+ * @param preserveFormatting  when true, retain formatting tags listed above
+ */
+export declare function sanitizeTranscriptText(raw: string, preserveFormatting?: boolean): string;
+/**
+ * Decode HTML entities only (no tag stripping). Useful for diagnostics.
+ */
+export declare function decodeHtmlEntities(text: string): string;
+/**
+ * Tags retained when `preserveFormatting=true`. Exposed for tests.
+ */
+export declare const PRESERVED_FORMATTING_TAGS: readonly string[];
+//# sourceMappingURL=htmlSanitizer.d.ts.map

package/dist/esm/util/htmlSanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlSanitizer.d.ts","sourceRoot":"","sources":["../../../src/util/htmlSanitizer.ts"],"names":[],"mappings":"AAyCA;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,kBAAkB,GAAE,OAAe,GAAG,MAAM,CAS/F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAAoB,CAAC"}

package/dist/esm/util/htmlSanitizer.js

@@ -0,0 +1,69 @@
+import he from 'he';
+/**
+ * HTML / formatting helpers for transcript text.
+ *
+ * Mirrors the Python library's `_TranscriptParser`:
+ * - `he.decode` (equivalent to Python's `html.unescape`) for entity resolution
+ * - `preserveFormatting=true` keeps a small set of formatting tags and
+ *   strips everything else (via negative-lookahead regex from Python source)
+ * - `preserveFormatting=false` strips every tag
+ */
+const FORMATTING_TAGS = [
+    'strong',
+    'em',
+    'b',
+    'i',
+    'mark',
+    'small',
+    'del',
+    'ins',
+    'sub',
+    'sup',
+];
+/** Regex that strips all HTML tags. */
+const STRIP_ALL_TAGS_REGEX = /<[^>]*>/g;
+/**
+ * Regex that strips every tag EXCEPT a small set of formatting tags.
+ *
+ * Constructed once at module load. Note: `[^>]*?` keeps each match confined
+ * to a single tag, so adjacent tags (e.g. `<font>x</font>`) are stripped
+ * independently rather than swallowed together.
+ */
+const STRIP_BUT_FORMATTING_REGEX = (() => {
+    const alt = FORMATTING_TAGS.join('|');
+    // Negative lookahead: don't match open/close of the formatting tags.
+    return new RegExp(`<\\/?(?!\\/?(${alt})\\b)[^>]*>`, 'gi');
+})();
+/**
+ * Sanitize a piece of HTML-formatted transcript text into plain text
+ * with HTML entities decoded.
+ *
+ * YouTube occasionally double-encodes entities (`&amp;#39;` instead of `&#39;`),
+ * so we decode repeatedly until the string stabilises (capped at 5 passes
+ * to defend against pathological cases).
+ *
+ * @param raw  raw `<text>` inner content from the timedtext XML
+ * @param preserveFormatting  when true, retain formatting tags listed above
+ */
+export function sanitizeTranscriptText(raw, preserveFormatting = false) {
+    let unescaped = raw;
+    for (let i = 0; i < 5; i++) {
+        const next = he.decode(unescaped);
+        if (next === unescaped)
+            break;
+        unescaped = next;
+    }
+    const regex = preserveFormatting ? STRIP_BUT_FORMATTING_REGEX : STRIP_ALL_TAGS_REGEX;
+    return unescaped.replace(regex, '');
+}
+/**
+ * Decode HTML entities only (no tag stripping). Useful for diagnostics.
+ */
+export function decodeHtmlEntities(text) {
+    return he.decode(text);
+}
+/**
+ * Tags retained when `preserveFormatting=true`. Exposed for tests.
+ */
+export const PRESERVED_FORMATTING_TAGS = FORMATTING_TAGS;
+//# sourceMappingURL=htmlSanitizer.js.map

package/dist/esm/util/htmlSanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlSanitizer.js","sourceRoot":"","sources":["../../../src/util/htmlSanitizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB;;;;;;;;GAQG;AAEH,MAAM,eAAe,GAAG;IACtB,QAAQ;IACR,IAAI;IACJ,GAAG;IACH,GAAG;IACH,MAAM;IACN,OAAO;IACP,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACG,CAAC;AAEX,uCAAuC;AACvC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,0BAA0B,GAAW,CAAC,GAAG,EAAE;IAC/C,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,qEAAqE;IACrE,OAAO,IAAI,MAAM,CAAC,gBAAgB,GAAG,aAAa,EAAE,IAAI,CAAC,CAAC;AAC5D,CAAC,CAAC,EAAE,CAAC;AAEL;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,qBAA8B,KAAK;IACrF,IAAI,SAAS,GAAG,GAAG,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM;QAC9B,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,oBAAoB,CAAC;IACrF,OAAO,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB,eAAe,CAAC"}

package/dist/esm/util/proxyUrl.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parsed proxy URL.
+ */
+export interface ParsedProxyUrl {
+    /** Protocol: http | https | socks | socks4 | socks5 */
+    readonly protocol: string;
+    /** Username, if provided. */
+    readonly username: string | undefined;
+    /** Password, if provided. */
+    readonly password: string | undefined;
+    /** Hostname (no port). */
+    readonly host: string;
+    /** Port, if provided. */
+    readonly port: number | undefined;
+}
+/**
+ * Parse a proxy URL like `http://user:pass@host:1080` or `socks5://host:1080`.
+ *
+ * Returns `null` if the URL is malformed.
+ */
+export declare function parseProxyUrl(url: string): ParsedProxyUrl | null;
+//# sourceMappingURL=proxyUrl.d.ts.map