videofetch-sdk 0.1.0__py3-none-any.whl

videofetch/__init__.py

@@ -0,0 +1,41 @@
+"""VideoFetch — official Python SDK.
+
+    import videofetch
+    client = videofetch.VideoFetch(api_key="vf_live_sk_...")
+    job = client.downloads.create(url="https://youtu.be/...", format="1080p")
+    result = job.wait()          # polls until completed/failed
+    print(result.download_url)   # presigned 7-day link (url destination)
+
+Async:
+    from videofetch.asyncio import AsyncVideoFetch
+    async with AsyncVideoFetch(api_key="...") as client:
+        result = await (await client.downloads.create(url=..., format="1080p")).wait()
+
+Webhooks (FastAPI example):
+    from videofetch.webhooks import construct_event
+    payload = await request.body()
+    event = construct_event(payload, request.headers.get("X-VideoFetch-Signature"), endpoint_secret)
+"""
+
+from .client import AsyncVideoFetch, VideoFetch  # noqa: F401
+from .errors import (  # noqa: F401
+    ApiError,
+    AuthenticationError,
+    JobFailedError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+    VideoFetchError,
+)
+from .models import Download, DownloadAttempt, DownloadList, FormatInfo, TrimSpec, VideoInfo  # noqa: F401
+from .resources import DownloadJob  # noqa: F401
+
+__version__ = "0.1.0"
+__all__ = [
+    "VideoFetch", "AsyncVideoFetch", "DownloadJob",
+    "VideoFetchError", "AuthenticationError", "QuotaExceededError", "ValidationError",
+    "NotFoundError", "RateLimitError", "ApiError", "JobFailedError",
+    "Download", "DownloadList", "DownloadAttempt", "TrimSpec", "FormatInfo", "VideoInfo",
+    "__version__",
+]

videofetch/asyncio.py

@@ -0,0 +1,7 @@
+"""Async entrypoint mirror (import-friendly for asyncio users).
+
+    from videofetch.asyncio import AsyncVideoFetch
+"""
+from .client import AsyncVideoFetch  # noqa: F401
+
+__all__ = ["AsyncVideoFetch"]

videofetch/client.py

@@ -0,0 +1,181 @@
+"""Sync + Async HTTP clients with retry, error mapping and typed resources.
+
+Design mirrors the OpenAI/Stripe SDKs:
+  VideoFetch(api_key)        → sync   client:  client.downloads.create(...)
+  AsyncVideoFetch(api_key)   → async  client:  await client.downloads.create(...)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .errors import VideoFetchError, map_error
+from .models import Download, DownloadList, TrimSpec, VideoInfo
+
+DEFAULT_BASE_URL = os.getenv("VIDEOFETCH_BASE_URL", "https://api.vidfetch.dev")
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_JOB_TIMEOUT = 120.0
+DEFAULT_POLL_INTERVAL = 2.0
+
+_TERMINAL = ("completed", "failed", "deleted")
+
+
+def _headers(api_key: str) -> dict:
+    return {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+
+
+def _retry_delay(attempt: int) -> float:
+    """2s → 3s → 5s → 8s → 13s (Fibonacci) + 20% jitter."""
+    a, b = 2.0, 3.0
+    for _ in range(attempt):
+        a, b = b, a + b
+    return min(a, 30.0) * random.uniform(0.8, 1.2)
+
+
+def _poll_delay(attempt: int) -> float:
+    """Poll backoff for job.wait: 2s → 3s → 5s → 8s → 13s → cap 30s."""
+    return min(_retry_delay(attempt), 30.0)
+
+
+# ────────────────────────── Sync client ──────────────────────────
+class VideoFetch:
+    """Sync client. Usage:
+        client = VideoFetch(api_key="vf_live_sk_...")
+        job = client.downloads.create(url=..., format="1080p")
+        result = job.wait(timeout=120)
+    """
+
+    downloads: "DownloadsResource"
+    info: "InfoResource"
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = DEFAULT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES,
+                 http_client: Optional[httpx.Client] = None):
+        self.api_key = api_key or os.getenv("VIDEOFETCH_API_KEY") or ""
+        if not self.api_key:
+            raise ValueError(
+                "No API key provided. Pass api_key=... or set VIDEOFETCH_API_KEY."
+            )
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = http_client or httpx.Client(
+            base_url=self.base_url, headers=_headers(self.api_key),
+            timeout=timeout, follow_redirects=True,
+            # do not inherit system proxy env (can hijack localhost/dev traffic);
+            # advanced users can pass their own http_client to override
+            trust_env=False,
+        )
+        # lazy import avoids circular dependency (resources imports client)
+        from .resources import DownloadsResource, InfoResource
+        self.downloads = DownloadsResource(self)
+        self.info = InfoResource(self)
+
+    def request(self, method: str, path: str, *, json_body: Optional[dict] = None,
+                params: Optional[dict] = None) -> Any:
+        """Send request with automatic retry on 429/5xx. Returns parsed JSON."""
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self._client.request(method, path, json=json_body, params=params)
+            except httpx.HTTPError as e:
+                if attempt < self.max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise VideoFetchError(f"Network error calling {path}: {e}", status_code=None) from e
+            if resp.status_code in (429,) or resp.status_code >= 500:
+                if attempt < self.max_retries:
+                    retry_after = resp.headers.get("Retry-After")
+                    delay = float(retry_after) if retry_after and retry_after.isdigit() else _retry_delay(attempt)
+                    time.sleep(min(delay, 30.0))
+                    continue
+            if resp.status_code >= 400:
+                body = _parse_body(resp)
+                raise map_error(resp.status_code, body)
+            if resp.status_code == 204:
+                return None
+            return _parse_body(resp)
+        raise VideoFetchError("request failed")  # pragma: no cover
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "VideoFetch":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+# ────────────────────────── Async client ─────────────────────────
+class AsyncVideoFetch:
+    """Async client for asyncio/Next.js backends. Same shape as VideoFetch, but
+    every resource method is a coroutine (await client.downloads.create(...)).
+    """
+
+    downloads: "AsyncDownloadsResource"
+    info: "AsyncInfoResource"
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = DEFAULT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES,
+                 http_client: Optional[httpx.AsyncClient] = None):
+        self.api_key = api_key or os.getenv("VIDEOFETCH_API_KEY") or ""
+        if not self.api_key:
+            raise ValueError("No API key provided. Pass api_key=... or set VIDEOFETCH_API_KEY.")
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._client = http_client or httpx.AsyncClient(
+            base_url=self.base_url, headers=_headers(self.api_key),
+            timeout=timeout, follow_redirects=True,
+            trust_env=False,
+        )
+        from .resources import AsyncDownloadsResource, AsyncInfoResource
+        self.downloads = AsyncDownloadsResource(self)
+        self.info = AsyncInfoResource(self)
+
+    async def request(self, method: str, path: str, *, json_body: Optional[dict] = None,
+                      params: Optional[dict] = None) -> Any:
+        import asyncio
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = await self._client.request(method, path, json=json_body, params=params)
+            except httpx.HTTPError as e:
+                if attempt < self.max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise VideoFetchError(f"Network error calling {path}: {e}", status_code=None) from e
+            if resp.status_code in (429,) or resp.status_code >= 500:
+                if attempt < self.max_retries:
+                    retry_after = resp.headers.get("Retry-After")
+                    delay = float(retry_after) if retry_after and retry_after.isdigit() else _retry_delay(attempt)
+                    await asyncio.sleep(min(delay, 30.0))
+                    continue
+            if resp.status_code >= 400:
+                body = _parse_body(resp)
+                raise map_error(resp.status_code, body)
+            if resp.status_code == 204:
+                return None
+            return _parse_body(resp)
+        raise VideoFetchError("request failed")  # pragma: no cover
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncVideoFetch":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+
+def _parse_body(resp: httpx.Response) -> Any:
+    try:
+        return resp.json()
+    except Exception:
+        return resp.text

videofetch/errors.py

@@ -0,0 +1,99 @@
+"""Type hierarchy for VideoFetch SDK errors.
+
+Mirrors the server error contract:
+  HTTP 4xx/5xx → {"detail": {"code": ..., "message": ..., "param": ...}}
+Terminal job failure → DownloadOut {status: "failed", error_code, error_message}
+"""
+
+
+class VideoFetchError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(self, message: str, *, code: str | None = None,
+                 status_code: int | None = None, param: str | None = None,
+                 response_body: object | None = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.param = param
+        self.response_body = response_body
+
+
+class AuthenticationError(VideoFetchError):
+    """Invalid/expired API key or JWT (401)."""
+
+
+class PermissionDeniedError(VideoFetchError):
+    """Authenticated but not allowed (403)."""
+
+
+class QuotaExceededError(VideoFetchError):
+    """Monthly quota exhausted (402)."""
+
+
+class ValidationError(VideoFetchError):
+    """Request rejected (400/422): bad url/format/trim/destination/webhook."""
+
+
+class NotFoundError(VideoFetchError):
+    """Resource does not exist or does not belong to this key (404)."""
+
+
+class RateLimitError(VideoFetchError):
+    """Too many requests (429). Respect Retry-After when present."""
+
+
+class ApiError(VideoFetchError):
+    """Server-side failure (5xx) or unknown non-2xx."""
+
+
+class JobFailedError(VideoFetchError):
+    """The download job reached a terminal failed state.
+
+    A failed download is never charged — see job.failed_not_charged.
+    """
+
+    def __init__(self, *, job_id: str, error_code: str | None, error_message: str | None):
+        super().__init__(
+            f"Download job {job_id} failed"
+            + (f" [{error_code}]: {error_message}" if error_code or error_message else ""),
+            code=error_code or "job_failed",
+        )
+        self.job_id = job_id
+        self.error_code = error_code
+        self.error_message = error_message
+        self.failed_not_charged = True
+
+
+def map_error(status_code: int, body: object, *, message: str | None = None) -> VideoFetchError:
+    """Translate an HTTP response into the right SDK error."""
+    detail = None
+    if isinstance(body, dict):
+        detail = body.get("detail")
+    if isinstance(detail, dict):
+        code = detail.get("code") or detail.get("type")
+        msg = detail.get("message") or detail.get("msg") or message or "Request failed"
+        param = detail.get("param")
+    elif isinstance(detail, str):
+        code = None
+        msg = detail
+        param = None
+    else:
+        code = None
+        msg = message or "Request failed"
+        param = None
+
+    if status_code == 401:
+        return AuthenticationError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    if status_code == 403:
+        return PermissionDeniedError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    if status_code == 402:
+        return QuotaExceededError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    if status_code in (400, 422):
+        return ValidationError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    if status_code == 404:
+        return NotFoundError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    if status_code == 429:
+        return RateLimitError(msg, code=code, status_code=status_code, param=param, response_body=body)
+    return ApiError(msg, code=code, status_code=status_code, param=param, response_body=body)

videofetch/models.py

@@ -0,0 +1,173 @@
+"""Typed models mirroring the VideoFetch API contract (openapi/openapi.json).
+
+Implemented as lightweight dataclasses with from_dict() so the SDK has zero
+runtime deps beyond httpx (no pydantic required by consumers).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+def _as_float(v: Any) -> Optional[float]:
+    return float(v) if v is not None else None
+
+
+def _as_int(v: Any) -> Optional[int]:
+    return int(v) if v is not None else None
+
+
+@dataclass
+class TrimSpec:
+    """Requested clip window in seconds (float). end must be > start."""
+    start: Optional[float] = None
+    end: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> Optional["TrimSpec"]:
+        if not d:
+            return None
+        return cls(start=_as_float(d.get("start")), end=_as_float(d.get("end")))
+
+    def to_dict(self) -> Optional[dict]:
+        if self.start is None and self.end is None:
+            return None
+        return {"start": self.start, "end": self.end}
+
+
+@dataclass
+class DownloadAttempt:
+    attempt_no: Optional[int] = None
+    strategy: Optional[str] = None          # direct | decodo_isp | decodo_dc
+    proxy_host: Optional[str] = None
+    result: Optional[str] = None
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    latency_ms: Optional[int] = None
+    started_at: Optional[str] = None
+    finished_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> Optional["DownloadAttempt"]:
+        if not d:
+            return None
+        return cls(
+            attempt_no=_as_int(d.get("attempt_no")), strategy=d.get("strategy"),
+            proxy_host=d.get("proxy_host"), result=d.get("result"),
+            error_code=d.get("error_code"), error_message=d.get("error_message"),
+            latency_ms=_as_int(d.get("latency_ms")), started_at=d.get("started_at"),
+            finished_at=d.get("finished_at"),
+        )
+
+
+@dataclass
+class Download:
+    """A download job (dl_xxx). Mirrors GET /v1/downloads/{id}."""
+    id: str
+    status: str                                # queued|processing|completed|failed|deleted
+    url: str
+    format: str                                # 144p..2160p|mp3
+    progress: int = 0
+    title: Optional[str] = None
+    video_id: Optional[str] = None
+    channel: Optional[str] = None
+    upload_date: Optional[str] = None
+    thumbnail: Optional[str] = None
+    duration_seconds: Optional[float] = None
+    size_bytes: Optional[int] = None
+    trim: Optional[TrimSpec] = None
+    destination_type: Optional[str] = None     # url|s3|r2|gcs|s3_compatible
+    download_url: Optional[str] = None         # presigned link (url destination only)
+    download_url_expires_at: Optional[str] = None
+    storage_key: Optional[str] = None          # user://<bucket>/<key> when destination used
+    processing_time_ms: Optional[int] = None
+    cost_usd: float = 0.0
+    attempts: int = 0
+    strategy: Optional[str] = None
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    estimated_bytes: Optional[int] = None
+    attempt_details: list[DownloadAttempt] = field(default_factory=list)
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in ("completed", "failed", "deleted")
+
+    @property
+    def failed_not_charged(self) -> bool:
+        return self.status == "failed"
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Download":
+        return cls(
+            id=d.get("id", ""), status=d.get("status", "queued"), url=d.get("url", ""),
+            format=d.get("format", "mp4"), progress=int(d.get("progress") or 0),
+            title=d.get("title"), video_id=d.get("video_id"), channel=d.get("channel"),
+            upload_date=d.get("upload_date"), thumbnail=d.get("thumbnail"),
+            duration_seconds=_as_float(d.get("duration_seconds")),
+            size_bytes=_as_int(d.get("size_bytes")),
+            trim=TrimSpec.from_dict(d.get("trim")),
+            destination_type=d.get("destination_type"), download_url=d.get("download_url"),
+            download_url_expires_at=d.get("download_url_expires_at"),
+            storage_key=d.get("storage_key"),
+            processing_time_ms=_as_int(d.get("processing_time_ms")),
+            cost_usd=float(d.get("cost_usd") or 0.0),
+            attempts=int(d.get("attempts") or 0), strategy=d.get("strategy"),
+            error_code=d.get("error_code"), error_message=d.get("error_message"),
+            created_at=d.get("created_at"), completed_at=d.get("completed_at"),
+            estimated_bytes=_as_int(d.get("estimated_bytes")),
+            attempt_details=[DownloadAttempt.from_dict(a) or DownloadAttempt()
+                             for a in (d.get("attempt_details") or [])],
+        )
+
+
+@dataclass
+class DownloadList:
+    items: list[Download] = field(default_factory=list)
+    total: int = 0
+    has_more: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DownloadList":
+        return cls(
+            items=[Download.from_dict(i) for i in (d.get("items") or [])],
+            total=int(d.get("total") or 0), has_more=bool(d.get("has_more")),
+        )
+
+
+@dataclass
+class FormatInfo:
+    quality: str
+    size: Optional[int] = None
+    container: str = "MP4"
+    note: Optional[str] = None
+
+
+@dataclass
+class VideoInfo:
+    """POST /v1/info result (free metadata lookup)."""
+    id: Optional[str] = None
+    url: str = ""
+    title: Optional[str] = None
+    duration: Optional[float] = None
+    thumbnail: Optional[str] = None
+    channel: Optional[str] = None
+    upload_date: Optional[str] = None
+    view_count: Optional[int] = None
+    formats: list[FormatInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "VideoInfo":
+        return cls(
+            id=d.get("id"), url=d.get("url", ""), title=d.get("title"),
+            duration=_as_float(d.get("duration")), thumbnail=d.get("thumbnail"),
+            channel=d.get("channel"), upload_date=d.get("upload_date"),
+            view_count=_as_int(d.get("view_count")),
+            formats=[FormatInfo(
+                quality=f.get("quality", ""), size=_as_int(f.get("size")),
+                container=f.get("container", "MP4"), note=f.get("note"),
+            ) for f in (d.get("formats") or [])],
+        )

videofetch/resources.py

@@ -0,0 +1,261 @@
+"""Downloads resource: create / retrieve / list / cancel + Job.wait() polling.
+
+Three-layer design (see docs/SDK_RELEASE_GUIDE.md):
+  L1  job = client.downloads.create(...)          # POST only, returns immediately
+  L2  result = job.wait(timeout=120)              # poll GET with backoff
+  L3  result = client.downloads.create_and_wait(...)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from .client import DEFAULT_JOB_TIMEOUT, _poll_delay
+from .errors import JobFailedError, VideoFetchError
+from .models import Download, DownloadList, TrimSpec, VideoInfo
+
+TERMINAL = ("completed", "failed", "deleted")
+
+
+# ────────────────────────── Sync resources ───────────────────────
+class DownloadsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def create(self, url: str, format: str = "720p", *,
+               trim: Optional[TrimSpec] = None,
+               destination: Optional[dict] = None,
+               webhook_url: Optional[str] = None,
+               **extra: dict) -> DownloadJob:
+        """Create a download job. Returns immediately with status 'queued'."""
+        body: dict = {"url": url, "format": format, **extra}
+        t = trim.to_dict() if trim else None
+        if t:
+            body["trim"] = t
+        if destination:
+            body["destination"] = destination
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        data = self._client.request("POST", "/v1/downloads", json_body=body)
+        return DownloadJob(self._client, Download.from_dict(data))
+
+    def retrieve(self, download_id: str) -> Download:
+        data = self._client.request("GET", f"/v1/downloads/{download_id}")
+        return Download.from_dict(data)
+
+    def list(self, *, status: Optional[str] = None, q: Optional[str] = None,
+             limit: int = 20, offset: int = 0) -> DownloadList:
+        params = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        if q:
+            params["q"] = q
+        data = self._client.request("GET", "/v1/downloads", params=params)
+        return DownloadList.from_dict(data)
+
+    def cancel(self, download_id: str) -> None:
+        """Cancel/delete a job (queued/processing). Safe to call on any state."""
+        self._client.request("DELETE", f"/v1/downloads/{download_id}")
+
+    def create_and_wait(self, url: str, format: str = "720p", *, timeout: float = DEFAULT_JOB_TIMEOUT,
+                        **kwargs) -> Download:
+        job = self.create(url, format, **kwargs)
+        return job.wait(timeout=timeout)
+
+
+class DownloadJob:
+    """Polling handle around a queued/processing download (sync)."""
+
+    def __init__(self, client, initial: Download):
+        self._client = client
+        self._download = initial
+
+    @property
+    def id(self) -> str:
+        return self._download.id
+
+    @property
+    def status(self) -> str:
+        return self._download.status
+
+    @property
+    def download(self) -> Download:
+        return self._download
+
+    def refresh(self) -> Download:
+        self._download = self._client.downloads.retrieve(self.id)
+        return self._download
+
+    def wait(self, *, timeout: float = DEFAULT_JOB_TIMEOUT, poll_interval: float = None) -> Download:
+        """Poll until terminal (completed/failed/deleted).
+
+        - Network errors do not abort; we keep polling until timeout.
+        - A failed job raises JobFailedError (failed downloads are never charged).
+        - timeout=0 / None means wait forever (CLI use). Cancel only stops local
+          waiting — the server-side job keeps running unless you call cancel().
+        """
+        deadline = None if (timeout is None or timeout <= 0) else time.monotonic() + timeout
+        attempt = 0
+        # If the create response already reached a terminal state, return immediately.
+        if self._download.is_terminal:
+            return self._raise_if_failed(self._download)
+        interval = poll_interval or 2.0
+        while True:
+            if deadline is not None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise VideoFetchError(
+                        f"Timed out after {timeout}s waiting for job {self.id}. "
+                        "The job is still running server-side — retrieve() it later.",
+                        code="job_timeout",
+                    )
+                time.sleep(min(interval, remaining))
+            else:
+                time.sleep(interval)
+            try:
+                self._download = self._client.downloads.retrieve(self.id)
+            except VideoFetchError:
+                if deadline is not None and time.monotonic() > deadline:
+                    raise
+                attempt += 1
+                interval = _poll_delay(attempt)
+                continue
+            if self._download.is_terminal:
+                return self._raise_if_failed(self._download)
+            attempt += 1
+            interval = _poll_delay(attempt)
+
+    @staticmethod
+    def _raise_if_failed(dl: Download) -> Download:
+        if dl.status == "failed":
+            raise JobFailedError(
+                job_id=dl.id, error_code=dl.error_code, error_message=dl.error_message)
+        return dl
+
+
+class InfoResource:
+    def __init__(self, client):
+        self._client = client
+
+    def lookup(self, url: str) -> VideoInfo:
+        data = self._client.request("POST", "/v1/info", json_body={"url": url})
+        return VideoInfo.from_dict(data)
+
+
+# ────────────────────────── Async resources ──────────────────────
+class AsyncDownloadsResource:
+    def __init__(self, client):
+        self._client = client
+
+    async def create(self, url: str, format: str = "720p", *,
+                     trim: Optional[TrimSpec] = None,
+                     destination: Optional[dict] = None,
+                     webhook_url: Optional[str] = None,
+                     **extra: dict) -> AsyncDownloadJob:
+        body: dict = {"url": url, "format": format, **extra}
+        t = trim.to_dict() if trim else None
+        if t:
+            body["trim"] = t
+        if destination:
+            body["destination"] = destination
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        data = await self._client.request("POST", "/v1/downloads", json_body=body)
+        return AsyncDownloadJob(self._client, Download.from_dict(data))
+
+    async def retrieve(self, download_id: str) -> Download:
+        data = await self._client.request("GET", f"/v1/downloads/{download_id}")
+        return Download.from_dict(data)
+
+    async def list(self, *, status: Optional[str] = None, q: Optional[str] = None,
+                   limit: int = 20, offset: int = 0) -> DownloadList:
+        params = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        if q:
+            params["q"] = q
+        data = await self._client.request("GET", "/v1/downloads", params=params)
+        return DownloadList.from_dict(data)
+
+    async def cancel(self, download_id: str) -> None:
+        await self._client.request("DELETE", f"/v1/downloads/{download_id}")
+
+    async def create_and_wait(self, url: str, format: str = "720p", *,
+                              timeout: float = DEFAULT_JOB_TIMEOUT, **kwargs) -> Download:
+        job = await self.create(url, format, **kwargs)
+        return await job.wait(timeout=timeout)
+
+
+class AsyncDownloadJob:
+    """Polling handle around a queued/processing download (async)."""
+
+    def __init__(self, client, initial: Download):
+        self._client = client
+        self._download = initial
+
+    @property
+    def id(self) -> str:
+        return self._download.id
+
+    @property
+    def status(self) -> str:
+        return self._download.status
+
+    @property
+    def download(self) -> Download:
+        return self._download
+
+    async def refresh(self) -> Download:
+        self._download = await self._client.downloads.retrieve(self.id)
+        return self._download
+
+    async def wait(self, *, timeout: float = DEFAULT_JOB_TIMEOUT,
+                   poll_interval: float = None) -> Download:
+        import asyncio
+
+        deadline = None if (timeout is None or timeout <= 0) else asyncio.get_event_loop().time() + timeout
+        if self._download.is_terminal:
+            return self._raise_if_failed(self._download)
+        interval = poll_interval or 2.0
+        attempt = 0
+        while True:
+            if deadline is not None:
+                remaining = deadline - asyncio.get_event_loop().time()
+                if remaining <= 0:
+                    raise VideoFetchError(
+                        f"Timed out after {timeout}s waiting for job {self.id}. "
+                        "The job is still running server-side — retrieve() it later.",
+                        code="job_timeout",
+                    )
+                await asyncio.sleep(min(interval, remaining))
+            else:
+                await asyncio.sleep(interval)
+            try:
+                self._download = await self._client.downloads.retrieve(self.id)
+            except VideoFetchError:
+                if deadline is not None and asyncio.get_event_loop().time() > deadline:
+                    raise
+                attempt += 1
+                interval = _poll_delay(attempt)
+                continue
+            if self._download.is_terminal:
+                return self._raise_if_failed(self._download)
+            attempt += 1
+            interval = _poll_delay(attempt)
+
+    @staticmethod
+    def _raise_if_failed(dl: Download) -> Download:
+        if dl.status == "failed":
+            raise JobFailedError(
+                job_id=dl.id, error_code=dl.error_code, error_message=dl.error_message)
+        return dl
+
+
+class AsyncInfoResource:
+    def __init__(self, client):
+        self._client = client
+
+    async def lookup(self, url: str) -> VideoInfo:
+        data = await self._client.request("POST", "/v1/info", json_body={"url": url})
+        return VideoInfo.from_dict(data)

videofetch/webhooks.py

@@ -0,0 +1,56 @@
+"""Webhook signature verification.
+
+The server signs the raw request body with the endpoint secret (HMAC-SHA256)
+and sends the digest in the `X-VideoFetch-Signature` header:
+
+    X-VideoFetch-Signature: sha256=<hex digest of raw body>
+
+Verify with the secret shown when you created the webhook endpoint:
+
+    from videofetch.webhooks import construct_event
+    event = construct_event(await request.body(), request.headers.get("X-VideoFetch-Signature"), secret)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Optional
+
+from .errors import VideoFetchError
+
+# Event names (docs/Design contract)
+WEBHOOK_EVENTS = (
+    "download.queued", "download.processing", "download.completed", "download.failed",
+)
+
+
+class SignatureVerificationError(VideoFetchError):
+    """The signature header is missing, malformed, or does not match."""
+
+
+def compute_signature(payload: bytes, secret: str) -> str:
+    """sha256=<hex> — mirrors the server implementation."""
+    digest = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+def construct_event(payload: bytes, sig_header: Optional[str], secret: str) -> dict:
+    """Verify the signature header against the raw body and return the parsed event.
+
+    Raises SignatureVerificationError if the header is missing or does not match.
+    """
+    if not sig_header:
+        raise SignatureVerificationError("No signature header was present.")
+    if not sig_header.startswith("sha256="):
+        raise SignatureVerificationError("Signature header is malformed (expected sha256=<hex>).")
+
+    expected = compute_signature(payload, secret)
+    if not hmac.compare_digest(expected, sig_header):
+        raise SignatureVerificationError("Signature does not match the payload and secret.")
+
+    try:
+        return json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise SignatureVerificationError("Payload is not valid JSON.") from None

videofetch_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: videofetch-sdk
+Version: 0.1.0
+Summary: Official VideoFetch SDK for Python — video ingestion API (YouTube URL → MP4/MP3 to your storage)
+Project-URL: Homepage, https://github.com/heavenlxj/videofetch-sdk/tree/main/python
+Project-URL: Documentation, https://videofetch.dev/docs
+Project-URL: Source, https://github.com/heavenlxj/videofetch-sdk/tree/main/python
+Author-email: VideoFetch <dev@videofetch.dev>
+License-Expression: MIT
+Keywords: api,download,sdk,video,videofetch,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# videofetch (Python SDK)
+
+Official [VideoFetch](https://vidfetch.dev) SDK — video ingestion API:
+give us a video URL, we deliver MP4/MP3 to your storage.
+
+```bash
+pip install videofetch-sdk
+```
+
+## Usage
+
+```python
+import videofetch
+
+client = videofetch.VideoFetch(api_key="vf_live_sk_...")
+
+# L1: create a job (returns immediately, status "queued")
+job = client.downloads.create(
+    url="https://www.youtube.com/watch?v=...",
+    format="1080p",                 # 144p..2160p | mp3
+    trim=videofetch.TrimSpec(start=120, end=420),   # optional clip window
+    # destination={"type": "r2", "id": "..."},      # optional direct-to-bucket
+)
+
+# L2: wait for the terminal state (polls with backoff)
+result = job.wait(timeout=120)
+print(result.status)        # "completed"
+print(result.download_url)  # presigned link, valid 7 days (url destination)
+print(result.storage_key)   # "user://<bucket>/<key>" (bucket destination)
+print(result.size_bytes, result.cost_usd)
+
+# L3: one-shot
+result = client.downloads.create_and_wait(url=..., format="1080p")
+```
+
+Async (FastAPI / Next.js backends):
+
+```python
+from videofetch.asyncio import AsyncVideoFetch
+
+async with AsyncVideoFetch(api_key="...") as client:
+    job = await client.downloads.create(url=..., format="1080p")
+    result = await job.wait(timeout=120)
+```
+
+Free metadata lookup:
+
+```python
+info = client.info.lookup("https://www.youtube.com/watch?v=...")
+print(info.title, info.duration, info.formats)   # available quality tiers
+```
+
+Webhooks (FastAPI):
+
+```python
+from fastapi import Request, HTTPException
+from videofetch.webhooks import construct_event, SignatureVerificationError
+
+@app.post("/webhooks/videofetch")
+async def on_event(request: Request):
+    body = await request.body()
+    try:
+        event = construct_event(body, request.headers.get("X-VideoFetch-Signature"), WEBHOOK_SECRET)
+    except SignatureVerificationError:
+        raise HTTPException(status_code=400, detail="bad signature")
+    if event["event"] == "download.completed":
+        ...  # fetch the result via client.downloads.retrieve(event["id"])
+    return {"ok": True}
+```
+
+## Configuration
+
+- `api_key` — required. Create keys in the Dashboard (`vf_live_sk_...`).
+  Falls back to the `VIDEOFETCH_API_KEY` env var.
+- `base_url` — defaults to the hosted API; override for local/single-server dev
+  (`http://localhost:8301`). Env: `VIDEOFETCH_BASE_URL`.
+- `timeout` (s), `max_retries` (default 2, automatic on 429/5xx).
+
+## Errors
+
+All SDK errors derive from `videofetch.VideoFetchError`:
+
+| error | meaning |
+|---|---|
+| `AuthenticationError` | bad/expired key (401) |
+| `QuotaExceededError` | monthly quota exhausted (402) |
+| `ValidationError` | bad url/format/trim/destination (400/422) |
+| `NotFoundError` | job/connection not found (404) |
+| `RateLimitError` | slow down (429) |
+| `JobFailedError` | job reached `failed` — **never charged** |
+
+## Serverless warning
+
+Do **not** call `job.wait()` in a Vercel/Cloudflare/Lambda function — it burns
+billed execution time. Create the job, persist its id, then respond to the
+`download.completed` webhook and `retrieve(id)` the final result.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

videofetch_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+videofetch/__init__.py,sha256=XTpu-QUH8bjLiywHgPNlALsMFPBq2dBhUCvYK9VO3I8,1538
+videofetch/asyncio.py,sha256=hS5T04uPBMKakVgmqDHDGyrl0vFfagcj9dsa_2-c_Pc,201
+videofetch/client.py,sha256=qJFjPfWffMiUJ4F8HpbJbBctI2f-qPWn5Bvu-qJnhTA,7412
+videofetch/errors.py,sha256=6XyD0DziJpLiQbxi1tv5wwFzqD1pFRKhSifVby1Elvo,3612
+videofetch/models.py,sha256=-38cEIRw31aFYAsvYrqvQTjs25tDSyX5odq5f9Ep40I,6421
+videofetch/resources.py,sha256=rAc7PT_HVc6Ox0o-kmVoTCWmnuPINZKlc1ZBBfkUlj8,10224
+videofetch/webhooks.py,sha256=b39cpKTlwuRB9FG76O-JcpzQjYLuqFKyBXofBdrM10w,2017
+videofetch_sdk-0.1.0.dist-info/METADATA,sha256=oT6xzFatc1ePG2THDD9YtTFFw31ZKjnTk5ykUx7Hnlo,4373
+videofetch_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+videofetch_sdk-0.1.0.dist-info/RECORD,,

videofetch_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any