Initial commit: TranscriptFetch Python SDK v0.1.0

Sync + async httpx clients, Pydantic v2 models, typed error hierarchy,
auto-pagination, retries with auto Idempotency-Key. Covers video/channel/
playlist/search/batch + health. Fully tested (respx), ruff + mypy clean.

Author: Chandler Casey

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Type check (mypy)
+        run: mypy src
+      - name: Test (pytest)
+        run: pytest -q

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+# Publishes to PyPI on a version tag (e.g. v0.1.0) using PyPI Trusted Publishing
+# (OIDC): no API tokens stored. Configure the publisher on PyPI first:
+# https://docs.pypi.org/trusted-publishers/
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Envs
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org).
+
+## [0.1.0] - Unreleased
+
+Initial release.
+
+- Sync `TranscriptFetch` and async `AsyncTranscriptFetch` clients (httpx).
+- `transcripts.video / channel / playlist / search / batch` + `health()`.
+- Auto-paginating `iter_channel / iter_playlist / iter_search`.
+- Typed Pydantic v2 models (`Transcript`, `VideoList`, `Video`, `Segment`, `BatchResponse`, `Usage`).
+- Typed exception hierarchy mapped from the API's canonical error codes.
+- Automatic retries with backoff (429 + 5xx) and auto Idempotency-Key.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TranscriptFetch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,102 @@
+# TranscriptFetch Python SDK
+
+Official, typed Python client for the [TranscriptFetch](https://transcriptfetch.com) API: fetch YouTube transcripts, channels, playlists, and search results as clean, structured data. Sync + async, fully type-hinted.
+
+```bash
+pip install transcriptfetch-sdk
+```
+
+## Quickstart
+
+```python
+from transcriptfetch import TranscriptFetch
+
+# api_key falls back to the TRANSCRIPTFETCH_API_KEY env var
+tf = TranscriptFetch(api_key="tf_live_...")
+
+t = tf.transcripts.video("https://youtu.be/aircAruvnKk")
+print(t.title)
+print(t.text)
+for seg in t.segments:
+    print(f"[{seg.start:.1f}] {seg.text}")
+
+print("credits left:", t.usage.balance)
+```
+
+Get an API key (100 free credits) at <https://transcriptfetch.com/app>. One credit per successful fetch; failed/blocked/no-transcript requests are free.
+
+## Endpoints
+
+```python
+tf.transcripts.video(video)                    # single transcript (text + segments)
+tf.transcripts.channel(channel, limit=, cursor=)   # a channel's videos (metadata)
+tf.transcripts.playlist(playlist, limit=, cursor=) # a playlist's videos
+tf.transcripts.search(query, limit=, cursor=)      # search YouTube
+tf.transcripts.batch(video_ids)                # up to 50 transcripts in one call
+tf.health()                                    # unauthenticated liveness probe
+```
+
+`video`/`channel`/`playlist` accept URLs or raw IDs (normalized automatically).
+
+## Pagination
+
+List endpoints are cursor-paginated. Iterate every result without managing cursors:
+
+```python
+for video in tf.transcripts.iter_channel("@lexfridman", limit=10):
+    print(video.video_id, video.title)
+```
+
+Or page manually via `page.next_cursor` and the `cursor=` argument.
+
+## Async
+
+```python
+import asyncio
+from transcriptfetch import AsyncTranscriptFetch
+
+async def main():
+    async with AsyncTranscriptFetch() as tf:
+        t = await tf.transcripts.video("aircAruvnKk")
+        print(t.text)
+        async for v in tf.transcripts.iter_search("how transformers work", limit=10):
+            print(v.title)
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `TranscriptFetchError`. API errors carry `.status`, `.code`, `.message`, and `.request_id`:
+
+```python
+from transcriptfetch import (
+    AuthenticationError, InsufficientCreditsError, InvalidRequestError,
+    RateLimitError, IdempotencyConflictError, UpstreamUnavailableError,
+    InternalServerError, APIError, APIConnectionError, APITimeoutError,
+)
+
+try:
+    tf.transcripts.video("bad")
+except InsufficientCreditsError:
+    ...                       # 402: top up at /pricing
+except RateLimitError as e:
+    print(e.retry_after)      # 429
+except APIError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+## Reliability
+
+- **Automatic retries** on `429` (honoring `Retry-After`) and `5xx`, with exponential backoff + jitter (`max_retries=2` by default).
+- **Idempotency**: every write auto-sends an `Idempotency-Key` so a retried request is never double-charged. Override per call with `idempotency_key=...`.
+- **Configurable:** `TranscriptFetch(api_key=..., base_url=..., timeout=30, max_retries=2)`. Both clients are context managers and accept a custom `http_client=` (httpx).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check . && mypy src && pytest
+```
+
+Tests are fully mocked (no network). MIT licensed.

examples/async_example.py

@@ -0,0 +1,14 @@
+"""Async usage. TRANSCRIPTFETCH_API_KEY=tf_live_... python examples/async_example.py"""
+
+import asyncio
+
+from transcriptfetch import AsyncTranscriptFetch
+
+
+async def main() -> None:
+    async with AsyncTranscriptFetch() as tf:
+        t = await tf.transcripts.video("aircAruvnKk")
+        print((t.text or "(no transcript)")[:200])
+
+
+asyncio.run(main())

examples/batch.py

@@ -0,0 +1,10 @@
+"""Fetch up to 50 transcripts in one call."""
+
+from transcriptfetch import TranscriptFetch
+
+with TranscriptFetch() as tf:
+    res = tf.transcripts.batch(["aircAruvnKk", "Tn6-PIqc4UM"])
+    for r in res.results:
+        print(r.video_id, r.outcome, "-", (r.text or "")[:60])
+    if res.usage:
+        print("credits spent:", res.usage.credits_spent)

examples/paginate.py

@@ -0,0 +1,9 @@
+"""Auto-paginate through a channel's videos (follows next_cursor for you)."""
+
+from transcriptfetch import TranscriptFetch
+
+with TranscriptFetch() as tf:
+    for i, video in enumerate(tf.transcripts.iter_channel("@lexfridman", limit=10)):
+        print(video.video_id, "-", video.title)
+        if i >= 24:  # stop after 25
+            break

examples/quickstart.py

@@ -0,0 +1,14 @@
+"""Fetch a single transcript.
+
+Run with your key set:  TRANSCRIPTFETCH_API_KEY=tf_live_... python examples/quickstart.py
+"""
+
+from transcriptfetch import TranscriptFetch
+
+with TranscriptFetch() as tf:  # reads TRANSCRIPTFETCH_API_KEY
+    t = tf.transcripts.video("https://youtu.be/aircAruvnKk")
+    print("title:", t.title)
+    print("text:", (t.text or "(no transcript)")[:500])
+    print("segments:", len(t.segments))
+    if t.usage:
+        print(f"credits spent: {t.usage.credits_spent} · balance: {t.usage.balance}")