Product Updates

New Features

• Added lyra-sdk/ai-tools subpath — 12 pre-built AI tools for Vercel AI SDK, Mastra, and LangChain (getVideo, getChannel, getComments, transcribeVideo, batchTranscribe, and more)
• Added vercelTool() wrapper — wraps tool definitions for Vercel AI SDK's tool() function
• Added createAITools(config) factory — instantiates all 12 tools with shared API key and optional cache
• Added single video transcript REST endpoint: GET /api/transcript/:id
• Added scripts/ai-tools.ts — integration test script for AI agent workflows with Gemini

Bug Fixes

• Fixed Zod peer dependency — removed optional: true from peerDependenciesMeta so lyra-sdk/ai-tools consumers are required to install zod
• Added concurrency limiting to batchTranscribe tool — capped at 5 parallel requests to prevent unbounded concurrent API calls
• Fixed import path collisions in ai-tools tool modules

Documentation

• Added Agent Providers section with Vercel AI SDK usage guide
• All 12 tools documented with parameter types, return types, and usage examples

Breaking Changes

• Zod is now a required peer dependency (previously optional) — install zod alongside lyra-sdk if you use lyra-sdk/ai-tools

New Features

• Added playlist and video retrieval capabilities with concurrent fetching and enriched metadata — getPlaylist and getVideos now support batched concurrent requests with full snippet enrichment
• Exposed URL parsing and formatting utilities via new public entry points (lyra-sdk/url, lyra-sdk/fmt) — no API key required

Bug Fixes

• Fixed 404 error messages for comment endpoints — resourceIdForParams now includes videoId and allThreadsRelatedToChannelId so getVideoComments and getChannelComments produce the correct resource ID in error context
• Added validation for concurrency parameter in hydrateMissingReplies — non-finite, zero, or negative values are normalized to prevent silent no-ops and RangeError crashes
• Normalized maxResults/maxItems to safe integers in comment pagination — prevents NaN and fractional values from being sent to the YouTube Data API
• Added validation for cached transcript data to prevent stale entries — cache entries are now validated for structural integrity before serving
• Added TranscriptOptions union fallback overload to transcribeVideo — callers passing the base TranscriptOptions type no longer fail overload resolution

Improvements

• Improved retry logic with exponential backoff for transient API failures — configurable retries and retryDelay on all transcript and comment requests
• Enhanced type inference for transcript requests with explicit TranscriptOptions overload in transcribeVideo
• Implemented concurrency limits for efficient reply fetching in hydrateMissingReplies — configurable per-call concurrency parameter
• Added fail-fast validation for YOUTUBE_API_KEY in batch transcript scripts with clear error messages and .env setup hints
• Added explicit Vitest imports to entrypoints.test.ts for consistency with other test files
• Aligned biome.json $schema version to match minimum installed @biomejs/biome version (2.4.12)

Breaking Changes

• None — fully backwards-compatible with v2.0.0

Transcript API

• transcribeVideo(id, options?) — fetch captions for a single video without an API key
• transcribePlaylist(id, options?) — batch fetch transcripts for every video in a playlist
• listCaptionTracks(id) — discover available language tracks before downloading
• Output formatters: toSRT(), toVTT(), toPlainText()
• TranscriptClient — reusable client with shared config

Batch Transcript

• Configurable concurrency (1–20 workers) for parallel transcript fetching
• from / to range filtering to process a subset of the playlist
• onProgress callback for real-time progress tracking
• Partial failure handling — individual video failures are caught and recorded, not thrown
• Returns per-video results with status: "success" | "failed"

Caching

• InMemoryCache — process-only cache with TTL and size limits (~0.03ms hits)
• FsCache — filesystem persistence with JSON storage (~0.3ms hits)
• CacheStore interface for custom backends (Redis, etc.)
• Automatic cache key generation per video ID, language, and metadata flag

Retry & Resilience

• Exponential backoff retry for transient HTTP failures (429, 5xx)
• retries and retryDelay options on all transcript requests
• AbortSignal support to cancel in-flight retry loops

Comments API

• comments(videoId, opts?) — fetch all comment threads with auto-pagination
• topComments(videoId, limit?) — top comments sorted by relevance
• commentReplies(commentId) — fetch all replies to a specific comment
• commentsWithReplies(videoId) — threads + all replies in one call
• searchComments(videoId, query) — keyword search within comments
• commentStats(videoId, threads) — aggregate stats (unique authors, reply ratio, most liked)
• commentQuery(videoId) — fluent builder for filtering and slicing comments

Internationalization (i18n)

• regions(hl?) — list all supported YouTube regions (110+)
• languages(hl?) — list all supported languages (80+)
• videoCategoriesByRegion(regionCode, hl?) — fetch region-specific video categories
• Localized names via hl parameter (e.g., ja for Japanese)

REST API

• New endpoints: /api/comments/{videoId}, /api/comments/{videoId}/top, /api/comment-replies/{id}
• New endpoint: /api/transcript/{id} — single video transcript (no API key)
• New endpoint: /api/playlist/{id}/transcript — batch playlist transcript
• Removed URL utility endpoints (moved to standalone lyra-sdk/url subpath)

Framework Examples

• Added Hono, NestJS, and Next.js API server examples alongside Express
• API Reference now shows framework-specific code samples (Express, Hono, Next.js)

Playlist Query

• Added POST /api/playlist/{id}/query endpoint for filtering, sorting, and slicing playlist videos
• Filter by duration, views, and likes with min/max ranges
• Sort by views, likes, or duration in ascending or descending order
• Range parameter to paginate results (1-indexed start/end)

Video API

• getVideo(id) — fetch full video details by ID or URL
• getVideos(ids) — batch fetch multiple videos
• getVideoTitle(id) — lightweight title-only lookup (1 quota unit)

Channel API

• getChannel(id) — fetch channel metadata by ID, @username, or URL
• getChannelVideos(id, limit) — fetch recent uploads for a channel

Playlist API

• getPlaylist(id) — fetch complete playlist with all videos and total duration
• getPlaylistInfo(id) — playlist metadata only (1 quota unit)
• getPlaylistIds(id) — fetch all video IDs with auto-pagination

URL Utilities

• parseUrl(url) — parse a YouTube URL into a structured result
• extractUrl(url, type?) — extract video, playlist, or channel IDs from a URL

Express REST API

• Full REST API wrapper around all SDK functions
• Interactive OpenAPI documentation at /docs/api-reference
• Local development server via npm run dev:express