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

nerdstack_ark-1.0.6/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 1.0.5
+
+### Added
+
+- `ArkStream.hls_expires_at` reports when `hls_url` and `thumbnail_url` stop
+  working, so a caller can refresh before playback breaks instead of guessing a
+  lifetime. Absent on older deployments, where it parses as `None`.
+
+### Changed
+
+- Documented that `hls_url` and `thumbnail_url` are signed and expire within
+  the hour, and must not be stored. `ArkFile.url` is a permanent CDN path, and
+  the identical field names made the opposite behaviour easy to miss: storing a
+  playback URL yields a link that works in testing and is dead when a user
+  opens it. Persist `id` and resolve playback on demand, or use `embed_url`,
+  which carries no credential and does not expire.
+
+### 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.4 → nerdstack_ark-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nerdstack-ark
-Version: 1.0.4
+Version: 1.0.6
 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

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

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

@@ -9,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"
@@ -42,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 ()

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

@@ -21,6 +21,7 @@ from ._shared import (
     api_url,
     image_url,
     parse_client_session,
+    parse_folder_list,
     query_string,
     read_exact,
     resolve_upload_source,
@@ -381,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}

nerdstack_ark-1.0.6/src/ark_py/errors.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class ArkError(Exception):
+    """A normalized Ark REST or upload error."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int | None = None,
+        request_id: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> 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
+
+    @property
+    def retryable(self) -> bool:
+        # BLOCKED_BY_EDGE is retryable: the request never reached Ark, and a
+        # challenge can clear on a retry or once the block is lifted.
+        return self.code in {"NETWORK_ERROR", "RATE_LIMITED", "BLOCKED_BY_EDGE"} or (
+            self.status is not None and self.status >= 500
+        )
+
+
+def _is_edge_block(response: httpx.Response, parsed: bool) -> bool:
+    """Whether a failure came from something in front of Ark rather than Ark.
+
+    The Ark API answers every request -- success or error -- with JSON, so an
+    HTML body on an error response cannot have come from Ark. In practice it is
+    a CDN or WAF challenge page: server-side SDK calls originate from
+    data-centre IP ranges, which bot protection scores as automated traffic.
+
+    Detected by content type rather than by matching challenge text, so this
+    holds for any interposed proxy and not just one vendor's wording.
+    """
+    if parsed:
+        return False
+    if response.status_code not in {403, 503, 429}:
+        return False
+    return "text/html" in response.headers.get("content-type", "")
+
+
+def error_from_response(response: httpx.Response) -> ArkError:
+    parsed = True
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+        parsed = False
+
+    # Reported before the status mapping below, which would otherwise call this
+    # INSUFFICIENT_SCOPE and send the developer to audit a token that is fine.
+    if _is_edge_block(response, parsed):
+        ray = response.headers.get("cf-ray")
+        return ArkError(
+            "BLOCKED_BY_EDGE",
+            "The request was blocked by a network in front of Ark and never reached it. "
+            "This usually means bot protection challenged the call because it came from a "
+            "data-centre IP, which is where server-side code runs. "
+            "The site owner can allow it by exempting the API path from the challenge."
+            + (f" Reference: cf-ray {ray}." if ray else ""),
+            status=response.status_code,
+            request_id=ray,
+            details={"cfRay": ray} if ray else None,
+        )
+
+    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 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,
+    )
+
+
+def network_error(error: httpx.HTTPError) -> ArkError:
+    return ArkError("NETWORK_ERROR", str(error) or "Network request failed")
+
+
+def upload_error(status: int, *, part_number: int | None = None) -> ArkError:
+    if status in {401, 403}:
+        return ArkError(
+            "UPLOAD_EXPIRED",
+            "The upload authorization expired before the transfer finished. Please retry.",
+            status=status,
+        )
+    if status == 413:
+        return ArkError(
+            "FILE_TOO_LARGE",
+            "The file is larger than this upload allows.",
+            status=status,
+        )
+    label = f"part {part_number} " if part_number is not None else ""
+    return ArkError("UPLOAD_FAILED", f"Upload {label}failed with status {status}", status=status)
+
+
+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.4 → nerdstack_ark-1.0.6}/src/ark_py/models.py

@@ -108,7 +108,15 @@ class ArkStream:
     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.
+    Playback is signed server-side per viewer, so it carries no credential, and
+    it does not expire. It is the one playback value that is safe to store.
+
+    **Do not store ``hls_url`` or ``thumbnail_url``.** Unlike ``ArkFile.url``,
+    which is a permanent CDN path, both are signed and expire within the hour
+    (``hls_expires_at`` says when). Persist ``id`` instead and call
+    ``streams.get(id)`` when you are about to play; treat them the way you
+    would a presigned URL. Writing one into a database or an email produces a
+    link that works in testing and is dead when a user opens it.
     """
 
     id: str
@@ -121,6 +129,9 @@ class ArkStream:
     size: int
     thumbnail_url: str | None
     hls_url: str | None
+    #: When ``hls_url``/``thumbnail_url`` stop working (ISO-8601), or None when
+    #: the library serves unsigned URLs that never expire.
+    hls_expires_at: str | None
     embed_url: str | None
     created_at: str
 
@@ -137,6 +148,7 @@ class ArkStream:
             size=int(value.get("size") or 0),
             thumbnail_url=_optional_string(value.get("thumbnailUrl")),
             hls_url=_optional_string(value.get("hlsUrl")),
+            hls_expires_at=_optional_string(value.get("hlsExpiresAt")),
             embed_url=_optional_string(value.get("embedUrl")),
             created_at=str(value.get("createdAt") or ""),
         )

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

@@ -21,6 +21,7 @@ from ._shared import (
     iter_exact,
     iter_file_range,
     parse_client_session,
+    parse_folder_list,
     query_string,
     read_exact,
     resolve_upload_source,
@@ -339,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}

{nerdstack_ark-1.0.4 → nerdstack_ark-1.0.6}/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.6/tests/test_edge_block.py

@@ -0,0 +1,62 @@
+"""A challenge page from a CDN in front of Ark must not read as a token problem.
+
+Regression test for a real incident: a customer's Netlify functions were
+challenged by Cloudflare bot protection, and the SDK reported the 403 as
+INSUFFICIENT_SCOPE. Their developer spent hours auditing token scopes for a
+request that never reached Ark at all.
+"""
+
+import httpx
+
+from ark_py.errors import error_from_response
+
+CHALLENGE_BODY = "<!DOCTYPE html><html><head><title>Just a moment...</title></head></html>"
+
+
+def _response(status, body, content_type, headers=None):
+    return httpx.Response(
+        status,
+        content=body,
+        headers={"content-type": content_type, **(headers or {})},
+    )
+
+
+def test_html_challenge_is_reported_as_an_edge_block():
+    error = error_from_response(
+        _response(403, CHALLENGE_BODY, "text/html; charset=UTF-8", {"cf-ray": "a376f9d70bd71709-CMH"})
+    )
+    assert error.code == "BLOCKED_BY_EDGE"
+    assert error.status == 403
+    # The ray id is the only handle on the block in the Cloudflare event log,
+    # so it has to survive into the error rather than be discarded.
+    assert error.details == {"cfRay": "a376f9d70bd71709-CMH"}
+    assert "cf-ray a376f9d70bd71709-CMH" in error.message
+
+
+def test_edge_block_is_retryable():
+    error = error_from_response(_response(403, CHALLENGE_BODY, "text/html"))
+    assert error.retryable is True
+
+
+def test_a_genuine_scope_failure_is_untouched():
+    body = '{"error": {"code": "INSUFFICIENT_SCOPE", "message": "Token lacks scope"}}'
+    error = error_from_response(_response(403, body, "application/json"))
+    assert error.code == "INSUFFICIENT_SCOPE"
+    assert error.retryable is False
+
+
+def test_non_html_403_keeps_the_status_mapping():
+    error = error_from_response(_response(403, "nope", "text/plain"))
+    assert error.code == "INSUFFICIENT_SCOPE"
+
+
+def test_html_on_an_unrelated_status_is_not_an_edge_block():
+    # A 500 HTML page is an origin fault, not a challenge; calling it an edge
+    # block would point the developer at Cloudflare for an Ark bug.
+    error = error_from_response(_response(500, "<html>oops</html>", "text/html"))
+    assert error.code == "INTERNAL_ERROR"
+
+
+def test_html_503_is_an_edge_block():
+    error = error_from_response(_response(503, CHALLENGE_BODY, "text/html"))
+    assert error.code == "BLOCKED_BY_EDGE"

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

@@ -24,6 +24,7 @@ STREAM_RESPONSE = {
     "size": 42,
     "thumbnailUrl": "https://cdn.test/thumb.jpg",
     "hlsUrl": "https://cdn.test/playlist.m3u8",
+    "hlsExpiresAt": "2026-09-03T01:00:00.000Z",
     "embedUrl": "https://player.test/embed",
     "createdAt": "2026-09-03T00:00:00.000Z",
 }
@@ -55,7 +56,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(
                 {
@@ -127,7 +137,11 @@ def test_streams_control_plane() -> None:
     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
+    fetched = streams.get("stream-1", app_id="app-1")
+    assert fetched.hls_url is not None
+    # Playback URLs are signed and short-lived; the expiry has to survive
+    # deserialization or a caller has no way to refresh before it lapses.
+    assert fetched.hls_expires_at == "2026-09-03T01:00:00.000Z"
     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")
@@ -284,3 +298,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"

nerdstack_ark-1.0.4/src/ark_py/errors.py

@@ -1,87 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-import httpx
-
-
-class ArkError(Exception):
-    """A normalized Ark REST or upload error."""
-
-    def __init__(
-        self,
-        code: str,
-        message: str,
-        *,
-        status: int | None = None,
-        request_id: str | None = None,
-        details: dict[str, Any] | None = None,
-    ) -> None:
-        super().__init__(message)
-        self.code = code
-        self.status = status
-        self.request_id = request_id
-        self.details = details
-
-    @property
-    def retryable(self) -> bool:
-        return self.code in {"NETWORK_ERROR", "RATE_LIMITED"} or (
-            self.status is not None and self.status >= 500
-        )
-
-
-def error_from_response(response: httpx.Response) -> ArkError:
-    try:
-        body = response.json()
-    except ValueError:
-        body = {}
-    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 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,
-    )
-
-
-def network_error(error: httpx.HTTPError) -> ArkError:
-    return ArkError("NETWORK_ERROR", str(error) or "Network request failed")
-
-
-def upload_error(status: int, *, part_number: int | None = None) -> ArkError:
-    if status in {401, 403}:
-        return ArkError(
-            "UPLOAD_EXPIRED",
-            "The upload authorization expired before the transfer finished. Please retry.",
-            status=status,
-        )
-    if status == 413:
-        return ArkError(
-            "FILE_TOO_LARGE",
-            "The file is larger than this upload allows.",
-            status=status,
-        )
-    label = f"part {part_number} " if part_number is not None else ""
-    return ArkError("UPLOAD_FAILED", f"Upload {label}failed with status {status}", status=status)
-
-
-def invalid_argument(message: str) -> ArkError:
-    return ArkError("INVALID_ARGUMENT", message)
-
-
-def _optional_string(value: object) -> str | None:
-    return value if isinstance(value, str) else None