Add Cloudflare container API sample

Author: devhims

.gitignore

@@ -3,11 +3,15 @@ dist
 
 *.log
 .DS_Store
+.env*.local
 
 
 /sample/.next/
 /sample/out/
 /sample/build/
 /sample/node_modules/
+/sample/server/node_modules/
+/sample/server/.wrangler/
+/sample/server/.dev.vars*
 
-/docs
+/docs

README.md

@@ -1,8 +1,15 @@
 # youtube-caption-extractor
 
-A small, dependency-light library that extracts the transcript (and basic
-metadata) from any public YouTube video. Works with both manual captions and
-YouTube's auto-generated subtitles, in any language the video has tracks for.
+Extract readable transcripts and basic metadata from public YouTube videos with
+one small TypeScript library. It works with manual captions and YouTube's
+auto-generated captions, and it can run in Node.js, serverless functions, edge
+runtimes, or a containerized API.
+
+- **Simple API** — `getSubtitles()` and `getVideoDetails()`
+- **Typed output** — ships first-party TypeScript definitions
+- **Runtime-friendly** — uses global `fetch`, with an optional custom transport
+- **Production-aware** — supports retries, caching, and proxy/custom egress
+- **Demo included** — a Next.js sample app plus a Cloudflare Container API
 
 ```ts
 import { getSubtitles } from 'youtube-caption-extractor';
@@ -16,16 +23,45 @@ const subtitles = await getSubtitles({ videoID: '7GeFt8suV8E', lang: 'en' });
 //   ]
 ```
 
+## Try it quickly
+
+```sh
+npm install youtube-caption-extractor
+```
+
+```ts
+import { getVideoDetails } from 'youtube-caption-extractor';
+
+const video = await getVideoDetails({
+  videoID: '7GeFt8suV8E',
+  lang: 'en',
+});
+
+console.log(video.title);
+console.log(video.subtitles.map((s) => s.text).join('\n'));
+```
+
+Want to click around first? Try the hosted demo:
+[youtube-caption-extractor.vercel.app](https://youtube-caption-extractor.vercel.app/).
+
+Want a full app example? See [`sample/`](./sample), which includes:
+
+- A polished Next.js UI
+- Local API testing with your machine's network egress
+- A Dockerized Hono API deployed through Cloudflare Containers
+- A server-side token-protected proxy so the container API is not publicly open
+
 ## Installation
 
 ```sh
 npm install youtube-caption-extractor
 ```
 
-Requires **Node.js ≥ 18** (uses the global `fetch` API). Works in Node.js,
-Bun, Deno, Cloudflare Workers, and any other modern JavaScript runtime that
-provides `fetch`. See [Deployment notes](#deployment-notes) for tips on
-keeping calls reliable from your runtime of choice.
+Requires **Node.js ≥ 18** when running on Node.js because the library uses the
+global `fetch` API. It also works in Bun, Deno, Cloudflare Workers, and other
+modern JavaScript runtimes that provide `fetch`. See
+[Deployment notes](#deployment-notes) for tips on keeping calls reliable from
+your runtime of choice.
 
 ## API
 
@@ -132,7 +168,35 @@ try {
 
 ## Deployment notes
 
-The library calls YouTube directly, so real-world reliability can depend on the network egress of your deployment. Local development and self-hosted setups tend to work out of the box. Some serverless and edge environments share IP ranges that see broader traffic patterns and may occasionally rate-limit, so for production workloads it's worth combining the patterns below.
+The library calls YouTube directly, so reliability depends partly on the network
+egress of the process making the request.
+
+Local development and self-hosted servers tend to work out of the box. Shared
+serverless, container, and edge IP ranges can sometimes be rate-limited or gated
+by YouTube's bot checks. That is not a library API issue; it is an egress
+reputation issue. For production, use the patterns below.
+
+### Recommended app architecture
+
+Keep YouTube extraction server-side. Do not call YouTube directly from browser
+code.
+
+```txt
+Browser → your app API route → youtube-caption-extractor → YouTube
+```
+
+If you use a separate API service, protect it with a server-side token:
+
+```txt
+Browser → your app API route → token-protected caption API → YouTube
+```
+
+The included [`sample/`](./sample) demonstrates this pattern with:
+
+- Next.js API routes as the public browser-facing API
+- A Cloudflare Worker that rejects requests without `Authorization: Bearer <token>`
+- A Cloudflare Container running a Hono/Node API
+- `CAPTION_API_TOKEN` kept server-side only, never in `NEXT_PUBLIC_*`
 
 ### Building resilient calls
 
@@ -191,6 +255,17 @@ Common uses for a custom `fetch`:
 - **Authenticated proxies** — add `Authorization` headers via a wrapper
 - **Regional routing** — direct outbound traffic through a specific region or provider
 
+### Local vs hosted behavior
+
+If extraction works locally but fails in a hosted environment with a message like
+`LOGIN_REQUIRED` or "Sign in to confirm you're not a bot", the hosted provider's
+egress IP is likely being challenged by YouTube. Your options are:
+
+1. Run the extraction API somewhere with reliable egress for your workload.
+2. Use the `fetch` option to route outbound YouTube requests through a trusted proxy.
+3. Cache successful results aggressively so fewer requests reach YouTube.
+4. Treat these failures as transient and retry with backoff where appropriate.
+
 ## Usage examples
 
 ### Next.js (App Router)

sample/.env.example

@@ -0,0 +1,10 @@
+# Browser requests go to the Next.js API routes by default. The Next.js
+# server can then proxy to a local API, local Wrangler, or deployed Worker.
+CAPTION_API_BASE_URL=http://localhost:8080
+CAPTION_API_TOKEN=
+
+# Local Wrangler Worker/container:
+# CAPTION_API_BASE_URL=http://localhost:8787
+
+# Deployed Cloudflare Worker/container:
+# CAPTION_API_BASE_URL=https://youtube-caption-extractor-api.thinktank-himanshu.workers.dev

sample/README.md

@@ -8,28 +8,71 @@ This is a Next.js project demonstrating the use of the `youtube-caption-extracto
 - Retrieve video details including title and description
 - Support for multiple languages
 
-## Getting Started
+## Local development
 
-First, install the dependencies:
-
-````bash
+```bash
 npm install
-# or
-yarn install
-# or
-pnpm install
+npm run dev
+```
 
-Then, run the development server:
+Open [http://localhost:3000](http://localhost:3000). By default, the UI calls the local Next.js API routes.
+
+The API app lives in `server/` and can be run separately from Next.js.
+
+For the fastest local loop, run the Hono API directly and point the Next.js API routes at it:
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-````
+npm --prefix server install
+npm run api:dev
+CAPTION_API_BASE_URL=http://localhost:8080 npm run dev
+```
+
+To test the full local Worker → Cloudflare Container path, run Wrangler with Docker and point the Next.js API routes at Wrangler:
+
+```bash
+npm --prefix server install
+npm run cf:dev
+CAPTION_API_BASE_URL=http://localhost:8787 CAPTION_API_TOKEN=<token> npm run dev
+```
+
+Cloudflare dashboard "live instances" only reflects deployed Cloudflare traffic. It does not change when testing the local Hono API or local Wrangler container.
+
+## Cloudflare container API
+
+This sample includes a self-contained Cloudflare Containers app in `server/`. It runs the API as a Dockerized Hono Node server and proxies requests through a Hono Worker.
+
+```bash
+npm --prefix server install
+npm run cf:deploy
+```
+
+After deploy, set Vercel/Next.js server-side environment variables to the Worker URL and shared API token:
+
+```bash
+CAPTION_API_BASE_URL=https://<your-worker>.<your-subdomain>.workers.dev
+CAPTION_API_TOKEN=<same-token-configured-on-the-worker>
+```
+
+Do not put `CAPTION_API_TOKEN` in a `NEXT_PUBLIC_*` variable. The browser calls the Next.js API routes, and the Next.js server attaches the token when it calls the Worker.
+
+The container endpoint supports:
+
+- `GET /health`
+- `GET /api/subtitles?videoID=<id>&lang=en`
+- `GET /api/videoDetails?videoID=<id>&lang=en`
+
+Optional runtime environment variables:
+
+- `CAPTION_API_TOKEN` — shared bearer token required by the Worker before it proxies to the container.
+- `OUTBOUND_PROXY_URL` — routes YouTube requests through an HTTP(S) proxy via `undici`.
+- `CACHE_TTL_SECONDS` — controls the warm in-memory response cache, default `21600`.
+- `ALLOWED_ORIGINS` — comma-separated browser origins for CORS, default `*`.
+- `CONTAINER_VERSION` — version prefix for container instance names; bump it to force fresh instances during rollouts.
+
+From `server/`, use `npx wrangler secret put CAPTION_API_TOKEN` to set the shared token on Cloudflare.
+From `server/`, use `npx wrangler secret put OUTBOUND_PROXY_URL` if the proxy URL contains credentials.
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+If the API returns `youtube_blocked_datacenter_ip`, the request reached the Cloudflare container but YouTube blocked the container's outbound datacenter IP. Use direct local API testing (`http://localhost:8080`) for local machine egress, or configure `OUTBOUND_PROXY_URL` with a trusted proxy for deployed Cloudflare container testing.
 
 ## Usage
 

sample/app/api/_lib/captionApiProxy.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server';
+
+const PROXY_HEADERS = ['content-type', 'cache-control', 'x-cache'];
+
+function captionApiBaseUrl(): string {
+  return (process.env.CAPTION_API_BASE_URL || '').replace(/\/+$/, '');
+}
+
+function captionApiToken(): string {
+  return process.env.CAPTION_API_TOKEN || '';
+}
+
+export async function proxyCaptionApi(
+  path: string,
+  searchParams: URLSearchParams
+): Promise<NextResponse | null> {
+  const baseUrl = captionApiBaseUrl();
+  if (!baseUrl) return null;
+
+  const upstreamUrl = `${baseUrl}${path}?${searchParams.toString()}`;
+  const token = captionApiToken();
+  const headers = new Headers();
+
+  if (token) {
+    headers.set('Authorization', `Bearer ${token}`);
+  }
+
+  try {
+    const upstream = await fetch(upstreamUrl, {
+      cache: 'no-store',
+      headers,
+    });
+    const responseHeaders = new Headers();
+
+    for (const header of PROXY_HEADERS) {
+      const value = upstream.headers.get(header);
+      if (value) responseHeaders.set(header, value);
+    }
+
+    return new NextResponse(await upstream.text(), {
+      headers: responseHeaders,
+      status: upstream.status,
+    });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        code: 'caption_api_unreachable',
+        message:
+          error instanceof Error ? error.message : 'Caption API unreachable',
+      },
+      { status: 502 }
+    );
+  }
+}

sample/app/api/_lib/handleError.ts

@@ -21,7 +21,7 @@ export function handleApiError(error: unknown): NextResponse {
       {
         code: 'youtube_blocked_datacenter_ip',
         message:
-          'YouTube is blocking this server. Most cloud hosts (Vercel, AWS Lambda, Cloudflare Workers) share IP ranges that YouTube gates with a bot challenge — no client-side fix can bypass it. The library works on residential IPs: run the demo locally to see it in action, or wire up a residential proxy via the `fetch` option.',
+          'YouTube is blocking this server egress. Cloud/container hosts often use shared datacenter IP ranges that YouTube gates with a bot challenge. If this persists on Cloudflare Containers, route outbound YouTube requests through the library `fetch` option using a trusted proxy.',
         debug: message,
       },
       { status: 503 }

sample/app/api/subtitles/route.ts

@@ -1,5 +1,6 @@
 import { getSubtitles } from 'youtube-caption-extractor';
 import { NextResponse, type NextRequest } from 'next/server';
+import { proxyCaptionApi } from '../_lib/captionApiProxy';
 import { handleApiError } from '../_lib/handleError';
 
 export async function GET(request: NextRequest) {
@@ -14,6 +15,9 @@ export async function GET(request: NextRequest) {
     );
   }
 
+  const proxied = await proxyCaptionApi('/api/subtitles', searchParams);
+  if (proxied) return proxied;
+
   try {
     const subtitles = await getSubtitles({ videoID, lang });
     return NextResponse.json({ subtitles }, { status: 200 });

sample/app/api/videoDetails/route.ts

@@ -1,5 +1,6 @@
 import { getVideoDetails } from 'youtube-caption-extractor';
 import { NextResponse, type NextRequest } from 'next/server';
+import { proxyCaptionApi } from '../_lib/captionApiProxy';
 import { handleApiError } from '../_lib/handleError';
 
 export async function GET(request: NextRequest) {
@@ -14,6 +15,9 @@ export async function GET(request: NextRequest) {
     );
   }
 
+  const proxied = await proxyCaptionApi('/api/videoDetails', searchParams);
+  if (proxied) return proxied;
+
   try {
     const videoDetails = await getVideoDetails({ videoID, lang });
     return NextResponse.json({ videoDetails }, { status: 200 });

sample/app/page.tsx

@@ -86,7 +86,17 @@ const LANGUAGES = [
   ['zh', 'Chinese'],
 ] as const;
 
-const SAMPLE_IDS = ['7GeFt8suV8E', 'jNQXAC9IVRw'];
+const SAMPLE_IDS = [
+  '7GeFt8suV8E',
+  'jNQXAC9IVRw',
+  'D37Ijn2o5U0',
+  'g9JIUM0MHgQ',
+  '6BB6exR8Zd8',
+];
+function apiUrl(path: string, params: URLSearchParams): string {
+  const query = params.toString();
+  return `${path}${query ? `?${query}` : ''}`;
+}
 
 export default function HomePage() {
   const [input, setInput] = useState('');
@@ -150,9 +160,10 @@ export default function HomePage() {
     setError(null);
     setQuery('');
     try {
+      const params = new URLSearchParams({ videoID: id, lang });
       const [subsRes, detailsRes] = await Promise.all([
-        fetch(`/api/subtitles?videoID=${id}&lang=${lang}`),
-        fetch(`/api/videoDetails?videoID=${id}&lang=${lang}`),
+        fetch(apiUrl('/api/subtitles', params)),
+        fetch(apiUrl('/api/videoDetails', params)),
       ]);
       if (!subsRes.ok) {
         setError(await readApiError(subsRes));