1.0.0: cover /me and job polling, document real platform support

Three things, all pointing at the same gap between what the SDK does and
what it says it does.

Coverage: the client was missing two of the API's eight endpoints. Adds
client.me() (free key validation + balance) and transcripts.job(jobId)
(poll an async audio-transcription job). A failed job is delivered as
ok:false at HTTP 200, which the shared envelope parser treats as a
request error, so parseEnvelope grew an allowFailureEnvelope option used
only by that route: the request succeeded, the job did not.

Docs: the README claimed YouTube only. video() and batch() have always
passed the input string straight through, so TikTok, Instagram and
direct media file URLs already worked. No behaviour change, just an
accurate README and JSDoc. channel/playlist/search stay marked as
YouTube-only, because they are.

Version: /docs/v1 promises the SDKs follow semver, and 0.x means the
opposite. Declaring the surface stable at 1.0.0 makes the published
promise true.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ksoEUHvR7DHdNujkGv8UT

Author: Chandler Casey

CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [1.0.0]
+
+First stable release. The public docs promise the SDKs follow semver, and a 0.x
+version says the opposite ("anything may break"), so the surface is now declared
+stable: breaking changes land only in a new major.
+
+Added
+
+- `client.me()` - validate the API key and read the credit balance. Free, and
+  unlike `health()` it authenticates, so it is a real credential test.
+- `transcripts.job(jobId)` - poll an async transcription job, created when a
+  video has no captions and the API escalates to transcribing its audio. A job
+  that failed is returned as a `TranscriptJob` with status `"failed"` rather
+  than thrown, because the request itself succeeded.
+- `Me` and `TranscriptJob` types.
+
+Changed
+
+- Documented the real platform coverage. `video()` and `batch()` accept YouTube,
+  TikTok and Instagram URLs as well as direct media file URLs, not YouTube only.
+  No behaviour change: the input string has always been passed through as-is.
+  `channel()`, `playlist()` and `search()` remain YouTube-only.
+
 ## [0.1.0]
 
 Initial release.

README.md

@@ -1,7 +1,9 @@
 # TranscriptFetch Node.js SDK
 
-The official Node.js / TypeScript client for the [TranscriptFetch API](https://transcriptfetch.com). Fetch YouTube transcripts, channels, playlists, and search as clean, typed data, with built-in retries, idempotency, and a typed error hierarchy.
+The official Node.js / TypeScript client for the [TranscriptFetch API](https://transcriptfetch.com). Fetch transcripts as clean, typed data, with built-in retries, idempotency, and a typed error hierarchy.
 
+- Transcripts from **YouTube, TikTok, Instagram, and direct media file URLs**
+- YouTube channel, playlist, and search listing
 - Typed responses (full TypeScript types, ESM + CommonJS)
 - Automatic retries on 429 and 5xx with backoff
 - Auto-generated idempotency keys on writes
@@ -34,14 +36,33 @@ console.log("credits left:", t.usage?.balance);
 
 Keep your key server-side. Never ship it to the browser.
 
+## Supported inputs
+
+`transcripts.video()` and `transcripts.batch()` accept:
+
+| Input | Example |
+| --- | --- |
+| YouTube URL or bare video ID | `https://youtu.be/aircAruvnKk`, `aircAruvnKk` |
+| TikTok video URL | `https://www.tiktok.com/@user/video/7137723462233555205` |
+| Instagram post or reel URL | `https://www.instagram.com/reel/Cxyz.../` |
+| Direct media file URL | `https://example.com/talk.mp3` |
+
+The string is sent to the API as-is, so the SDK never has to be upgraded for the
+API to accept a new input.
+
+`channel()`, `playlist()`, and `search()` are YouTube-only concepts and take
+YouTube handles, IDs, and queries.
+
 ## Endpoints
 
 ```ts
 await tf.transcripts.video(video);                     // single transcript (text + segments)
-await tf.transcripts.channel(channel, { limit, cursor });   // a channel's videos (metadata)
-await tf.transcripts.playlist(playlist, { limit, cursor }); // a playlist's videos
-await tf.transcripts.search(query, { limit, cursor });      // search YouTube
 await tf.transcripts.batch(videoIds);                  // up to 50 transcripts in one call
+await tf.transcripts.channel(channel, { limit, cursor });   // a YouTube channel's videos (metadata)
+await tf.transcripts.playlist(playlist, { limit, cursor }); // a YouTube playlist's videos
+await tf.transcripts.search(query, { limit, cursor });      // search YouTube
+await tf.transcripts.job(jobId);                       // poll an async transcription job (free)
+await tf.me();                                         // validate the key, read the balance (free)
 await tf.health();                                     // unauthenticated liveness probe
 ```
 
@@ -100,6 +121,11 @@ const tf = new TranscriptFetch({
 - API docs: https://transcriptfetch.com/docs
 - Python SDK: https://github.com/TranscriptFetch/python-sdk
 
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org/). Breaking
+changes only land in a new major version.
+
 ## License
 
 MIT

examples/quickstart.mjs

@@ -4,6 +4,7 @@ import { TranscriptFetch } from "transcriptfetch";
 
 const tf = new TranscriptFetch();
 
+// A TikTok or Instagram URL, or a direct media file URL, works here too.
 const t = await tf.transcripts.video("https://youtu.be/aircAruvnKk");
 console.log(t.title);
 console.log(t.text?.slice(0, 200), "...");

package-lock.json

@@ -1,9 +1,11 @@
 {
   "name": "transcriptfetch",
-  "version": "0.1.0",
-  "description": "Official Node.js/TypeScript SDK for the TranscriptFetch API: fetch YouTube transcripts, channels, playlists, and search as clean, typed data.",
+  "version": "1.0.0",
+  "description": "Official Node.js/TypeScript SDK for the TranscriptFetch API: transcripts for YouTube, TikTok, Instagram and direct media URLs, plus YouTube channel, playlist and search listing, as clean typed data.",
   "keywords": [
     "youtube",
+    "tiktok",
+    "instagram",
     "transcript",
     "captions",
     "subtitles",

package.json

@@ -2,7 +2,7 @@
 
 import { resolveConfig, type ClientOptions, type ResolvedConfig } from "./config";
 import { APIConnectionError, APITimeoutError } from "./errors";
-import type { Health } from "./models";
+import { normalizeMe, type Health, type Me } from "./models";
 import { Transcripts } from "./resources/transcripts";
 import { backoffMs, buildHeaders, isRetryable, newIdempotencyKey, parseEnvelope } from "./transport";
 
@@ -13,6 +13,8 @@ export interface RequestOptions {
   auth?: boolean;
   /** Auto-generate an Idempotency-Key when one is not supplied. */
   idempotent?: boolean;
+  /** Accept a 2xx `ok: false` body as data rather than raising (job polling). */
+  allowFailureEnvelope?: boolean;
 }
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
@@ -29,7 +31,7 @@ const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout
  * ```
  */
 export class TranscriptFetch {
-  /** The transcripts resource: video, channel, playlist, search, batch. */
+  /** The transcripts resource: video, batch, channel, playlist, search, job. */
   readonly transcripts: Transcripts;
   private readonly config: ResolvedConfig;
 
@@ -78,10 +80,20 @@ export class TranscriptFetch {
         attempt += 1;
         continue;
       }
-      return parseEnvelope(response);
+      return parseEnvelope(response, { allowFailureEnvelope: options.allowFailureEnvelope });
     }
   }
 
+  /**
+   * Validate the API key and read the account's credit balance. Free.
+   *
+   * Unlike {@link health}, this authenticates, so it is the right credential
+   * test for an integration.
+   */
+  async me(): Promise<Me> {
+    return normalizeMe(await this.request("GET", "/api/v1/me"));
+  }
+
   /** Unauthenticated liveness probe. No credits used. */
   async health(): Promise<Health> {
     return (await this.request("GET", "/api/v1/health", { auth: false })) as unknown as Health;

src/client.ts

@@ -1,6 +1,9 @@
 /**
  * Official Node.js / TypeScript SDK for the TranscriptFetch API.
  *
+ * Transcribes YouTube, TikTok and Instagram videos as well as direct media
+ * file URLs; channel, playlist and search listing are YouTube only.
+ *
  * ```ts
  * import { TranscriptFetch } from "transcriptfetch";
  *
@@ -37,5 +40,7 @@ export type {
   VideoList,
   BatchResult,
   BatchResponse,
+  TranscriptJob,
+  Me,
   Health,
 } from "./models";

src/index.ts

@@ -68,6 +68,34 @@ export interface BatchResponse {
   usage: Usage | null;
 }
 
+/** The account behind the API key, from `/me`. */
+export interface Me {
+  kind: "me";
+  userId: string;
+  /** Remaining credit balance. */
+  credits: number;
+  usage: Usage | null;
+}
+
+/**
+ * The state of an async transcription job.
+ *
+ * A job exists when a request had no captions to read and escalated to audio
+ * transcription. "failed" is a normal outcome here rather than an HTTP error:
+ * the endpoint answers 200 in all three states and `status` carries the meaning.
+ */
+export interface TranscriptJob {
+  kind: "transcript_job";
+  jobId: string;
+  /** processing | completed | failed */
+  status: string;
+  /** The finished transcript. Only present once `status` is "completed". */
+  transcript: Transcript | null;
+  /** Why the job failed. Only present when `status` is "failed". */
+  error: { code: string | null; message: string | null } | null;
+  usage: Usage | null;
+}
+
 /** The public health-check body. */
 export interface Health {
   status: string;
@@ -165,6 +193,42 @@ export function normalizeVideoList(env: Wire): VideoList {
   };
 }
 
+/** Parse a `{ data, usage }` account envelope. */
+export function normalizeMe(env: Wire): Me {
+  const d = obj(env.data);
+  return {
+    kind: "me",
+    userId: str(pick(d, "userId", "user_id")),
+    credits: num(pick(d, "credits")),
+    usage: normalizeUsage(env),
+  };
+}
+
+/**
+ * Parse a job-poll envelope.
+ *
+ * Unlike the other endpoints, status / job_id sit at the top level next to
+ * `data` rather than inside it, and a failed job arrives as `ok: false` with an
+ * `error` block at 200.
+ */
+export function normalizeJob(env: Wire): TranscriptJob {
+  const status = str(pick(env, "status"));
+  const rawError = obj(env.error);
+  const hasError = env.error != null && typeof env.error === "object";
+  return {
+    kind: "transcript_job",
+    jobId: str(pick(env, "jobId", "job_id")),
+    status,
+    // Only "completed" carries data; the other states leave it null so callers
+    // cannot mistake an empty placeholder for a real (empty) transcript.
+    transcript: status === "completed" ? normalizeTranscript(env) : null,
+    error: hasError
+      ? { code: strOrNull(pick(rawError, "code")), message: strOrNull(pick(rawError, "message")) }
+      : null,
+    usage: normalizeUsage(env),
+  };
+}
+
 /** Parse a `{ data, usage }` batch envelope. */
 export function normalizeBatch(env: Wire): BatchResponse {
   const d = obj(env.data);

src/models.ts

@@ -1,15 +1,17 @@
 /**
- * The `transcripts` resource: video / channel / playlist / search / batch,
- * plus auto-paginating async iterators.
+ * The `transcripts` resource: video / batch / channel / playlist / search /
+ * job, plus auto-paginating async iterators.
  */
 
 import type { TranscriptFetch } from "../client";
 import {
   normalizeBatch,
+  normalizeJob,
   normalizeTranscript,
   normalizeVideoList,
   type BatchResponse,
   type Transcript,
+  type TranscriptJob,
   type Video,
   type VideoList,
 } from "../models";
@@ -19,6 +21,7 @@ const CHANNEL = "/api/v1/transcripts/channel";
 const PLAYLIST = "/api/v1/transcripts/playlist";
 const SEARCH = "/api/v1/transcripts/search";
 const BATCH = "/api/v1/transcripts/batch";
+const JOBS = "/api/v1/transcripts/jobs";
 
 /** Options for the paginated list endpoints (channel, playlist, search). */
 export interface ListOptions {
@@ -40,7 +43,13 @@ function listBody(key: string, value: string, options: ListOptions): Record<stri
 export class Transcripts {
   constructor(private readonly client: TranscriptFetch) {}
 
-  /** Fetch a single video's transcript (text + timestamped segments). */
+  /**
+   * Fetch a single video's transcript (text + timestamped segments).
+   *
+   * Accepts a YouTube, TikTok or Instagram URL, a bare YouTube video ID, or a
+   * direct media file URL. The string is passed through to the API untouched,
+   * so newly supported inputs work without an SDK upgrade.
+   */
   async video(video: string, options: { idempotencyKey?: string } = {}): Promise<Transcript> {
     const env = await this.client.request("POST", VIDEO, {
       body: { video },
@@ -80,7 +89,7 @@ export class Transcripts {
     return normalizeVideoList(env);
   }
 
-  /** Fetch up to 50 transcripts in one call. */
+  /** Fetch up to 50 transcripts in one call. Same accepted inputs as {@link video}. */
   async batch(videoIds: string[], options: { idempotencyKey?: string } = {}): Promise<BatchResponse> {
     const env = await this.client.request("POST", BATCH, {
       body: { videoIds },
@@ -90,6 +99,22 @@ export class Transcripts {
     return normalizeBatch(env);
   }
 
+  /**
+   * Poll an async transcription job by id. Free: credits are charged once, on
+   * delivery.
+   *
+   * A job is created when a video has no captions and the API escalates to
+   * transcribing its audio. A failed job comes back as a `TranscriptJob` with
+   * status "failed" rather than as a thrown error, because the request itself
+   * succeeded.
+   */
+  async job(jobId: string): Promise<TranscriptJob> {
+    const env = await this.client.request("GET", `${JOBS}/${encodeURIComponent(jobId)}`, {
+      allowFailureEnvelope: true,
+    });
+    return normalizeJob(env);
+  }
+
   // ── Auto-paginating iterators ───────────────────────────────────────────────
 
   /** Iterate every video in a channel, transparently following cursors. */

src/resources/transcripts.ts

@@ -46,12 +46,25 @@ export function backoffMs(attempt: number, retryAfter?: string | null): number {
 
 type Envelope = Record<string, unknown>;
 
+export interface ParseOptions {
+  /**
+   * Return a 2xx `ok: false` body instead of throwing.
+   *
+   * Only the job-poll endpoint needs this: a job that failed to transcribe is a
+   * reportable state delivered at HTTP 200, not a failed request.
+   */
+  allowFailureEnvelope?: boolean;
+}
+
 /**
  * Return the parsed JSON body, or throw the mapped APIError. Handles both the
  * `{ ok, request_id, data, usage }` envelope and the bare health-check body
  * (which has no `ok` field).
  */
-export async function parseEnvelope(response: Response): Promise<Envelope> {
+export async function parseEnvelope(
+  response: Response,
+  options: ParseOptions = {},
+): Promise<Envelope> {
   let payload: unknown = null;
   try {
     payload = await response.json();
@@ -62,7 +75,9 @@ export async function parseEnvelope(response: Response): Promise<Envelope> {
   const isObj = payload != null && typeof payload === "object";
   const requestId = isObj ? ((payload as Envelope).request_id as string | undefined) ?? null : null;
 
-  const isError = response.status >= 400 || (isObj && (payload as Envelope).ok === false);
+  const failureEnvelope =
+    isObj && (payload as Envelope).ok === false && !options.allowFailureEnvelope;
+  const isError = response.status >= 400 || failureEnvelope;
   if (isError) {
     raiseApiError(
       response.status,