wherobots-python-sdk 0.5.0__tar.gz → 0.6.0__tar.gz

{wherobots_python_sdk-0.5.0/wherobots_python_sdk.egg-info → wherobots_python_sdk-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -13,22 +13,21 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests>=2.33.0
-Requires-Dist: boto3>=1.34.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: boto3>=1.43.108
 Dynamic: license-file
 
 # Wherobots Python SDK
 
 [![CI](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 [![Version](https://img.shields.io/pypi/v/wherobots-python-sdk?color=orange)](https://pypi.org/project/wherobots-python-sdk/)
 
@@ -46,6 +45,7 @@ Additional Wherobots surfaces will be added over time.
 - Typed dataclass models for all API responses (no pydantic dependency)
 - Environment-based configuration
 - Files: list, create folders, upload, download, rename and delete in your Wherobots file area
+- Tasks: list and run tasks such as RasterFlow inference, then follow their runs, logs and cost
 
 ## Installation
 
@@ -462,6 +462,47 @@ with wherobots.Wherobots() as wb:
 
 The three `Wherobots*Error` classes above subclass `WherobotsAPIError`.
 
+## Tasks
+
+A task is a named unit of work, such as RasterFlow inference, that your organization can run.
+`wb.tasks` lists and runs tasks; `wb.task_runs` follows the runs. Tasks need the Runs feature on
+your organization.
+
+```python
+import time
+
+import wherobots
+
+with wherobots.Wherobots() as wb:
+    for task in wb.tasks.list().items:
+        print(task.name, task.display_name, task.regions)
+
+    task = wb.tasks.get("my-task")
+    print(task.input_schema)  # JSON Schema the inputs must satisfy
+
+    started = wb.tasks.run("my-task", {"aoi": "s3://bucket/aoi.geojson"}, name="nightly")
+    run = wb.task_runs.get(started.task_run_id)
+    while run.is_active:
+        time.sleep(10)
+        run = wb.task_runs.get(run.task_run_id)
+
+    print(run.state, run.results, run.error_message)
+    print(wb.task_runs.logs(run.task_run_id).entries)
+    print(wb.task_runs.cost(run.task_run_id).total_cost_usd)
+```
+
+- `tasks.run` uses `region=` if passed, then the configured region, then your organization's
+  default region.
+- Listings return an `OffsetPage`; pass `page.next_offset` as `offset=` for the next one.
+- `TaskRunState.is_active` is `True` for `PENDING`, `SUBMITTED`, `RUNNING` and `CANCELLING`. A
+  state the SDK does not know yet is kept as its raw string and counts as not active, so a
+  polling loop stops on it.
+- A run's state can lag the run by up to 2 minutes.
+- `task_runs.logs` pages forward: pass the previous page's `next_since` as `since=`. It is `None`
+  once the run has finished and every line has been returned.
+- `task_runs.cost` can take up to 45 minutes after a run ends to settle; `is_settling` stays
+  `True` until then.
+
 ## Enums
 
 ### JobStatus
@@ -689,6 +730,14 @@ To set up a Storage Integration, follow the
 | GET    | `/runs/{id}/logs`      | Get run logs       |
 | GET    | `/runs/{id}/metrics`   | Get run metrics    |
 | GET    | `/runs`                | List runs          |
+| GET    | `/tasks`               | List tasks         |
+| GET    | `/tasks/{name}`        | Get a task         |
+| POST   | `/tasks/{name}/runs`   | Run a task         |
+| GET    | `/task-runs`           | List task runs     |
+| GET    | `/task-runs/{id}`      | Get a task run     |
+| GET    | `/task-runs/{id}/logs` | Get task run logs  |
+| GET    | `/task-runs/{id}/cost` | Get task run cost  |
+| POST   | `/task-runs/{id}/cancel` | Cancel a task run |
 
 Base URL: `https://api.cloud.wherobots.com`
 

wherobots_python_sdk-0.5.0/PKG-INFO → wherobots_python_sdk-0.6.0/README.md

@@ -1,34 +1,7 @@
-Metadata-Version: 2.4
-Name: wherobots-python-sdk
-Version: 0.5.0
-Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
-Author-email: Wherobots <support@wherobots.com>
-License-Expression: Apache-2.0
-Project-URL: Homepage, https://www.wherobots.com
-Project-URL: Repository, https://github.com/wherobots/wherobots-python-sdk
-Project-URL: Issues, https://github.com/wherobots/wherobots-python-sdk/issues
-Project-URL: Documentation, https://docs.wherobots.com
-Keywords: wherobots,spark,sedona,geospatial,jobs,sdk,rest-api
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.33.0
-Requires-Dist: boto3>=1.34.0
-Dynamic: license-file
-
 # Wherobots Python SDK
 
 [![CI](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/wherobots/wherobots-python-sdk/actions/workflows/ci.yml)
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 [![Version](https://img.shields.io/pypi/v/wherobots-python-sdk?color=orange)](https://pypi.org/project/wherobots-python-sdk/)
 
@@ -46,6 +19,7 @@ Additional Wherobots surfaces will be added over time.
 - Typed dataclass models for all API responses (no pydantic dependency)
 - Environment-based configuration
 - Files: list, create folders, upload, download, rename and delete in your Wherobots file area
+- Tasks: list and run tasks such as RasterFlow inference, then follow their runs, logs and cost
 
 ## Installation
 
@@ -462,6 +436,47 @@ with wherobots.Wherobots() as wb:
 
 The three `Wherobots*Error` classes above subclass `WherobotsAPIError`.
 
+## Tasks
+
+A task is a named unit of work, such as RasterFlow inference, that your organization can run.
+`wb.tasks` lists and runs tasks; `wb.task_runs` follows the runs. Tasks need the Runs feature on
+your organization.
+
+```python
+import time
+
+import wherobots
+
+with wherobots.Wherobots() as wb:
+    for task in wb.tasks.list().items:
+        print(task.name, task.display_name, task.regions)
+
+    task = wb.tasks.get("my-task")
+    print(task.input_schema)  # JSON Schema the inputs must satisfy
+
+    started = wb.tasks.run("my-task", {"aoi": "s3://bucket/aoi.geojson"}, name="nightly")
+    run = wb.task_runs.get(started.task_run_id)
+    while run.is_active:
+        time.sleep(10)
+        run = wb.task_runs.get(run.task_run_id)
+
+    print(run.state, run.results, run.error_message)
+    print(wb.task_runs.logs(run.task_run_id).entries)
+    print(wb.task_runs.cost(run.task_run_id).total_cost_usd)
+```
+
+- `tasks.run` uses `region=` if passed, then the configured region, then your organization's
+  default region.
+- Listings return an `OffsetPage`; pass `page.next_offset` as `offset=` for the next one.
+- `TaskRunState.is_active` is `True` for `PENDING`, `SUBMITTED`, `RUNNING` and `CANCELLING`. A
+  state the SDK does not know yet is kept as its raw string and counts as not active, so a
+  polling loop stops on it.
+- A run's state can lag the run by up to 2 minutes.
+- `task_runs.logs` pages forward: pass the previous page's `next_since` as `since=`. It is `None`
+  once the run has finished and every line has been returned.
+- `task_runs.cost` can take up to 45 minutes after a run ends to settle; `is_settling` stays
+  `True` until then.
+
 ## Enums
 
 ### JobStatus
@@ -689,6 +704,14 @@ To set up a Storage Integration, follow the
 | GET    | `/runs/{id}/logs`      | Get run logs       |
 | GET    | `/runs/{id}/metrics`   | Get run metrics    |
 | GET    | `/runs`                | List runs          |
+| GET    | `/tasks`               | List tasks         |
+| GET    | `/tasks/{name}`        | Get a task         |
+| POST   | `/tasks/{name}/runs`   | Run a task         |
+| GET    | `/task-runs`           | List task runs     |
+| GET    | `/task-runs/{id}`      | Get a task run     |
+| GET    | `/task-runs/{id}/logs` | Get task run logs  |
+| GET    | `/task-runs/{id}/cost` | Get task run cost  |
+| POST   | `/task-runs/{id}/cancel` | Cancel a task run |
 
 Base URL: `https://api.cloud.wherobots.com`
 

{wherobots_python_sdk-0.5.0 → wherobots_python_sdk-0.6.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=83.0.0", "wheel"]
+requires = ["setuptools>=84.2.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -7,7 +7,7 @@ name = "wherobots-python-sdk"
 dynamic = ["version"]
 description = "Python SDK for Wherobots (currently covers the Jobs REST API)"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "Apache-2.0"
 authors = [
     {name = "Wherobots", email = "support@wherobots.com"}
@@ -17,7 +17,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -25,8 +24,8 @@ classifiers = [
 ]
 keywords = ["wherobots", "spark", "sedona", "geospatial", "jobs", "sdk", "rest-api"]
 dependencies = [
-    "requests>=2.33.0",
-    "boto3>=1.34.0",
+    "requests>=2.34.2",
+    "boto3>=1.43.108",
 ]
 
 [project.urls]
@@ -38,17 +37,17 @@ Documentation = "https://docs.wherobots.com"
 # PEP 735 dev dependencies — installed with `uv sync --group dev`.
 [dependency-groups]
 dev = [
-    "pytest>=8.0",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.11.1",
-    "ruff>=0.15,<0.17",
-    "pyrefly>=0.16",
-    "import-linter>=2.1",
-    "pre-commit>=3.8",
-    "hypothesis>=6.100",
-    "cosmic-ray>=8.4",
-    "ast-grep-cli>=0.39",
-    "types-requests>=2.31",
+    "pytest==9.1.1",
+    "pytest-cov==7.1.0",
+    "pytest-mock==3.16.0",
+    "ruff==0.17.0",
+    "pyrefly==1.3.2",
+    "import-linter==2.15",
+    "pre-commit==4.7.0",
+    "hypothesis==6.170.2",
+    "cosmic-ray==8.7.0",
+    "ast-grep-cli==0.50.0",
+    "types-requests==2.33.0.20261006",
 ]
 
 [tool.setuptools.packages.find]
@@ -60,12 +59,14 @@ wherobots = ["py.typed"]
 [tool.setuptools.dynamic]
 version = {attr = "wherobots.__version__.__version__"}
 
-# SLOP REPELLANT ruff rail: line-length 100, py310 target, select = ["ALL"]
-# plus the typing.Any/typing.cast ban all come from the base config.
+# SLOP REPELLANT ruff rail: line-length 100, select = ["ALL"] and the
+# typing.Any/typing.cast ban come from the base config. The base targets
+# py310 (the kit's floor); this project overrides it to its own py311 floor.
 # NOTE: `lint.select`/`lint.ignore` would REPLACE the base's — tune only via
 # the extend-* keys.
 [tool.ruff]
 extend = ".slop-repellant/ruff-base.toml"
+target-version = "py311"
 # .slop-repellant/ is vendored, kit-MANAGED tooling (re-rendered on
 # slop-repellant-update) — linting it locally would fork the managed files.
 extend-exclude = ["env", ".venv", "venv", "build", "dist", ".slop-repellant"]

{wherobots_python_sdk-0.5.0 → wherobots_python_sdk-0.6.0}/tests/test_files_api.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import logging
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -45,7 +45,7 @@ def files_api(mock_env):
 @pytest.fixture
 def creds_payload():
     """Sample TemporaryAwsCredentials JSON, well in the future."""
-    expiry = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat()
+    expiry = (datetime.now(UTC) + timedelta(hours=1)).isoformat()
     return {
         "accessKeyId": "ASIAEXAMPLE0001",
         "secretAccessKey": "supersecretvaluedoNotleak",

{wherobots_python_sdk-0.5.0 → wherobots_python_sdk-0.6.0}/tests/test_models.py

@@ -987,7 +987,7 @@ class TestStorageIntegrationTypes:
 # ---------------------------------------------------------------------------
 
 
-from datetime import datetime, timedelta, timezone  # noqa: E402
+from datetime import UTC, datetime, timedelta  # noqa: E402
 
 
 class TestTemporaryAwsCredentials:
@@ -1006,7 +1006,7 @@ class TestTemporaryAwsCredentials:
         assert creds.expiration.year == 2026
 
     def test_is_expired_true_for_past(self):
-        past = datetime.now(timezone.utc) - timedelta(seconds=1)
+        past = datetime.now(UTC) - timedelta(seconds=1)
         creds = TemporaryAwsCredentials(
             access_key_id="ASIA1234",
             secret_access_key="s",
@@ -1018,7 +1018,7 @@ class TestTemporaryAwsCredentials:
 
     def test_is_expired_respects_leeway(self):
         # 30s in the future, leeway 60s ⇒ considered expired.
-        soon = datetime.now(timezone.utc) + timedelta(seconds=30)
+        soon = datetime.now(UTC) + timedelta(seconds=30)
         creds = TemporaryAwsCredentials(
             access_key_id="ASIA1234",
             secret_access_key="s",
@@ -1034,7 +1034,7 @@ class TestTemporaryAwsCredentials:
             access_key_id="ASIAEXAMPLE1234",
             secret_access_key="ULTRASECRETzzzzzzzz",
             session_token="TOKEN_payload_here",
-            expiration=datetime(2026, 1, 1, tzinfo=timezone.utc),
+            expiration=datetime(2026, 1, 1, tzinfo=UTC),
             region="us-west-2",
         )
         rendered = repr(creds)

wherobots_python_sdk-0.6.0/tests/test_tasks.py

@@ -0,0 +1,296 @@
+"""Tests for the Tasks surface: Wherobots -> Tasks / TaskRuns."""
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+from hypothesis import given
+from hypothesis import strategies as st
+
+from wherobots import (
+    OffsetPage,
+    Region,
+    Task,
+    TaskRun,
+    TaskRunState,
+    TaskRunSummary,
+    Wherobots,
+    WherobotsAPIError,
+    WherobotsConfig,
+)
+
+BASE = "https://api.test.wherobots.com"
+
+TASK_RUN = {
+    "taskRunId": "tr_1",
+    "taskName": "rasterflow-inference",
+    "state": "SUCCEEDED",
+    "region": "aws-us-west-2",
+    "submittedAt": "2026-10-20T18:00:00Z",
+    "startedAt": "2026-10-20T18:00:05Z",
+    "endedAt": "2026-10-20T18:10:05Z",
+    "durationSeconds": 600,
+    "name": "nightly",
+    "inputs": {"aoi": "s3://bucket/aoi.geojson"},
+    "results": {"output": "s3://bucket/out.parquet"},
+    "cached": True,
+    "errorMessage": None,
+}
+
+
+@pytest.fixture
+def session():
+    with patch("wherobots.api.base.requests.Session") as mock_session_cls:
+        sess = mock_session_cls.return_value
+        sess.headers = {}
+        yield sess
+
+
+def _wb(session, region="aws-us-west-2", body=None):
+    session.request.return_value = _ok(body)
+    return Wherobots(WherobotsConfig(api_key="test-key-123", region=region, base_url=BASE))
+
+
+def _ok(body=None):
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.json.return_value = body if body is not None else {}
+    resp.raise_for_status.return_value = None
+    return resp
+
+
+def _sent(session):
+    call = session.request.call_args
+    return call.args[0], call.args[1], call.kwargs["params"], call.kwargs["json"]
+
+
+def test_surfaces_are_cached_on_the_client(session):
+    wb = _wb(session)
+    assert wb.tasks is wb.tasks
+    assert wb.task_runs is wb.task_runs
+
+
+def test_list_tasks_sends_filters_and_parses_the_page(session):
+    body = {
+        "items": [{"name": "a", "displayName": "A", "regions": ["aws-us-west-2", 7]}],
+        "total": 3,
+        "limit": 1,
+        "offset": 1,
+    }
+    wb = _wb(session, body=body)
+
+    page = wb.tasks.list(regions=[Region.US_WEST_2, "aws-eu-west-1"], limit=1, offset=1)
+
+    assert _sent(session) == (
+        "GET",
+        f"{BASE}/tasks",
+        {"limit": 1, "offset": 1, "regions": ["aws-us-west-2", "aws-eu-west-1"]},
+        None,
+    )
+    assert [t.name for t in page.items] == ["a"]
+    assert page.items[0].regions == ["aws-us-west-2"]
+    assert page.next_offset == 2
+
+
+@pytest.mark.parametrize("regions", ["aws-us-west-2", Region.US_WEST_2])
+def test_one_region_is_not_split_into_characters(session, regions):
+    wb = _wb(session, body={"items": [], "total": 0, "limit": 50, "offset": 0})
+    wb.tasks.list(regions=regions)
+    assert _sent(session)[2]["regions"] == ["aws-us-west-2"]
+
+
+def test_get_task_encodes_the_name_and_parses_schemas(session):
+    body = {
+        "name": "a.b",
+        "displayName": "A",
+        "inputSchema": {"type": "object"},
+        "examples": [{"name": "small", "inputs": {"n": 1}}, "junk"],
+    }
+    wb = _wb(session, body=body)
+
+    task = wb.tasks.get("a/b")
+
+    assert _sent(session)[1] == f"{BASE}/tasks/a%2Fb"
+    assert isinstance(task, Task)
+    assert task.input_schema == {"type": "object"}
+    assert task.output_schema is None
+    assert [(e.name, e.inputs) for e in task.examples] == [("small", {"n": 1})]
+
+
+@pytest.mark.parametrize(
+    ("configured", "explicit", "expected"),
+    [
+        ("aws-us-west-2", None, "aws-us-west-2"),
+        ("aws-us-west-2", Region.EU_WEST_1, "aws-eu-west-1"),
+        (None, None, None),
+    ],
+)
+def test_run_task_picks_the_region(session, configured, explicit, expected):
+    wb = _wb(session, region=configured, body=TASK_RUN)
+
+    run = wb.tasks.run("rasterflow-inference", {"aoi": "x"}, region=explicit)
+
+    method, url, _, body = _sent(session)
+    assert (method, url) == ("POST", f"{BASE}/tasks/rasterflow-inference/runs")
+    assert body == {"inputs": {"aoi": "x"}} | ({"region": expected} if expected else {})
+    assert isinstance(run, TaskRunSummary)
+    assert run.task_run_id == "tr_1"
+
+
+def test_run_task_sends_the_run_name(session):
+    wb = _wb(session, body=TASK_RUN)
+    wb.tasks.run("rasterflow-inference", name="nightly")
+    assert _sent(session)[3]["name"] == "nightly"
+
+
+def test_list_task_runs_sends_filters(session):
+    wb = _wb(session, body={"items": [TASK_RUN], "total": 1, "limit": 50, "offset": 0})
+    after = datetime(2026, 10, 1, tzinfo=UTC)
+
+    page = wb.task_runs.list(
+        task_name="raster*", states=[TaskRunState.RUNNING, "PENDING"], created_after=after
+    )
+
+    assert _sent(session)[2] == {
+        "limit": 50,
+        "offset": 0,
+        "taskName": "raster*",
+        "state": ["RUNNING", "PENDING"],
+        "createdAfter": "2026-10-01T00:00:00+00:00",
+    }
+    assert page.items[0].state is TaskRunState.SUCCEEDED
+    assert page.next_offset is None
+
+
+def test_list_task_runs_reads_a_naive_datetime_as_local_time(session):
+    wb = _wb(session, body={"items": [], "total": 0, "limit": 50, "offset": 0})
+    naive = datetime(2026, 10, 1, 9, 30)
+
+    wb.task_runs.list(created_after=naive, states="RUNNING")
+
+    params = _sent(session)[2]
+    assert datetime.fromisoformat(params["createdAfter"]) == naive.astimezone()
+    assert params["createdAfter"].endswith("+00:00")
+    assert params["state"] == ["RUNNING"]
+
+
+def test_get_task_run_parses_the_outcome(session):
+    wb = _wb(session, body=TASK_RUN)
+
+    run = wb.task_runs.get("tr/1")
+
+    assert _sent(session)[1] == f"{BASE}/task-runs/tr%2F1"
+    assert isinstance(run, TaskRun)
+    assert run.results == {"output": "s3://bucket/out.parquet"}
+    assert run.cached is True
+    assert run.duration_seconds == 600
+    assert run.submitted_at == datetime(2026, 10, 20, 18, tzinfo=UTC)
+    assert not run.is_active
+
+
+def test_task_run_keeps_an_unknown_state():
+    run = TaskRunSummary.from_dict({**TASK_RUN, "state": "PAUSED"})
+    assert run.state == "PAUSED"
+    assert not run.is_active
+
+
+@pytest.mark.parametrize("state", list(TaskRunState))
+def test_only_unfinished_states_are_active(state):
+    expected = state.value in {"PENDING", "SUBMITTED", "RUNNING", "CANCELLING"}
+    assert TaskRunSummary.from_dict({**TASK_RUN, "state": state.value}).is_active is expected
+
+
+def test_logs_pass_since_and_keep_nanosecond_timestamps(session):
+    stamp = "2026-06-04T18:01:12.680610267Z"
+    body = {
+        "taskRunId": "tr_1",
+        "items": [{"timestamp": stamp, "level": "INFO", "message": "hi"}],
+        "nextSince": stamp,
+    }
+    wb = _wb(session, body=body)
+
+    logs = wb.task_runs.logs("tr_1", since="2026-06-04T18:00:00Z")
+
+    assert _sent(session)[1:3] == (
+        f"{BASE}/task-runs/tr_1/logs",
+        {"since": "2026-06-04T18:00:00Z"},
+    )
+    assert logs.entries[0].timestamp == stamp
+    assert logs.next_since == stamp
+
+
+def test_cost_is_a_decimal(session):
+    body = {
+        "taskRunId": "tr_1",
+        "totalCostUsd": "1.10",
+        "units": 11,
+        "unitType": "RSU",
+        "isSettling": True,
+    }
+    wb = _wb(session, body=body)
+
+    cost = wb.task_runs.cost("tr_1")
+
+    assert _sent(session)[1] == f"{BASE}/task-runs/tr_1/cost"
+    assert cost.total_cost_usd == Decimal("1.10")
+    assert cost.is_settling is True
+
+
+@pytest.mark.parametrize(
+    "broken",
+    [
+        {"totalCostUsd": None},
+        {"totalCostUsd": "n/a"},
+        {"totalCostUsd": "NaN"},
+        {"totalCostUsd": float("inf")},
+        {"isSettling": None},
+    ],
+)
+def test_an_unreadable_cost_is_an_error_not_zero(session, broken):
+    body = {"taskRunId": "tr_1", "totalCostUsd": "0", "units": 0, "unitType": "RSU"}
+    wb = _wb(session, body={**body, "isSettling": False, **broken})
+    with pytest.raises(WherobotsAPIError, match="Task run cost"):
+        wb.task_runs.cost("tr_1")
+
+
+def test_cancel_posts(session):
+    wb = _wb(session)
+
+    wb.task_runs.cancel("tr_1")
+
+    assert _sent(session)[:2] == ("POST", f"{BASE}/task-runs/tr_1/cancel")
+
+
+def test_a_non_object_body_is_an_api_error(session):
+    wb = _wb(session, body=["not", "an", "object"])
+    with pytest.raises(WherobotsAPIError, match="unexpected body"):
+        wb.task_runs.get("tr_1")
+
+
+def test_http_errors_surface_as_api_errors(session):
+    resp = MagicMock()
+    resp.status_code = 404
+    resp.headers = {}
+    resp.json.return_value = {"errors": [{"message": "Task not found"}], "requestId": "r"}
+    resp.raise_for_status.side_effect = requests.HTTPError(response=resp)
+    wb = _wb(session)
+    session.request.return_value = resp
+
+    with pytest.raises(WherobotsAPIError) as err:
+        wb.tasks.get("missing")
+    assert err.value.status_code == 404
+
+
+@given(
+    total=st.integers(min_value=0, max_value=500),
+    offset=st.integers(min_value=0, max_value=500),
+    count=st.integers(min_value=0, max_value=100),
+)
+def test_next_offset_stops_at_the_end(total, offset, count):
+    page = OffsetPage(items=[None] * count, total=total, limit=100, offset=offset)
+    if page.next_offset is None:
+        assert count == 0 or offset + count >= total
+    else:
+        assert page.next_offset == offset + count < total