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

nerdstack_ark-1.0.5/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 1.0.5
+
+### Fixed
+
+- `folders.list()` and `AsyncFolders.list()` returned an empty tuple against
+  every real workspace. `GET /api/v2/folders` returns the array under
+  `folders`, but the SDK read `data` — the key `/api/v2/files` uses. The
+  missing key was silently coerced to an empty list, so callers that resolve a
+  folder by name saw "no such folder", called `create()`, and got back
+  "A folder with this name already exists here". Nesting was unusable for the
+  same reason, since resolving `a/b/c` lists children at each level.
+
+  Both envelopes are now accepted, so an older deployment keeps working.
+
+- A folder-list body the SDK cannot parse now raises `ArkError` with code
+  `INVALID_RESPONSE` instead of being reported as an empty list. The silent
+  empty result is what made the bug above expensive to diagnose: `list()` and
+  `create()` reported opposite things and neither raised.
+
+- `ArkError` now exposes `message`. It was documented and passed to
+  `Exception.__init__`, but never stored, so `error.message` raised
+  `AttributeError` inside callers' own error handlers. `str(error)` was the
+  only thing that worked.
+
+- `ark_py.__version__` read `1.0.0` while the package was on 1.0.4. It is now
+  read from the installed distribution metadata, so it cannot drift again.
+
+### Internal
+
+- Folder parsing moved to `_shared.parse_folder_list`. The identical code was
+  duplicated in the sync and async clients, which is why one bug needed fixing
+  in two places, and why the async client had no folder test at all.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.3
+Version: 1.0.5
 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
@@ -132,9 +132,21 @@ session = ark.create_client_session(ttl_seconds=900)
 
 ## 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.
+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)
@@ -147,9 +159,10 @@ 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`.
+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
 

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

@@ -89,9 +89,21 @@ session = ark.create_client_session(ttl_seconds=900)
 
 ## 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.
+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)
@@ -104,9 +116,10 @@ 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`.
+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
 

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

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

@@ -1,5 +1,8 @@
 """Official Python SDK for Ark storage."""
 
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
 from .async_client import AsyncArk
 from .errors import ArkError
 from .models import (
@@ -38,4 +41,10 @@ __all__ = [
     "create_s3_client",
 ]
 
-__version__ = "1.0.0"
+# Read from the installed distribution rather than hard-coded. This said
+# "1.0.0" while pyproject.toml said 1.0.4, so anyone reporting a bug with
+# ark_py.__version__ quoted a version that had not shipped in months.
+try:  # pragma: no cover - depends on install state, not on logic
+    __version__ = _version("nerdstack-ark")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0.dev0"

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.5}/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
@@ -8,7 +9,7 @@ from pathlib import Path
 from typing import Any, BinaryIO
 from urllib.parse import quote, urlencode
 
-from .errors import invalid_argument
+from .errors import invalid_argument, invalid_response
 from .models import ClientSession, ImageOptions
 
 DEFAULT_BASE_URL = "https://ark.nerdstackgrp.com"
@@ -41,6 +42,34 @@ def image_url(base_url: str, version: str, asset_id: str, options: ImageOptions)
     return api_url(base_url, version, f"/assets/{segment(asset_id)}/image{suffix}")
 
 
+def parse_folder_list(value: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    """Pull the folder array out of a GET /folders body.
+
+    The two list endpoints do not share an envelope: /files returns
+    ``{"data": [...], "nextCursor": ...}`` while /folders returns
+    ``{"folders": [...], "pagination": {...}}``. The SDK read ``data`` for
+    both, so folders.list() returned nothing against every real workspace --
+    silently, because a missing key was coerced to an empty list.
+
+    Both keys are accepted so an older deployment keeps working, and anything
+    else raises rather than reporting an empty folder list that the caller
+    cannot distinguish from a real one.
+
+    Lives here rather than in each client because the identical parsing was
+    duplicated in sync.py and async_client.py -- which is why one bug needed
+    fixing in two places.
+    """
+    for key in ("folders", "data"):
+        raw = value.get(key)
+        if isinstance(raw, list):
+            return [item for item in raw if isinstance(item, Mapping)]
+
+    raise invalid_response(
+        "The folder list response was not in a recognised format. "
+        f"Expected a 'folders' array, got keys: {sorted(map(str, value.keys())) or 'none'}."
+    )
+
+
 def parse_client_session(value: Mapping[str, Any]) -> ClientSession:
     raw_scopes = value.get("scopes")
     scopes = tuple(str(scope) for scope in raw_scopes) if isinstance(raw_scopes, list) else ()
@@ -180,3 +209,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.3 → nerdstack_ark-1.0.5}/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,16 +15,22 @@ import httpx
 from ._shared import (
     DEFAULT_BASE_URL,
     DEFAULT_CONTENT_TYPE,
+    DEFAULT_VIDEO_CHUNK_SIZE,
+    MAX_VIDEO_CHUNK_RETRIES,
     UploadSource,
     api_url,
     image_url,
     parse_client_session,
+    parse_folder_list,
     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
@@ -375,12 +382,7 @@ class AsyncFolders:
             "GET",
             f"/folders{query_string({'parentId': parent_id})}",
         )
-        raw_data = value.get("data")
-        return tuple(
-            ArkFolder.from_dict(item)
-            for item in (raw_data if isinstance(raw_data, list) else [])
-            if isinstance(item, Mapping)
-        )
+        return tuple(ArkFolder.from_dict(item) for item in parse_folder_list(value))
 
     async def create(self, name: str, *, parent_id: str | None = None) -> ArkFolder:
         payload: dict[str, Any] = {"name": name}
@@ -525,6 +527,138 @@ class AsyncStreams:
         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)

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.5}/src/ark_py/errors.py

@@ -19,6 +19,11 @@ class ArkError(Exception):
     ) -> None:
         super().__init__(message)
         self.code = code
+        # Kept as an attribute, not just handed to Exception. The README
+        # documents `error.message`, and only `str(error)` actually worked --
+        # so every caller following the docs hit an AttributeError inside
+        # their own error handler, which is the worst possible place for one.
+        self.message = message
         self.status = status
         self.request_id = request_id
         self.details = details
@@ -83,5 +88,17 @@ def invalid_argument(message: str) -> ArkError:
     return ArkError("INVALID_ARGUMENT", message)
 
 
+def invalid_response(message: str) -> ArkError:
+    """A 2xx body the SDK could not make sense of.
+
+    Coercing an unrecognised shape to an empty list is what turned a one-line
+    parsing bug into a workflow that could never succeed: `list()` reported no
+    folders, `create()` then refused because the folder was already there, and
+    nothing anywhere raised. Failing loudly here means the next such mismatch
+    is a stack trace pointing at the response, not a silent wrong answer.
+    """
+    return ArkError("INVALID_RESPONSE", message)
+
+
 def _optional_string(value: object) -> str | None:
     return value if isinstance(value, str) else None

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.5}/src/ark_py/models.py

@@ -101,7 +101,15 @@ 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."""
+    """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

{nerdstack_ark-1.0.3 → nerdstack_ark-1.0.5}/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,
@@ -19,12 +21,16 @@ from ._shared import (
     iter_exact,
     iter_file_range,
     parse_client_session,
+    parse_folder_list,
     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 (
@@ -334,12 +340,7 @@ 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 (raw_data if isinstance(raw_data, list) else [])
-            if isinstance(item, Mapping)
-        )
+        return tuple(ArkFolder.from_dict(item) for item in parse_folder_list(value))
 
     def create(self, name: str, *, parent_id: str | None = None) -> ArkFolder:
         payload: dict[str, Any] = {"name": name}
@@ -479,3 +480,145 @@ class Streams:
     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.3 → nerdstack_ark-1.0.5}/tests/test_async.py

@@ -199,3 +199,68 @@ async def test_async_upload_requires_stream_metadata() -> None:
     with pytest.raises(ArkError, match="filename is required"):
         await ark.files.upload(source(), size=4)
     await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_reads_the_api_envelope() -> None:
+    """The async client had no folder coverage at all, which is why it carried
+    the same 'data' vs 'folders' bug as the sync client and nothing caught it.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response(
+            {
+                "folders": [
+                    {"id": "folder-1", "name": "Media", "parentId": None},
+                    {"id": "folder-2", "name": "Docs", "parentId": "folder-1"},
+                ],
+                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
+            }
+        )
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    folders = await ark.folders.list()
+    assert [folder.name for folder in folders] == ["Media", "Docs"]
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_still_accepts_a_data_envelope() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"data": [{"id": "f1", "name": "Legacy", "parentId": None}]})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    assert [folder.name for folder in await ark.folders.list()] == ["Legacy"]
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_rejects_an_unrecognised_body() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"unexpected": []})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    with pytest.raises(ArkError) as caught:
+        await ark.folders.list()
+    assert caught.value.code == "INVALID_RESPONSE"
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_async_folders_list_passes_parent_id_through() -> None:
+    """Nested resolution walks children level by level, so parentId has to
+    reach the query string for anything below the root to be listable."""
+    urls: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        urls.append(str(request.url))
+        return json_response({"folders": [], "pagination": {"total": 0}})
+
+    client = async_client_for(handler)
+    ark = AsyncArk("token", client=client)
+    await ark.folders.list(parent_id="folder-1")
+    assert "parentId=folder-1" in urls[0]
+    await client.aclose()

nerdstack_ark-1.0.5/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.3 → nerdstack_ark-1.0.5}/tests/test_sync.py

@@ -55,7 +55,16 @@ def test_resources_models_images_and_errors() -> None:
         if request.url.path.endswith("/files"):
             return json_response({"data": [file_response(4)], "nextCursor": "next"})
         if request.url.path.endswith("/folders"):
-            return json_response({"data": [{"id": "folder-1", "name": "Media", "parentId": None}]})
+            # The envelope the API actually sends. This mock previously
+            # returned {"data": ...}, matching the SDK's mistaken expectation
+            # rather than the server, so it passed while every real call
+            # returned nothing.
+            return json_response(
+                {
+                    "folders": [{"id": "folder-1", "name": "Media", "parentId": None}],
+                    "pagination": {"page": 1, "limit": 50, "total": 1, "pages": 1},
+                }
+            )
         if request.url.path.endswith("/usage"):
             return json_response(
                 {
@@ -284,3 +293,82 @@ 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_the_shape_the_api_actually_returns() -> None:
+    """GET /v2/folders returns {"folders": [...], "pagination": {...}}.
+
+    The SDK read "data" -- the key /v2/files uses -- so this returned an empty
+    tuple against every real workspace. Nothing raised: the parser's
+    isinstance guard turned the missing key into [], so callers that resolve a
+    folder by name saw "no such folder", called create(), and got back "a
+    folder with this name already exists". That contradiction is what made the
+    bug expensive to diagnose, and it shipped because the test mock returned
+    the same wrong shape the code expected.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response(
+            {
+                "folders": [
+                    {"id": "folder-1", "name": "Media", "parentId": None},
+                    {"id": "folder-2", "name": "Docs", "parentId": None},
+                ],
+                "pagination": {"page": 1, "limit": 50, "total": 2, "pages": 1},
+            }
+        )
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    folders = ark.folders.list()
+    assert [folder.name for folder in folders] == ["Media", "Docs"]
+    client.close()
+
+
+def test_folders_list_still_accepts_a_data_envelope() -> None:
+    """A deployment that has not been updated must keep working."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"data": [{"id": "f1", "name": "Legacy", "parentId": None}]})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    assert [folder.name for folder in ark.folders.list()] == ["Legacy"]
+    client.close()
+
+
+def test_folders_list_rejects_a_body_it_does_not_understand() -> None:
+    """An unrecognised body must not be silently reported as "no folders".
+
+    Returning () for a response the SDK failed to parse is what turned a
+    parsing bug into a workflow that could never succeed.
+    """
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"unexpected": []})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    with pytest.raises(ArkError) as caught:
+        ark.folders.list()
+    assert caught.value.code == "INVALID_RESPONSE"
+    client.close()
+
+
+def test_folders_list_distinguishes_empty_from_unparseable() -> None:
+    """An genuinely empty folder list is still an empty tuple, not an error."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return json_response({"folders": [], "pagination": {"total": 0}})
+
+    client = client_for(handler)
+    ark = Ark("token", client=client)
+    assert ark.folders.list() == ()
+    client.close()
+
+
+def test_ark_error_exposes_message() -> None:
+    """The README documents `message`; only `str(error)` actually worked."""
+    error = ArkError("NOT_FOUND", "missing", status=404)
+    assert error.message == "missing"
+    assert str(error) == "missing"