videofetch-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

videofetch_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 0.3.0 — 2026-09-22
+
+Added
+- **Webhook delivery inspection:** `client.webhooks.deliveries(endpoint_id, limit=50)` returns a
+  `WebhookDeliveriesResult` with the endpoint's current state, aggregate `health`
+  (`total`/`succeeded`/`dead`/`pending`/`success_rate`, plus `max_attempts` and
+  `retry_schedule_seconds`), and the recent `items` (each a `WebhookDelivery`).
+- **Webhook replay:** `client.webhooks.replay(event_id)` re-queues a past event and returns a
+  `ReplayResult(queued, event_id)`. A `NotFoundError` means the delivery is not visible to your
+  account.
+- **Idempotency helpers:** `delivery_id(headers)` and `attempt_number(headers)` read the new
+  `X-VideoFetch-Delivery` and `X-VideoFetch-Attempt` headers case-insensitively.
+- **Queue hints on queued downloads:** `Download.queue_position` (1 == next to be claimed),
+  `ahead_of_you`, and `estimated_wait_seconds`. All three are populated only while
+  `status == "queued"` and are `None` in every other state.
+- **Per-key usage attribution:** `Usage.key_used_bytes` / `Usage.key_used_gb` report this key's own
+  accumulated usage, alongside the account-level figures.
+- **Save the result locally:** `client.downloads.download_to(download_id, path=None)` (and the async
+  `await client.downloads.download_to(...)`) streams a completed job's file to disk in chunks and
+  returns the absolute path of the saved file. With no destination configured for the job the
+  platform issues a time-limited, self-authorizing `download_url`, and this method saves it for you —
+  to `<sanitized title or job id>.<mp3|mp4>` in the current directory by default, or to the file path
+  (or existing directory) you pass. The API key is never sent to that link; if it has expired the
+  server re-signs it on the next job fetch and the save is retried once. Preconditions are typed:
+  a non-completed job raises `DownloadNotCompletedError`, and a completed job without a
+  `download_url` raises `DownloadURLUnavailableError`.
+
+Changed (breaking)
+- **Attempt records no longer expose a raw egress host.** `DownloadAttempt.egress` replaces the
+  0.2.0 host field and carries a neutral label: `"relay"` when the attempt was served through an
+  alternate route, `null` for a direct attempt. Internal egress hosts are not part of the public
+  contract.
+- **The strategy vocabulary is now `"direct" | "relay" | "relay_secondary"`** for both
+  `Download.strategy` and `DownloadAttempt.strategy`. Any value outside the vocabulary is
+  normalised to `"relay"`.
+- Attempt `error_message` strings are scrubbed of egress addresses and credentials before they are
+  returned to you.
+- **`Usage.used_bytes` / `Usage.used_gb` are now account-level.** They report the whole account's
+  current-month billable usage (the quota is account-level and shared by every key), not the calling
+  key's usage. Use the new `key_used_bytes` / `key_used_gb` for per-key attribution.
+- **Downloads are account-level visible.** `GET /v1/downloads` (list) and
+  `GET /v1/downloads/{id}` (detail) now return every job owned by the account, regardless of which
+  key created it; any key in the account may also cancel/delete any of the account's jobs.
+- **Webhook delivery semantics changed.** Deliveries are now **at-least-once**: the same event may be
+  delivered more than once. Retries are capped at **3 attempts** (the first send counts as attempt 1;
+  the previous limit was 5) with a 30s → 300s backoff (±20% jitter). **4xx responses are permanent
+  failures and are not retried**, except `408` and `429`. **Ordering is not guaranteed** — sort by
+  each event's `seq`. New headers accompany every attempt:
+  - `X-VideoFetch-Delivery` — stable per-event idempotency key.
+  - `X-VideoFetch-Attempt` — the attempt number (1 = first).
+  - `X-VideoFetch-Timestamp` — when the attempt was sent.
+  `X-VideoFetch-Event` and `X-VideoFetch-Signature` are unchanged.
+
+Migration
+- If you read the raw host field from 0.2.0, read `egress` instead — it is a label, not a hostname.
+- Branch on `strategy == "direct"` vs anything else. Pin `videofetch-sdk==0.2.*` if you need the old
+  response shape while you migrate.
+- **Deduplicate webhooks by `X-VideoFetch-Delivery`.** Because delivery is at-least-once, persist the
+  delivery id (e.g. a unique index) and skip events you have already processed. Use
+  `videofetch.delivery_id(request.headers)` and `videofetch.attempt_number(request.headers)` in your
+  handler, and order events by `seq` rather than arrival time.
+- If you displayed `used_gb` as a per-key number, switch to `key_used_gb` for that, or keep
+  `used_gb` and relabel it as account-level month usage.
+- Downloads created by other keys in your account may now appear in list/detail results. If you need
+  per-key filtering, record the creating key on your side.
+

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: videofetch-sdk
-Version: 0.2.0
+Version: 0.3.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
@@ -59,6 +59,22 @@ print(result.size_bytes, result.cost_usd)
 result = client.downloads.create_and_wait(url=..., format="1080p")
 ```
 
+Save the artifact locally. Created with no destination configured, the job completes
+with a time-limited `download_url`; `download_to` streams it to disk and returns the
+absolute path of the saved file:
+
+```python
+path = client.downloads.download_to(result.id)          # ./<title>.mp4 in the current dir
+path = client.downloads.download_to(result.id, "out/clip.mp4")   # explicit file path
+path = client.downloads.download_to(result.id, "out/")           # existing directory
+print(path)   # "/abs/path/out/clip.mp4"
+```
+
+The default name is the sanitized title (or the job id) plus `.mp3` for `format="mp3"`
+and `.mp4` otherwise. The self-authorizing link is fetched without your API key, and an
+expired link is re-signed and retried once. A job that is not `completed` raises
+`DownloadNotCompletedError`.
+
 Async (FastAPI / Next.js backends):
 
 ```python
@@ -114,6 +130,8 @@ All SDK errors derive from `videofetch.VideoFetchError`:
 | `NotFoundError` | job/connection not found (404) |
 | `RateLimitError` | slow down (429) |
 | `JobFailedError` | job reached `failed` — **never charged** |
+| `DownloadNotCompletedError` | `download_to()` called before the job is `completed` |
+| `DownloadURLUnavailableError` | completed job has no `download_url` (bucket destination) |
 
 ## Serverless warning
 

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/README.md

@@ -33,6 +33,22 @@ print(result.size_bytes, result.cost_usd)
 result = client.downloads.create_and_wait(url=..., format="1080p")
 ```
 
+Save the artifact locally. Created with no destination configured, the job completes
+with a time-limited `download_url`; `download_to` streams it to disk and returns the
+absolute path of the saved file:
+
+```python
+path = client.downloads.download_to(result.id)          # ./<title>.mp4 in the current dir
+path = client.downloads.download_to(result.id, "out/clip.mp4")   # explicit file path
+path = client.downloads.download_to(result.id, "out/")           # existing directory
+print(path)   # "/abs/path/out/clip.mp4"
+```
+
+The default name is the sanitized title (or the job id) plus `.mp3` for `format="mp3"`
+and `.mp4` otherwise. The self-authorizing link is fetched without your API key, and an
+expired link is re-signed and retried once. A job that is not `completed` raises
+`DownloadNotCompletedError`.
+
 Async (FastAPI / Next.js backends):
 
 ```python
@@ -88,6 +104,8 @@ All SDK errors derive from `videofetch.VideoFetchError`:
 | `NotFoundError` | job/connection not found (404) |
 | `RateLimitError` | slow down (429) |
 | `JobFailedError` | job reached `failed` — **never charged** |
+| `DownloadNotCompletedError` | `download_to()` called before the job is `completed` |
+| `DownloadURLUnavailableError` | completed job has no `download_url` (bucket destination) |
 
 ## Serverless warning
 

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "videofetch-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Official VideoFetch SDK for Python — video ingestion API (YouTube URL → MP4/MP3 to your storage)"
 readme = "README.md"
 requires-python = ">=3.9"

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/src/videofetch/__init__.py

@@ -5,6 +5,7 @@
     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)
+    path = client.downloads.download_to(result.id)   # save the file locally → abs path
 
 Usage & alerts (v0.2.0):
     usage = client.usage.get()               # quota_gb, used_pct, alert_level, ...
@@ -29,6 +30,8 @@ from .client import AsyncVideoFetch, VideoFetch  # noqa: F401
 from .errors import (  # noqa: F401
     ApiError,
     AuthenticationError,
+    DownloadNotCompletedError,
+    DownloadURLUnavailableError,
     JobFailedError,
     NotFoundError,
     PermissionDeniedError,
@@ -44,33 +47,47 @@ from .models import (  # noqa: F401
     DownloadAttempt,
     DownloadList,
     FormatInfo,
+    ReplayResult,
     TrimSpec,
     Usage,
     UsageAlerts,
     VideoInfo,
+    WebhookDeliveriesResult,
+    WebhookDelivery,
+    WebhookDeliveryHealth,
     WebhookEndpoint,
     WebhookList,
     WebhookTestResult,
 )
 from .resources import DownloadJob  # noqa: F401
 from .webhooks import (  # noqa: F401
+    ATTEMPT_HEADER,
+    DELIVERY_HEADER,
+    TIMESTAMP_HEADER,
     WEBHOOK_EVENTS,
     SignatureVerificationError,
+    attempt_number,
     compute_signature,
     construct_event,
+    delivery_id,
     verify_webhook_signature,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __all__ = [
     "VideoFetch", "AsyncVideoFetch", "DownloadJob",
     "VideoFetchError", "AuthenticationError", "PermissionDeniedError", "QuotaExceededError",
     "ValidationError", "NotFoundError", "RateLimitError", "ApiError", "JobFailedError",
+    "DownloadNotCompletedError", "DownloadURLUnavailableError",
     "Download", "DownloadList", "DownloadAttempt", "TrimSpec", "FormatInfo", "VideoInfo",
     # v0.2.0
     "Usage", "UsageAlerts", "AlertState", "AlertEvent",
     "WebhookEndpoint", "WebhookList", "WebhookTestResult",
     "WEBHOOK_EVENTS", "SignatureVerificationError",
     "compute_signature", "construct_event", "verify_webhook_signature",
+    # v0.3.0
+    "WebhookDelivery", "WebhookDeliveriesResult", "WebhookDeliveryHealth", "ReplayResult",
+    "delivery_id", "attempt_number",
+    "DELIVERY_HEADER", "ATTEMPT_HEADER", "TIMESTAMP_HEADER",
     "__version__",
 ]

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/src/videofetch/client.py

@@ -106,6 +106,16 @@ class VideoFetch:
             return _parse_body(resp)
         raise VideoFetchError("request failed")  # pragma: no cover
 
+    def open_stream(self, url: str) -> httpx.Response:
+        """Open a streaming GET to an absolute URL WITHOUT the API key.
+
+        Download links are self-authorizing (time-limited), so the client's
+        default headers are intentionally not attached: the request is built
+        directly and sent through this client's transport. The caller owns the
+        returned response and must close it.
+        """
+        return self._client.send(httpx.Request("GET", url), stream=True)
+
     def close(self) -> None:
         self._client.close()
 
@@ -177,6 +187,10 @@ class AsyncVideoFetch:
             return _parse_body(resp)
         raise VideoFetchError("request failed")  # pragma: no cover
 
+    async def open_stream(self, url: str) -> httpx.Response:
+        """Async twin of :meth:`VideoFetch.open_stream` — no API key is sent."""
+        return await self._client.send(httpx.Request("GET", url), stream=True)
+
     async def close(self) -> None:
         await self._client.aclose()
 

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/src/videofetch/errors.py

@@ -12,6 +12,11 @@ v0.2.0 error semantics:
   402  QuotaExceededError    — carries remaining_gb.
   400  ValidationError       — code ∈ {invalid_format, invalid_trim, invalid_url, invalid_webhook};
                                carries param.
+
+v0.3.0 error semantics:
+  download_to() local-save preconditions:
+    DownloadNotCompletedError — status is not "completed" yet (code=job_not_completed).
+    DownloadURLUnavailableError — completed but no download_url (code=download_url_unavailable).
 """
 
 from __future__ import annotations
@@ -118,6 +123,39 @@ class JobFailedError(VideoFetchError):
         self.failed_not_charged = True
 
 
+class DownloadNotCompletedError(VideoFetchError):
+    """The job has not reached `completed`, so there is no artifact to save yet.
+
+    Wait for the terminal state first (``job.wait()`` or the ``download.completed``
+    webhook) and call ``download_to()`` afterwards.
+    """
+
+    def __init__(self, *, job_id: str, status: str):
+        super().__init__(
+            f"Download job {job_id} is not ready to save: status is {status!r} "
+            "(expected 'completed'). Wait for the job to finish before downloading it.",
+            code="job_not_completed",
+        )
+        self.job_id = job_id
+        self.status = status
+
+
+class DownloadURLUnavailableError(VideoFetchError):
+    """The completed job exposes no downloadable link.
+
+    This happens when the file was delivered straight to your own bucket
+    (``destination_type`` other than ``url``) — read it from your storage instead.
+    """
+
+    def __init__(self, *, job_id: str):
+        super().__init__(
+            f"Download job {job_id} completed but has no download_url "
+            "(it was delivered to your own storage destination).",
+            code="download_url_unavailable",
+        )
+        self.job_id = job_id
+
+
 def _parse_retry_after(headers) -> Optional[float]:
     """Retry-After is either delta-seconds or an HTTP date; SDK handles seconds."""
     if not headers:

{videofetch_sdk-0.2.0 → videofetch_sdk-0.3.0}/src/videofetch/models.py

@@ -43,8 +43,8 @@ class TrimSpec:
 @dataclass
 class DownloadAttempt:
     attempt_no: Optional[int] = None
-    strategy: Optional[str] = None          # direct | decodo_isp | decodo_dc
-    proxy_host: Optional[str] = None
+    strategy: Optional[str] = None          # direct | relay | relay_secondary
+    egress: Optional[str] = None        # "relay" or None (direct); real egress hosts are never returned
     result: Optional[str] = None
     error_code: Optional[str] = None
     error_message: Optional[str] = None
@@ -58,7 +58,7 @@ class DownloadAttempt:
             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"),
+            egress=d.get("egress"), 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"),
@@ -95,6 +95,10 @@ class Download:
     completed_at: Optional[str] = None
     estimated_bytes: Optional[int] = None
     attempt_details: list[DownloadAttempt] = field(default_factory=list)
+    # Queue position hints — only populated while status == "queued"; null otherwise.
+    queue_position: Optional[int] = None        # 1 == next to be claimed
+    ahead_of_you: Optional[int] = None
+    estimated_wait_seconds: Optional[int] = None
 
     @property
     def is_terminal(self) -> bool:
@@ -125,6 +129,9 @@ class Download:
             estimated_bytes=_as_int(d.get("estimated_bytes")),
             attempt_details=[DownloadAttempt.from_dict(a) or DownloadAttempt()
                              for a in (d.get("attempt_details") or [])],
+            queue_position=_as_int(d.get("queue_position")),
+            ahead_of_you=_as_int(d.get("ahead_of_you")),
+            estimated_wait_seconds=_as_int(d.get("estimated_wait_seconds")),
         )
 
 
@@ -182,14 +189,18 @@ class VideoInfo:
 class Usage:
     """GET /v1/usage — account quota snapshot + live alert level + concurrency.
 
-    `used_bytes`/`used_gb` are this key's lifetime usage; `account_used_*_month`
-    is the account-wide current-month billable usage (the quota is account-level).
+    `used_bytes`/`used_gb` are the ACCOUNT-WIDE current-month billable usage (the
+    quota is account-level and shared by every key). `key_used_bytes`/`key_used_gb`
+    are this key's own accumulated usage, for per-key attribution.
+    `account_used_*_month` mirror the account-level current-month figures.
     """
     key_id: str = ""
     plan: str = "free"
     quota_gb: Optional[float] = None
     used_bytes: int = 0
     used_gb: float = 0.0
+    key_used_bytes: int = 0
+    key_used_gb: float = 0.0
     remaining_gb: Optional[float] = None
     payg_balance_cents: int = 0
     payg_rate_usd_per_gb: float = 0.5
@@ -209,6 +220,8 @@ class Usage:
             quota_gb=_as_float(d.get("quota_gb")),
             used_bytes=int(d.get("used_bytes") or 0),
             used_gb=float(d.get("used_gb") or 0.0),
+            key_used_bytes=int(d.get("key_used_bytes") or 0),
+            key_used_gb=float(d.get("key_used_gb") or 0.0),
             remaining_gb=_as_float(d.get("remaining_gb")),
             payg_balance_cents=int(d.get("payg_balance_cents") or 0),
             payg_rate_usd_per_gb=float(d.get("payg_rate_usd_per_gb") or 0.0),
@@ -361,3 +374,99 @@ class WebhookTestResult:
             signature_header=d.get("signature_header", ""),
             signature_format=d.get("signature_format", ""),
         )
+
+
+# ──────────────────── Webhook deliveries + replay (v0.3.0) ───────────────────
+@dataclass
+class WebhookDeliveryHealth:
+    """Aggregate delivery health for one endpoint (GET /v1/webhooks/{id}/deliveries)."""
+    total: int = 0
+    succeeded: int = 0
+    dead: int = 0
+    pending: int = 0
+    success_rate: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> "WebhookDeliveryHealth":
+        d = d or {}
+        return cls(
+            total=int(d.get("total") or 0), succeeded=int(d.get("succeeded") or 0),
+            dead=int(d.get("dead") or 0), pending=int(d.get("pending") or 0),
+            success_rate=_as_float(d.get("success_rate")),
+        )
+
+
+@dataclass
+class WebhookDelivery:
+    """A single webhook delivery attempt (or its final state).
+
+    Deliveries are at-least-once: retried up to `max_attempts` (3) with backoff
+    on transient errors; 4xx responses other than 408/429 are permanent failures
+    that are not retried. Ordering is NOT guaranteed — sort by `seq`.
+    """
+    event_id: str = ""                 # idempotency key (X-VideoFetch-Delivery)
+    event: str = ""
+    seq: int = 0
+    status: str = "pending"            # pending | succeeded | dead
+    attempts: int = 0
+    max_attempts: int = 3
+    last_status_code: Optional[int] = None
+    last_error: Optional[str] = None
+    next_attempt_at: Optional[str] = None
+    created_at: Optional[str] = None
+    delivered_at: Optional[str] = None
+    download_id: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookDelivery":
+        return cls(
+            event_id=str(d.get("event_id", "")), event=d.get("event", ""),
+            seq=int(d.get("seq") or 0), status=d.get("status", "pending"),
+            attempts=int(d.get("attempts") or 0),
+            max_attempts=int(d.get("max_attempts") or 0),
+            last_status_code=_as_int(d.get("last_status_code")),
+            last_error=_as_str(d.get("last_error")),
+            next_attempt_at=_as_str(d.get("next_attempt_at")),
+            created_at=_as_str(d.get("created_at")),
+            delivered_at=_as_str(d.get("delivered_at")),
+            download_id=_as_str(d.get("download_id")),
+        )
+
+
+@dataclass
+class WebhookDeliveriesResult:
+    """GET /v1/webhooks/{endpoint_id}/deliveries — endpoint state + recent deliveries."""
+    endpoint_id: str = ""
+    active: bool = True
+    auto_disabled_at: Optional[str] = None
+    consecutive_failures: int = 0
+    max_attempts: int = 3
+    retry_schedule_seconds: str = ""   # e.g. "30,300"
+    health: WebhookDeliveryHealth = field(default_factory=WebhookDeliveryHealth)
+    items: list[WebhookDelivery] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebhookDeliveriesResult":
+        return cls(
+            endpoint_id=str(d.get("endpoint_id", "")), active=bool(d.get("active", True)),
+            auto_disabled_at=_as_str(d.get("auto_disabled_at")),
+            consecutive_failures=int(d.get("consecutive_failures") or 0),
+            max_attempts=int(d.get("max_attempts") or 0),
+            retry_schedule_seconds=_as_str(d.get("retry_schedule_seconds")) or "",
+            health=WebhookDeliveryHealth.from_dict(d.get("health")),
+            items=[WebhookDelivery.from_dict(i) for i in (d.get("items") or [])],
+        )
+
+
+@dataclass
+class ReplayResult:
+    """POST /v1/webhooks/deliveries/{event_id}/replay result.
+
+    A 404 means the delivery is not visible to this account.
+    """
+    queued: bool = False
+    event_id: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ReplayResult":
+        return cls(queued=bool(d.get("queued")), event_id=str(d.get("event_id", "")))