Skip to content

v2.0.0 — dual ESM/CJS build + critical import fixes

Latest

Choose a tag to compare

@wickes1 wickes1 released this 08 Jun 16:05
· 5 commits to main since this release

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 exports map was restructured: import resolves the ESM build, require resolves 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: import from a "type": "module" project no longer fails with ERR_MODULE_NOT_FOUND (compiled ESM emitted extensionless relative re-exports).
  • Critical: new YouTubeTranscriptApi() no longer throws require is not defined in ESM (require('http')/require('https') in an ES module).
  • Robust ytInitialPlayerResponse and 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 raises NoTranscriptFound.
  • Typed error mapping: IpBlocked (403), VideoUnavailable (404/410), and a retryable RequestFailed (429 / transport failures / 5xx, carrying cause).
  • 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.
  • axios bumped 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/cli type-resolution check.
  • CI matrix (Node 18/20/22), husky pre-commit/pre-push hooks, a files allowlist, and an engines floor.
  • Exported option and transcript types plus the new RequestFailed error.

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.