nerdstack-ark 1.0.2__tar.gz → 1.0.4__tar.gz

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.2
+Version: 1.0.4
 Summary: Official Python SDK for Ark storage, with sync, async, and S3-compatible access.
 Project-URL: Homepage, https://ark.nerdstackgrp.com
 Project-URL: Documentation, https://github.com/joshhumphrey02/ark-sdk/tree/master/packages/ark-py#readme
@@ -130,6 +130,40 @@ session = ark.create_client_session(ttl_seconds=900)
 # Hand session.token to @nerdstackgrp/ark-client in the browser.
 ```
 
+## Ark Streams
+
+Both synchronous and asynchronous clients expose Ark Streams. `upload` is the
+one call most applications need: it creates the video and sends the bytes,
+resuming from the server's acknowledged offset if the connection drops.
+
+```python
+stream = ark.streams.upload(
+    "./launch.mp4",
+    title="Product launch",
+    app_id=app_id,
+    on_progress=lambda sent, total: print(f"{sent}/{total}"),
+)
+```
+
+Use `create` directly when the bytes belong to someone else -- a browser, or a
+worker -- and you only need the upload ticket:
+
+```python
+creation = ark.streams.create("Product launch", size_bytes, app_id=app_id)
+print(creation.stream.id, creation.upload.endpoint)
+
+ark.streams.import_from_url("Remote video", source_url, app_id=app_id)
+page = ark.streams.list(app_id=app_id, limit=50)
+stream = ark.streams.get(creation.stream.id, app_id=app_id)
+ark.streams.refresh_upload_url(stream.id, app_id=app_id)
+ark.streams.delete(stream.id, app_id=app_id)
+```
+
+The same methods on `AsyncArk.streams` are awaitable. Encoding continues after
+an upload returns, so poll `get` until `status` is `ready`; `hls_url`,
+`thumbnail_url` and `embed_url` are `None` until then. `embed_url` is an
+Ark-hosted player page that can go straight into an iframe.
+
 ## S3-compatible access
 
 ```python

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/README.md

@@ -87,6 +87,40 @@ session = ark.create_client_session(ttl_seconds=900)
 # Hand session.token to @nerdstackgrp/ark-client in the browser.
 ```
 
+## Ark Streams
+
+Both synchronous and asynchronous clients expose Ark Streams. `upload` is the
+one call most applications need: it creates the video and sends the bytes,
+resuming from the server's acknowledged offset if the connection drops.
+
+```python
+stream = ark.streams.upload(
+    "./launch.mp4",
+    title="Product launch",
+    app_id=app_id,
+    on_progress=lambda sent, total: print(f"{sent}/{total}"),
+)
+```
+
+Use `create` directly when the bytes belong to someone else -- a browser, or a
+worker -- and you only need the upload ticket:
+
+```python
+creation = ark.streams.create("Product launch", size_bytes, app_id=app_id)
+print(creation.stream.id, creation.upload.endpoint)
+
+ark.streams.import_from_url("Remote video", source_url, app_id=app_id)
+page = ark.streams.list(app_id=app_id, limit=50)
+stream = ark.streams.get(creation.stream.id, app_id=app_id)
+ark.streams.refresh_upload_url(stream.id, app_id=app_id)
+ark.streams.delete(stream.id, app_id=app_id)
+```
+
+The same methods on `AsyncArk.streams` are awaitable. Encoding continues after
+an upload returns, so poll `get` until `status` is `ready`; `hls_url`,
+`thumbnail_url` and `embed_url` are `None` until then. `embed_url` is an
+Ark-hosted player page that can go straight into an iframe.
+
 ## S3-compatible access
 
 ```python

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.2"
+version = "1.0.4"
 description = "Official Python SDK for Ark storage, with sync, async, and S3-compatible access."
 readme = "README.md"
 requires-python = ">=3.10"

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/__init__.py

@@ -5,11 +5,16 @@ from .errors import ArkError
 from .models import (
     ArkFile,
     ArkFolder,
+    ArkStream,
     ArkUsage,
     ClientSession,
     FilePage,
     ImageOptions,
     StorageUsage,
+    StreamCreation,
+    StreamPage,
+    StreamStatus,
+    StreamUploadTicket,
 )
 from .s3 import create_s3_client
 from .sync import Ark
@@ -19,12 +24,17 @@ __all__ = [
     "ArkError",
     "ArkFile",
     "ArkFolder",
+    "ArkStream",
     "ArkUsage",
     "AsyncArk",
     "ClientSession",
     "FilePage",
     "ImageOptions",
     "StorageUsage",
+    "StreamCreation",
+    "StreamPage",
+    "StreamStatus",
+    "StreamUploadTicket",
     "create_s3_client",
 ]
 

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/_shared.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import base64
 import mimetypes
 import os
 from collections.abc import Iterable, Iterator, Mapping
@@ -180,3 +181,46 @@ def sorted_parts(parts: Iterable[dict[str, object]]) -> list[dict[str, object]]:
         return value
 
     return sorted(parts, key=part_number)
+
+
+# --- Ark Streams resumable upload (TUS) -------------------------------------
+#
+# Video goes to the encoding network over TUS rather than through the presigned
+# path files use: an encode is long enough that a dropped connection is normal
+# rather than exceptional, so the protocol has to be able to say "you already
+# have the first N bytes, continue from there".
+
+#: TUS sends metadata as base64, so a filename with non-ASCII characters
+#: survives the header intact.
+def tus_metadata(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
+#: Default slice sent per PATCH. Large enough that a long video is not thousands
+#: of round trips, small enough that a failure re-sends little.
+DEFAULT_VIDEO_CHUNK_SIZE = 64 * 1024 * 1024
+
+#: Consecutive failures tolerated per chunk before giving up. Each retry first
+#: asks the server what it actually holds, so a retry never duplicates bytes.
+MAX_VIDEO_CHUNK_RETRIES = 2
+
+
+def validate_chunk_size(chunk_size: int) -> None:
+    if isinstance(chunk_size, bool) or not isinstance(chunk_size, int) or chunk_size <= 0:
+        raise invalid_argument("chunk_size must be a positive integer")
+
+
+def resumed_offset(header: str | None, total: int, fallback: Exception) -> int:
+    """Read an Upload-Offset the server reported, or re-raise.
+
+    A server that answers with an offset past the end of the file, or with
+    something unparseable, cannot be resumed from safely -- continuing would
+    either skip bytes or corrupt the video.
+    """
+    try:
+        offset = int(header or "")
+    except ValueError:
+        raise fallback from None
+    if offset < 0 or offset > total:
+        raise fallback
+    return offset

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/async_client.py

@@ -4,8 +4,9 @@ import asyncio
 import builtins
 import mimetypes
 import os
-from collections.abc import AsyncIterable, AsyncIterator, Mapping
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Mapping
 from contextlib import suppress
+from pathlib import Path
 from types import TracebackType
 from typing import Any, BinaryIO, TypeVar, cast
 
@@ -14,6 +15,8 @@ import httpx
 from ._shared import (
     DEFAULT_BASE_URL,
     DEFAULT_CONTENT_TYPE,
+    DEFAULT_VIDEO_CHUNK_SIZE,
+    MAX_VIDEO_CHUNK_RETRIES,
     UploadSource,
     api_url,
     image_url,
@@ -21,13 +24,27 @@ from ._shared import (
     query_string,
     read_exact,
     resolve_upload_source,
+    resumed_offset,
     segment,
     sorted_parts,
+    tus_metadata,
     upload_payload,
+    validate_chunk_size,
     validate_size,
 )
 from .errors import ArkError, error_from_response, invalid_argument, network_error, upload_error
-from .models import ArkFile, ArkFolder, ArkUsage, ClientSession, FilePage, ImageOptions
+from .models import (
+    ArkFile,
+    ArkFolder,
+    ArkStream,
+    ArkUsage,
+    ClientSession,
+    FilePage,
+    ImageOptions,
+    StreamCreation,
+    StreamPage,
+    StreamUploadTicket,
+)
 
 T = TypeVar("T")
 AsyncSource = str | os.PathLike[str] | BinaryIO | AsyncIterable[bytes]
@@ -56,6 +73,7 @@ class AsyncArk:
         self.folders = AsyncFolders(self)
         self.images = AsyncImages(self)
         self.imports = AsyncImports(self)
+        self.streams = AsyncStreams(self)
 
     async def __aenter__(self) -> AsyncArk:
         return self
@@ -426,6 +444,226 @@ class AsyncImports:
         return bool(value.get("cancelled"))
 
 
+class AsyncStreams:
+    """Asynchronous Ark Streams video control-plane APIs."""
+
+    def __init__(self, ark: AsyncArk) -> None:
+        self._ark = ark
+
+    async def create(
+        self,
+        title: str,
+        size_bytes: int,
+        *,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+    ) -> StreamCreation:
+        payload: dict[str, Any] = {"title": title, "sizeBytes": size_bytes}
+        if app_id is not None:
+            payload["appId"] = app_id
+        if collection_id is not None:
+            payload["collectionId"] = collection_id
+        value = await self._ark._request("POST", "/streams", json=payload)
+        stream = value.get("stream")
+        upload = value.get("upload")
+        if not isinstance(stream, Mapping) or not isinstance(upload, Mapping):
+            raise ArkError("INTERNAL_ERROR", "Ark returned an invalid stream creation response")
+        return StreamCreation(
+            ArkStream.from_dict(stream),
+            StreamUploadTicket(str(upload["endpoint"])),
+        )
+
+    async def import_from_url(
+        self,
+        title: str,
+        url: str,
+        *,
+        app_id: str | None = None,
+        access_token: str | None = None,
+        size_bytes: int | None = None,
+    ) -> ArkStream:
+        payload: dict[str, Any] = {"title": title, "url": url}
+        if app_id is not None:
+            payload["appId"] = app_id
+        if access_token is not None:
+            payload["accessToken"] = access_token
+        if size_bytes is not None:
+            payload["sizeBytes"] = size_bytes
+        value = await self._ark._request("POST", "/streams/fetch", json=payload)
+        return ArkStream.from_dict(value)
+
+    async def list(
+        self,
+        *,
+        app_id: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> StreamPage:
+        suffix = query_string({"appId": app_id, "limit": limit, "cursor": cursor})
+        value = await self._ark._request("GET", f"/streams{suffix}")
+        raw_streams = value.get("streams")
+        streams = tuple(
+            ArkStream.from_dict(item)
+            for item in (raw_streams if isinstance(raw_streams, list) else [])
+            if isinstance(item, Mapping)
+        )
+        next_cursor = value.get("nextCursor")
+        return StreamPage(streams, next_cursor if isinstance(next_cursor, str) else None)
+
+    async def get(self, stream_id: str, *, app_id: str | None = None) -> ArkStream:
+        suffix = query_string({"appId": app_id})
+        value = await self._ark._request("GET", f"/streams/{segment(stream_id)}{suffix}")
+        return ArkStream.from_dict(value)
+
+    async def refresh_upload_url(
+        self,
+        stream_id: str,
+        *,
+        app_id: str | None = None,
+    ) -> StreamUploadTicket:
+        suffix = query_string({"appId": app_id})
+        value = await self._ark._request(
+            "POST", f"/streams/{segment(stream_id)}/upload-url{suffix}", json={}
+        )
+        return StreamUploadTicket(str(value["endpoint"]))
+
+    async def delete(self, stream_id: str, *, app_id: str | None = None) -> None:
+        suffix = query_string({"appId": app_id})
+        await self._ark._request("DELETE", f"/streams/{segment(stream_id)}{suffix}")
+
+    async def upload(
+        self,
+        source: str | Path | BinaryIO,
+        *,
+        title: str | None = None,
+        size: int | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+        chunk_size: int = DEFAULT_VIDEO_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> ArkStream:
+        """Create a stream and upload the video, resuming across failures.
+
+        The async twin of `Streams.upload`. See that method for why this exists
+        rather than leaving TUS to the caller.
+        """
+        validate_chunk_size(chunk_size)
+        resolved = resolve_upload_source(
+            source,
+            size=size,
+            filename=filename,
+            content_type=content_type or "video/mp4",
+        )
+
+        created = await self.create(
+            title or Path(resolved.filename).stem,
+            resolved.size,
+            app_id=app_id,
+            collection_id=collection_id,
+        )
+
+        upload_url = await self._create_tus_upload(created.upload.endpoint, resolved)
+        handle = resolved.path.open("rb") if resolved.path is not None else resolved.stream
+        try:
+            await self._send_chunks(
+                upload_url, handle, resolved.size, chunk_size, on_progress
+            )
+        finally:
+            if resolved.path is not None:
+                handle.close()
+        return created.stream
+
+    async def _create_tus_upload(self, endpoint: str, resolved: UploadSource) -> str:
+        url = self._ark._url(endpoint) if endpoint.startswith("/") else endpoint
+        try:
+            response = await self._ark._client.request(
+                "POST",
+                url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                    "Upload-Length": str(resolved.size),
+                    "Upload-Metadata": (
+                        f"filename {tus_metadata(resolved.filename)},"
+                        f"filetype {tus_metadata(resolved.content_type)}"
+                    ),
+                },
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise error_from_response(response)
+
+        location = response.headers.get("location")
+        if not location:
+            raise ArkError("INTERNAL_ERROR", "Ark did not return an upload location")
+        return str(httpx.URL(url).join(location))
+
+    async def _send_chunks(
+        self,
+        upload_url: str,
+        handle: BinaryIO,
+        total: int,
+        chunk_size: int,
+        on_progress: Callable[[int, int], None] | None,
+    ) -> None:
+        offset = 0
+        retries = 0
+        while offset < total:
+            handle.seek(offset)
+            chunk = handle.read(min(chunk_size, total - offset))
+            if not chunk:
+                raise ArkError(
+                    "INVALID_ARGUMENT",
+                    "The video source ended before the declared size was reached",
+                )
+            try:
+                response = await self._ark._client.request(
+                    "PATCH",
+                    upload_url,
+                    headers={
+                        "authorization": f"Bearer {self._ark._token}",
+                        "Tus-Resumable": "1.0.0",
+                        "Upload-Offset": str(offset),
+                        "Content-Type": "application/offset+octet-stream",
+                    },
+                    content=chunk,
+                )
+                if response.is_error:
+                    raise error_from_response(response)
+                acknowledged = response.headers.get("upload-offset")
+                try:
+                    offset = max(offset + len(chunk), int(acknowledged or ""))
+                except ValueError:
+                    offset += len(chunk)
+                retries = 0
+                if on_progress is not None:
+                    on_progress(offset, total)
+            except ArkError as error:
+                if retries >= MAX_VIDEO_CHUNK_RETRIES:
+                    raise
+                retries += 1
+                offset = await self._head_offset(upload_url, total, error)
+
+    async def _head_offset(self, upload_url: str, total: int, fallback: ArkError) -> int:
+        try:
+            head = await self._ark._client.request(
+                "HEAD",
+                upload_url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                },
+            )
+        except httpx.HTTPError:
+            raise fallback from None
+        if head.is_error:
+            raise fallback
+        return resumed_offset(head.headers.get("upload-offset"), total, fallback)
+
+
 def _as_async_iterable(source: AsyncSource) -> AsyncIterator[bytes] | None:
     method = getattr(source, "__aiter__", None)
     if method is None:

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/errors.py

@@ -35,12 +35,23 @@ def error_from_response(response: httpx.Response) -> ArkError:
         body = response.json()
     except ValueError:
         body = {}
-    envelope = body.get("error", {}) if isinstance(body, dict) else {}
-    if not isinstance(envelope, dict):
-        envelope = {}
+    raw_error = body.get("error") if isinstance(body, dict) else None
+    envelope = raw_error if isinstance(raw_error, dict) else {}
+    status_codes = {
+        400: "INVALID_ARGUMENT",
+        401: "UNAUTHORIZED",
+        402: "QUOTA_EXCEEDED",
+        403: "INSUFFICIENT_SCOPE",
+        404: "NOT_FOUND",
+        429: "RATE_LIMITED",
+    }
     return ArkError(
-        str(envelope.get("code") or "INTERNAL_ERROR"),
-        str(envelope.get("message") or f"Request failed with status {response.status_code}"),
+        str(envelope.get("code") or status_codes.get(response.status_code, "INTERNAL_ERROR")),
+        str(
+            envelope.get("message")
+            or (raw_error if isinstance(raw_error, str) else None)
+            or f"Request failed with status {response.status_code}"
+        ),
         status=response.status_code,
         request_id=_optional_string(envelope.get("requestId")),
         details=envelope.get("details") if isinstance(envelope.get("details"), dict) else None,

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/models.py

@@ -96,6 +96,69 @@ class FilePage:
     next_cursor: str | None
 
 
+StreamStatus = Literal["created", "uploading", "processing", "ready", "failed"]
+
+
+@dataclass(frozen=True, slots=True)
+class ArkStream:
+    """A video managed by Ark Streams.
+
+    ``hls_url``, ``thumbnail_url`` and ``embed_url`` are None until ``status``
+    is ``"ready"``: an encode takes time, and returning a URL that 404s would be
+    worse than reporting that it is unfinished. Poll ``streams.get`` until then.
+
+    ``embed_url`` is an Ark-hosted player page -- put it straight in an iframe.
+    Playback is signed server-side per viewer, so it carries no credential.
+    """
+
+    id: str
+    title: str
+    status: StreamStatus | str
+    encode_progress: int
+    duration_seconds: int
+    width: int
+    height: int
+    size: int
+    thumbnail_url: str | None
+    hls_url: str | None
+    embed_url: str | None
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ArkStream:
+        return cls(
+            id=str(value["id"]),
+            title=str(value["title"]),
+            status=str(value.get("status") or "created"),
+            encode_progress=int(value.get("encodeProgress") or 0),
+            duration_seconds=int(value.get("durationSeconds") or 0),
+            width=int(value.get("width") or 0),
+            height=int(value.get("height") or 0),
+            size=int(value.get("size") or 0),
+            thumbnail_url=_optional_string(value.get("thumbnailUrl")),
+            hls_url=_optional_string(value.get("hlsUrl")),
+            embed_url=_optional_string(value.get("embedUrl")),
+            created_at=str(value.get("createdAt") or ""),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StreamUploadTicket:
+    endpoint: str
+
+
+@dataclass(frozen=True, slots=True)
+class StreamCreation:
+    stream: ArkStream
+    upload: StreamUploadTicket
+
+
+@dataclass(frozen=True, slots=True)
+class StreamPage:
+    streams: tuple[ArkStream, ...]
+    next_cursor: str | None
+
+
 @dataclass(frozen=True, slots=True)
 class ClientSession:
     token: str

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/src/ark_py/sync.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import builtins
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
 from contextlib import suppress
 from pathlib import Path
@@ -12,6 +12,8 @@ import httpx
 
 from ._shared import (
     DEFAULT_BASE_URL,
+    DEFAULT_VIDEO_CHUNK_SIZE,
+    MAX_VIDEO_CHUNK_RETRIES,
     UploadSource,
     api_url,
     ensure_stream_complete,
@@ -22,12 +24,26 @@ from ._shared import (
     query_string,
     read_exact,
     resolve_upload_source,
+    resumed_offset,
     segment,
     sorted_parts,
+    tus_metadata,
     upload_payload,
+    validate_chunk_size,
 )
 from .errors import ArkError, error_from_response, network_error, upload_error
-from .models import ArkFile, ArkFolder, ArkUsage, ClientSession, FilePage, ImageOptions
+from .models import (
+    ArkFile,
+    ArkFolder,
+    ArkStream,
+    ArkUsage,
+    ClientSession,
+    FilePage,
+    ImageOptions,
+    StreamCreation,
+    StreamPage,
+    StreamUploadTicket,
+)
 
 T = TypeVar("T")
 
@@ -55,6 +71,7 @@ class Ark:
         self.folders = Folders(self)
         self.images = Images(self)
         self.imports = Imports(self)
+        self.streams = Streams(self)
 
     def __enter__(self) -> Ark:
         return self
@@ -379,3 +396,233 @@ class Imports:
     def cancel(self, import_id: str) -> bool:
         value = self._ark._request("POST", f"/imports/{segment(import_id)}/cancel", json={})
         return bool(value.get("cancelled"))
+
+
+class Streams:
+    """Ark Streams video creation, import, playback metadata, and lifecycle APIs."""
+
+    def __init__(self, ark: Ark) -> None:
+        self._ark = ark
+
+    def create(
+        self,
+        title: str,
+        size_bytes: int,
+        *,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+    ) -> StreamCreation:
+        payload: dict[str, Any] = {"title": title, "sizeBytes": size_bytes}
+        if app_id is not None:
+            payload["appId"] = app_id
+        if collection_id is not None:
+            payload["collectionId"] = collection_id
+        value = self._ark._request("POST", "/streams", json=payload)
+        stream = value.get("stream")
+        upload = value.get("upload")
+        if not isinstance(stream, Mapping) or not isinstance(upload, Mapping):
+            raise ArkError("INTERNAL_ERROR", "Ark returned an invalid stream creation response")
+        return StreamCreation(
+            ArkStream.from_dict(stream),
+            StreamUploadTicket(str(upload["endpoint"])),
+        )
+
+    def import_from_url(
+        self,
+        title: str,
+        url: str,
+        *,
+        app_id: str | None = None,
+        access_token: str | None = None,
+        size_bytes: int | None = None,
+    ) -> ArkStream:
+        payload: dict[str, Any] = {"title": title, "url": url}
+        if app_id is not None:
+            payload["appId"] = app_id
+        if access_token is not None:
+            payload["accessToken"] = access_token
+        if size_bytes is not None:
+            payload["sizeBytes"] = size_bytes
+        return ArkStream.from_dict(self._ark._request("POST", "/streams/fetch", json=payload))
+
+    def list(
+        self,
+        *,
+        app_id: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> StreamPage:
+        suffix = query_string({"appId": app_id, "limit": limit, "cursor": cursor})
+        value = self._ark._request("GET", f"/streams{suffix}")
+        raw_streams = value.get("streams")
+        streams = tuple(
+            ArkStream.from_dict(item)
+            for item in (raw_streams if isinstance(raw_streams, list) else [])
+            if isinstance(item, Mapping)
+        )
+        next_cursor = value.get("nextCursor")
+        return StreamPage(streams, next_cursor if isinstance(next_cursor, str) else None)
+
+    def get(self, stream_id: str, *, app_id: str | None = None) -> ArkStream:
+        suffix = query_string({"appId": app_id})
+        return ArkStream.from_dict(
+            self._ark._request("GET", f"/streams/{segment(stream_id)}{suffix}")
+        )
+
+    def refresh_upload_url(
+        self,
+        stream_id: str,
+        *,
+        app_id: str | None = None,
+    ) -> StreamUploadTicket:
+        suffix = query_string({"appId": app_id})
+        value = self._ark._request(
+            "POST", f"/streams/{segment(stream_id)}/upload-url{suffix}", json={}
+        )
+        return StreamUploadTicket(str(value["endpoint"]))
+
+    def delete(self, stream_id: str, *, app_id: str | None = None) -> None:
+        suffix = query_string({"appId": app_id})
+        self._ark._request("DELETE", f"/streams/{segment(stream_id)}{suffix}")
+
+    def upload(
+        self,
+        source: str | Path | BinaryIO,
+        *,
+        title: str | None = None,
+        size: int | None = None,
+        filename: str | None = None,
+        content_type: str | None = None,
+        app_id: str | None = None,
+        collection_id: str | None = None,
+        chunk_size: int = DEFAULT_VIDEO_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> ArkStream:
+        """Create a stream and upload the video, resuming across failures.
+
+        `create()` only returns a ticket; the bytes still have to be sent, and
+        doing that correctly means speaking TUS. Without this a Python caller
+        had to implement the protocol themselves, which is the one part of
+        Streams they should not have to think about.
+
+        Returns the stream as it was at creation. Encoding continues afterwards,
+        so poll `get()` for `status == "ready"` before using the playback URLs.
+        """
+        validate_chunk_size(chunk_size)
+        resolved = resolve_upload_source(
+            source,
+            size=size,
+            filename=filename,
+            content_type=content_type or "video/mp4",
+        )
+
+        created = self.create(
+            title or Path(resolved.filename).stem,
+            resolved.size,
+            app_id=app_id,
+            collection_id=collection_id,
+        )
+
+        upload_url = self._create_tus_upload(created.upload.endpoint, resolved)
+        handle = resolved.path.open("rb") if resolved.path is not None else resolved.stream
+        try:
+            self._send_chunks(upload_url, handle, resolved.size, chunk_size, on_progress)
+        finally:
+            if resolved.path is not None:
+                handle.close()
+        return created.stream
+
+    def _create_tus_upload(self, endpoint: str, resolved: UploadSource) -> str:
+        """Open the TUS upload and return the URL to send chunks to."""
+        url = self._ark._url(endpoint) if endpoint.startswith("/") else endpoint
+        try:
+            response = self._ark._client.request(
+                "POST",
+                url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                    "Upload-Length": str(resolved.size),
+                    "Upload-Metadata": (
+                        f"filename {tus_metadata(resolved.filename)},"
+                        f"filetype {tus_metadata(resolved.content_type)}"
+                    ),
+                },
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
+        if response.is_error:
+            raise error_from_response(response)
+
+        location = response.headers.get("location")
+        if not location:
+            raise ArkError("INTERNAL_ERROR", "Ark did not return an upload location")
+        # The server may answer with a relative location.
+        return str(httpx.URL(url).join(location))
+
+    def _send_chunks(
+        self,
+        upload_url: str,
+        handle: BinaryIO,
+        total: int,
+        chunk_size: int,
+        on_progress: Callable[[int, int], None] | None,
+    ) -> None:
+        offset = 0
+        retries = 0
+        while offset < total:
+            handle.seek(offset)
+            chunk = handle.read(min(chunk_size, total - offset))
+            if not chunk:
+                raise ArkError(
+                    "INVALID_ARGUMENT",
+                    "The video source ended before the declared size was reached",
+                )
+            try:
+                response = self._ark._client.request(
+                    "PATCH",
+                    upload_url,
+                    headers={
+                        "authorization": f"Bearer {self._ark._token}",
+                        "Tus-Resumable": "1.0.0",
+                        "Upload-Offset": str(offset),
+                        "Content-Type": "application/offset+octet-stream",
+                    },
+                    content=chunk,
+                )
+                if response.is_error:
+                    raise error_from_response(response)
+                # Trust the server's acknowledged offset over our own arithmetic:
+                # it is the only party that knows what actually landed.
+                acknowledged = response.headers.get("upload-offset")
+                try:
+                    offset = max(offset + len(chunk), int(acknowledged or ""))
+                except ValueError:
+                    offset += len(chunk)
+                retries = 0
+                if on_progress is not None:
+                    on_progress(offset, total)
+            except ArkError as error:
+                if retries >= MAX_VIDEO_CHUNK_RETRIES:
+                    raise
+                retries += 1
+                # Ask what the server holds rather than assuming the chunk was
+                # lost -- a failure after the bytes landed would otherwise send
+                # them twice.
+                offset = self._head_offset(upload_url, total, error)
+
+    def _head_offset(self, upload_url: str, total: int, fallback: ArkError) -> int:
+        try:
+            head = self._ark._client.request(
+                "HEAD",
+                upload_url,
+                headers={
+                    "authorization": f"Bearer {self._ark._token}",
+                    "Tus-Resumable": "1.0.0",
+                },
+            )
+        except httpx.HTTPError:
+            raise fallback from None
+        if head.is_error:
+            raise fallback
+        return resumed_offset(head.headers.get("upload-offset"), total, fallback)

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/tests/test_async.py

@@ -8,6 +8,7 @@ from typing import Any
 import httpx
 import pytest
 from conftest import file_response, json_response
+from test_sync import STREAM_RESPONSE
 
 from ark_py import ArkError, AsyncArk
 
@@ -42,6 +43,35 @@ async def test_async_resources_and_default_url() -> None:
     await client.aclose()
 
 
+@pytest.mark.asyncio
+async def test_async_streams_control_plane() -> None:
+    async def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            return json_response(
+                {"stream": STREAM_RESPONSE, "upload": {"endpoint": "/streams/stream-1/upload"}},
+                201,
+            )
+        if request.url.path.endswith("/streams/fetch"):
+            return json_response(STREAM_RESPONSE, 202)
+        if request.url.path.endswith("/upload-url"):
+            return json_response({"endpoint": "/streams/stream-1/upload"})
+        if request.method == "DELETE":
+            return httpx.Response(204)
+        if request.url.path.endswith("/stream-1"):
+            return json_response(STREAM_RESPONSE)
+        return json_response({"streams": [STREAM_RESPONSE], "nextCursor": None})
+
+    client = async_client_for(handler)
+    streams = AsyncArk("token", base_url="https://ark.test", client=client).streams
+    assert (await streams.create("Launch", 42)).stream.id == "stream-1"
+    assert (await streams.import_from_url("Remote", "https://video.test/a.mp4")).size == 42
+    assert len((await streams.list(app_id="app-1")).streams) == 1
+    assert (await streams.get("stream-1")).status == "ready"
+    assert (await streams.refresh_upload_url("stream-1")).endpoint.endswith("/upload")
+    assert await streams.delete("stream-1") is None
+    await client.aclose()
+
+
 @pytest.mark.asyncio
 async def test_async_iterable_multipart_upload_is_bounded() -> None:
     data = bytes(range(10))

nerdstack_ark-1.0.4/tests/test_stream_upload.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+import pytest
+from conftest import json_response
+
+from ark_py import Ark, ArkError
+
+STREAM = {
+    "id": "stream-1",
+    "title": "clip",
+    "status": "created",
+    "encodeProgress": 0,
+    "durationSeconds": 0,
+    "width": 0,
+    "height": 0,
+    "size": 9,
+    "thumbnailUrl": None,
+    "hlsUrl": None,
+    "embedUrl": None,
+    "createdAt": "2026-09-03T00:00:00.000Z",
+}
+
+
+class TusServer:
+    """A TUS endpoint that records what it was sent.
+
+    `fail_at_offset` makes exactly one PATCH fail *after* accepting the bytes,
+    which is the case worth testing: a client that assumes a failed request
+    transferred nothing would resend those bytes and corrupt the video.
+    """
+
+    def __init__(self, total: int, *, fail_at_offset: int | None = None) -> None:
+        self.total = total
+        self.fail_at_offset = fail_at_offset
+        self.received = bytearray()
+        self.patches: list[int] = []
+        self.head_calls = 0
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            return json_response({"stream": STREAM, "upload": {"endpoint": "/streams/stream-1/upload"}})
+
+        if request.url.path == "/api/v2/streams/stream-1/upload" and request.method == "POST":
+            assert request.headers["upload-length"] == str(self.total)
+            assert "filename" in request.headers["upload-metadata"]
+            return httpx.Response(201, headers={"location": "/api/v2/streams/stream-1/upload/abc"})
+
+        if request.url.path.endswith("/upload/abc") and request.method == "HEAD":
+            self.head_calls += 1
+            return httpx.Response(200, headers={"upload-offset": str(len(self.received))})
+
+        if request.url.path.endswith("/upload/abc") and request.method == "PATCH":
+            offset = int(request.headers["upload-offset"])
+            self.patches.append(offset)
+            body = request.read()
+            # The server only accepts a write that starts where it left off.
+            assert offset == len(self.received), "client resent or skipped bytes"
+            self.received.extend(body)
+            if self.fail_at_offset is not None and offset == self.fail_at_offset:
+                self.fail_at_offset = None
+                return httpx.Response(500, json={"error": "flaky"})
+            return httpx.Response(204, headers={"upload-offset": str(len(self.received))})
+
+        raise AssertionError(f"unexpected {request.method} {request.url}")
+
+
+def client_for(server: TusServer) -> Ark:
+    return Ark(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.Client(transport=httpx.MockTransport(server.handler)),
+    )
+
+
+def test_uploads_a_file_in_chunks(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    server = TusServer(9)
+
+    stream = client_for(server).streams.upload(path, chunk_size=4)
+
+    assert stream.id == "stream-1"
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.patches == [0, 4, 8]
+
+
+def test_resumes_from_the_server_offset_after_a_failure(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    # The failure lands after the server stored bytes 4-7.
+    server = TusServer(9, fail_at_offset=4)
+
+    client_for(server).streams.upload(path, chunk_size=4)
+
+    # The whole file arrives exactly once: the retry asked where to continue
+    # rather than resending the chunk that had in fact landed.
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.head_calls == 1
+
+
+def test_reports_progress(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    seen: list[tuple[int, int]] = []
+
+    client_for(TusServer(9)).streams.upload(
+        path, chunk_size=4, on_progress=lambda done, total: seen.append((done, total))
+    )
+
+    assert seen == [(4, 9), (8, 9), (9, 9)]
+
+
+def test_derives_the_title_from_the_filename(tmp_path: Path) -> None:
+    path = tmp_path / "my-launch-video.mp4"
+    path.write_bytes(b"abc")
+    titles: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            import json as _json
+
+            titles.append(_json.loads(request.read())["title"])
+            return json_response({"stream": STREAM, "upload": {"endpoint": "/streams/stream-1/upload"}})
+        if request.method == "POST":
+            return httpx.Response(201, headers={"location": "/api/v2/streams/stream-1/upload/abc"})
+        return httpx.Response(204, headers={"upload-offset": "3"})
+
+    Ark(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.Client(transport=httpx.MockTransport(handler)),
+    ).streams.upload(path)
+
+    assert titles == ["my-launch-video"]
+
+
+def test_rejects_an_invalid_chunk_size(tmp_path: Path) -> None:
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abc")
+
+    with pytest.raises(ArkError) as excinfo:
+        client_for(TusServer(3)).streams.upload(path, chunk_size=0)
+
+    assert excinfo.value.code == "INVALID_ARGUMENT"
+
+
+@pytest.mark.asyncio
+async def test_async_upload_matches_the_sync_client(tmp_path: Path) -> None:
+    """The async client must transfer identically, not merely succeed."""
+    from ark_py import AsyncArk
+
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"abcdefghi")
+    server = TusServer(9, fail_at_offset=4)
+
+    ark = AsyncArk(
+        "token",
+        base_url="https://ark.test",
+        client=httpx.AsyncClient(transport=httpx.MockTransport(server.handler)),
+    )
+    stream = await ark.streams.upload(path, chunk_size=4)
+
+    assert stream.id == "stream-1"
+    assert bytes(server.received) == b"abcdefghi"
+    assert server.head_calls == 1

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.4}/tests/test_sync.py

@@ -13,6 +13,21 @@ from conftest import file_response, json_response
 
 from ark_py import Ark, ArkError, ImageOptions
 
+STREAM_RESPONSE = {
+    "id": "stream-1",
+    "title": "Launch",
+    "status": "ready",
+    "encodeProgress": 100,
+    "durationSeconds": 12,
+    "width": 1920,
+    "height": 1080,
+    "size": 42,
+    "thumbnailUrl": "https://cdn.test/thumb.jpg",
+    "hlsUrl": "https://cdn.test/playlist.m3u8",
+    "embedUrl": "https://player.test/embed",
+    "createdAt": "2026-09-03T00:00:00.000Z",
+}
+
 
 def client_for(handler: Any) -> httpx.Client:
     return httpx.Client(transport=httpx.MockTransport(handler))
@@ -87,6 +102,38 @@ def test_resources_models_images_and_errors() -> None:
     client.close()
 
 
+def test_streams_control_plane() -> None:
+    requests: list[tuple[str, str]] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append((request.method, str(request.url)))
+        if request.url.path.endswith("/streams") and request.method == "POST":
+            return json_response(
+                {"stream": STREAM_RESPONSE, "upload": {"endpoint": "/streams/stream-1/upload"}},
+                201,
+            )
+        if request.url.path.endswith("/streams/fetch"):
+            return json_response(STREAM_RESPONSE, 202)
+        if request.url.path.endswith("/upload-url"):
+            return json_response({"endpoint": "/streams/stream-1/upload?appId=app-1"})
+        if request.method == "DELETE":
+            return httpx.Response(204)
+        if request.url.path.endswith("/stream-1"):
+            return json_response(STREAM_RESPONSE)
+        return json_response({"streams": [STREAM_RESPONSE], "nextCursor": "next"})
+
+    client = client_for(handler)
+    streams = Ark("token", base_url="https://ark.test", client=client).streams
+    assert streams.create("Launch", 42, app_id="app-1").upload.endpoint.endswith("/upload")
+    assert streams.import_from_url("Remote", "https://video.test/a.mp4").id == "stream-1"
+    assert streams.list(app_id="app-1", limit=10).next_cursor == "next"
+    assert streams.get("stream-1", app_id="app-1").hls_url is not None
+    assert streams.refresh_upload_url("stream-1", app_id="app-1").endpoint.endswith("appId=app-1")
+    assert streams.delete("stream-1", app_id="app-1") is None
+    assert requests[2] == ("GET", "https://ark.test/api/v2/streams?appId=app-1&limit=10")
+    client.close()
+
+
 def test_single_path_upload_streams_and_completes(tmp_path: Path) -> None:
     data = b"streamed from disk"
     path = tmp_path / "photo.jpg"