eastworlds-forge 0.2.0__tar.gz

eastworlds_forge-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+# the CLI's own state inside folders it uploads/downloads
+.forge/
+
+# internal notes: never publish
+docs/PRIVATE_INFO.md
+
+
+# macOS
+.DS_Store

eastworlds_forge-0.2.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: eastworlds-forge
+Version: 0.2.0
+Summary: The Forge command-line interface: sign in with a Forge API key, download and upload dataset episodes, convert MCAP <-> LeRobot v2.1 locally.
+Project-URL: Documentation, https://forge.eastworlds.io/how-to/cli
+Project-URL: Source, https://github.com/Eastworld-Labs/forge_cli
+Project-URL: Releases, https://github.com/Eastworld-Labs/forge_cli/releases
+Requires-Python: >=3.10
+Requires-Dist: av>=15
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcap-ros2-support>=0.5
+Requires-Dist: mcap>=1.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: platformdirs>=4
+Requires-Dist: pyarrow>=15
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1
+Requires-Dist: tomli>=2; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=25; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# forge
+
+The Forge command-line interface. Sign in once with a Forge API key, then download and upload dataset episodes, convert MCAP ↔ LeRobot v2.1, and lower the video frame rate. **Conversion and frame-rate changes run on your computer only**; Forge stores and serves episodes exactly as they were uploaded.
+
+The full guide is on Forge: **[Documentation → Command-Line Interface (CLI)](https://forge.eastworlds.io/how-to/cli)**.
+
+## Install
+
+**Linux only:** x86_64 or arm64, glibc 2.28+ (e.g. Ubuntu 20.04+, Debian 12+, RHEL/Rocky 8+). On Windows, run it inside WSL2 (Ubuntu). macOS is not supported. No root, Python or ffmpeg needed.
+
+```bash
+curl -fsSL https://forge.eastworlds.io/install.sh | bash
+```
+
+This installs forge with its own Python into `~/.forge` (about 310 MB) and links `forge` and `eforge` (the same program) into `~/.local/bin`. A specific version: `… | bash -s -- 0.2.0`.
+
+Prefer a Python tool manager (Linux)? `uv tool install eastworlds-forge` or `pipx install eastworlds-forge`.
+
+## Sign in
+
+```bash
+forge
+```
+
+The first run opens **Forge → API keys** with a CLI key filled in. Press **Create**, copy the command the page shows, and paste it at the prompt. In CI, set `FORGE_API_KEY` instead.
+
+## Use
+
+```bash
+forge datasets list
+forge download eastworlds/yam-fold-handkerchief -o ./data --verdict valid
+forge download eastworlds/yam-fold-handkerchief -o ./lerobot --format lerobot-v21 --fps 10
+forge upload ./recordings/2026-09-29 --to eastworlds/yam-fold-handkerchief
+forge convert mcap-to-lerobot ./data/eastworlds/yam-fold-handkerchief -o ./lerobot/yam_fold
+forge convert lerobot-to-mcap ./lerobot/yam_fold -o ./mcap_again
+```
+
+Global options such as `--json`, `--profile` and `-y` go before the command: `forge --json datasets list`.
+
+`forge update` updates, `forge doctor` checks the setup, `forge uninstall` removes everything (your keys stay unless you confirm).
+
+| Exit code | Meaning |
+|---|---|
+| 0 | OK |
+| 1 | Failure |
+| 2 | Usage or validation error |
+| 3 | Bad or expired key |
+| 4 | Missing scope |
+| 5 | Not found |
+| 6 | Conflict |
+| 7 | Server or network error |
+| 130 | Interrupted |
+
+## Develop
+
+```bash
+python3.11 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+```
+
+- `src/forge_cli/convert/` is a port of the production-verified MCAP → LeRobot v2.1 converter. `tests/test_convert_golden.py` compares the two on real recordings when `FORGE_VERIFIED_SAMPLE` and `FORGE_GOLDEN_EPISODES` are set.
+- `install/install.sh` is the installer; `tests/test_install.py` runs it against a local fake release.
+- `scripts/build_release.py --out dist/release` builds what the download host serves. On a `vX.Y.Z` tag, `.github/workflows/release.yml` publishes it to Tencent COS behind EdgeOne (`https://cli-forge.eastworlds.io`); setup in [docs/RELEASE_INFRA.md](docs/RELEASE_INFRA.md).
+
+Design: [docs/INITIAL_PLAN_V2.md](docs/INITIAL_PLAN_V2.md). What was built: [docs/INITIAL_DONE_V2.md](docs/INITIAL_DONE_V2.md).

eastworlds_forge-0.2.0/README.md

@@ -0,0 +1,66 @@
+# forge
+
+The Forge command-line interface. Sign in once with a Forge API key, then download and upload dataset episodes, convert MCAP ↔ LeRobot v2.1, and lower the video frame rate. **Conversion and frame-rate changes run on your computer only**; Forge stores and serves episodes exactly as they were uploaded.
+
+The full guide is on Forge: **[Documentation → Command-Line Interface (CLI)](https://forge.eastworlds.io/how-to/cli)**.
+
+## Install
+
+**Linux only:** x86_64 or arm64, glibc 2.28+ (e.g. Ubuntu 20.04+, Debian 12+, RHEL/Rocky 8+). On Windows, run it inside WSL2 (Ubuntu). macOS is not supported. No root, Python or ffmpeg needed.
+
+```bash
+curl -fsSL https://forge.eastworlds.io/install.sh | bash
+```
+
+This installs forge with its own Python into `~/.forge` (about 310 MB) and links `forge` and `eforge` (the same program) into `~/.local/bin`. A specific version: `… | bash -s -- 0.2.0`.
+
+Prefer a Python tool manager (Linux)? `uv tool install eastworlds-forge` or `pipx install eastworlds-forge`.
+
+## Sign in
+
+```bash
+forge
+```
+
+The first run opens **Forge → API keys** with a CLI key filled in. Press **Create**, copy the command the page shows, and paste it at the prompt. In CI, set `FORGE_API_KEY` instead.
+
+## Use
+
+```bash
+forge datasets list
+forge download eastworlds/yam-fold-handkerchief -o ./data --verdict valid
+forge download eastworlds/yam-fold-handkerchief -o ./lerobot --format lerobot-v21 --fps 10
+forge upload ./recordings/2026-09-29 --to eastworlds/yam-fold-handkerchief
+forge convert mcap-to-lerobot ./data/eastworlds/yam-fold-handkerchief -o ./lerobot/yam_fold
+forge convert lerobot-to-mcap ./lerobot/yam_fold -o ./mcap_again
+```
+
+Global options such as `--json`, `--profile` and `-y` go before the command: `forge --json datasets list`.
+
+`forge update` updates, `forge doctor` checks the setup, `forge uninstall` removes everything (your keys stay unless you confirm).
+
+| Exit code | Meaning |
+|---|---|
+| 0 | OK |
+| 1 | Failure |
+| 2 | Usage or validation error |
+| 3 | Bad or expired key |
+| 4 | Missing scope |
+| 5 | Not found |
+| 6 | Conflict |
+| 7 | Server or network error |
+| 130 | Interrupted |
+
+## Develop
+
+```bash
+python3.11 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+```
+
+- `src/forge_cli/convert/` is a port of the production-verified MCAP → LeRobot v2.1 converter. `tests/test_convert_golden.py` compares the two on real recordings when `FORGE_VERIFIED_SAMPLE` and `FORGE_GOLDEN_EPISODES` are set.
+- `install/install.sh` is the installer; `tests/test_install.py` runs it against a local fake release.
+- `scripts/build_release.py --out dist/release` builds what the download host serves. On a `vX.Y.Z` tag, `.github/workflows/release.yml` publishes it to Tencent COS behind EdgeOne (`https://cli-forge.eastworlds.io`); setup in [docs/RELEASE_INFRA.md](docs/RELEASE_INFRA.md).
+
+Design: [docs/INITIAL_PLAN_V2.md](docs/INITIAL_PLAN_V2.md). What was built: [docs/INITIAL_DONE_V2.md](docs/INITIAL_DONE_V2.md).

eastworlds_forge-0.2.0/pyproject.toml

@@ -0,0 +1,138 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "eastworlds-forge"
+dynamic = ["version"]
+
+description = "The Forge command-line interface: sign in with a Forge API key, download and upload dataset episodes, convert MCAP <-> LeRobot v2.1 locally."
+
+readme = "README.md"
+
+requires-python = ">=3.10"
+
+dependencies = [
+    "httpx>=0.27",
+    "typer>=0.12",
+    "rich>=13",
+    "platformdirs>=4",
+
+    # Python < 3.11 does not include tomllib.
+    "tomli>=2; python_version < '3.11'",
+
+    "tomli-w>=1",
+
+    # Conversion and frame-rate changes run locally and are core CLI features.
+    "av>=15",
+    "mcap>=1.2",
+    "mcap-ros2-support>=0.5",
+    "numpy>=1.26",
+    "pyarrow>=15",
+]
+
+
+[project.optional-dependencies]
+
+# Optional OS keychain/keyring integration.
+keyring = [
+    "keyring>=25",
+]
+
+# Local development/test dependencies.
+dev = [
+    "pytest>=8",
+    "respx>=0.21",
+    "ruff>=0.5",
+]
+
+
+[project.scripts]
+
+# Primary CLI command.
+forge = "forge_cli.cli:main"
+
+# Alias that avoids conflicts with other tools named `forge`.
+eforge = "forge_cli.cli:main"
+
+
+[project.urls]
+Documentation = "https://forge.eastworlds.io/how-to/cli"
+Source = "https://github.com/Eastworld-Labs/forge_cli"
+Releases = "https://github.com/Eastworld-Labs/forge_cli/releases"
+
+
+# ---------------------------------------------------------------------------
+# Versioning
+# ---------------------------------------------------------------------------
+
+# Keep the package version in one location:
+#
+#   src/forge_cli/__init__.py
+#
+# Example:
+#
+#   __version__ = "0.2.0"
+#
+# Hatch reads that value when building the wheel/sdist.
+[tool.hatch.version]
+path = "src/forge_cli/__init__.py"
+
+
+# ---------------------------------------------------------------------------
+# Build configuration
+# ---------------------------------------------------------------------------
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forge_cli"]
+
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/pyproject.toml",
+]
+
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+filterwarnings = [
+    "ignore::DeprecationWarning:mcap_ros2.*",
+]
+
+
+# ---------------------------------------------------------------------------
+# Ruff
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+
+extend-exclude = [
+    "src/forge_cli/vendor",
+    "scripts",
+]
+
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+]
+
+# typer.Option(...) / typer.Argument(...) in function defaults is the
+# conventional Typer API style.
+ignore = ["B008"]

eastworlds_forge-0.2.0/src/forge_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Forge developer CLI."""
+
+__version__ = "0.2.0"

eastworlds_forge-0.2.0/src/forge_cli/__main__.py

@@ -0,0 +1,3 @@
+from forge_cli.cli import main
+
+raise SystemExit(main())

eastworlds_forge-0.2.0/src/forge_cli/api/backend.py

@@ -0,0 +1,131 @@
+"""The Forge API (`api-forge.*`): identity, catalog, downloads.
+
+Only this module knows these paths and payload shapes. Responses stay plain
+dicts: the server adds fields freely and an old CLI must keep working.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+from urllib.parse import quote
+
+from .http import ApiClient, _flatten
+
+TERMINAL_DOWNLOAD_STATES = {"ready", "failed", "expired", "needs_resolution"}
+
+
+def split_dataset(full_name: str) -> tuple[str, str]:
+    namespace, sep, slug = full_name.strip().strip("/").partition("/")
+    if not sep or not namespace or not slug or "/" in slug:
+        from ..core.errors import UsageError
+
+        raise UsageError(f"expected NAMESPACE/DATASET, got {full_name!r}")
+    return namespace, slug
+
+
+def _ds(namespace: str, slug: str) -> str:
+    return f"/api/v1/{quote(namespace, safe='')}/{quote(slug, safe='')}"
+
+
+class Backend:
+    def __init__(self, client: ApiClient) -> None:
+        self.c = client
+
+    # ------------------------------------------------------------ identity
+    def me(self) -> dict[str, Any]:
+        return self.c.get("/api/v1/me", what="check key")
+
+    def viewer_config(self) -> dict[str, Any]:
+        return self.c.get("/api/v1/viewer-config", what="read viewer-config")
+
+    # ------------------------------------------------------------ datasets
+    def list_datasets(self, *, limit: int | None = None, **filters: Any) -> Iterator[dict[str, Any]]:
+        return self.c.paginate("/api/v1/datasets", filters, limit=limit)
+
+    def get_dataset(self, namespace: str, slug: str) -> dict[str, Any]:
+        return self.c.get(_ds(namespace, slug), what=f"dataset {namespace}/{slug}")
+
+    def create_dataset(self, namespace: str, slug: str, **fields: Any) -> dict[str, Any]:
+        body = {"namespace": namespace, "slug": slug, **{k: v for k, v in fields.items() if v is not None}}
+        return self.c.post("/api/v1/datasets", body, what=f"create dataset {namespace}/{slug}")
+
+    # ------------------------------------------------------------ episodes
+    def list_episodes(
+        self, namespace: str, slug: str, *, limit: int | None = None, **filters: Any
+    ) -> Iterator[dict[str, Any]]:
+        return self.c.paginate(f"{_ds(namespace, slug)}/episodes", filters, limit=limit)
+
+    def get_episode(self, namespace: str, slug: str, name: str) -> dict[str, Any]:
+        return self.c.get(
+            f"{_ds(namespace, slug)}/episodes/{quote(name, safe='')}", what=f"episode {name}"
+        )
+
+    def signed_file_url(self, namespace: str, slug: str, name: str, relpath: str) -> str | None:
+        """A short-lived presigned GET for one manifest file, or None when the
+        server has per-file links switched off (the media gateway is on)."""
+        from ..core.errors import ForgeError
+
+        try:
+            body = self.c.get(
+                f"{_ds(namespace, slug)}/episodes/{quote(name, safe='')}/files/{quote(relpath)}",
+                params={"signed": "1"}, what=f"link for {name}/{relpath}",
+            )
+        except ForgeError as exc:
+            if exc.exit_code in (4, 5):  # forbidden / not found: no per-file links here
+                return None
+            raise
+        return body.get("url") if isinstance(body, dict) else None
+
+    # ----------------------------------------------------------- downloads
+    def downloads_health(self) -> dict[str, Any]:
+        return self.c.get("/api/v1/downloads/health", what="downloads health")
+
+    def file_types(self, dataset: str, episodes: list[str] | None) -> dict[str, Any]:
+        # GET with names in the query string until it gets long, then POST --
+        # the same switch the web app makes (80 names).
+        if episodes is not None and len(episodes) > 80:
+            return self.c.post(
+                "/api/v1/downloads/file-types",
+                {"dataset": dataset, "episodes": episodes},
+                retry=True,
+                what="list file types",
+            )
+        params = _flatten({"dataset": dataset, "episodes": episodes})
+        return self.c.get("/api/v1/downloads/file-types", params=params, what="list file types")
+
+    def create_download(self, selections: list[dict[str, Any]], mode: str) -> dict[str, Any]:
+        return self.c.post(
+            "/api/v1/downloads", {"selections": selections, "mode": mode}, what="create download"
+        )
+
+    def get_download(self, sid: str) -> dict[str, Any]:
+        return self.c.get(f"/api/v1/downloads/{quote(sid, safe='')}", what=f"download {sid}")
+
+    def repackage(self, sid: str) -> dict[str, Any]:
+        return self.c.post(f"/api/v1/downloads/{quote(sid, safe='')}/repackage", what="repackage")
+
+    def resolve_meta(self, sid: str, info: dict[str, Any], tasks: list[str] | None) -> dict[str, Any]:
+        body: dict[str, Any] = {"info": info}
+        if tasks is not None:
+            body["tasks"] = tasks
+        return self.c.post(f"/api/v1/downloads/{quote(sid, safe='')}/meta", body, what="resolve info.json")
+
+    def archive_location(self, sid: str, part: int | None) -> str | None:
+        """Where the archive bytes are.
+
+        Redirect mode (the default): the 307's presigned COS URL, valid ~300 s,
+        so callers ask again when a resumed transfer needs a fresh one. Proxy
+        mode: None, meaning "stream it from this API" (`archive_stream`).
+        """
+        params = {"part": part} if part else None
+        response = self.c.send(
+            "GET", f"/api/v1/downloads/{quote(sid, safe='')}/archive", params=params, what="archive"
+        )
+        if response.status_code in (301, 302, 303, 307, 308):
+            return response.headers["location"]
+        response.close()
+        return None
+
+    def archive_path(self, sid: str) -> str:
+        return f"/api/v1/downloads/{quote(sid, safe='')}/archive"

eastworlds_forge-0.2.0/src/forge_cli/api/http.py

@@ -0,0 +1,207 @@
+"""The one HTTP client both Forge services are called through.
+
+- `Authorization: Bearer` goes ONLY to the host it was built for. Presigned
+  COS URLs are fetched with a separate, credential-free client (transfer/).
+- A real `User-Agent`: Cloudflare in front of api-forge/uploads-forge answers
+  the default Python agents with a 403 (error 1010).
+- Retries with exponential backoff + jitter on connection errors, 429 (honouring
+  Retry-After) and 502/503/504. Non-idempotent POSTs are retried only when the
+  caller says the endpoint is safe to repeat.
+- FastAPI's `detail` becomes a ForgeError carrying the CLI's exit code.
+"""
+
+from __future__ import annotations
+
+import platform
+import random
+import time
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .. import __version__
+from ..core.errors import (
+    AuthError,
+    Conflict,
+    ForgeError,
+    NotFound,
+    PermissionDenied,
+    ServerError,
+    UsageError,
+)
+
+USER_AGENT = f"forge-cli/{__version__} (python-httpx/{httpx.__version__}; {platform.system().lower()})"
+RETRY_STATUSES = {429, 502, 503, 504}
+IDEMPOTENT = {"GET", "HEAD", "PUT", "DELETE", "OPTIONS"}
+
+
+def detail_text(response: httpx.Response) -> tuple[str, Any]:
+    try:
+        body = response.json()
+    except ValueError:
+        return (response.text or response.reason_phrase or "").strip()[:500], None
+    detail = body.get("detail", body) if isinstance(body, dict) else body
+    if isinstance(detail, str):
+        return detail, body
+    if isinstance(detail, dict) and isinstance(detail.get("message"), str):
+        return detail["message"], detail
+    if isinstance(detail, list):  # FastAPI 422 validation errors
+        parts = []
+        for item in detail[:5]:
+            if isinstance(item, dict):
+                loc = ".".join(str(p) for p in item.get("loc", []) if p != "body")
+                parts.append(f"{loc}: {item.get('msg')}" if loc else str(item.get("msg")))
+        return "; ".join(parts) or "invalid request", detail
+    return str(detail)[:500], detail
+
+
+def error_for(response: httpx.Response, *, what: str) -> ForgeError:
+    message, detail = detail_text(response)
+    status = response.status_code
+    text = f"{what}: {message}" if message else f"{what}: HTTP {status}"
+    if status == 401:
+        return AuthError(
+            text,
+            hint="the key is not valid, revoked or expired. Run: forge auth login",
+            detail=detail,
+        )
+    if status == 403:
+        hint = None
+        if "scope" in message:
+            hint = "create a key with that scope on Forge → API keys, then run: forge auth login"
+        elif "1010" in message or "cloudflare" in message.lower():
+            hint = "blocked by Cloudflare; check your network/proxy"
+        return PermissionDenied(text, hint=hint, detail=detail)
+    if status == 404:
+        return NotFound(text, detail=detail)
+    if status == 409:
+        return Conflict(text, detail=detail)
+    if status in (400, 413, 422):
+        return UsageError(text, detail=detail)
+    if status >= 500:
+        return ServerError(text, detail=detail)
+    return ForgeError(text, detail=detail)
+
+
+class ApiClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        *,
+        timeout: float = 60.0,
+        retries: int = 5,
+        backoff: float = 0.5,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.host = urlsplit(self.base_url).netloc
+        self.retries = retries
+        self.backoff = backoff
+        self._sleep = sleep
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self.http = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=httpx.Timeout(timeout, connect=10.0),
+            follow_redirects=False,  # a 307 to COS must not carry the Bearer header
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _delay(self, attempt: int, response: httpx.Response | None) -> float:
+        if response is not None:
+            retry_after = response.headers.get("retry-after")
+            if retry_after and retry_after.isdigit():
+                return min(60.0, float(retry_after))
+        return min(30.0, self.backoff * (2**attempt)) * (0.5 + random.random() / 2)
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        json: Any = None,
+        retry: bool | None = None,
+        ok: tuple[int, ...] = (),
+        what: str | None = None,
+    ) -> httpx.Response:
+        """One request with the retry policy. Returns the response for 2xx/3xx
+        (and any status in `ok`); raises ForgeError otherwise."""
+        method = method.upper()
+        may_retry = (method in IDEMPOTENT) if retry is None else retry
+        attempt = 0
+        label = what or f"{method} {path}"
+        while True:
+            response: httpx.Response | None = None
+            try:
+                response = self.http.request(method, path, params=params, json=json)
+            except httpx.TransportError as exc:
+                if not may_retry or attempt >= self.retries:
+                    raise ServerError(
+                        f"{label}: cannot reach {self.host} ({type(exc).__name__}: {exc})",
+                        hint="check the network, or the profile's URL (forge auth status)",
+                    ) from exc
+            else:
+                if response.status_code < 400 or response.status_code in ok:
+                    return response
+                if response.status_code not in RETRY_STATUSES or not may_retry or attempt >= self.retries:
+                    raise error_for(response, what=label)
+            self._sleep(self._delay(attempt, response))
+            attempt += 1
+
+    def get(self, path: str, **kw: Any) -> Any:
+        return self.send("GET", path, **kw).json()
+
+    def post(self, path: str, body: Any = None, **kw: Any) -> Any:
+        return self.send("POST", path, json=body if body is not None else {}, **kw).json()
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self.send("DELETE", path, **kw).json()
+
+    def paginate(self, path: str, params: dict | None = None, *, page: int = 200, limit: int | None = None):
+        """Yield items across `{items,total,limit,offset}` pages."""
+        offset, seen = 0, 0
+        while True:
+            query = dict(params or {})
+            query.update({"limit": page, "offset": offset})
+            data = self.get(path, params=list(_flatten(query)))
+            items = data.get("items") or []
+            for item in items:
+                yield item
+                seen += 1
+                if limit is not None and seen >= limit:
+                    return
+            offset += len(items)
+            total = data.get("total")
+            if not items or (total is not None and offset >= total):
+                return
+
+
+def _flatten(params: dict) -> list[tuple[str, Any]]:
+    """`{"task": ["a","b"]}` -> repeated query params, dropping None."""
+    out: list[tuple[str, Any]] = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            out.extend((key, v) for v in value)
+        elif isinstance(value, bool):
+            out.append((key, "true" if value else "false"))
+        else:
+            out.append((key, value))
+    return out