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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.1
+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.1 → 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.1 → nerdstack_ark-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nerdstack-ark"
-version = "1.0.1"
+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.1 → 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,13 +24,18 @@ __all__ = [
     "ArkError",
     "ArkFile",
     "ArkFolder",
+    "ArkStream",
     "ArkUsage",
     "AsyncArk",
     "ClientSession",
     "FilePage",
     "ImageOptions",
     "StorageUsage",
+    "StreamCreation",
+    "StreamPage",
+    "StreamStatus",
+    "StreamUploadTicket",
     "create_s3_client",
 ]
 
-__version__ = "1.0.1"
+__version__ = "1.0.0"

{nerdstack_ark-1.0.1 → nerdstack_ark-1.0.3}/src/ark_py/_shared.py

@@ -180,42 +180,3 @@ def sorted_parts(parts: Iterable[dict[str, object]]) -> list[dict[str, object]]:
         return value
 
     return sorted(parts, key=part_number)
-
-
-def folders_payload(value: Mapping[str, Any]) -> list[Any]:
-    """Read a folder list under either key Ark may return it as.
-
-    The public API documents `folders`, and that is the handler that actually
-    serves `/v2/folders`; the developer-API handler for the same path returns
-    `data`. Reading only `data` meant this call silently returned zero folders
-    against a perfectly valid response -- worse than an error, because nothing
-    surfaced. Both keys are accepted so the SDK works whichever answers.
-    """
-    for key in ("folders", "data"):
-        candidate = value.get(key)
-        if isinstance(candidate, list):
-            return candidate
-    return []
-
-
-MAX_REQUEST_ATTEMPTS = 3
-RETRY_BASE_DELAY_SECONDS = 0.5
-
-
-def is_retryable_status(status: int) -> bool:
-    """Only these are worth retrying; auth and validation failures are not."""
-    return status == 429 or status >= 500
-
-
-def retry_delay_seconds(attempt: int) -> float:
-    """Exponential backoff with full jitter.
-
-    Jitter matters: without it every client that failed at the same moment
-    retries at the same moment and re-creates the overload that caused the
-    failure. Mirrors the TypeScript client so both SDKs behave alike under
-    load.
-    """
-    import random
-
-    ceiling = min(RETRY_BASE_DELAY_SECONDS * (2 ** (attempt - 1)), 30.0)
-    return random.random() * ceiling

{nerdstack_ark-1.0.1 → nerdstack_ark-1.0.3}/src/ark_py/async_client.py

@@ -15,11 +15,7 @@ from ._shared import (
     DEFAULT_BASE_URL,
     DEFAULT_CONTENT_TYPE,
     UploadSource,
-    MAX_REQUEST_ATTEMPTS,
     api_url,
-    folders_payload,
-    is_retryable_status,
-    retry_delay_seconds,
     image_url,
     parse_client_session,
     query_string,
@@ -31,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]
@@ -60,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
@@ -105,28 +113,15 @@ class AsyncArk:
         *,
         json: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
-        # See the sync client: retried with backoff so a transient failure on a
-        # large upload does not surface as an error the caller must retry.
-        response = None
-        for attempt in range(1, MAX_REQUEST_ATTEMPTS + 1):
-            try:
-                response = await self._client.request(
-                    method,
-                    self._url(path),
-                    headers={"authorization": f"Bearer {self._token}"},
-                    json=dict(json) if json is not None else None,
-                )
-            except httpx.HTTPError as error:
-                if attempt == MAX_REQUEST_ATTEMPTS:
-                    raise network_error(error) from error
-                await asyncio.sleep(retry_delay_seconds(attempt))
-                continue
-            if not is_retryable_status(response.status_code):
-                break
-            if attempt == MAX_REQUEST_ATTEMPTS:
-                break
-            await asyncio.sleep(retry_delay_seconds(attempt))
-        assert response is not None
+        try:
+            response = await self._client.request(
+                method,
+                self._url(path),
+                headers={"authorization": f"Bearer {self._token}"},
+                json=dict(json) if json is not None else None,
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
         if response.is_error:
             raise error_from_response(response)
         if response.status_code == 204:
@@ -380,9 +375,10 @@ class AsyncFolders:
             "GET",
             f"/folders{query_string({'parentId': parent_id})}",
         )
+        raw_data = value.get("data")
         return tuple(
             ArkFolder.from_dict(item)
-            for item in folders_payload(value)
+            for item in (raw_data if isinstance(raw_data, list) else [])
             if isinstance(item, Mapping)
         )
 
@@ -442,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.1 → 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.1 → nerdstack_ark-1.0.3}/src/ark_py/models.py

@@ -15,7 +15,15 @@ class ArkFile:
     folder_id: str | None
     status: str
     checksum: str | None
+    #: Permanent, unsigned CDN delivery URL. Safe to store; it does not expire.
+    #: Use this value as-is -- never build a URL from the id or name, and never
+    #: append a query parameter to reach a variant. ``thumbnail_url`` is the
+    #: thumbnail.
     url: str
+    #: Permanent CDN URL for the generated thumbnail, or None if there is none.
+    thumbnail_url: str | None
+    #: Permanent CDN URL for the compressed variant, or None if there is none.
+    compressed_url: str | None
     created_at: str | None
 
     @classmethod
@@ -30,6 +38,8 @@ class ArkFile:
             status=str(value.get("status") or "available"),
             checksum=_optional_string(value.get("checksum")),
             url=str(value.get("url") or ""),
+            thumbnail_url=_optional_string(value.get("thumbnailUrl")),
+            compressed_url=_optional_string(value.get("compressedUrl")),
             created_at=_optional_string(value.get("createdAt")),
         )
 
@@ -86,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.1 → nerdstack_ark-1.0.3}/src/ark_py/sync.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import builtins
-import time
 from collections.abc import Mapping
 from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
 from contextlib import suppress
@@ -15,11 +14,7 @@ from ._shared import (
     DEFAULT_BASE_URL,
     UploadSource,
     api_url,
-    MAX_REQUEST_ATTEMPTS,
     ensure_stream_complete,
-    folders_payload,
-    is_retryable_status,
-    retry_delay_seconds,
     image_url,
     iter_exact,
     iter_file_range,
@@ -32,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")
 
@@ -60,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
@@ -105,32 +112,15 @@ class Ark:
         *,
         json: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
-        # Retried with backoff, matching the TypeScript client. A transient
-        # network failure on a multi-megabyte upload otherwise surfaced as a
-        # bare NETWORK_ERROR that succeeded on the caller's own retry -- work
-        # every caller had to reimplement.
-        response = None
-        last_error: Exception | None = None
-        for attempt in range(1, MAX_REQUEST_ATTEMPTS + 1):
-            try:
-                response = self._client.request(
-                    method,
-                    self._url(path),
-                    headers={"authorization": f"Bearer {self._token}"},
-                    json=dict(json) if json is not None else None,
-                )
-            except httpx.HTTPError as error:
-                last_error = error
-                if attempt == MAX_REQUEST_ATTEMPTS:
-                    raise network_error(error) from error
-                time.sleep(retry_delay_seconds(attempt))
-                continue
-            if not is_retryable_status(response.status_code):
-                break
-            if attempt == MAX_REQUEST_ATTEMPTS:
-                break
-            time.sleep(retry_delay_seconds(attempt))
-        assert response is not None
+        try:
+            response = self._client.request(
+                method,
+                self._url(path),
+                headers={"authorization": f"Bearer {self._token}"},
+                json=dict(json) if json is not None else None,
+            )
+        except httpx.HTTPError as error:
+            raise network_error(error) from error
         if response.is_error:
             raise error_from_response(response)
         if response.status_code == 204:
@@ -344,9 +334,10 @@ class Folders:
 
     def list(self, *, parent_id: str | None = None) -> tuple[ArkFolder, ...]:
         value = self._ark._request("GET", f"/folders{query_string({'parentId': parent_id})}")
+        raw_data = value.get("data")
         return tuple(
             ArkFolder.from_dict(item)
-            for item in folders_payload(value)
+            for item in (raw_data if isinstance(raw_data, list) else [])
             if isinstance(item, Mapping)
         )
 
@@ -400,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.1 → 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.1 → 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"
@@ -237,96 +284,3 @@ def test_non_seekable_stream_requires_size_and_filename() -> None:
     with pytest.raises(ArkError, match="filename is required"):
         ark.files.upload(NonSeekable(b"data"), size=4)
     ark._client.close()
-
-
-def test_folders_list_reads_documented_folders_key() -> None:
-    """The shape production returns.
-
-    Reading only `data` made this return an empty tuple against a perfectly
-    valid response -- silently, which is worse than raising: a caller sees an
-    account with no folders rather than an error they can act on.
-    """
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        return json_response(
-            {
-                "folders": [
-                    {"id": "f1", "name": "Products", "parentId": None},
-                    {"id": "f2", "name": "Docs", "parentId": None},
-                ],
-                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
-            }
-        )
-
-    ark = Ark("token", client=client_for(handler))
-    folders = ark.folders.list()
-    assert len(folders) == 2
-    assert folders[0].name == "Products"
-    assert folders[1].id == "f2"
-
-
-def test_folders_list_still_reads_data_key() -> None:
-    """The developer-API handler for the same path. Both must work."""
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        return json_response({"data": [{"id": "f9", "name": "Only", "parentId": None}]})
-
-    ark = Ark("token", client=client_for(handler))
-    folders = ark.folders.list()
-    assert len(folders) == 1
-    assert folders[0].id == "f9"
-
-
-def test_folders_list_tolerates_an_unexpected_shape() -> None:
-    def handler(request: httpx.Request) -> httpx.Response:
-        return json_response({"unexpected": True})
-
-    ark = Ark("token", client=client_for(handler))
-    assert ark.folders.list() == ()
-
-
-def test_request_retries_a_transient_server_error() -> None:
-    """A 500 is retried; the caller sees the eventual success.
-
-    A transient network failure on a multi-megabyte upload previously surfaced
-    as a bare NETWORK_ERROR that succeeded on the caller's own retry -- work
-    every caller had to reimplement, and which the TypeScript client already
-    did.
-    """
-    attempts = {"n": 0}
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        attempts["n"] += 1
-        if attempts["n"] < 3:
-            return json_response({"error": {"message": "boom"}}, 500)
-        return json_response(
-            {
-                "storage": {
-                    "usedBytes": 1,
-                    "pendingBytes": 0,
-                    "limitBytes": 2,
-                    "availableBytes": 1,
-                },
-                "tier": "free",
-                "status": "active",
-            }
-        )
-
-    ark = Ark("token", client=client_for(handler))
-    usage = ark.usage()
-    assert attempts["n"] == 3
-    assert usage.storage.used_bytes == 1
-
-
-def test_request_does_not_retry_a_client_error() -> None:
-    """Auth and validation failures are final: retrying them only wastes time."""
-    attempts = {"n": 0}
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        attempts["n"] += 1
-        return json_response({"error": {"code": "UNAUTHORIZED"}}, 401)
-
-    ark = Ark("token", client=client_for(handler))
-    with pytest.raises(ArkError):
-        ark.usage()
-    assert attempts["n"] == 1