videopiper 0.1.0__py3-none-any.whl

videopiper/__init__.py

@@ -0,0 +1,16 @@
+"""Official Python SDK for the Video Piper API (https://videopiper.com/docs/)."""
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, VideoPiper
+from .errors import VideoPiperConnectionError, VideoPiperError, WaitTimeoutError, WebhookVerificationError
+from .webhooks import verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "VideoPiper",
+    "VideoPiperConnectionError",
+    "VideoPiperError",
+    "WaitTimeoutError",
+    "WebhookVerificationError",
+    "__version__",
+    "verify_webhook",
+]

videopiper/_http.py

@@ -0,0 +1,207 @@
+import email.utils
+import http.client
+import json
+import random
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections import deque
+from typing import Any, Dict, Mapping, NamedTuple, Optional
+
+from ._version import __version__
+from .errors import VideoPiperConnectionError, VideoPiperError
+
+USER_AGENT = f"videopiper-python/{__version__}"
+
+# A 429 is only worth retrying when the limit is the per-second one; the daily and test limits don't clear in seconds.
+_RETRYABLE_429 = {"RATE_LIMITED", "HTTP_429"}
+_RETRYABLE_STATUS = {500, 502, 503, 504}
+
+
+class Response(NamedTuple):
+    status: int
+    headers: Mapping[str, str]  # names in lower case
+    body: bytes
+
+
+class TransportError(Exception):
+    """The request got no answer: a network failure or a timeout."""
+
+
+class UrllibTransport:
+    """Sends requests with the standard library. Any object with the same ``send`` can replace it (a test double, a proxy)."""
+
+    def send(self, method: str, url: str, headers: Mapping[str, str], body: Optional[bytes], timeout: float) -> Response:
+        request = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return Response(response.status, _lower(response.headers), response.read())
+        except urllib.error.HTTPError as error:
+            with error:
+                return Response(error.code, _lower(error.headers), error.read())
+        except (urllib.error.URLError, http.client.HTTPException, OSError) as error:
+            raise TransportError(str(getattr(error, "reason", error))) from error
+
+
+def _lower(headers: Any) -> Dict[str, str]:
+    return {name.lower(): value for name, value in headers.items()}
+
+
+class _RateLimiter:
+    """At most ``per_second`` calls in any one second (the API allows 5 per key). 0 turns it off."""
+
+    def __init__(self, per_second: int) -> None:
+        self._per_second = per_second
+        self._stamps: "deque[float]" = deque()
+        self._lock = threading.Lock()
+
+    def wait(self) -> None:
+        if self._per_second <= 0:
+            return
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                while self._stamps and self._stamps[0] <= now - 1.0:
+                    self._stamps.popleft()
+                if len(self._stamps) < self._per_second:
+                    self._stamps.append(now)
+                    return
+                delay = self._stamps[0] + 1.0 - now
+            time.sleep(delay)
+
+
+def _retry_after(value: Optional[str]) -> Optional[float]:
+    """Retry-After in seconds (it is seconds or an HTTP date), or None."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, when.timestamp() - time.time())
+
+
+def _to_error(response: Response) -> VideoPiperError:
+    body: Dict[str, Any] = {}
+    text = response.body.decode("utf-8", "replace")
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict):
+            body = parsed
+    except ValueError:
+        pass  # Not JSON (a gateway page, or storage's XML): fall back to the status and the start of the text.
+    details = body.get("details")
+    return VideoPiperError(
+        body["message"] if isinstance(body.get("message"), str) else (text[:300] or f"HTTP {response.status}"),
+        status=response.status,
+        code=body["error"] if isinstance(body.get("error"), str) else f"HTTP_{response.status}",
+        request_id=body.get("requestId") if isinstance(body.get("requestId"), str) else response.headers.get("x-amzn-requestid"),
+        details=details if isinstance(details, list) else None,
+    )
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        upload_timeout: float,
+        max_retries: int,
+        retry_base_delay: float,
+        max_retry_delay: float,
+        requests_per_second: int,
+        transport: Any,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._upload_timeout = upload_timeout
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._max_retry_delay = max_retry_delay
+        self._transport = transport
+        self._limiter = _RateLimiter(requests_per_second)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        retry: bool = False,
+    ) -> Any:
+        """A call to the API: authenticated, rate limited, JSON in and out.
+
+        ``retry`` says a POST is safe to send again; GET, PUT, PATCH and DELETE always are, and so is any request
+        that carries an idempotency key.
+        """
+        url = self._base_url + path
+        pairs = [(name, _query_value(value)) for name, value in (query or {}).items() if value is not None]
+        if pairs:
+            url += "?" + urllib.parse.urlencode(pairs)
+        headers = {"Authorization": f"Bearer {self._api_key}", "Accept": "application/json", "User-Agent": USER_AGENT}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        retryable = method != "POST" or retry or bool(idempotency_key)
+        response = self._send(method, url, headers, data, self._timeout, retryable, limited=True)
+        return json.loads(response.body) if response.body else None
+
+    def put_part(self, url: str, data: bytes) -> None:
+        """Sends one part's bytes to its pre-signed URL: no Authorization header, no rate limit (it is storage, not the API)."""
+        headers = {"User-Agent": USER_AGENT, "Content-Type": "application/octet-stream"}
+        self._send("PUT", url, headers, data, self._upload_timeout, True, limited=False)
+
+    def _send(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        data: Optional[bytes],
+        timeout: float,
+        retryable: bool,
+        *,
+        limited: bool,
+    ) -> Response:
+        attempt = 0
+        while True:
+            if limited:
+                self._limiter.wait()
+            can_retry = retryable and attempt < self._max_retries
+            retry_after: Optional[float] = None
+            try:
+                response = self._transport.send(method, url, headers, data, timeout)
+            except TransportError as error:
+                failure: VideoPiperError = VideoPiperConnectionError(str(error))
+                if not can_retry:
+                    raise failure from error
+            else:
+                if 200 <= response.status < 300:
+                    return response
+                failure = _to_error(response)
+                retry_after = _retry_after(response.headers.get("retry-after"))
+                worth_retrying = failure.code in _RETRYABLE_429 if response.status == 429 else response.status in _RETRYABLE_STATUS
+                if not (can_retry and worth_retrying):
+                    raise failure
+            delay = retry_after if retry_after is not None else random.uniform(0, min(8.0, self._retry_base_delay * 2 ** attempt))
+            if delay > self._max_retry_delay:
+                raise failure
+            time.sleep(delay)
+            attempt += 1
+
+
+def _query_value(value: Any) -> str:
+    return str(value).lower() if isinstance(value, bool) else str(value)

videopiper/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

videopiper/client.py

@@ -0,0 +1,72 @@
+import os
+from typing import Any, Optional
+
+from ._http import HttpClient, UrllibTransport
+from .resources import (
+    AccountApi,
+    Edits,
+    EditTokens,
+    LiveStreams,
+    ThumbnailTokens,
+    UploadTokens,
+    UsageApi,
+    Videos,
+    Webhooks,
+)
+
+DEFAULT_BASE_URL = "https://api.videopiper.dev/v1"
+
+
+class VideoPiper:
+    """The Video Piper API client.
+
+    :param api_key: your API key (``vp_live_...``, or ``vp_test_...`` for test mode). Default: the
+        ``VIDEO_PIPER_API_KEY`` environment variable.
+    :param base_url: default: the ``VIDEO_PIPER_API_URL`` environment variable, else https://api.videopiper.dev/v1.
+    :param timeout: seconds a request may wait for the network (default 60).
+    :param upload_timeout: the same for a part upload (default 600).
+    :param max_retries: times a failed request that is safe to repeat is sent again (default 3). 0 turns retries off.
+    :param retry_base_delay: the first retry waits up to this many seconds, the next up to twice as long, and so on,
+        with jitter (default 0.5).
+    :param max_retry_delay: a ``Retry-After`` longer than this is not waited for; the error is raised instead (default 60).
+    :param requests_per_second: the API allows 5 per second per key, and the client keeps to it by default. 0 turns
+        the limit off.
+    :param transport: an object with ``send(method, url, headers, body, timeout)`` to use instead of ``urllib``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        upload_timeout: float = 600.0,
+        max_retries: int = 3,
+        retry_base_delay: float = 0.5,
+        max_retry_delay: float = 60.0,
+        requests_per_second: int = 5,
+        transport: Any = None,
+    ) -> None:
+        key = api_key or os.environ.get("VIDEO_PIPER_API_KEY")
+        if not key:
+            raise ValueError("No API key: pass api_key or set VIDEO_PIPER_API_KEY")
+        http = HttpClient(
+            api_key=key,
+            base_url=(base_url or os.environ.get("VIDEO_PIPER_API_URL") or DEFAULT_BASE_URL).rstrip("/"),
+            timeout=timeout,
+            upload_timeout=upload_timeout,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            max_retry_delay=max_retry_delay,
+            requests_per_second=requests_per_second,
+            transport=transport or UrllibTransport(),
+        )
+        self.videos = Videos(http)
+        self.edits = Edits(http)
+        self.upload_tokens = UploadTokens(http)
+        self.edit_tokens = EditTokens(http)
+        self.thumbnail_tokens = ThumbnailTokens(http)
+        self.usage = UsageApi(http)
+        self.account = AccountApi(http)
+        self.webhooks = Webhooks(http)
+        self.live_streams = LiveStreams(http)

videopiper/errors.py

@@ -0,0 +1,51 @@
+from typing import Any, Dict, List, Optional
+
+
+class VideoPiperError(Exception):
+    """Any failed call.
+
+    For an error the API answered, ``status`` is the HTTP status and ``code`` its stable ``error`` code
+    (PLAN_LIMIT_REACHED, RATE_LIMITED, ...): program against ``code``, show ``message``. Quote ``request_id`` when
+    asking for help. ``details`` lists every problem of a rejected request (400 INVALID_REQUEST) as
+    ``{"field": ..., "message": ...}``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "",
+        request_id: Optional[str] = None,
+        details: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.details = details
+
+    def __str__(self) -> str:
+        return f"{self.status} {self.code}: {self.message}" if self.status else f"{self.code}: {self.message}"
+
+
+class VideoPiperConnectionError(VideoPiperError):
+    """The request never got an answer (network failure or timeout). ``status`` is 0, ``code`` CONNECTION_ERROR."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="CONNECTION_ERROR")
+
+
+class WaitTimeoutError(VideoPiperError):
+    """``wait_until_done`` ran out of time. ``status`` is 0, ``code`` WAIT_TIMEOUT; ``last_status`` is the last one seen."""
+
+    def __init__(self, video_id: str, timeout: float, last_status: Optional[str]) -> None:
+        super().__init__(
+            f"Video {video_id} was still {last_status or 'unknown'} after {round(timeout)}s", code="WAIT_TIMEOUT"
+        )
+        self.last_status = last_status
+
+
+class WebhookVerificationError(ValueError):
+    """A webhook delivery that can't be trusted: a missing header, a bad or old signature, or a body that isn't JSON."""

videopiper/resources.py

@@ -0,0 +1,457 @@
+"""The API's areas as objects on the client: ``client.videos``, ``client.edits``, ``client.webhooks`` and so on.
+
+Arguments are Python names (``file_name``, ``max_height``); they are sent with the API's camelCase names. Objects inside
+a request (``trim``, ``redactions``, ``clips``, ``metadata``) are sent exactly as the API documents them. Methods that
+start something take ``dry_run=True`` (check the request without creating or starting anything) and, where the API
+supports it, ``idempotency_key`` (the same key and request answers the first response again, so a retry can't create a
+second video).
+"""
+import base64
+import io
+import os
+import re
+import time
+from typing import IO, Any, BinaryIO, Callable, Dict, Iterator, List, Optional, Union
+
+from ._http import HttpClient
+from .errors import WaitTimeoutError
+from .types import (
+    CompleteResponse,
+    CreateUploadResponse,
+    EditResponse,
+    ImportResponse,
+    LiveIngest,
+    LiveStream,
+    LiveStreamsPage,
+    PartUrlsResponse,
+    ReprocessResponse,
+    Usage,
+    VideoStatus,
+    VideosPage,
+    VideoSummary,
+    WebhookConfig,
+)
+
+# Statuses after which a video won't change.
+FINAL_STATUSES = frozenset({"SUCCEEDED", "FAILED", "TIMED_OUT", "ABORTED", "HISTORY_UNAVAILABLE"})
+
+Progress = Callable[[Dict[str, Any]], None]
+
+
+def _camel(name: str) -> str:
+    return re.sub(r"_([a-z])", lambda match: match.group(1).upper(), name)
+
+
+def _body(options: Dict[str, Any], keep_none: bool = False) -> Dict[str, Any]:
+    return {_camel(name): value for name, value in options.items() if keep_none or value is not None}
+
+
+def _write(
+    http: HttpClient,
+    path: str,
+    body: Dict[str, Any],
+    *,
+    dry_run: bool = False,
+    idempotency_key: Optional[str] = None,
+    safe_to_repeat: bool = False,
+) -> Any:
+    return http.request(
+        "POST",
+        path,
+        body=body,
+        query={"dryRun": True} if dry_run else None,
+        # Dry runs change nothing, so they can always be sent again; the API ignores keys on them.
+        idempotency_key=None if dry_run else idempotency_key,
+        retry=dry_run or safe_to_repeat,
+    )
+
+
+def _read_exactly(stream: IO[bytes], size: int) -> bytes:
+    chunks = []
+    while size > 0:
+        chunk = stream.read(size)
+        if not chunk:
+            raise ValueError("The stream ended before the size given for the upload")
+        chunks.append(chunk)
+        size -= len(chunk)
+    return b"".join(chunks)
+
+
+class Videos:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        file_name: str,
+        size_bytes: Optional[int] = None,
+        *,
+        idempotency_key: Optional[str] = None,
+        dry_run: bool = False,
+        **options: Any,
+    ) -> CreateUploadResponse:
+        """Starts an upload. Send the bytes with ``get_part_urls`` and ``complete``, or use ``upload_file``.
+
+        Options: ``title``, ``description``, ``max_height``, ``metadata``, ``camera``, ``layout``, ``streaming``,
+        ``prestart``, ``duration_seconds``.
+        """
+        body = _body({"file_name": file_name, "size_bytes": size_bytes, **options})
+        return _write(self._http, "/videos", body, dry_run=dry_run, idempotency_key=idempotency_key)
+
+    def import_url(
+        self, source_url: str, *, idempotency_key: Optional[str] = None, dry_run: bool = False, **options: Any
+    ) -> ImportResponse:
+        """Has the API download a public HTTPS URL, then process it like an upload.
+
+        Options: ``file_name``, ``title``, ``description``, ``max_height``, ``trim``, ``redactions``,
+        ``delete_original``, ``captions``, ``auto_redact``, ``metadata``.
+        """
+        body = _body({"source_url": source_url, **options})
+        return _write(self._http, "/videos", body, dry_run=dry_run, idempotency_key=idempotency_key)
+
+    def upload_file(self, path: str, *, file_name: Optional[str] = None, **options: Any) -> CompleteResponse:
+        """Uploads a local file end to end and returns the ``complete`` response; use ``wait_until_done`` next.
+
+        Create, then for each part: ask for its URL just before sending it (the URLs expire after 15 minutes) and PUT
+        its bytes, then complete. Options are those of ``upload_stream``.
+        """
+        with open(path, "rb") as stream:
+            return self.upload_stream(stream, os.path.getsize(path), file_name or os.path.basename(path), **options)
+
+    def upload_bytes(self, data: bytes, file_name: str, **options: Any) -> CompleteResponse:
+        """Like ``upload_file``, for bytes you already hold."""
+        return self.upload_stream(io.BytesIO(data), len(data), file_name, **options)
+
+    def upload_stream(
+        self,
+        stream: BinaryIO,
+        size_bytes: int,
+        file_name: str,
+        *,
+        idempotency_key: Optional[str] = None,
+        on_progress: Optional[Progress] = None,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        max_height: Optional[int] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        duration_seconds: Optional[float] = None,
+        **process_options: Any,
+    ) -> CompleteResponse:
+        """Uploads ``size_bytes`` read from a file-like object, one part at a time.
+
+        ``idempotency_key`` makes the whole upload retry-safe: create uses it and complete uses ``<key>:complete``.
+        ``on_progress`` is called after each part with ``videoId``, ``partNumber``, ``partCount``, ``bytesUploaded``
+        and ``totalBytes``. ``process_options`` (``trim``, ``redactions``, ``captions``, ``auto_redact``,
+        ``delete_original``) are applied when processing starts.
+        """
+        created = self.create(
+            file_name,
+            size_bytes,
+            idempotency_key=idempotency_key,
+            title=title,
+            description=description,
+            max_height=max_height,
+            metadata=metadata,
+            duration_seconds=duration_seconds,
+        )
+        video_id, part_count = created["videoId"], created["partCount"]
+        uploaded = 0
+        for number in range(1, part_count + 1):
+            part = self.get_part_urls(video_id, [number])["parts"][0]
+            self._http.put_part(part["url"], _read_exactly(stream, part["sizeBytes"]))
+            uploaded += part["sizeBytes"]
+            if on_progress:
+                on_progress(
+                    {"videoId": video_id, "partNumber": number, "partCount": part_count, "bytesUploaded": uploaded, "totalBytes": size_bytes}
+                )
+        return self.complete(
+            video_id, idempotency_key=f"{idempotency_key}:complete" if idempotency_key else None, **process_options
+        )
+
+    def get_part_urls(
+        self,
+        video_id: str,
+        part_numbers: Optional[List[int]] = None,
+        *,
+        file: Optional[str] = None,
+        parts: Optional[List[Dict[str, int]]] = None,
+    ) -> PartUrlsResponse:
+        """Pre-signed URLs (valid 15 minutes) for up to 100 parts. Ask just before you upload each part.
+
+        ``file="camera"`` is for the second file of a screen + camera upload; ``parts`` (``partNumber`` and
+        ``sizeBytes`` each) is for streaming uploads.
+        """
+        body = _body({"part_numbers": part_numbers, "file": file, "parts": parts})
+        return self._http.request("POST", f"/videos/{video_id}/parts", body=body, retry=True)
+
+    def complete(
+        self, video_id: str, *, idempotency_key: Optional[str] = None, dry_run: bool = False, **options: Any
+    ) -> CompleteResponse:
+        """Finishes the upload and starts processing. Calling it again never starts a second job.
+
+        Options: ``trim``, ``redactions``, ``captions``, ``auto_redact``, ``delete_original``, and for streaming
+        uploads ``source`` and ``camera`` (``sizeBytes`` and ``partCount``).
+        """
+        return _write(
+            self._http, f"/videos/{video_id}/complete", _body(options),
+            dry_run=dry_run, idempotency_key=idempotency_key, safe_to_repeat=True,
+        )
+
+    def abort(self, video_id: str) -> Any:
+        """Discards an unfinished upload."""
+        return self._http.request("POST", f"/videos/{video_id}/abort", retry=True)
+
+    def heartbeat(self, video_id: str) -> Any:
+        """Keeps a pre-started recording job waiting; send one about every 10 seconds."""
+        return self._http.request("POST", f"/videos/{video_id}/heartbeat")
+
+    def get(self, video_id: str, *, link_ttl: Optional[int] = None) -> VideoStatus:
+        """Status and progress, and (when finished) the download, playback and streaming links.
+
+        ``link_ttl`` is how many seconds (300 to 86400) the playback and streaming links last.
+        """
+        return self._http.request("GET", f"/videos/{video_id}", query={"linkTtl": link_ttl})
+
+    def list(
+        self, *, limit: Optional[int] = None, next_token: Optional[str] = None, metadata: Optional[Dict[str, str]] = None
+    ) -> VideosPage:
+        """One page of videos, newest first. Use ``list_all`` to go through every page.
+
+        ``metadata`` filters (up to 5, AND'd together): ``metadata={"lessonId": "123"}``.
+        """
+        query: Dict[str, Any] = {"limit": limit, "nextToken": next_token}
+        for name, value in (metadata or {}).items():
+            query[f"metadata.{name}"] = value
+        return self._http.request("GET", "/videos", query=query)
+
+    def list_all(self, *, limit: Optional[int] = None, metadata: Optional[Dict[str, str]] = None) -> Iterator[VideoSummary]:
+        """Every video, newest first, fetching pages as you go: ``for video in client.videos.list_all(): ...``"""
+        next_token: Optional[str] = None
+        while True:
+            page = self.list(limit=limit, next_token=next_token, metadata=metadata)
+            yield from page.get("videos", [])
+            next_token = page.get("nextToken")
+            if not next_token:
+                return
+
+    def update(self, video_id: str, **fields: Any) -> Dict[str, Any]:
+        """Changes ``title``, ``description`` or ``metadata``. ``None`` clears a field or a metadata key."""
+        return self._http.request("PATCH", f"/videos/{video_id}", body=_body(fields, keep_none=True))
+
+    def delete(self, video_id: str) -> Dict[str, Any]:
+        """Removes the video and its files (irreversible)."""
+        return self._http.request("DELETE", f"/videos/{video_id}")
+
+    def cancel(self, video_id: str) -> Dict[str, Any]:
+        """Stops processing."""
+        return self._http.request("POST", f"/videos/{video_id}/cancel", retry=True)
+
+    def reprocess(
+        self, video_id: str, *, idempotency_key: Optional[str] = None, dry_run: bool = False, **options: Any
+    ) -> ReprocessResponse:
+        """Processes the video again as a new video. Options are not inherited: send everything you want applied.
+
+        Options: ``max_height``, ``trim``, ``redactions``, ``captions``, ``auto_redact``, ``delete_original``,
+        ``metadata``, ``title``, ``description``, ``layout``.
+        """
+        return _write(
+            self._http, f"/videos/{video_id}/reprocess", _body(options), dry_run=dry_run, idempotency_key=idempotency_key
+        )
+
+    def wait_until_done(
+        self,
+        video_id: str,
+        *,
+        timeout: float = 1800.0,
+        interval: float = 3.0,
+        max_interval: float = 15.0,
+        on_status: Optional[Callable[[VideoStatus], None]] = None,
+        link_ttl: Optional[int] = None,
+    ) -> VideoStatus:
+        """Checks the status until the video reaches a final one and returns it.
+
+        Final: SUCCEEDED, FAILED, TIMED_OUT, ABORTED or HISTORY_UNAVAILABLE. It does not raise for FAILED, so check
+        ``["status"]``. The pause between checks starts at ``interval`` seconds and grows by half each time up to
+        ``max_interval``. Raises ``WaitTimeoutError`` after ``timeout`` seconds. Webhooks are better than polling in
+        production.
+        """
+        deadline = time.monotonic() + timeout
+        pause = interval
+        while True:
+            status = self.get(video_id, link_ttl=link_ttl)
+            if on_status:
+                on_status(status)
+            if status.get("status") in FINAL_STATUSES:
+                return status
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise WaitTimeoutError(video_id, timeout, status.get("status"))
+            time.sleep(min(pause, left))
+            pause = min(max_interval, pause * 1.5)
+
+    def list_thumbnails(self, video_id: str) -> Dict[str, Any]:
+        """Candidate thumbnail frames and the current choice, for a finished video."""
+        return self._http.request("GET", f"/videos/{video_id}/thumbnails")
+
+    def choose_thumbnail(
+        self,
+        video_id: str,
+        *,
+        candidate: Optional[int] = None,
+        time: Optional[float] = None,
+        image: Union[bytes, str, None] = None,
+        content_type: Optional[str] = None,
+        crop: Optional[Dict[str, float]] = None,
+    ) -> Dict[str, Any]:
+        """Chooses the thumbnail: a ``candidate`` index (0 is the automatic poster), any ``time`` of the video, or your
+        own ``image`` (JPEG or PNG bytes, with ``content_type``). ``crop`` (fractions ``x``, ``y``, ``w``, ``h``) goes
+        with a time or an image. A time or a crop is made by a short job: poll ``list_thumbnails`` until
+        ``current.status`` is ``ready``.
+        """
+        if isinstance(image, bytes):
+            image = base64.b64encode(image).decode("ascii")
+        body = _body({"candidate": candidate, "time": time, "image": image, "content_type": content_type, "crop": crop})
+        return self._http.request("POST", f"/videos/{video_id}/thumbnail", body=body, retry=True)
+
+    def get_chapters(self, video_id: str) -> Dict[str, Any]:
+        return self._http.request("GET", f"/videos/{video_id}/chapters")
+
+    def set_chapters(self, video_id: str, chapters: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Replaces the chapters of a finished video (an empty list removes them): ``[{"start": 0, "title": "Intro"}]``."""
+        return self._http.request("PUT", f"/videos/{video_id}/chapters", body={"chapters": chapters})
+
+    def delete_chapters(self, video_id: str) -> Dict[str, Any]:
+        return self._http.request("DELETE", f"/videos/{video_id}/chapters")
+
+    def set_embed(self, video_id: str, enabled: bool) -> Dict[str, Any]:
+        """Turns the embeddable player on or off. Turning it off revokes the code; turning it on again makes a new one."""
+        return self._http.request("PUT", f"/videos/{video_id}/embed", body={"enabled": enabled})
+
+
+class Edits:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self, clips: List[Dict[str, Any]], *, idempotency_key: Optional[str] = None, dry_run: bool = False, **options: Any
+    ) -> EditResponse:
+        """Makes a new video from clips of your finished videos (trim, stitch, splice).
+
+        ``clips`` are ``{"videoId": ..., "start": ..., "end": ..., "transition": {...}}``. Options: ``file_name``,
+        ``title``, ``description``, ``max_height``, ``redactions``, ``captions``, ``auto_redact``, ``metadata``.
+        """
+        body = {"edit": {"clips": clips}, **_body(options)}
+        return _write(self._http, "/videos", body, dry_run=dry_run, idempotency_key=idempotency_key)
+
+
+class _Tokens:
+    """Short-lived tokens that let a browser do one thing without your API key. Make them on your server."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+
+class UploadTokens(_Tokens):
+    def create(self, **options: Any) -> Dict[str, Any]:
+        """Options: ``expires_in``, ``max_bytes``, ``max_seconds``, ``max_height``, ``captions``, ``auto_redact``, ``metadata``."""
+        return self._http.request("POST", "/upload-tokens", body=_body(options))
+
+
+class EditTokens(_Tokens):
+    def create(self, video_ids: List[str], **options: Any) -> Dict[str, Any]:
+        """Options: ``expires_in``, ``max_seconds``, ``title``, ``metadata``."""
+        return self._http.request("POST", "/edit-tokens", body=_body({"video_ids": video_ids, **options}))
+
+
+class ThumbnailTokens(_Tokens):
+    def create(self, video_id: str, *, expires_in: Optional[int] = None) -> Dict[str, Any]:
+        return self._http.request("POST", "/thumbnail-tokens", body=_body({"video_id": video_id, "expires_in": expires_in}))
+
+
+class UsageApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, month: Optional[str] = None) -> Usage:
+        """Processing, storage and delivery for a ``YYYY-MM`` month (default: this one). Always empty with a test key."""
+        return self._http.request("GET", "/usage", query={"month": month})
+
+
+class AccountApi:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self) -> Dict[str, Any]:
+        """The account, its plan and this month's usage."""
+        return self._http.request("GET", "/account")
+
+
+class Webhooks:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self) -> WebhookConfig:
+        return self._http.request("GET", "/webhook")
+
+    def set(self, url: str, *, events: Optional[List[str]] = None, enabled: Optional[bool] = None) -> WebhookConfig:
+        """Sets the endpoint. The response carries the signing secret (``whsec_...``) for ``verify_webhook``."""
+        return self._http.request("PUT", "/webhook", body=_body({"url": url, "events": events, "enabled": enabled}))
+
+    def delete(self) -> Dict[str, Any]:
+        return self._http.request("DELETE", "/webhook")
+
+    def rotate_secret(self) -> WebhookConfig:
+        """A new signing secret; the old one stops working at once."""
+        return self._http.request("POST", "/webhook/rotate")
+
+    def test(self) -> Dict[str, Any]:
+        """Sends a test event and reports the endpoint's answer."""
+        return self._http.request("POST", "/webhook/test")
+
+    def deliveries(self, *, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """The last 30 days of delivery attempts."""
+        return self._http.request("GET", "/webhook/deliveries", query={"limit": limit})["deliveries"]
+
+
+class LiveStreams:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, *, dry_run: bool = False, **options: Any) -> LiveStream:
+        """Makes a stream to broadcast to: its ingest (RTMPS URL and stream key), a watch link and a playback link. Pro and Scale.
+
+        Options: ``title``, ``description``, ``metadata``, ``record``, ``captions``, ``auto_redact``, ``max_duration_minutes``.
+        """
+        return _write(self._http, "/live-streams", _body(options), dry_run=dry_run)
+
+    def get(self, live_stream_id: str) -> LiveStream:
+        return self._http.request("GET", f"/live-streams/{live_stream_id}")
+
+    def list(self, *, limit: Optional[int] = None, next_token: Optional[str] = None) -> LiveStreamsPage:
+        return self._http.request("GET", "/live-streams", query={"limit": limit, "nextToken": next_token})
+
+    def list_all(self, *, limit: Optional[int] = None) -> Iterator[LiveStream]:
+        """Every stream, newest first, fetching pages as you go."""
+        next_token: Optional[str] = None
+        while True:
+            page = self.list(limit=limit, next_token=next_token)
+            yield from page.get("liveStreams", [])
+            next_token = page.get("nextToken")
+            if not next_token:
+                return
+
+    def update(self, live_stream_id: str, **fields: Any) -> LiveStream:
+        """Changes ``title``, ``description`` or ``metadata``. ``None`` clears a field or a metadata key."""
+        return self._http.request("PATCH", f"/live-streams/{live_stream_id}", body=_body(fields, keep_none=True))
+
+    def get_ingest(self, live_stream_id: str) -> LiveIngest:
+        """The ingest URL and stream key again, while the stream is open."""
+        return self._http.request("GET", f"/live-streams/{live_stream_id}/ingest")["ingest"]
+
+    def end(self, live_stream_id: str) -> LiveStream:
+        """Ends the broadcast now; the status becomes ``ended`` a moment later."""
+        return self._http.request("POST", f"/live-streams/{live_stream_id}/end")
+
+    def delete(self, live_stream_id: str) -> Dict[str, Any]:
+        """Stops the stream if it is live and deletes it. A video already saved from its recording is kept."""
+        return self._http.request("DELETE", f"/live-streams/{live_stream_id}")

videopiper/types.py

@@ -0,0 +1,165 @@
+"""Response shapes, from docs/openapi.yaml and docs/payloads.md.
+
+Responses are plain dicts with the API's own (camelCase) keys; these TypedDicts describe them for type checkers.
+Any field can be missing, so read the optional ones with ``.get``. Times are seconds.
+"""
+from typing import Any, Dict, List, TypedDict
+
+
+class CreateUploadResponse(TypedDict, total=False):
+    videoId: str
+    partSize: int  # bytes per part (the last part may be smaller)
+    partCount: int
+    camera: Dict[str, int]
+    status: str
+    statusPath: str
+
+
+class ImportResponse(TypedDict, total=False):
+    videoId: str
+    status: str
+    fileName: str
+    statusPath: str
+
+
+class EditResponse(TypedDict, total=False):
+    videoId: str
+    clips: int
+    status: str
+
+
+class CompleteResponse(TypedDict, total=False):
+    videoId: str
+    status: str
+    statusPath: str
+
+
+class ReprocessResponse(TypedDict, total=False):
+    videoId: str
+    reprocessOf: str
+    status: str
+    statusPath: str
+
+
+class PartUrl(TypedDict):
+    partNumber: int
+    sizeBytes: int
+    url: str  # pre-signed, valid 15 minutes: PUT the bytes with no Authorization header
+
+
+class PartUrlsResponse(TypedDict):
+    parts: List[PartUrl]
+    expiresInSeconds: int
+
+
+class VideoSummary(TypedDict, total=False):
+    videoId: str
+    fileName: str
+    title: str
+    description: str
+    createdAt: int
+    sizeBytes: int
+    state: str  # UPLOADING, READY_TO_START or SUBMITTED
+    mode: str  # live or test
+    clips: int
+    reprocessOf: str
+    metadata: Dict[str, str]
+    captions: bool
+    autoRedact: bool
+    embeddable: bool
+    outcome: str  # SUCCEEDED, FAILED, TIMED_OUT or ABORTED; absent while it runs
+    endedAt: float
+    durationSeconds: float
+    height: int
+
+
+class VideosPage(TypedDict, total=False):
+    videos: List[VideoSummary]
+    nextToken: str
+
+
+class VideoStatus(TypedDict, total=False):
+    videoId: str
+    status: str  # UPLOADING, READY_TO_START, SUBMITTED, RUNNING, SUCCEEDED, FAILED, TIMED_OUT, ABORTED, ...
+    mode: str
+    title: str
+    description: str
+    metadata: Dict[str, str]
+    deletesAt: int  # test videos only
+    downloadUrl: str  # pre-signed MP4 link (SUCCEEDED only)
+    downloadExpiresInSeconds: int
+    posterUrl: str
+    playbackUrl: str
+    posterPlaybackUrl: str
+    playbackExpiresAt: float
+    chaptersUrl: str
+    streamUrl: str  # HLS master playlist (Pro and Scale)
+    streamExpiresAt: float
+    captions: Dict[str, Any]
+    autoRedaction: Dict[str, Any]
+    embed: Dict[str, Any]
+    thumbnail: Dict[str, Any]
+    startedAt: float
+    stoppedAt: float
+    progress: Dict[str, Any]
+    result: Dict[str, Any]
+    processing: Dict[str, Any]
+
+
+class Usage(TypedDict, total=False):
+    month: str
+    complete: bool
+    processing: Dict[str, float]
+    storage: Dict[str, Any]
+    delivery: Dict[str, Any]
+    live: Dict[str, Any]
+
+
+class WebhookConfig(TypedDict, total=False):
+    configured: bool
+    url: str
+    events: List[str]
+    enabled: bool
+    secret: str  # whsec_ prefixed signing secret, for verify_webhook
+    createdAt: str
+    updatedAt: str
+
+
+class LiveIngest(TypedDict):
+    rtmpsUrl: str
+    streamKey: str  # lets whoever holds it broadcast to this stream: give it only to the broadcaster
+
+
+class LiveStream(TypedDict, total=False):
+    liveStreamId: str
+    status: str  # idle, live, ended, expired or failed
+    mode: str
+    title: str
+    description: str
+    metadata: Dict[str, str]
+    record: bool
+    maxDurationMinutes: int
+    createdAt: int
+    startedAt: int
+    endedAt: int
+    durationSeconds: int
+    viewers: int
+    videoId: str  # the video saved from the recording
+    usage: Dict[str, float]
+    ingest: LiveIngest
+    watch: Dict[str, str]
+    playbackUrl: str
+    playbackExpiresAt: int
+
+
+class LiveStreamsPage(TypedDict, total=False):
+    liveStreams: List[LiveStream]
+    nextToken: str
+
+
+class WebhookEvent(TypedDict):
+    id: str
+    type: str
+    livemode: bool  # False for events about test-mode videos
+    createdAt: str
+    data: Dict[str, Any]

videopiper/webhooks.py

@@ -0,0 +1,55 @@
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Mapping, Union
+
+from .errors import WebhookVerificationError
+
+
+def verify_webhook(
+    secret: str,
+    body: Union[str, bytes],
+    headers: Mapping[str, str],
+    tolerance_seconds: int = 300,
+) -> Dict[str, Any]:
+    """Checks a webhook delivery and returns the parsed event.
+
+    Standard Webhooks: the signature is the base64 HMAC-SHA256 of ``"<id>.<timestamp>.<body>"`` with the bytes of the
+    secret after ``whsec_``, sent as ``v1,<signature>`` in ``webhook-signature`` (several may be sent, separated by
+    spaces). Pass the raw request body, before any JSON parsing. Raises ``WebhookVerificationError`` if a header is
+    missing, no ``v1`` signature matches, the timestamp is more than ``tolerance_seconds`` from now, or the body isn't JSON.
+    """
+    lowered = {name.lower(): value for name, value in headers.items()}
+    event_id = lowered.get("webhook-id")
+    timestamp = lowered.get("webhook-timestamp")
+    signatures = lowered.get("webhook-signature")
+    if not event_id or not timestamp or not signatures:
+        raise WebhookVerificationError("Missing webhook-id, webhook-timestamp or webhook-signature header")
+
+    try:
+        sent_at = int(timestamp)
+    except ValueError:
+        raise WebhookVerificationError("Invalid webhook-timestamp header") from None
+    if abs(time.time() - sent_at) > tolerance_seconds:
+        raise WebhookVerificationError("Timestamp is outside the tolerance")
+
+    raw = body.encode("utf-8") if isinstance(body, str) else bytes(body)
+    key = base64.b64decode(secret[len("whsec_"):] if secret.startswith("whsec_") else secret)
+    digest = hmac.new(key, f"{event_id}.{timestamp}.".encode() + raw, hashlib.sha256).digest()
+    expected = base64.b64encode(digest)
+
+    valid = False
+    for entry in signatures.split(" "):
+        version, _, given = entry.partition(",")
+        # Look at every entry (no early exit), and compare in constant time.
+        if version == "v1" and hmac.compare_digest(given.encode(), expected):
+            valid = True
+    if not valid:
+        raise WebhookVerificationError("No matching signature")
+
+    try:
+        return json.loads(raw)
+    except ValueError:
+        raise WebhookVerificationError("Body is not valid JSON") from None

videopiper-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: videopiper
+Version: 0.1.0
+Summary: Official Python SDK for the Video Piper API: upload, import, edit and stream videos, with webhook verification.
+Author: PodWorks3D LLC
+License: MIT
+Project-URL: Homepage, https://videopiper.com/docs/
+Keywords: video,api,sdk,video-api,transcoding,hls,webhooks,live-streaming
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# videopiper
+
+The official Python SDK for the [Video Piper](https://videopiper.com/) API: upload or import videos, cut and join them, stream live, and check webhooks. Python 3.9 or newer, no dependencies (it uses the standard library), type hints included.
+
+```sh
+pip install videopiper
+```
+
+Keep your API key on your server. To let a browser upload, record or edit, make a short-lived token with the SDK and give the page that (see [Tokens for browsers](#tokens-for-browsers)).
+
+## Quickstart
+
+Upload a file, wait for it to process, and get the download link:
+
+```python
+from videopiper import VideoPiper
+
+client = VideoPiper()  # reads VIDEO_PIPER_API_KEY
+
+upload = client.videos.upload_file("lesson.mp4", title="Lesson 1")
+video = client.videos.wait_until_done(upload["videoId"])
+
+if video["status"] == "SUCCEEDED":
+    print(video["downloadUrl"])  # an MP4 link, valid for 15 minutes
+else:
+    print("Processing ended with", video["status"])
+```
+
+`upload_file` creates the video, then for each part asks for its upload URL just before sending that part (the URLs expire after 15 minutes), sends the bytes with no `Authorization` header, and completes the upload. Any file size works; parts go one at a time and only one part is held in memory.
+
+## Setup
+
+```python
+client = VideoPiper(
+    api_key="vpk_...",                        # default: the VIDEO_PIPER_API_KEY environment variable
+    base_url="https://api.videopiper.dev/v1",  # default: VIDEO_PIPER_API_URL, then this
+    timeout=60,                                # seconds, per request
+    max_retries=3,                             # see Retries
+)
+```
+
+Other options: `upload_timeout` (per part, default 10 minutes), `retry_base_delay`, `max_retry_delay`, `requests_per_second` (default 5, the API's limit per key; 0 turns it off) and `transport` (an object with `send(method, url, headers, body, timeout)`, to use instead of `urllib`).
+
+Arguments are Python names (`file_name`, `max_height`) and are sent with the API's camelCase names. Objects inside a request (`trim`, `redactions`, `clips`, `metadata`) are sent exactly as the [API docs](https://videopiper.com/docs/) show them. Responses are plain dicts with the API's keys; `videopiper.types` has `TypedDict`s for the main ones.
+
+## Videos
+
+```python
+# Upload from disk, from bytes, or from a file-like object
+client.videos.upload_file("lesson.mp4", max_height=720, captions=True, on_progress=print)
+client.videos.upload_bytes(data, "clip.mp4", metadata={"lessonId": "123"})
+client.videos.upload_stream(stream, size_bytes, "recording.webm")
+
+# Have the API download a public HTTPS URL
+video = client.videos.import_url("https://example.com/tutorial.mp4", max_height=1080)
+
+# Status, and the links once it has finished
+status = client.videos.get(video["videoId"])  # playbackUrl, streamUrl, downloadUrl, posterUrl
+done = client.videos.wait_until_done(video["videoId"], timeout=600, on_status=lambda s: print(s["status"]))
+
+# Lists: one page, or every video
+page = client.videos.list(limit=25, metadata={"lessonId": "123"})
+for item in client.videos.list_all(limit=100):
+    print(item["videoId"], item.get("outcome"))
+
+client.videos.update(video_id, title="New title", metadata={"archived": None})  # None clears
+client.videos.reprocess(video_id, max_height=2160, trim={"start": 30})           # a new video from the same upload
+client.videos.cancel(video_id)                                                   # stop processing
+client.videos.delete(video_id)
+```
+
+`wait_until_done` checks the status with a growing pause (3 s up to 15 s) until the video reaches a final status and returns it; `FAILED`, `TIMED_OUT` and `ABORTED` are returned, not raised, so look at `["status"]`. It raises `WaitTimeoutError` after `timeout` seconds (default 30 minutes). In production prefer [webhooks](#webhooks) to polling.
+
+The steps behind `upload_file` are public too, for streaming uploads and other special cases: `create`, `get_part_urls`, `complete`, `abort` and `heartbeat`.
+
+Also on `client.videos`: `list_thumbnails`, `choose_thumbnail`, `get_chapters`, `set_chapters`, `delete_chapters` and `set_embed`.
+
+## Edits
+
+Make a new video from clips of finished videos: trim, stitch and splice.
+
+```python
+edit = client.edits.create(
+    [
+        {"videoId": intro_id, "end": 60},
+        {"videoId": lesson_id, "start": 90, "transition": {"type": "fade", "seconds": 0.75}},
+    ],
+    file_name="Lesson 1 (final)",
+)
+```
+
+## Dry runs and idempotency
+
+`dry_run=True` checks a request without creating or starting anything (it doesn't count toward your daily limit) and returns `{"valid": True, "dryRun": True, ...}`; an edit also reports its length. It works on `videos.create`, `import_url`, `complete`, `reprocess`, `edits.create` and `live_streams.create`.
+
+```python
+check = client.edits.create(clips, dry_run=True)
+print(check["durationSeconds"])
+```
+
+An `idempotency_key` makes a retry safe: the same key with the same request returns the first response again (kept 24 hours) instead of creating a second video.
+
+```python
+client.videos.import_url(url, idempotency_key=f"import-{lesson_id}")
+client.videos.upload_file(path, idempotency_key=f"upload-{lesson_id}")  # complete uses "<key>:complete"
+```
+
+## Tokens for browsers
+
+```python
+upload = client.upload_tokens.create(max_seconds=600, metadata={"userId": "u_1"})
+# <video-piper-recorder upload-token="{upload['uploadToken']}">
+edit = client.edit_tokens.create([a, b], max_seconds=300)
+thumb = client.thumbnail_tokens.create(video_id)
+```
+
+These go with the web components in [`@videopiper/elements`](https://www.npmjs.com/package/@videopiper/elements).
+
+## Usage and account
+
+```python
+usage = client.usage.get("2026-10")  # processing, storage and delivery against the plan
+account = client.account.get()
+```
+
+## Live streams (Pro and Scale)
+
+```python
+stream = client.live_streams.create(title="Product demo", record=True, max_duration_minutes=60)
+print(stream["ingest"]["rtmpsUrl"], stream["ingest"]["streamKey"])  # for OBS: give the key only to the broadcaster
+print(stream["watch"]["url"])                                       # for viewers
+client.live_streams.end(stream["liveStreamId"])                     # the recording becomes a normal video
+```
+
+Also `get`, `list`, `list_all`, `update`, `get_ingest` and `delete`.
+
+## Webhooks
+
+Set the endpoint, and keep the signing secret it returns:
+
+```python
+config = client.webhooks.set("https://example.com/hooks/video-piper", events=["video.ready", "video.failed"])
+# config["secret"] is "whsec_..."
+```
+
+Check every delivery with `verify_webhook` on the **raw** body (before JSON parsing). It returns the parsed event, or raises `WebhookVerificationError` if a header is missing, no signature matches (it accepts several, separated by spaces), or the timestamp is more than 5 minutes off (change it with `tolerance_seconds`).
+
+```python
+from flask import Flask, request
+from videopiper import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+
+@app.post("/hooks/video-piper")
+def video_piper_hook():
+    try:
+        event = verify_webhook(WEBHOOK_SECRET, request.get_data(), request.headers)
+    except WebhookVerificationError:
+        return "", 401
+    if event["type"] == "video.ready":
+        print("ready", event["data"]["videoId"])
+    return "", 204
+```
+
+Deliveries are at-least-once: deduplicate on `event["id"]` (the `webhook-id` header). Also on `client.webhooks`: `get`, `delete`, `rotate_secret`, `test` and `deliveries`.
+
+## Errors
+
+Every failed call raises `VideoPiperError`:
+
+```python
+from videopiper import VideoPiperError
+
+try:
+    client.videos.upload_file("lesson.mp4")
+except VideoPiperError as error:
+    print(error.status, error.code, error.message, error.request_id)
+    if error.code == "PLAN_LIMIT_REACHED":
+        ...  # out of Free minutes
+    for problem in error.details or []:  # INVALID_REQUEST lists every problem
+        print(problem["field"], problem["message"])
+    raise
+```
+
+Program against `code` (`PLAN_LIMIT_REACHED`, `DAILY_LIMIT`, `RATE_LIMITED`, `NOT_FOUND`, ...), not the message. Quote `request_id` when asking for help. A request that got no answer raises `VideoPiperConnectionError` (`status` 0, `code` `CONNECTION_ERROR`); `wait_until_done` running out of time raises `WaitTimeoutError`. All three are `VideoPiperError`s.
+
+## Retries and rate limits
+
+Failed requests are sent again, up to `max_retries` times with exponential backoff and jitter, when it is safe: network errors, `RATE_LIMITED` (429) and 500, 502, 503 or 504, on `GET`, `PUT`, `PATCH` and `DELETE`, on the idempotent `POST`s (part URLs, `complete`, `cancel`, `abort`) and on any `POST` that carries an `idempotency_key`. Daily, quota and plan limits are not retried. A `Retry-After` header is honoured (a wait longer than `max_retry_delay`, 60 s by default, raises instead).
+
+The client sends at most 5 requests a second (the API's limit per key); lower or raise it with `requests_per_second`.
+
+## Test mode
+
+A test key (`vp_test_...`, made in the app under Account, API keys, Create test key) works the same way and is free: it only sees test videos, which are one MP4 of at most 60 seconds and 480p, marked TEST, and deleted after 24 hours. Use it in tests and CI. A test key can't read the account or change the webhook, and `usage.get` is always empty for it.
+
+```python
+client = VideoPiper(os.environ["VIDEO_PIPER_TEST_KEY"])
+```
+
+Test webhook events carry `livemode: false`.
+
+## License
+
+MIT. Docs: <https://videopiper.com/docs/>.

videopiper-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+videopiper/__init__.py,sha256=ZCicOehvhUhfn1cmUd8Lx1qJAPlNc73TDxTxIA5NESs,519
+videopiper/_http.py,sha256=9O6bPtrxyd5xzkU_8-CUz7XRLnLY2N4gZLfo51n5l2Y,7867
+videopiper/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+videopiper/client.py,sha256=8nWkyvyD6Z4Rasx5XUQE2Pdc7Lpzr6wYL9jWDBWXhOk,2837
+videopiper/errors.py,sha256=_HiRvXGLMjye2ubheqOdMOg0DyCaoOYj8J6a75ldY_8,1920
+videopiper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+videopiper/resources.py,sha256=zxBkI6KfPgpLpnx3PIIthg_PVL1vAWQ44_zX0bTmovw,20514
+videopiper/types.py,sha256=2mU9qlHu1hdORM0lotRvK1bwuiWqgjjOYofk7ntmC7o,4018
+videopiper/webhooks.py,sha256=O9ItdAh2KPkmch8O_61hFWuFrCN_ZIdkqrrS8lpqafU,2328
+videopiper-0.1.0.dist-info/licenses/LICENSE,sha256=XD6DG1HT_5S0gosCdylX4sFrsEXT0WeCv_JBXPCIWeE,1071
+videopiper-0.1.0.dist-info/METADATA,sha256=fGs92dqZGLwhVnmfmtQMRJ9oWOTOnKCg-ujHzw85opQ,10327
+videopiper-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+videopiper-0.1.0.dist-info/top_level.txt,sha256=koOBjpRzXI5eYlIdKxWqu332HyXONcqBkl5Mp-ta1KQ,11
+videopiper-0.1.0.dist-info/RECORD,,

videopiper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

videopiper-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PodWorks3D LLC
+
+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.

videopiper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+videopiper