2.4.0: add sync and async monitor lifecycle and event pagination

Author: Chandler Casey

.github/workflows/release.yml

@@ -19,6 +19,12 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - name: Test
+        run: |
+          python -m pip install -e ".[dev]"
+          ruff check .
+          mypy src
+          pytest -q
       - name: Build
         run: |
           python -m pip install --upgrade pip build

CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## [2.4.0] - 2026-09-27
+
+### Added
+
+- Monitor create, list, get, update/pause/resume, delete, check-now, events and
+  automatic event pagination. Includes typed settings, news cursors, delivery
+  state, inline/follow-up transcript results and check errors. Creation exposes
+  the one-time webhook secret. Create/check share the existing idempotent retry
+  transport. Python includes sync and async methods.
+- Single-video options for mode, timestamps and callback URL, including
+  captions-only and plain-text requests generated by the Playground.
+- HTTP contract tests for monitor requests/responses, partial updates, pagination,
+  errors and retries; release workflows run the tests before publishing.
+
 ## [2.3.0] - 2026-09-15
 
 ### Added

README.md

@@ -77,6 +77,52 @@ pending = [r.job_id for r in res.results if r.outcome == "processing"]
 res = tf.transcripts.batch(ids, mode="captions")   # captions only, no audio fallback
 ```
 
+## Monitors (2.4.0+)
+
+Watch a YouTube channel or a TikTok/Instagram profile for new videos. Creation
+records a free baseline and starts scheduled checks; existing videos are skipped.
+Checks with no new videos are free. A check finding videos costs 1 credit, plus
+transcript charges when enabled. See [monitor docs](https://transcriptfetch.com/docs/monitors)
+for plan limits, audio billing, retention and webhook verification.
+
+```python
+with TranscriptFetch(timeout=120) as tf:
+    monitor = tf.monitors.create("@lexfridman", interval_minutes=60, transcripts=True)
+    # Save monitor.webhook_secret securely: it is only returned on creation.
+    # Optional webhook_url="https://your-app.com/hooks/transcriptfetch".
+    # YouTube only: tab="shorts" (or "videos" / "live").
+    all_monitors = tf.monitors.list()
+    news = tf.monitors.list(since=all_monitors.last_event_id)
+    current = tf.monitors.get(monitor.id)
+    page = tf.monitors.events(monitor.id, limit=10)
+    for event in tf.monitors.iter_events(monitor.id, since=current.last_event_id):
+        print(event.type, event.data)
+    tf.monitors.update(monitor.id, status="paused")
+    tf.monitors.update(monitor.id, webhook_url=None, name=None, transcripts=False)
+    # Omitted settings stay unchanged. None clears webhook_url/name.
+    tf.monitors.update(monitor.id, status="active")
+    checked = tf.monitors.check(monitor.id)  # may spend credits
+    if checked.error:  # listing failure, even with HTTP 200
+        print(checked.error)
+    tf.monitors.delete(monitor.id)  # removes events too
+```
+
+`AsyncTranscriptFetch` exposes the same methods with `await`; use `async for`
+with `tf.monitors.iter_events(...)`. Models use snake_case. `monitor.videos`
+events carry `data.videos` and optional `data.transcripts` with `ok`, `processing`
+or `error` outcomes. `monitor.transcript` events carry the follow-up result
+in `data`, linked to the parent via `videos_event_id`. `delivery` describes
+webhook attempts. Reading never marks events read: persist the latest event id
+and pass it as `since`. Iteration preserves `since` across cursor pages.
+Create/check accept `idempotency_key`; the generated key stays stable on retries.
+Use a longer client timeout for creation/manual checks, which read the platform.
+
+Single-video options are also supported:
+
+```python
+transcript = tf.transcripts.video("dQw4w9WgXcQ", mode="captions", timestamps=False)
+```
+
 ## Pagination
 
 List endpoints are cursor-paginated. Iterate every result without managing cursors:

src/transcriptfetch/__init__.py

@@ -33,6 +33,22 @@
     ApiErrorBlock,
     BatchResponse,
     BatchResult,
+    Monitor,
+    MonitorCheck,
+    MonitorDeleted,
+    MonitorDelivery,
+    MonitorEvent,
+    MonitorEventList,
+    MonitorInterval,
+    MonitorLastError,
+    MonitorLimits,
+    MonitorList,
+    MonitorSnapshot,
+    MonitorTranscriptData,
+    MonitorTranscriptEvent,
+    MonitorTranscriptResult,
+    MonitorVideosData,
+    MonitorVideosEvent,
     Segment,
     Transcript,
     Usage,
@@ -45,6 +61,22 @@
     "__version__",
     "TranscriptFetch",
     "AsyncTranscriptFetch",
+    "Monitor",
+    "MonitorSnapshot",
+    "MonitorLastError",
+    "MonitorLimits",
+    "MonitorList",
+    "MonitorDeleted",
+    "MonitorDelivery",
+    "MonitorTranscriptResult",
+    "MonitorVideosData",
+    "MonitorTranscriptData",
+    "MonitorVideosEvent",
+    "MonitorTranscriptEvent",
+    "MonitorEvent",
+    "MonitorEventList",
+    "MonitorCheck",
+    "MonitorInterval",
     # models
     "Usage",
     "Account",

src/transcriptfetch/_version.py

@@ -1 +1 @@
-__version__ = "2.3.0"
+__version__ = "2.4.0"

src/transcriptfetch/async_client.py

@@ -19,6 +19,7 @@
 )
 from .errors import APIConnectionError, APITimeoutError
 from .models import Account
+from .resources.monitors import AsyncMonitors
 from .resources.transcripts import AsyncTranscripts
 
 
@@ -48,6 +49,7 @@ def __init__(
         self._http = http_client or httpx.AsyncClient(
             base_url=self._config.base_url, timeout=self._config.timeout
         )
+        self.monitors = AsyncMonitors(self)
         self.transcripts = AsyncTranscripts(self)
 
     async def _request(

src/transcriptfetch/client.py

@@ -19,6 +19,7 @@
 )
 from .errors import APIConnectionError, APITimeoutError
 from .models import Account
+from .resources.monitors import Monitors
 from .resources.transcripts import Transcripts
 
 
@@ -45,6 +46,7 @@ def __init__(
         self._http = http_client or httpx.Client(
             base_url=self._config.base_url, timeout=self._config.timeout
         )
+        self.monitors = Monitors(self)
         self.transcripts = Transcripts(self)
 
     def _request(

src/transcriptfetch/models.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -201,3 +201,126 @@ class BatchResponse(_Model):
     kind: Literal["transcript_batch"] = "transcript_batch"
     results: List[BatchResult] = Field(default_factory=list)
     usage: Optional[Usage] = None
+
+
+# Monitor response models -----------------------------------------------------
+MonitorInterval = Literal[15, 60, 360, 1440]
+
+
+class MonitorSnapshot(_Model):
+    id: str
+    name: Optional[str] = None
+    type: str = "channel"
+    platform: str = "youtube"
+    target: str = ""
+
+
+class MonitorLastError(ApiErrorBlock):
+    at: Optional[str] = None
+
+
+class Monitor(MonitorSnapshot):
+    """A scheduled monitor. webhook_secret and baseline_count appear only on creation."""
+
+    kind: str = "monitor"
+    options: Dict[str, Any] = Field(default_factory=dict)
+    status: str = "active"
+    has_new: bool = False
+    last_event_id: Optional[str] = None
+    interval_minutes: int = 60
+    transcripts: bool = False
+    webhook_url: Optional[str] = None
+    next_check_at: Optional[str] = None
+    last_checked_at: Optional[str] = None
+    last_error: Optional[MonitorLastError] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    webhook_secret: Optional[str] = Field(default=None, repr=False)
+    baseline_count: Optional[int] = None
+    usage: Optional[Usage] = None
+
+
+class MonitorLimits(_Model):
+    max_monitors: Optional[int] = None
+    min_interval_minutes: int = 60
+
+
+class MonitorList(_Model):
+    kind: str = "monitor_list"
+    monitors: List[Monitor] = Field(default_factory=list)
+    has_new: bool = False
+    last_event_id: Optional[str] = None
+    limits: MonitorLimits = Field(default_factory=MonitorLimits)
+
+
+class MonitorDeleted(_Model):
+    kind: str = "monitor_deleted"
+    id: str
+
+
+class MonitorDelivery(_Model):
+    status: str = "none"
+    attempts: int = 0
+    last_attempt_at: Optional[str] = None
+    next_attempt_at: Optional[str] = None
+    last_error: Optional[str] = None
+    delivered_at: Optional[str] = None
+
+
+class MonitorTranscriptResult(_Model):
+    job_id: Optional[str] = None
+    video_id: str
+    url: str = ""
+    outcome: str
+    transcript: Optional[Transcript] = None
+    error: Optional[ApiErrorBlock] = None
+
+
+class MonitorVideosData(_Model):
+    videos: List[Video] = Field(default_factory=list)
+    transcripts: Optional[List[MonitorTranscriptResult]] = None
+
+
+class MonitorTranscriptData(MonitorTranscriptResult):
+    videos_event_id: str
+
+
+class MonitorVideosEvent(_Model):
+    id: str
+    type: Literal["monitor.videos"]
+    created_at: str
+    monitor: MonitorSnapshot
+    credits_spent: int = 0
+    data: MonitorVideosData
+    delivery: Optional[MonitorDelivery] = None
+
+
+class MonitorTranscriptEvent(_Model):
+    id: str
+    type: Literal["monitor.transcript"]
+    created_at: str
+    monitor: MonitorSnapshot
+    credits_spent: int = 0
+    data: MonitorTranscriptData
+    delivery: Optional[MonitorDelivery] = None
+
+
+MonitorEvent = Union[MonitorVideosEvent, MonitorTranscriptEvent]
+
+
+class MonitorEventList(_Model):
+    kind: str = "monitor_event_list"
+    monitor_id: str
+    events: List[MonitorEvent] = Field(default_factory=list)
+    next_cursor: Optional[str] = None
+
+
+class MonitorCheck(_Model):
+    """A check may return HTTP 200 with error set when the listing failed."""
+
+    kind: str = "monitor_check"
+    monitor: Monitor
+    new_videos: int = 0
+    event: Optional[MonitorEvent] = None
+    error: Optional[ApiErrorBlock] = None
+    usage: Optional[Usage] = None

src/transcriptfetch/resources/__init__.py

@@ -1,3 +1,4 @@
+from .monitors import AsyncMonitors, Monitors
 from .transcripts import AsyncTranscripts, Transcripts
 
-__all__ = ["Transcripts", "AsyncTranscripts"]
+__all__ = ["Transcripts", "AsyncTranscripts", "Monitors", "AsyncMonitors"]