youtube-audio-transcript-api 1.0.0

package/README.md

@@ -0,0 +1,258 @@
+<p align="center">
+  <img src="https://youtubetranscript.dev/logo.svg" alt="YouTubeTranscript.dev" width="60" />
+</p>
+
+<h1 align="center">youtube-transcript-api</h1>
+
+<p align="center">
+  Official Node.js / TypeScript SDK for the <a href="https://youtubetranscript.dev">YouTubeTranscript.dev</a> API (V2).
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/youtube-transcript-api"><img src="https://img.shields.io/npm/v/youtube-transcript-api" alt="npm" /></a>
+  <a href="https://youtubetranscript.dev"><img src="https://img.shields.io/badge/API-v2-brightgreen" alt="API Version" /></a>
+  <a href="https://github.com/youtubetranscript/youtube-transcript-api/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/youtube-transcript-api" alt="License" /></a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install youtube-transcript-api
+```
+
+```bash
+pnpm add youtube-transcript-api
+```
+
+```bash
+yarn add youtube-transcript-api
+```
+
+## Quick Start
+
+```typescript
+import { YouTubeTranscript } from "youtube-transcript-api";
+
+const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+
+// Simple — just pass a video ID or URL
+const result = await yt.getTranscript("dQw4w9WgXcQ");
+console.log(result.data?.transcript.text);
+```
+
+Get your API key at **[youtubetranscript.dev](https://youtubetranscript.dev)**
+
+## Features
+
+- ✅ Full V2 API coverage — transcribe, batch, jobs, polling
+- ✅ TypeScript-first with complete type definitions
+- ✅ Zero dependencies — uses native `fetch` (Node 18+)
+- ✅ Typed errors for every API error code
+- ✅ Built-in polling helpers for async ASR jobs
+- ✅ ESM and CommonJS support
+
+## Usage
+
+### Basic Transcription
+
+```typescript
+import { YouTubeTranscript } from "youtube-transcript-api";
+
+const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+
+// By video ID
+const result = await yt.getTranscript("dQw4w9WgXcQ");
+
+// By URL
+const result = await yt.getTranscript("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+
+// With translation
+const result = await yt.getTranscript("dQw4w9WgXcQ", "es");
+```
+
+### Full Options
+
+```typescript
+const result = await yt.transcribe({
+  video: "dQw4w9WgXcQ",
+  language: "fr",
+  source: "manual",
+  format: {
+    timestamp: true,
+    paragraphs: true,
+    words: false,
+  },
+});
+
+console.log(result.status);                    // "completed"
+console.log(result.data?.transcript.text);     // Full transcript text
+console.log(result.data?.transcript.language); // "fr"
+console.log(result.data?.transcript.segments); // Timestamped segments
+console.log(result.credits_used);              // Credits consumed
+```
+
+### Batch Processing (up to 100 videos)
+
+```typescript
+const result = await yt.batch({
+  video_ids: [
+    "dQw4w9WgXcQ",
+    "jNQXAC9IVRw",
+    "9bZkp7q19f0",
+  ],
+  format: { timestamp: true },
+});
+
+console.log(result.summary);
+// { total: 3, succeeded: 3, failed: 0, processing: 0 }
+
+for (const item of result.results) {
+  console.log(`${item.data?.video_id}: ${item.data?.transcript.text.slice(0, 100)}...`);
+}
+```
+
+### ASR Audio Transcription (Async)
+
+For videos without captions, use ASR with a webhook or polling:
+
+```typescript
+// Option 1: Webhook (recommended for production)
+const result = await yt.transcribe({
+  video: "VIDEO_ID",
+  source: "asr",
+  allow_asr: true,
+  webhook_url: "https://yoursite.com/webhook",
+});
+// result.status === "processing"
+// result.job_id === "job_abc123"
+
+// Option 2: Poll until complete
+const result = await yt.transcribe({
+  video: "VIDEO_ID",
+  source: "asr",
+  allow_asr: true,
+});
+
+if (result.job_id) {
+  const final = await yt.waitForJob(result.job_id, {
+    interval: 5000,     // poll every 5s
+    maxAttempts: 60,     // give up after 5 minutes
+  });
+  console.log(final.data?.transcript.text);
+}
+```
+
+### ASR Confirmation Flow
+
+V2 requires explicit confirmation before ASR charges. If you don't set `allow_asr: true` and captions aren't available:
+
+```typescript
+const result = await yt.transcribe({
+  video: "VIDEO_WITHOUT_CAPTIONS",
+  source: "asr",
+  // allow_asr not set
+});
+
+if (result.status === "requires_asr_confirmation") {
+  console.log(result.estimated_credits);  // e.g. 5
+  console.log(result.duration_minutes);   // e.g. 7.5
+  console.log(result.suggestion);         // "Set allow_asr=true to proceed"
+
+  // User confirms → retry with allow_asr
+  const confirmed = await yt.transcribe({
+    video: "VIDEO_WITHOUT_CAPTIONS",
+    source: "asr",
+    allow_asr: true,
+    webhook_url: "https://yoursite.com/webhook",
+  });
+}
+```
+
+### Job & Batch Polling
+
+```typescript
+// Poll a single job
+const job = await yt.getJob("job_abc123");
+
+// Poll with format options
+const job = await yt.getJob("job_abc123", {
+  include_segments: true,
+  include_paragraphs: true,
+});
+
+// Poll a batch
+const batch = await yt.getBatch("batch_abc123");
+
+// Auto-poll until done
+const completed = await yt.waitForJob("job_abc123");
+const completedBatch = await yt.waitForBatch("batch_abc123");
+```
+
+## Error Handling
+
+Every API error maps to a typed exception:
+
+```typescript
+import {
+  YouTubeTranscript,
+  InvalidRequestError,
+  AuthenticationError,
+  InsufficientCreditsError,
+  NoCaptionsError,
+  RateLimitError,
+} from "youtube-transcript-api";
+
+try {
+  await yt.getTranscript("invalid");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log("Bad API key");
+  } else if (error instanceof InsufficientCreditsError) {
+    console.log("Top up at https://youtubetranscript.dev/pricing");
+  } else if (error instanceof NoCaptionsError) {
+    console.log("No captions — try source: 'asr' with allow_asr: true");
+  } else if (error instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof InvalidRequestError) {
+    console.log(`Bad request: ${error.message}`);
+  }
+}
+```
+
+| Error Class | HTTP Status | When |
+|---|---|---|
+| `InvalidRequestError` | 400 | Invalid JSON, missing fields, bad video ID |
+| `AuthenticationError` | 401 | Missing or invalid API key |
+| `InsufficientCreditsError` | 402 | Not enough credits |
+| `NoCaptionsError` | 404 | No captions and ASR not used |
+| `RateLimitError` | 429 | Too many requests |
+| `YouTubeTranscriptError` | Other | Server errors, unexpected responses |
+
+## Configuration
+
+```typescript
+const yt = new YouTubeTranscript({
+  apiKey: "your_api_key",        // Required
+  baseUrl: "https://...",        // Override API base URL
+  timeout: 60_000,               // Request timeout in ms (default: 30s)
+});
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- API key from [youtubetranscript.dev](https://youtubetranscript.dev)
+
+## Links
+
+- 🌐 [Website](https://youtubetranscript.dev)
+- 📖 [Full API Docs](https://youtubetranscript.dev/api-docs)
+- 📐 [OpenAPI Spec](https://youtubetranscript.dev/api-docs#openapi)
+- 💰 [Pricing](https://youtubetranscript.dev/pricing)
+- 🐛 [Issues](https://github.com/youtubetranscript/youtube-transcript-api/issues)
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/dist/index.d.mts

@@ -0,0 +1,208 @@
+/** Control which extra fields are included in the response. */
+interface FormatOptions {
+    /** Include timestamped segments */
+    timestamp?: boolean;
+    /** Include paragraph groupings */
+    paragraphs?: boolean;
+    /** Include word-level timestamps */
+    words?: boolean;
+}
+/** Caption source preference. */
+type Source = "auto" | "manual" | "asr";
+interface TranscribeRequest {
+    /** YouTube URL or 11-character video ID */
+    video: string;
+    /** ISO 639-1 language code (e.g. "es", "fr"). Omit for best available. */
+    language?: string;
+    /** Caption source: "auto" (default), "manual", or "asr" */
+    source?: Source;
+    /** Explicitly confirm ASR usage when captions are unavailable */
+    allow_asr?: boolean;
+    /** Control extra output fields */
+    format?: FormatOptions;
+    /** URL to receive async results. Required for source="asr". */
+    webhook_url?: string;
+}
+interface BatchRequest {
+    /** Array of YouTube URLs or 11-character video IDs (max 100) */
+    video_ids: string[];
+    /** ISO 639-1 language code */
+    language?: string;
+    /** Caption source preference */
+    source?: Source;
+    /** Explicitly confirm ASR usage */
+    allow_asr?: boolean;
+    /** Control extra output fields */
+    format?: FormatOptions;
+    /** URL to receive async results */
+    webhook_url?: string;
+}
+interface TranscriptPayload {
+    /** Full transcript text */
+    text: string;
+    /** Detected / returned language */
+    language: string;
+    /** Source of the transcript: manual captions, auto, or asr */
+    source: string;
+    /** Timestamped segments (when format.timestamp = true) */
+    segments?: Record<string, unknown>[];
+    /** Paragraph groupings (when format.paragraphs = true) */
+    paragraphs?: Record<string, unknown>[];
+    /** Word-level timestamps (when format.words = true) */
+    words?: Record<string, unknown>[];
+}
+type TranscribeStatus = "completed" | "processing" | "failed" | "requires_asr_confirmation";
+interface TranscribeResponse {
+    request_id: string;
+    status: TranscribeStatus;
+    data?: {
+        video_id: string;
+        transcript: TranscriptPayload;
+        video_title?: string | null;
+    };
+    error?: string;
+    job_id?: string | null;
+    estimated_credits?: number;
+    duration_minutes?: number | null;
+    suggestion?: string;
+    credits_used?: number;
+}
+type BatchStatus = "completed" | "partial" | "processing";
+interface BatchResponse {
+    batch_id: string;
+    status: BatchStatus;
+    results: TranscribeResponse[];
+    summary?: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        processing: number;
+    };
+    credits_used?: number;
+}
+interface ErrorResponse {
+    error: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface YouTubeTranscriptOptions {
+    /** Your API key from https://youtubetranscript.dev/dashboard */
+    apiKey: string;
+    /** Base URL override (default: https://youtubetranscript.dev/api/v2) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
+declare class YouTubeTranscript {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * Create a new YouTubeTranscript client.
+     *
+     * ```ts
+     * const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+     * ```
+     *
+     * Get your API key at https://youtubetranscript.dev
+     */
+    constructor(options: YouTubeTranscriptOptions);
+    /**
+     * Transcribe a single YouTube video.
+     *
+     * ```ts
+     * const result = await yt.transcribe({ video: "dQw4w9WgXcQ" });
+     * console.log(result.data?.transcript.text);
+     * ```
+     */
+    transcribe(request: TranscribeRequest): Promise<TranscribeResponse>;
+    /**
+     * Shorthand: transcribe a video by URL or ID with minimal config.
+     *
+     * ```ts
+     * const result = await yt.getTranscript("dQw4w9WgXcQ");
+     * ```
+     */
+    getTranscript(video: string, language?: string): Promise<TranscribeResponse>;
+    /**
+     * Transcribe multiple videos in a single request (up to 100).
+     *
+     * ```ts
+     * const result = await yt.batch({
+     *   video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
+     * });
+     * ```
+     */
+    batch(request: BatchRequest): Promise<BatchResponse>;
+    /**
+     * Poll an async transcription job (ASR).
+     *
+     * ```ts
+     * const status = await yt.getJob("job_abc123");
+     * ```
+     */
+    getJob(jobId: string, options?: {
+        include_segments?: boolean;
+        include_paragraphs?: boolean;
+        include_words?: boolean;
+    }): Promise<TranscribeResponse>;
+    /**
+     * Poll a batch job.
+     *
+     * ```ts
+     * const status = await yt.getBatch("batch_abc123");
+     * ```
+     */
+    getBatch(batchId: string): Promise<BatchResponse>;
+    /**
+     * Poll a job until it completes or fails.
+     *
+     * ```ts
+     * const result = await yt.waitForJob("job_abc123", {
+     *   interval: 5000,
+     *   maxAttempts: 60,
+     * });
+     * ```
+     */
+    waitForJob(jobId: string, options?: {
+        interval?: number;
+        maxAttempts?: number;
+    }): Promise<TranscribeResponse>;
+    /**
+     * Poll a batch until it completes.
+     */
+    waitForBatch(batchId: string, options?: {
+        interval?: number;
+        maxAttempts?: number;
+    }): Promise<BatchResponse>;
+    private post;
+    private get;
+    private request;
+    private createError;
+}
+
+declare class YouTubeTranscriptError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, body: ErrorResponse);
+}
+declare class InvalidRequestError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class AuthenticationError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class InsufficientCreditsError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class NoCaptionsError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class RateLimitError extends YouTubeTranscriptError {
+    readonly retryAfter?: number;
+    constructor(body: ErrorResponse, retryAfter?: number);
+}
+
+export { AuthenticationError, type BatchRequest, type BatchResponse, type BatchStatus, type ErrorResponse, type FormatOptions, InsufficientCreditsError, InvalidRequestError, NoCaptionsError, RateLimitError, type Source, type TranscribeRequest, type TranscribeResponse, type TranscribeStatus, type TranscriptPayload, YouTubeTranscript, YouTubeTranscriptError, type YouTubeTranscriptOptions };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+/** Control which extra fields are included in the response. */
+interface FormatOptions {
+    /** Include timestamped segments */
+    timestamp?: boolean;
+    /** Include paragraph groupings */
+    paragraphs?: boolean;
+    /** Include word-level timestamps */
+    words?: boolean;
+}
+/** Caption source preference. */
+type Source = "auto" | "manual" | "asr";
+interface TranscribeRequest {
+    /** YouTube URL or 11-character video ID */
+    video: string;
+    /** ISO 639-1 language code (e.g. "es", "fr"). Omit for best available. */
+    language?: string;
+    /** Caption source: "auto" (default), "manual", or "asr" */
+    source?: Source;
+    /** Explicitly confirm ASR usage when captions are unavailable */
+    allow_asr?: boolean;
+    /** Control extra output fields */
+    format?: FormatOptions;
+    /** URL to receive async results. Required for source="asr". */
+    webhook_url?: string;
+}
+interface BatchRequest {
+    /** Array of YouTube URLs or 11-character video IDs (max 100) */
+    video_ids: string[];
+    /** ISO 639-1 language code */
+    language?: string;
+    /** Caption source preference */
+    source?: Source;
+    /** Explicitly confirm ASR usage */
+    allow_asr?: boolean;
+    /** Control extra output fields */
+    format?: FormatOptions;
+    /** URL to receive async results */
+    webhook_url?: string;
+}
+interface TranscriptPayload {
+    /** Full transcript text */
+    text: string;
+    /** Detected / returned language */
+    language: string;
+    /** Source of the transcript: manual captions, auto, or asr */
+    source: string;
+    /** Timestamped segments (when format.timestamp = true) */
+    segments?: Record<string, unknown>[];
+    /** Paragraph groupings (when format.paragraphs = true) */
+    paragraphs?: Record<string, unknown>[];
+    /** Word-level timestamps (when format.words = true) */
+    words?: Record<string, unknown>[];
+}
+type TranscribeStatus = "completed" | "processing" | "failed" | "requires_asr_confirmation";
+interface TranscribeResponse {
+    request_id: string;
+    status: TranscribeStatus;
+    data?: {
+        video_id: string;
+        transcript: TranscriptPayload;
+        video_title?: string | null;
+    };
+    error?: string;
+    job_id?: string | null;
+    estimated_credits?: number;
+    duration_minutes?: number | null;
+    suggestion?: string;
+    credits_used?: number;
+}
+type BatchStatus = "completed" | "partial" | "processing";
+interface BatchResponse {
+    batch_id: string;
+    status: BatchStatus;
+    results: TranscribeResponse[];
+    summary?: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        processing: number;
+    };
+    credits_used?: number;
+}
+interface ErrorResponse {
+    error: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface YouTubeTranscriptOptions {
+    /** Your API key from https://youtubetranscript.dev/dashboard */
+    apiKey: string;
+    /** Base URL override (default: https://youtubetranscript.dev/api/v2) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+
+declare class YouTubeTranscript {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * Create a new YouTubeTranscript client.
+     *
+     * ```ts
+     * const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+     * ```
+     *
+     * Get your API key at https://youtubetranscript.dev
+     */
+    constructor(options: YouTubeTranscriptOptions);
+    /**
+     * Transcribe a single YouTube video.
+     *
+     * ```ts
+     * const result = await yt.transcribe({ video: "dQw4w9WgXcQ" });
+     * console.log(result.data?.transcript.text);
+     * ```
+     */
+    transcribe(request: TranscribeRequest): Promise<TranscribeResponse>;
+    /**
+     * Shorthand: transcribe a video by URL or ID with minimal config.
+     *
+     * ```ts
+     * const result = await yt.getTranscript("dQw4w9WgXcQ");
+     * ```
+     */
+    getTranscript(video: string, language?: string): Promise<TranscribeResponse>;
+    /**
+     * Transcribe multiple videos in a single request (up to 100).
+     *
+     * ```ts
+     * const result = await yt.batch({
+     *   video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
+     * });
+     * ```
+     */
+    batch(request: BatchRequest): Promise<BatchResponse>;
+    /**
+     * Poll an async transcription job (ASR).
+     *
+     * ```ts
+     * const status = await yt.getJob("job_abc123");
+     * ```
+     */
+    getJob(jobId: string, options?: {
+        include_segments?: boolean;
+        include_paragraphs?: boolean;
+        include_words?: boolean;
+    }): Promise<TranscribeResponse>;
+    /**
+     * Poll a batch job.
+     *
+     * ```ts
+     * const status = await yt.getBatch("batch_abc123");
+     * ```
+     */
+    getBatch(batchId: string): Promise<BatchResponse>;
+    /**
+     * Poll a job until it completes or fails.
+     *
+     * ```ts
+     * const result = await yt.waitForJob("job_abc123", {
+     *   interval: 5000,
+     *   maxAttempts: 60,
+     * });
+     * ```
+     */
+    waitForJob(jobId: string, options?: {
+        interval?: number;
+        maxAttempts?: number;
+    }): Promise<TranscribeResponse>;
+    /**
+     * Poll a batch until it completes.
+     */
+    waitForBatch(batchId: string, options?: {
+        interval?: number;
+        maxAttempts?: number;
+    }): Promise<BatchResponse>;
+    private post;
+    private get;
+    private request;
+    private createError;
+}
+
+declare class YouTubeTranscriptError extends Error {
+    readonly status: number;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, body: ErrorResponse);
+}
+declare class InvalidRequestError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class AuthenticationError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class InsufficientCreditsError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class NoCaptionsError extends YouTubeTranscriptError {
+    constructor(body: ErrorResponse);
+}
+declare class RateLimitError extends YouTubeTranscriptError {
+    readonly retryAfter?: number;
+    constructor(body: ErrorResponse, retryAfter?: number);
+}
+
+export { AuthenticationError, type BatchRequest, type BatchResponse, type BatchStatus, type ErrorResponse, type FormatOptions, InsufficientCreditsError, InvalidRequestError, NoCaptionsError, RateLimitError, type Source, type TranscribeRequest, type TranscribeResponse, type TranscribeStatus, type TranscriptPayload, YouTubeTranscript, YouTubeTranscriptError, type YouTubeTranscriptOptions };

package/dist/index.js

@@ -0,0 +1,271 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  InsufficientCreditsError: () => InsufficientCreditsError,
+  InvalidRequestError: () => InvalidRequestError,
+  NoCaptionsError: () => NoCaptionsError,
+  RateLimitError: () => RateLimitError,
+  YouTubeTranscript: () => YouTubeTranscript,
+  YouTubeTranscriptError: () => YouTubeTranscriptError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var YouTubeTranscriptError = class extends Error {
+  constructor(status, body) {
+    super(body.message || body.error);
+    this.name = "YouTubeTranscriptError";
+    this.status = status;
+    this.errorCode = body.error;
+    this.details = body.details;
+  }
+};
+var InvalidRequestError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(400, body);
+    this.name = "InvalidRequestError";
+  }
+};
+var AuthenticationError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(401, body);
+    this.name = "AuthenticationError";
+  }
+};
+var InsufficientCreditsError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(402, body);
+    this.name = "InsufficientCreditsError";
+  }
+};
+var NoCaptionsError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(404, body);
+    this.name = "NoCaptionsError";
+  }
+};
+var RateLimitError = class extends YouTubeTranscriptError {
+  constructor(body, retryAfter) {
+    super(429, body);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://youtubetranscript.dev/api/v2";
+var DEFAULT_TIMEOUT = 3e4;
+var YouTubeTranscript = class {
+  /**
+   * Create a new YouTubeTranscript client.
+   *
+   * ```ts
+   * const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+   * ```
+   *
+   * Get your API key at https://youtubetranscript.dev
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error(
+        "API key is required. Get one at https://youtubetranscript.dev"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  // ---------------------------------------------------
+  // Public methods
+  // ---------------------------------------------------
+  /**
+   * Transcribe a single YouTube video.
+   *
+   * ```ts
+   * const result = await yt.transcribe({ video: "dQw4w9WgXcQ" });
+   * console.log(result.data?.transcript.text);
+   * ```
+   */
+  async transcribe(request) {
+    return this.post("/transcribe", request);
+  }
+  /**
+   * Shorthand: transcribe a video by URL or ID with minimal config.
+   *
+   * ```ts
+   * const result = await yt.getTranscript("dQw4w9WgXcQ");
+   * ```
+   */
+  async getTranscript(video, language) {
+    return this.transcribe({ video, language });
+  }
+  /**
+   * Transcribe multiple videos in a single request (up to 100).
+   *
+   * ```ts
+   * const result = await yt.batch({
+   *   video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
+   * });
+   * ```
+   */
+  async batch(request) {
+    return this.post("/batch", request);
+  }
+  /**
+   * Poll an async transcription job (ASR).
+   *
+   * ```ts
+   * const status = await yt.getJob("job_abc123");
+   * ```
+   */
+  async getJob(jobId, options) {
+    const params = new URLSearchParams();
+    if (options?.include_segments) params.set("include_segments", "true");
+    if (options?.include_paragraphs) params.set("include_paragraphs", "true");
+    if (options?.include_words) params.set("include_words", "true");
+    const query = params.toString();
+    const path = `/jobs/${jobId}${query ? `?${query}` : ""}`;
+    return this.get(path);
+  }
+  /**
+   * Poll a batch job.
+   *
+   * ```ts
+   * const status = await yt.getBatch("batch_abc123");
+   * ```
+   */
+  async getBatch(batchId) {
+    return this.get(`/batch/${batchId}`);
+  }
+  /**
+   * Poll a job until it completes or fails.
+   *
+   * ```ts
+   * const result = await yt.waitForJob("job_abc123", {
+   *   interval: 5000,
+   *   maxAttempts: 60,
+   * });
+   * ```
+   */
+  async waitForJob(jobId, options) {
+    const interval = options?.interval || 5e3;
+    const maxAttempts = options?.maxAttempts || 60;
+    for (let i = 0; i < maxAttempts; i++) {
+      const result = await this.getJob(jobId);
+      if (result.status === "completed" || result.status === "failed") {
+        return result;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(
+      `Job ${jobId} did not complete after ${maxAttempts} attempts`
+    );
+  }
+  /**
+   * Poll a batch until it completes.
+   */
+  async waitForBatch(batchId, options) {
+    const interval = options?.interval || 5e3;
+    const maxAttempts = options?.maxAttempts || 60;
+    for (let i = 0; i < maxAttempts; i++) {
+      const result = await this.getBatch(batchId);
+      if (result.status === "completed") {
+        return result;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(
+      `Batch ${batchId} did not complete after ${maxAttempts} attempts`
+    );
+  }
+  // ---------------------------------------------------
+  // HTTP helpers
+  // ---------------------------------------------------
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "youtube-transcript-sdk/1.0.0"
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw this.createError(response.status, data, response.headers);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof YouTubeTranscriptError) throw error;
+      if (error.name === "AbortError") {
+        throw new Error(`Request to ${path} timed out after ${this.timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  createError(status, body, headers) {
+    switch (status) {
+      case 400:
+        return new InvalidRequestError(body);
+      case 401:
+        return new AuthenticationError(body);
+      case 402:
+        return new InsufficientCreditsError(body);
+      case 404:
+        return new NoCaptionsError(body);
+      case 429: {
+        const retryAfter = headers.get("Retry-After");
+        return new RateLimitError(
+          body,
+          retryAfter ? parseInt(retryAfter, 10) : void 0
+        );
+      }
+      default:
+        return new YouTubeTranscriptError(status, body);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  InsufficientCreditsError,
+  InvalidRequestError,
+  NoCaptionsError,
+  RateLimitError,
+  YouTubeTranscript,
+  YouTubeTranscriptError
+});

package/dist/index.mjs

@@ -0,0 +1,238 @@
+// src/errors.ts
+var YouTubeTranscriptError = class extends Error {
+  constructor(status, body) {
+    super(body.message || body.error);
+    this.name = "YouTubeTranscriptError";
+    this.status = status;
+    this.errorCode = body.error;
+    this.details = body.details;
+  }
+};
+var InvalidRequestError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(400, body);
+    this.name = "InvalidRequestError";
+  }
+};
+var AuthenticationError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(401, body);
+    this.name = "AuthenticationError";
+  }
+};
+var InsufficientCreditsError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(402, body);
+    this.name = "InsufficientCreditsError";
+  }
+};
+var NoCaptionsError = class extends YouTubeTranscriptError {
+  constructor(body) {
+    super(404, body);
+    this.name = "NoCaptionsError";
+  }
+};
+var RateLimitError = class extends YouTubeTranscriptError {
+  constructor(body, retryAfter) {
+    super(429, body);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://youtubetranscript.dev/api/v2";
+var DEFAULT_TIMEOUT = 3e4;
+var YouTubeTranscript = class {
+  /**
+   * Create a new YouTubeTranscript client.
+   *
+   * ```ts
+   * const yt = new YouTubeTranscript({ apiKey: "your_api_key" });
+   * ```
+   *
+   * Get your API key at https://youtubetranscript.dev
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error(
+        "API key is required. Get one at https://youtubetranscript.dev"
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  // ---------------------------------------------------
+  // Public methods
+  // ---------------------------------------------------
+  /**
+   * Transcribe a single YouTube video.
+   *
+   * ```ts
+   * const result = await yt.transcribe({ video: "dQw4w9WgXcQ" });
+   * console.log(result.data?.transcript.text);
+   * ```
+   */
+  async transcribe(request) {
+    return this.post("/transcribe", request);
+  }
+  /**
+   * Shorthand: transcribe a video by URL or ID with minimal config.
+   *
+   * ```ts
+   * const result = await yt.getTranscript("dQw4w9WgXcQ");
+   * ```
+   */
+  async getTranscript(video, language) {
+    return this.transcribe({ video, language });
+  }
+  /**
+   * Transcribe multiple videos in a single request (up to 100).
+   *
+   * ```ts
+   * const result = await yt.batch({
+   *   video_ids: ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
+   * });
+   * ```
+   */
+  async batch(request) {
+    return this.post("/batch", request);
+  }
+  /**
+   * Poll an async transcription job (ASR).
+   *
+   * ```ts
+   * const status = await yt.getJob("job_abc123");
+   * ```
+   */
+  async getJob(jobId, options) {
+    const params = new URLSearchParams();
+    if (options?.include_segments) params.set("include_segments", "true");
+    if (options?.include_paragraphs) params.set("include_paragraphs", "true");
+    if (options?.include_words) params.set("include_words", "true");
+    const query = params.toString();
+    const path = `/jobs/${jobId}${query ? `?${query}` : ""}`;
+    return this.get(path);
+  }
+  /**
+   * Poll a batch job.
+   *
+   * ```ts
+   * const status = await yt.getBatch("batch_abc123");
+   * ```
+   */
+  async getBatch(batchId) {
+    return this.get(`/batch/${batchId}`);
+  }
+  /**
+   * Poll a job until it completes or fails.
+   *
+   * ```ts
+   * const result = await yt.waitForJob("job_abc123", {
+   *   interval: 5000,
+   *   maxAttempts: 60,
+   * });
+   * ```
+   */
+  async waitForJob(jobId, options) {
+    const interval = options?.interval || 5e3;
+    const maxAttempts = options?.maxAttempts || 60;
+    for (let i = 0; i < maxAttempts; i++) {
+      const result = await this.getJob(jobId);
+      if (result.status === "completed" || result.status === "failed") {
+        return result;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(
+      `Job ${jobId} did not complete after ${maxAttempts} attempts`
+    );
+  }
+  /**
+   * Poll a batch until it completes.
+   */
+  async waitForBatch(batchId, options) {
+    const interval = options?.interval || 5e3;
+    const maxAttempts = options?.maxAttempts || 60;
+    for (let i = 0; i < maxAttempts; i++) {
+      const result = await this.getBatch(batchId);
+      if (result.status === "completed") {
+        return result;
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    throw new Error(
+      `Batch ${batchId} did not complete after ${maxAttempts} attempts`
+    );
+  }
+  // ---------------------------------------------------
+  // HTTP helpers
+  // ---------------------------------------------------
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "youtube-transcript-sdk/1.0.0"
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        throw this.createError(response.status, data, response.headers);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof YouTubeTranscriptError) throw error;
+      if (error.name === "AbortError") {
+        throw new Error(`Request to ${path} timed out after ${this.timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  createError(status, body, headers) {
+    switch (status) {
+      case 400:
+        return new InvalidRequestError(body);
+      case 401:
+        return new AuthenticationError(body);
+      case 402:
+        return new InsufficientCreditsError(body);
+      case 404:
+        return new NoCaptionsError(body);
+      case 429: {
+        const retryAfter = headers.get("Retry-After");
+        return new RateLimitError(
+          body,
+          retryAfter ? parseInt(retryAfter, 10) : void 0
+        );
+      }
+      default:
+        return new YouTubeTranscriptError(status, body);
+    }
+  }
+};
+export {
+  AuthenticationError,
+  InsufficientCreditsError,
+  InvalidRequestError,
+  NoCaptionsError,
+  RateLimitError,
+  YouTubeTranscript,
+  YouTubeTranscriptError
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "youtube-audio-transcript-api",
+  "version": "1.0.0",
+  "description": "Official Node.js/TypeScript SDK for the YouTubeTranscript.dev API — extract, transcribe, and translate YouTube videos at scale.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "youtube",
+    "transcript",
+    "youtube-transcript",
+    "youtube-api",
+    "subtitles",
+    "captions",
+    "speech-to-text",
+    "asr",
+    "transcription",
+    "video-to-text",
+    "youtube-transcript-api",
+    "ai",
+    "batch",
+    "webhook"
+  ],
+  "author": "YouTubeTranscript.dev",
+  "license": "MIT",
+  "homepage": "https://youtubetranscript.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/youtubetranscript/youtube-transcript-api"
+  },
+  "bugs": {
+    "url": "https://github.com/youtubetranscript/youtube-transcript-api/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}