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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.2
+Version: 1.0.3
 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,27 @@ 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 the Ark Streams control
+plane. Creating a video returns a TUS endpoint for the client that owns the
+video bytes. A remote import is fetched directly by Ark's video provider.
+
+```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. Poll `get` while a video
+is uploading or encoding; `hls_url` and `embed_url` are populated when its
+status becomes `ready`.
+
 ## S3-compatible access
 
 ```python

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

@@ -87,6 +87,27 @@ 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 the Ark Streams control
+plane. Creating a video returns a TUS endpoint for the client that owns the
+video bytes. A remote import is fetched directly by Ark's video provider.
+
+```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. Poll `get` while a video
+is uploading or encoding; `hls_url` and `embed_url` are populated when its
+status becomes `ready`.
+
 ## S3-compatible access
 
 ```python

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.2"
+version = "1.0.3"
 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.3}/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.3}/src/ark_py/async_client.py

@@ -27,7 +27,18 @@ from ._shared import (
     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 +67,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 +438,94 @@ 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}")
+
+
 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.3}/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.3}/src/ark_py/models.py

@@ -96,6 +96,61 @@ 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. Playback URLs are None until it is ready."""
+
+    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.3}/src/ark_py/sync.py

@@ -27,7 +27,18 @@ from ._shared import (
     upload_payload,
 )
 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 +66,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 +391,91 @@ 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}")

{nerdstack_ark-1.0.2 → nerdstack_ark-1.0.3}/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.2 → nerdstack_ark-1.0.3}/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"