Podcast support in the docs and model, and fix the 202 async path

Podcasts: /transcripts/video accepts a Spotify or Apple Podcasts episode
URL or an RSS feed URL and resolves it to that episode's audio, so the
README, JSDoc and keywords now say so. Adds Transcript.podcast (show,
episode, published_at, feed_url, audio_url, resolved_via) and
Transcript.platform, both already on the wire and both previously
dropped on the floor by the normalizer.

202: a source without captions is transcribed from its audio and answers
202 with data.kind "transcript_job" and no text. The SDK ran that through
the transcript normalizer and handed back an empty Transcript with no
sign a job existed. Fixed the way the Python SDK does it, so the two
behave the same: kind relaxed from a literal to a string, data: null
tolerated (obj() already absorbed it), and the envelope's status, job_id
and poll_url lifted onto the model. Additive, so nothing that compiled
before stops compiling.

TranscriptJob now extends Transcript instead of wrapping one, which is
what makes the poll loop a plain `while (t.status === "processing")`
with the same shape coming out of video() and job(). It keeps the extra
error block, since a failed job is still delivered as ok:false at 200.

The README poll loop was compiled against src before being written down.

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

Author: Chandler Casey

CHANGELOG.md

@@ -14,17 +14,28 @@ 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.
+  source has no captions and the API escalates to transcribing its audio. A job
+  that failed is returned with status `"failed"` rather than thrown, because
+  the request itself succeeded.
+- Async job support on `Transcript`. A source without captions answers 202 with
+  no text, which the SDK used to hand back as an empty transcript with no sign a
+  job existed. `status`, `jobId` and `pollUrl` are now lifted from the envelope
+  onto the model, so `video()` and `job()` return the same shape and the poll
+  loop is a `while (t.status === "processing")`.
+- `Transcript.podcast`, the show and episode behind a podcast transcript, and
+  `Transcript.platform` (`youtube` | `tiktok` | `instagram` | `podcast` | `file`).
+- `Me`, `TranscriptJob` and `PodcastMeta` 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.
+  TikTok and Instagram URLs, direct media file URLs, and podcast links (Spotify,
+  Apple Podcasts, or an RSS feed), not YouTube only. No behaviour change: the
+  input string has always been passed through as-is. `channel()`, `playlist()`
+  and `search()` remain YouTube-only, because no other source has those.
+- `Transcript.kind` is a plain string rather than the literal `"transcript"`.
+  A 202 returns `"transcript_job"`, and pinning the type made a valid response
+  look like a wrong one.
 
 ## [0.1.0]
 

README.md

@@ -2,7 +2,7 @@
 
 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**
+- Transcripts from **YouTube, TikTok, Instagram, podcasts, 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
@@ -45,14 +45,46 @@ Keep your key server-side. Never ship it to the browser.
 | 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.../` |
+| Podcast episode or feed | `https://open.spotify.com/episode/...`, `https://podcasts.apple.com/...`, `https://feeds.example.com/show.xml` |
 | 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.
 
+A podcast link is resolved to that episode's audio automatically, and the
+response carries a `podcast` block naming the show and episode:
+
+```ts
+const t = await tf.transcripts.video("https://open.spotify.com/episode/...");
+console.log(t.podcast?.show, "-", t.podcast?.episode);
+```
+
 `channel()`, `playlist()`, and `search()` are YouTube-only concepts and take
 YouTube handles, IDs, and queries.
 
+## Sources without captions
+
+When a source has no captions the API transcribes its audio, which takes longer
+than one request. You get a transcript back with `status: "processing"` and a
+`jobId` instead of text. Poll it:
+
+```ts
+let t = await tf.transcripts.video("https://example.com/episode.mp3");
+
+while (t.status === "processing") {
+  await new Promise((r) => setTimeout(r, 5_000));
+  // Polling is free: credits are charged once, on delivery.
+  const polled = await tf.transcripts.job(t.jobId!);
+  if (polled.status === "failed") throw new Error(polled.error?.message ?? "job failed");
+  t = polled;
+}
+
+console.log(t.text);
+```
+
+Everything else answers in one call, so `status` is null there and no polling is
+needed.
+
 ## Endpoints
 
 ```ts

src/index.ts

@@ -1,8 +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.
+ * Transcribes YouTube, TikTok and Instagram videos, direct media file URLs,
+ * and podcast episodes (Spotify, Apple Podcasts, or an RSS feed); channel,
+ * playlist and search listing are YouTube only.
  *
  * ```ts
  * import { TranscriptFetch } from "transcriptfetch";
@@ -36,6 +37,7 @@ export type {
   Usage,
   Segment,
   Transcript,
+  PodcastMeta,
   Video,
   VideoList,
   BatchResult,

src/models.ts

@@ -21,14 +21,52 @@ export interface Segment {
   text: string;
 }
 
-/** A single video's transcript. */
+/**
+ * The show and episode behind a podcast transcript.
+ *
+ * Present only when the input resolved to a podcast episode. A job polled back
+ * later carries the short form (show + episode); the rest is filled in on the
+ * response that did the resolving, so treat every field as optional.
+ */
+export interface PodcastMeta {
+  show: string | null;
+  episode: string | null;
+  publishedAt: string | null;
+  feedUrl: string | null;
+  audioUrl: string | null;
+  /** How the link was matched to a feed, e.g. "rss" or "itunes_search". */
+  resolvedVia: string | null;
+}
+
+/**
+ * A single video's transcript, from any supported source.
+ *
+ * This also covers the "not ready yet" case. A source with no captions is
+ * transcribed from its audio, and the API answers 202 with `kind:
+ * "transcript_job"` and no text. `kind` is therefore a plain string rather than
+ * a literal: pinning it would make a perfectly good 202 look like a wrong
+ * shape. When `status` is "processing", pass `jobId` to `transcripts.job()`
+ * until it reports "completed".
+ */
 export interface Transcript {
-  kind: "transcript";
+  /** transcript | transcript_job */
+  kind: string;
   videoId: string;
+  /** Source platform: youtube | tiktok | instagram | podcast | file. */
+  platform: string | null;
   title: string | null;
   text: string | null;
   segments: Segment[];
+  /** Set only when the input resolved to a podcast episode. */
+  podcast: PodcastMeta | null;
   usage: Usage | null;
+  // Envelope-level fields, lifted onto the model so an async job round-trips as
+  // one object (the API returns them beside `data`, not inside it).
+  /** processing | completed | failed. Only set on async transcription jobs. */
+  status: string | null;
+  jobId: string | null;
+  /** Path to poll for the finished transcript. */
+  pollUrl: string | null;
 }
 
 /** A video reference from a channel/playlist/search list (metadata only). */
@@ -78,22 +116,18 @@ export interface Me {
 }
 
 /**
- * The state of an async transcription job.
+ * A polled transcription job: a {@link Transcript} plus why it failed, if it did.
+ *
+ * It extends Transcript rather than wrapping one so the poll loop reads the
+ * same whether the transcript arrived synchronously or via a job, and so the
+ * completed job can be handed to anything that takes a Transcript.
  *
- * 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.
+ * "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;
+export interface TranscriptJob extends Transcript {
   /** 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. */
@@ -167,16 +201,41 @@ function normalizeVideo(raw: unknown): Video {
   };
 }
 
-/** Parse a `{ data, usage }` transcript envelope. */
+function normalizePodcast(raw: unknown): PodcastMeta | null {
+  if (!raw || typeof raw !== "object") return null;
+  const p = raw as Wire;
+  return {
+    show: strOrNull(pick(p, "show")),
+    episode: strOrNull(pick(p, "episode")),
+    publishedAt: strOrNull(pick(p, "publishedAt", "published_at")),
+    feedUrl: strOrNull(pick(p, "feedUrl", "feed_url")),
+    audioUrl: strOrNull(pick(p, "audioUrl", "audio_url")),
+    resolvedVia: strOrNull(pick(p, "resolvedVia", "resolved_via")),
+  };
+}
+
+/**
+ * Parse a `{ data, usage }` transcript envelope.
+ *
+ * `data` is null while an async job is still processing, which `obj()` already
+ * absorbs, so a 202 parses into a Transcript carrying only its job fields.
+ */
 export function normalizeTranscript(env: Wire): Transcript {
   const d = obj(env.data);
   return {
-    kind: "transcript",
+    // Trust the wire kind: a 202 says "transcript_job", a finished one says
+    // "transcript".
+    kind: str(pick(d, "kind")) || "transcript",
     videoId: str(pick(d, "videoId", "video_id")),
+    platform: strOrNull(pick(d, "platform")),
     title: strOrNull(pick(d, "title")),
     text: strOrNull(pick(d, "text")),
     segments: normalizeSegments(d.segments),
+    podcast: normalizePodcast(d.podcast),
     usage: normalizeUsage(env),
+    status: strOrNull(pick(env, "status")),
+    jobId: strOrNull(pick(env, "jobId", "job_id")),
+    pollUrl: strOrNull(pick(env, "pollUrl", "poll_url")),
   };
 }
 
@@ -205,27 +264,17 @@ export function normalizeMe(env: Wire): Me {
 }
 
 /**
- * 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.
+ * Parse a job-poll envelope: a transcript envelope that may also carry an
+ * `error` block, which a failed job delivers at HTTP 200 alongside `ok: false`.
  */
 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,
+    ...normalizeTranscript(env),
     error: hasError
       ? { code: strOrNull(pick(rawError, "code")), message: strOrNull(pick(rawError, "message")) }
       : null,
-    usage: normalizeUsage(env),
   };
 }
 

src/resources/transcripts.ts

@@ -44,11 +44,17 @@ export class Transcripts {
   constructor(private readonly client: TranscriptFetch) {}
 
   /**
-   * Fetch a single video's transcript (text + timestamped segments).
+   * Fetch a single 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.
+   * Accepts a YouTube, TikTok or Instagram URL, a bare YouTube video ID, a
+   * direct media file URL, or a podcast link (Spotify, Apple Podcasts, or an
+   * RSS feed), which is resolved to that episode's audio and comes back with a
+   * `podcast` block. The string is passed through to the API untouched, so
+   * newly supported inputs work without an SDK upgrade.
+   *
+   * A source with no captions is transcribed from its audio, and the result
+   * comes back as a job: `status` is "processing" and `jobId` is set, with no
+   * text yet. Poll {@link job} with that id until it reports "completed".
    */
   async video(video: string, options: { idempotencyKey?: string } = {}): Promise<Transcript> {
     const env = await this.client.request("POST", VIDEO, {
@@ -103,10 +109,18 @@ export class Transcripts {
    * 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.
+   * Returns the same shape {@link video} does, plus an `error` block. A failed
+   * job comes back as status "failed" rather than as a thrown error, because
+   * the request itself succeeded.
+   *
+   * ```ts
+   * let t = await tf.transcripts.video("https://example.com/episode.mp3");
+   * while (t.status === "processing") {
+   *   await new Promise((r) => setTimeout(r, 5000));
+   *   t = await tf.transcripts.job(t.jobId!);
+   * }
+   * console.log(t.text);
+   * ```
    */
   async job(jobId: string): Promise<TranscriptJob> {
     const env = await this.client.request("GET", `${JOBS}/${encodeURIComponent(jobId)}`, {