Repository navigation
A remediation release. 1.x was not importable in standard Node ESM; this release fixes that and ships a proper dual ESM/CJS build, plus parsing, security, and type-surface hardening.
⚠️ Breaking
- The
exportsmap was restructured:importresolves the ESM build,requireresolves the CJS build, and TypeScript resolves the matching declarations for each. fetchTranscript(id, ['en'], false, 'text')→ options object:fetchTranscript(id, { languages: ['en'], formatter: 'text' }). The positional form still works but is deprecated.- Requires Node >= 18.
Fixed
- Critical:
importfrom a"type": "module"project no longer fails withERR_MODULE_NOT_FOUND(compiled ESM emitted extensionless relative re-exports). - Critical:
new YouTubeTranscriptApi()no longer throwsrequire is not definedin ESM (require('http')/require('https')in an ES module). - Robust
ytInitialPlayerResponseand captions extraction via a string/escape-aware brace-depth scanner that survives};inside JSON string values. - Correct caption decode order (escaped
</>no longer drop cues); a transcript that parses to zero snippets now raisesNoTranscriptFound. - Typed error mapping:
IpBlocked(403),VideoUnavailable(404/410), and a retryableRequestFailed(429 / transport failures / 5xx, carryingcause). - Cache hits no longer make a network round-trip; the HTML and transcript caches are LRU-bounded (
cache.maxSize, default 100).
Security
- Invidious caption-URL SSRF hardening: origin-pinned, absolute-URL override and redirects disabled, private/loopback/link-local hosts blocked.
- ReDoS-bounded caption tag stripping with a per-snippet length cap.
axiosbumped to^1.17.0, clearing known runtime advisories on the proxy/redirect paths.
Added
- Dual ESM + CJS build via
tsup, a post-build ESM/CJS smoke gate, and an@arethetypeswrong/clitype-resolution check. - CI matrix (Node 18/20/22), husky pre-commit/pre-push hooks, a
filesallowlist, and anenginesfloor. - Exported option and transcript types plus the new
RequestFailederror.
Verified: 80 tests, attw clean across node10 / node16-CJS / node16-ESM / bundler, npm audit --prod clean, and a real packed-tarball consumer imports by name in both ESM and CJS.