--- name: bijection-convex-youtube-cache description: "Evaluate and integrate the Youtube Cache component with Bijection." --- # Youtube Cache YouTube video metadata caching with rate limiting, TTL, reservation system, and batch lookups for Convex. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: convex-youtube-cache - Source: https://github.com/TimpiaAI/convex-youtube-metadata - npm: https://www.npmjs.com/package/convex-youtube-cache - Directory: https://bijection.com/components/convex-youtube-cache Read the upstream README for setup, license, and compatibility before using it. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes convex-youtube-cache. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. # convex-youtube-cache ## Instructions Use convex-youtube-cache to cache youtube video metadata with built-in rate limiting, ttl management, and batch lookups to prevent api quota exhaustion in convex apps. This Convex component integrates directly with your backend. ### Installation ```bash npm install convex-youtube-cache ``` ### Capabilities - Prevent YouTube API quota exhaustion with built-in rate limiting and reservation system - Reduce response times with TTL-based caching and stale-while-revalidate strategy - Optimize API usage with batch lookups that fetch up to 50 videos in a single request - Eliminate duplicate requests with automatic reservation queuing and retry logic ## Examples ### how to cache YouTube video metadata in Convex without hitting API limits The convex-youtube-cache component provides automatic caching with configurable TTL and built-in rate limiting to stay within YouTube API quotas. It includes a reservation system that queues requests when quota is exhausted and implements stale-while-revalidate for fast responses. ### batch fetch YouTube video data in Convex application Use the getVideos method to fetch metadata for up to 50 videos in a single API call, optimizing quota usage. The component automatically handles caching, rate limiting, and returns an array of VideoMetadata objects with title, description, thumbnails, and channel information. ### implement YouTube API rate limiting in Convex The convex-youtube-cache component includes built-in rate limiting with configurable daily quotas (default 10,000 units). When quota is exhausted, it creates reservations that wait up to 10 seconds for capacity, then gracefully degrades by returning stale data or null. ### prevent duplicate YouTube API requests in Convex The reservation system prevents duplicate in-flight requests by queuing identical video ID requests. Multiple concurrent requests for the same video will wait for a single API call to complete, reducing quota usage and preventing race conditions. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by convex-youtube-cache is not needed ## Troubleshooting **How does convex-youtube-cache prevent API quota exhaustion?** The convex-youtube-cache component includes built-in rate limiting with configurable daily quotas (default 10,000 units per day). When quota is exhausted, it creates reservations that queue requests and wait up to a configurable timeout (default 10 seconds) before gracefully degrading to return stale cached data or null. **Can I fetch multiple YouTube videos efficiently with this component?** Yes, the convex-youtube-cache component provides a getVideos method that supports batch lookups for up to 50 video IDs in a single YouTube API call. This significantly reduces quota usage compared to individual requests and includes the same caching and rate limiting features. **What happens when cached YouTube data becomes stale?** The convex-youtube-cache component implements a stale-while-revalidate strategy. When cached data exceeds its TTL, it returns the stale data immediately for fast response times, then fetches fresh data from the YouTube API in the background if quota is available. **How do I monitor YouTube API usage with this component?** The convex-youtube-cache component provides a getCacheStats method that returns hit rate, quota usage, and active reservations. You can call this from a Convex query to monitor performance and track how efficiently your app is using the YouTube API quota. **Does convex-youtube-cache handle YouTube API errors and retries?** Yes, the convex-youtube-cache component includes retry logic with exponential backoff for transient HTTP errors. It supports configurable retry attempts (default 3) and base retry delays (default 1 second) to handle temporary YouTube API failures gracefully. ## Resources - [npm package](https://www.npmjs.com/package/convex-youtube-cache) - [GitHub repository](https://github.com/TimpiaAI/convex-youtube-metadata) - [Live demo](https://youtube-metadata-demo.vercel.app) - [Convex Components Directory](https://www.convex.dev/components/convex-youtube-cache) - [Convex documentation](https://docs.convex.dev)