ytranscript-api 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# ytranscript-api
+
+Official JavaScript/TypeScript client for the [yTranscript API](https://ytranscript.com/developers) — reliable YouTube transcript extraction without IP bans, proxy management, or player-response scraping.
+
+- **No IP bans** — the managed extraction layer absorbs YouTube's bot detection for you
+- **Captionless videos work** — automatic Whisper speech-to-text fallback
+- **Simple, typed** — one method, structured segments, zero dependencies
+
+## Install
+
+```bash
+npm install ytranscript-api
+```
+
+## Quickstart
+
+```ts
+import { YTranscript } from "ytranscript-api";
+
+const yt = new YTranscript("yk_live_...");   // get a key at ytranscript.com/developers
+
+const t = await yt.transcript("dQw4w9WgXcQ");        // video ID or any YouTube URL
+console.log(t.lang);                                  // "en"
+console.log(t.segments[0]);                           // { text, offset, duration }
+console.log(t.text);                                  // full transcript as one string
+
+console.log(yt.lastQuota);                            // { limit, used, rateLimitRemaining }
+```
+
+### Options
+
+```ts
+await yt.transcript("https://youtu.be/dQw4w9WgXcQ", { lang: "es" });
+
+new YTranscript(key, { timeoutMs: 60_000 });
+```
+
+### Error handling
+
+```ts
+import { YTranscriptError } from "ytranscript-api";
+
+try {
+  await yt.transcript(videoId);
+} catch (err) {
+  if (err instanceof YTranscriptError) {
+    err.code;    // "no_transcript" | "quota_exceeded" | "rate_limited" | ...
+    err.status;  // HTTP status
+  }
+}
+```
+
+## Pricing & keys
+
+Plans start at $29/mo for 10,000 units (captions = 1 unit, Whisper = 15 units). Get an API key at **[ytranscript.com/developers](https://ytranscript.com/developers)**.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,114 @@
+"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, {
+  YTranscript: () => YTranscript,
+  YTranscriptError: () => YTranscriptError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://ytranscript.com/api/v1";
+var YTranscriptError = class extends Error {
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "YTranscriptError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var YTranscript = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  /** Quota headers from the most recent successful request */
+  lastQuota = null;
+  constructor(apiKey, options = {}) {
+    if (!apiKey || !apiKey.startsWith("yk_")) {
+      throw new YTranscriptError(
+        "unauthorized",
+        0,
+        "An API key (yk_live_...) is required. Get one at https://ytranscript.com/developers"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+  }
+  /**
+   * Fetch the transcript for a video. Accepts a video ID or any YouTube URL.
+   */
+  async transcript(videoIdOrUrl, options = {}) {
+    const params = new URLSearchParams();
+    if (/^[\w-]{11}$/.test(videoIdOrUrl)) {
+      params.set("videoId", videoIdOrUrl);
+    } else {
+      params.set("url", videoIdOrUrl);
+    }
+    if (options.lang) params.set("lang", options.lang);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}/transcript?${params}`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw new YTranscriptError(
+        "network_error",
+        0,
+        `Request failed: ${err instanceof Error ? err.message : "unknown network error"}`
+      );
+    }
+    const limit = Number(response.headers.get("x-quota-limit"));
+    const used = Number(response.headers.get("x-quota-used"));
+    const rateRemaining = Number(response.headers.get("x-ratelimit-remaining"));
+    if (Number.isFinite(limit) && Number.isFinite(used)) {
+      this.lastQuota = {
+        limit,
+        used,
+        rateLimitRemaining: Number.isFinite(rateRemaining) ? rateRemaining : 0
+      };
+    }
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+      const code = body?.error?.code ?? "fetch_failed";
+      const message = body?.error?.message ?? `Request failed with status ${response.status}`;
+      throw new YTranscriptError(code, response.status, message);
+    }
+    const segments = body.segments ?? [];
+    return {
+      videoId: body.video_id,
+      lang: body.lang,
+      whisper: Boolean(body.whisper),
+      cached: Boolean(body.cached),
+      unitsCharged: Number(body.units_charged ?? 1),
+      segments,
+      text: segments.map((s) => s.text).join(" ")
+    };
+  }
+};
+var index_default = YTranscript;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  YTranscript,
+  YTranscriptError
+});

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+/**
+ * ytranscript-api — official JavaScript/TypeScript client for the yTranscript API.
+ *
+ * Docs & API keys: https://ytranscript.com/developers
+ */
+interface TranscriptSegment {
+    /** Segment text */
+    text: string;
+    /** Start offset in milliseconds */
+    offset: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+interface Transcript {
+    videoId: string;
+    /** BCP-47-ish language code of the returned transcript */
+    lang: string;
+    /** True when the transcript was produced by Whisper speech-to-text (captionless video) */
+    whisper: boolean;
+    /** True when served from cache */
+    cached: boolean;
+    /** Quota units this request consumed (captions: 1, Whisper: 15) */
+    unitsCharged: number;
+    segments: TranscriptSegment[];
+    /** Convenience: all segment text joined with spaces */
+    text: string;
+}
+interface QuotaInfo {
+    limit: number;
+    used: number;
+    rateLimitRemaining: number;
+}
+type ErrorCode = "unauthorized" | "quota_exceeded" | "rate_limited" | "bad_request" | "no_transcript" | "fetch_failed" | "network_error";
+declare class YTranscriptError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    constructor(code: ErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** Override the API base URL (rarely needed) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 120s — Whisper fallbacks take time) */
+    timeoutMs?: number;
+}
+interface TranscriptOptions {
+    /** Preferred language code (e.g. "en", "es"). Defaults to the video's source language. */
+    lang?: string;
+}
+declare class YTranscript {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    /** Quota headers from the most recent successful request */
+    lastQuota: QuotaInfo | null;
+    constructor(apiKey: string, options?: ClientOptions);
+    /**
+     * Fetch the transcript for a video. Accepts a video ID or any YouTube URL.
+     */
+    transcript(videoIdOrUrl: string, options?: TranscriptOptions): Promise<Transcript>;
+}
+
+export { type ClientOptions, type ErrorCode, type QuotaInfo, type Transcript, type TranscriptOptions, type TranscriptSegment, YTranscript, YTranscriptError, YTranscript as default };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ytranscript-api — official JavaScript/TypeScript client for the yTranscript API.
+ *
+ * Docs & API keys: https://ytranscript.com/developers
+ */
+interface TranscriptSegment {
+    /** Segment text */
+    text: string;
+    /** Start offset in milliseconds */
+    offset: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+interface Transcript {
+    videoId: string;
+    /** BCP-47-ish language code of the returned transcript */
+    lang: string;
+    /** True when the transcript was produced by Whisper speech-to-text (captionless video) */
+    whisper: boolean;
+    /** True when served from cache */
+    cached: boolean;
+    /** Quota units this request consumed (captions: 1, Whisper: 15) */
+    unitsCharged: number;
+    segments: TranscriptSegment[];
+    /** Convenience: all segment text joined with spaces */
+    text: string;
+}
+interface QuotaInfo {
+    limit: number;
+    used: number;
+    rateLimitRemaining: number;
+}
+type ErrorCode = "unauthorized" | "quota_exceeded" | "rate_limited" | "bad_request" | "no_transcript" | "fetch_failed" | "network_error";
+declare class YTranscriptError extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    constructor(code: ErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** Override the API base URL (rarely needed) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 120s — Whisper fallbacks take time) */
+    timeoutMs?: number;
+}
+interface TranscriptOptions {
+    /** Preferred language code (e.g. "en", "es"). Defaults to the video's source language. */
+    lang?: string;
+}
+declare class YTranscript {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    /** Quota headers from the most recent successful request */
+    lastQuota: QuotaInfo | null;
+    constructor(apiKey: string, options?: ClientOptions);
+    /**
+     * Fetch the transcript for a video. Accepts a video ID or any YouTube URL.
+     */
+    transcript(videoIdOrUrl: string, options?: TranscriptOptions): Promise<Transcript>;
+}
+
+export { type ClientOptions, type ErrorCode, type QuotaInfo, type Transcript, type TranscriptOptions, type TranscriptSegment, YTranscript, YTranscriptError, YTranscript as default };

package/dist/index.js

@@ -0,0 +1,88 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://ytranscript.com/api/v1";
+var YTranscriptError = class extends Error {
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "YTranscriptError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var YTranscript = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  /** Quota headers from the most recent successful request */
+  lastQuota = null;
+  constructor(apiKey, options = {}) {
+    if (!apiKey || !apiKey.startsWith("yk_")) {
+      throw new YTranscriptError(
+        "unauthorized",
+        0,
+        "An API key (yk_live_...) is required. Get one at https://ytranscript.com/developers"
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+  }
+  /**
+   * Fetch the transcript for a video. Accepts a video ID or any YouTube URL.
+   */
+  async transcript(videoIdOrUrl, options = {}) {
+    const params = new URLSearchParams();
+    if (/^[\w-]{11}$/.test(videoIdOrUrl)) {
+      params.set("videoId", videoIdOrUrl);
+    } else {
+      params.set("url", videoIdOrUrl);
+    }
+    if (options.lang) params.set("lang", options.lang);
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}/transcript?${params}`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw new YTranscriptError(
+        "network_error",
+        0,
+        `Request failed: ${err instanceof Error ? err.message : "unknown network error"}`
+      );
+    }
+    const limit = Number(response.headers.get("x-quota-limit"));
+    const used = Number(response.headers.get("x-quota-used"));
+    const rateRemaining = Number(response.headers.get("x-ratelimit-remaining"));
+    if (Number.isFinite(limit) && Number.isFinite(used)) {
+      this.lastQuota = {
+        limit,
+        used,
+        rateLimitRemaining: Number.isFinite(rateRemaining) ? rateRemaining : 0
+      };
+    }
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+      const code = body?.error?.code ?? "fetch_failed";
+      const message = body?.error?.message ?? `Request failed with status ${response.status}`;
+      throw new YTranscriptError(code, response.status, message);
+    }
+    const segments = body.segments ?? [];
+    return {
+      videoId: body.video_id,
+      lang: body.lang,
+      whisper: Boolean(body.whisper),
+      cached: Boolean(body.cached),
+      unitsCharged: Number(body.units_charged ?? 1),
+      segments,
+      text: segments.map((s) => s.text).join(" ")
+    };
+  }
+};
+var index_default = YTranscript;
+export {
+  YTranscript,
+  YTranscriptError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ytranscript-api",
+  "version": "0.1.0",
+  "description": "Reliable YouTube transcript extraction API client — no IP bans, no proxy management, Whisper fallback for captionless videos.",
+  "keywords": [
+    "youtube",
+    "transcript",
+    "youtube transcript api",
+    "captions",
+    "subtitles",
+    "whisper",
+    "speech-to-text"
+  ],
+  "homepage": "https://ytranscript.com/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nnnoel/ytranscript.git",
+    "directory": "sdk/js"
+  },
+  "license": "MIT",
+  "author": "yTranscript <support@ytranscript.com>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}