pytellybox 0.1.0__py3-none-any.whl

pytellybox/__init__.py

@@ -0,0 +1,37 @@
+"""Async client for Tellybox (https://github.com/sandermvanvliet/Tellybox)."""
+
+from pytellybox.client import EXTRA_MINUTES_MAX, TellyboxClient
+from pytellybox.errors import (
+    TellyboxAuthError,
+    TellyboxConnectionError,
+    TellyboxError,
+    TellyboxForbiddenError,
+    TellyboxNotFoundError,
+    TellyboxRequestError,
+    TellyboxTimeUpError,
+    TellyboxUnavailableError,
+)
+from pytellybox.models import (
+    LAST_FIVE_S,
+    TV,
+    AdminState,
+    Day,
+    Disk,
+    Group,
+    Home,
+    Info,
+    Jobs,
+    KidProfile,
+    NowPlaying,
+    Profile,
+    Show,
+    ShowRef,
+    Tile,
+)
+
+__all__ = [
+    "EXTRA_MINUTES_MAX", "LAST_FIVE_S", "TV", "AdminState", "Day", "Disk", "Group", "Home", "Info", "Jobs",
+    "KidProfile", "NowPlaying", "Profile", "Show", "ShowRef", "TellyboxAuthError", "TellyboxClient",
+    "TellyboxConnectionError", "TellyboxError", "TellyboxForbiddenError", "TellyboxNotFoundError",
+    "TellyboxRequestError", "TellyboxTimeUpError", "TellyboxUnavailableError", "Tile",
+]

pytellybox/admin_state.json

@@ -0,0 +1,21 @@
+{
+  "instance_id": "3f2a9c0e5b7d4e1f8a6b2c3d4e5f6a7b",
+  "version": "2026.09.29.5",
+  "api": 1,
+  "day": {"date": "2026-09-29", "resets_at": "2026-09-30T02:00:00+00:00"},
+  "tv": {"connection": "CONNECTED", "reachable": true, "device": "TV"},
+  "now_playing": {"episode_id": 4, "show_id": 2, "title": "Alongside", "show": "Harbour Pups",
+                  "state": "playing", "position_s": 312, "duration_s": 660, "profile_ids": [1]},
+  "group": {"remaining_s": 1790, "time_up": false, "last_five": false, "action": "continue", "reason": null,
+            "grace_ends_at": null, "session_started_at": "2026-09-29T13:10:00+00:00", "session_elapsed_s": 1200},
+  "profiles": [
+    {"id": 1, "name": "Mila", "avatar": "fox", "allowance_s": 3600, "extra_s": 900, "used_s": 2710,
+     "remaining_s": 1790, "unlimited": false, "blocked": false, "mode": "ignore_pauses", "max_session_s": 5400,
+     "session_elapsed_s": 1200, "can_start": true, "reason": null, "watching": true, "last_five": false},
+    {"id": 2, "name": "Noah", "avatar": null, "allowance_s": 2700, "extra_s": 0, "used_s": 2700,
+     "remaining_s": 0, "unlimited": false, "blocked": false, "mode": "ignore_pauses", "max_session_s": null,
+     "session_elapsed_s": null, "can_start": false, "reason": "allowance", "watching": false, "last_five": true}
+  ],
+  "jobs": {"queued": 1, "running": 1, "failed": 0, "held_ready": 3},
+  "disk": {"media_bytes": 48213000000, "free_bytes": 120000000000}
+}

pytellybox/client.py

@@ -0,0 +1,234 @@
+"""Async client for a Tellybox server: the admin API (token) and the kid API (browse and play)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+import aiohttp
+
+from pytellybox.errors import (
+    TellyboxAuthError,
+    TellyboxConnectionError,
+    TellyboxError,
+    TellyboxForbiddenError,
+    TellyboxNotFoundError,
+    TellyboxRequestError,
+    TellyboxTimeUpError,
+    TellyboxUnavailableError,
+)
+from pytellybox.models import AdminState, Home, Info, KidProfile, Show
+
+DEFAULT_TIMEOUT_S = 10.0
+EVENTS_READ_TIMEOUT_S = 45.0  # Tellybox sends a keepalive every 15 s
+EXTRA_MINUTES_MAX = 240
+
+
+class TellyboxClient:
+    """One Tellybox server.
+
+    `base_url` is the server's root, e.g. `https://tellybox.example` or `http://192.0.2.10:8080`; a trailing
+    slash is ignored. `token` is an API token (`tbx_...`) created on Tellybox's Integrations page; it may be
+    None for `info()` and the kid API only. The caller owns `session` (Home Assistant passes its shared one);
+    the client never closes it. The token is sent only as `Authorization: Bearer` to `/api/admin/*` and is
+    never logged or put in an exception message.
+
+    Error mapping, for every call: connection problems and timeouts raise TellyboxConnectionError;
+    401 TellyboxAuthError; 403 TellyboxForbiddenError; 404 TellyboxNotFoundError; 400/422
+    TellyboxRequestError (with Tellybox's `detail`); 409 on play TellyboxTimeUpError; 503
+    TellyboxUnavailableError; any other non-2xx TellyboxError.
+    """
+
+    def __init__(
+        self, base_url: str, token: str | None, session: aiohttp.ClientSession, *, timeout: float = DEFAULT_TIMEOUT_S
+    ) -> None:
+        self._base_url = base_url.strip().rstrip("/")
+        self._token = token
+        self._session = session
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+
+    def __repr__(self) -> str:
+        return f"TellyboxClient({self._base_url!r})"
+
+    @property
+    def base_url(self) -> str:
+        """The normalised base URL, without a trailing slash."""
+        return self._base_url
+
+    def url(self, path: str) -> str:
+        """Absolute URL for a server path such as `/img/episode/4.jpg` (images need no auth)."""
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    # ----------------------------------------------------------------------- plumbing
+
+    def _headers(self, path: str) -> dict[str, str]:
+        if self._token and path.startswith("/api/admin/"):
+            return {"Authorization": f"Bearer {self._token}"}
+        return {}
+
+    async def _request(
+        self, method: str, path: str, *, json_body: Any = None, params: dict[str, str] | None = None,
+        conflict_is_time_up: bool = False,
+    ) -> Any:
+        """One JSON request; returns the decoded body (None when empty) or raises a TellyboxError."""
+        try:
+            async with self._session.request(
+                method, self.url(path), headers=self._headers(path), json=json_body, params=params,
+                timeout=self._timeout,
+            ) as resp:
+                if resp.status >= 400:
+                    raise await _error_for(resp, conflict_is_time_up)
+                raw = await resp.read()
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise TellyboxConnectionError(f"Cannot reach Tellybox: {type(err).__name__}") from None
+        if not raw:
+            return None
+        try:
+            return json.loads(raw)
+        except ValueError:
+            raise TellyboxError("Tellybox sent a response that is not JSON") from None
+
+    # ----------------------------------------------------------------------- admin API (docs/admin-api.md)
+
+    async def info(self) -> Info:
+        """`GET /api/info`, no token needed."""
+        return Info.from_dict(await self._request("GET", "/api/info"))
+
+    async def state(self) -> AdminState:
+        """`GET /api/admin/state` (read scope)."""
+        return AdminState.from_dict(await self._request("GET", "/api/admin/state"))
+
+    async def events(self) -> AsyncIterator[AdminState]:
+        """`GET /api/admin/events` (read scope): yields the current state at once, then one per change.
+
+        Keepalive comments are skipped. The read timeout is EVENTS_READ_TIMEOUT_S. When the stream ends or
+        breaks, the iterator raises TellyboxConnectionError; it never reconnects on its own (the caller
+        decides the backoff). A 401 on connect raises TellyboxAuthError.
+        """
+        path = "/api/admin/events"
+        timeout = aiohttp.ClientTimeout(total=None, sock_connect=self._timeout.total, sock_read=EVENTS_READ_TIMEOUT_S)
+        headers = {**self._headers(path), "Accept": "text/event-stream"}
+        try:
+            async with self._session.get(self.url(path), headers=headers, timeout=timeout) as resp:
+                if resp.status >= 400:
+                    raise await _error_for(resp, False)
+                data: list[str] = []
+                async for raw in resp.content:
+                    line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+                    if not line:
+                        if data:
+                            payload, data = "\n".join(data), []
+                            yield _parse_event(payload)
+                    elif line.startswith(":"):
+                        continue
+                    elif line.startswith("data:"):
+                        value = line[5:]
+                        data.append(value[1:] if value.startswith(" ") else value)
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise TellyboxConnectionError(f"Event stream broke: {type(err).__name__}") from None
+        raise TellyboxConnectionError("Event stream ended")
+
+    async def _override(self, method: str, action: str, **kwargs: Any) -> AdminState:
+        return AdminState.from_dict(await self._request(method, f"/api/admin/overrides/{action}", **kwargs))
+
+    async def add_time(self, minutes: int, profile_ids: Sequence[int] | None = None) -> AdminState:
+        """`POST /api/admin/overrides/extra` (control). `minutes` 1..240; None = every kid."""
+        if isinstance(minutes, bool) or not isinstance(minutes, int) or not 1 <= minutes <= EXTRA_MINUTES_MAX:
+            raise ValueError(f"minutes must be an integer from 1 to {EXTRA_MINUTES_MAX}")
+        return await self._override("POST", "extra", json_body=_body(profile_ids, minutes=minutes))
+
+    async def set_unlimited(self, profile_ids: Sequence[int] | None = None) -> AdminState:
+        """`POST /api/admin/overrides/unlimited` (control): unlimited today."""
+        return await self._override("POST", "unlimited", json_body=_body(profile_ids))
+
+    async def block(self, profile_ids: Sequence[int] | None = None) -> AdminState:
+        """`POST /api/admin/overrides/block` (control): blocked today, immediately."""
+        return await self._override("POST", "block", json_body=_body(profile_ids))
+
+    async def stop_now(self) -> AdminState:
+        """`POST /api/admin/overrides/stop` (control)."""
+        return await self._override("POST", "stop", json_body={})
+
+    async def clear_today(self, profile_ids: Sequence[int] | None = None) -> AdminState:
+        """`DELETE /api/admin/overrides/today?profile_ids=1,3` (control): clears unlimited and block."""
+        params = {"profile_ids": _csv(profile_ids)} if profile_ids is not None else None
+        return await self._override("DELETE", "today", params=params)
+
+    # ----------------------------------------------------------------------- kid API (docs/kid-api.md), no token
+
+    async def kid_profiles(self) -> list[KidProfile]:
+        """`GET /api/kid/profiles`."""
+        return [KidProfile.from_dict(p) for p in await self._request("GET", "/api/kid/profiles")]
+
+    async def home(self, profile_ids: Sequence[int] | None = None) -> Home:
+        """`GET /api/kid/home?profiles=1,3`."""
+        return Home.from_dict(await self._request("GET", "/api/kid/home", params=_profiles_param(profile_ids)))
+
+    async def show(self, show_id: int, profile_ids: Sequence[int] | None = None) -> Show:
+        """`GET /api/kid/shows/{id}?profiles=1,3`."""
+        data = await self._request("GET", f"/api/kid/shows/{int(show_id)}", params=_profiles_param(profile_ids))
+        return Show.from_dict(data)
+
+    async def play(self, episode_id: int, profile_ids: Sequence[int]) -> None:
+        """`POST /api/kid/play`. 409 raises TellyboxTimeUpError: Tellybox's timer always decides."""
+        await self._request(
+            "POST", "/api/kid/play", json_body={"episode_id": episode_id, "profile_ids": list(profile_ids)},
+            conflict_is_time_up=True,
+        )
+
+    async def pause(self) -> None:
+        """`POST /api/kid/pause`."""
+        await self._request("POST", "/api/kid/pause", json_body={})
+
+    async def resume(self) -> None:
+        """`POST /api/kid/resume`."""
+        await self._request("POST", "/api/kid/resume", json_body={})
+
+
+def _csv(ids: Sequence[int]) -> str:
+    return ",".join(str(int(i)) for i in ids)
+
+
+def _body(profile_ids: Sequence[int] | None, **fields: Any) -> dict[str, Any]:
+    body = dict(fields)
+    if profile_ids is not None:
+        body["profile_ids"] = [int(i) for i in profile_ids]
+    return body
+
+
+def _profiles_param(profile_ids: Sequence[int] | None) -> dict[str, str] | None:
+    return {"profiles": _csv(profile_ids)} if profile_ids is not None else None
+
+
+def _parse_event(payload: str) -> AdminState:
+    try:
+        return AdminState.from_dict(json.loads(payload))
+    except (ValueError, KeyError, TypeError):
+        raise TellyboxError("Tellybox sent an event that is not a state") from None
+
+
+async def _error_for(resp: aiohttp.ClientResponse, conflict_is_time_up: bool) -> TellyboxError:
+    """Map a non-2xx response to the matching error. Only Tellybox's `detail` ends up in the message."""
+    status = resp.status
+    detail = ""
+    try:
+        body = await resp.json(content_type=None)
+    except (ValueError, aiohttp.ClientError):
+        body = None
+    if isinstance(body, dict) and body.get("detail") is not None:
+        detail = str(body["detail"])
+    text = detail or f"HTTP {status}"
+    if status == 401:
+        return TellyboxAuthError(text)
+    if status == 403:
+        return TellyboxForbiddenError(text)
+    if status == 404:
+        return TellyboxNotFoundError(text)
+    if status in (400, 422):
+        return TellyboxRequestError(text)
+    if status == 409 and conflict_is_time_up:
+        return TellyboxTimeUpError(text)
+    if status == 503:
+        return TellyboxUnavailableError(text)
+    return TellyboxError(text)

pytellybox/errors.py

@@ -0,0 +1,35 @@
+"""Errors raised by the Tellybox client. Every error is a `TellyboxError`."""
+
+from __future__ import annotations
+
+
+class TellyboxError(Exception):
+    """Base class for every client error."""
+
+
+class TellyboxConnectionError(TellyboxError):
+    """Tellybox can't be reached: connection refused, timeout, or an event stream that ended."""
+
+
+class TellyboxAuthError(TellyboxError):
+    """401: the token is missing, unknown or revoked. Home Assistant starts a reauth flow."""
+
+
+class TellyboxForbiddenError(TellyboxError):
+    """403: the token lacks the scope, e.g. an override with a read-only token."""
+
+
+class TellyboxNotFoundError(TellyboxError):
+    """404: no such episode or show (or it isn't visible to kids)."""
+
+
+class TellyboxRequestError(TellyboxError):
+    """400/422: Tellybox refused the request (bad minutes, unknown profile ids...). `str()` is its detail."""
+
+
+class TellyboxTimeUpError(TellyboxError):
+    """409 on play: someone in the group is out of time (PR-4). Playing is refused, never forced."""
+
+
+class TellyboxUnavailableError(TellyboxError):
+    """503: Tellybox is up, but its cast service or the TV isn't; nothing was applied."""

pytellybox/mock.py

@@ -0,0 +1,445 @@
+"""A mock Tellybox server for developing and testing integrations without a real Tellybox.
+
+`python -m pytellybox.mock --port 8099 --token tbx_dev [--read-token tbx_ro]` serves:
+- `/api/info`, `/api/admin/state`, `/api/admin/events` (SSE with keepalive), the override routes, with the
+  same auth rules as Tellybox (401 / 403, a read-only token via `read_tokens`);
+- `/api/kid/profiles`, `/home`, `/shows/{id}`, `/state`, `/play` (409 when a watcher can't start), `/pause`,
+  `/resume`;
+- `/img/...` placeholder images.
+Overrides change the scripted state the way Tellybox would (extra time, unlimited, block, clear, stop) and
+push a new event. Tests and scripts drive it through `MockTellybox`: `set_state(dict)`, `push()`,
+`calls` (recorded requests), and `app` (an aiohttp `web.Application`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import copy
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from importlib import resources
+from typing import Any
+
+from aiohttp import web
+
+_LAST_FIVE_S = 300
+_PLACEHOLDER_IMAGE = (  # a 1x1 GIF; the mock has no image library
+    b"GIF89a\x01\x00\x01\x00\x80\x00\x00\x80\x80\x80\x00\x00\x00!\xf9\x04\x01\x00\x00\x00\x00,"
+    b"\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02\x02D\x01\x00;"
+)
+
+_EPISODES = {
+    4: {"show_id": 2, "title": "Alongside", "duration_s": 660},
+    5: {"show_id": 2, "title": "Lost Ball", "duration_s": 600},
+    6: {"show_id": 3, "title": "Big Splash", "duration_s": 480},
+}
+_SHOWS = {2: "Harbour Pups", 3: "Bubble Bay"}
+
+Handler = Callable[[web.Request], Awaitable[web.StreamResponse]]
+
+
+def default_state() -> dict[str, Any]:
+    """A copy of the packaged example state (Mila watching, Noah out of time)."""
+    return json.loads(resources.files("pytellybox").joinpath("admin_state.json").read_text(encoding="utf-8"))
+
+
+def _json_error(status: int, detail: str) -> web.Response:
+    return web.json_response({"detail": detail}, status=status)
+
+
+class MockTellybox:
+    """A scripted Tellybox. `tokens` may control; `read_tokens` may only read (403 on an override)."""
+
+    def __init__(
+        self, state: dict[str, Any] | None = None, *, token: str = "tbx_mock", read_tokens: Iterable[str] = (),
+        keepalive_s: float = 15.0,
+    ) -> None:
+        self.tokens: set[str] = {token}
+        self.read_tokens: set[str] = set(read_tokens)
+        self.keepalive_s = keepalive_s
+        self.calls: list[dict[str, Any]] = []
+        self._state: dict[str, Any] = copy.deepcopy(state) if state is not None else default_state()
+        self._subscribers: set[asyncio.Queue[str | None]] = set()
+        self._runner: web.AppRunner | None = None
+        self.app = web.Application(middlewares=[self._record, self._auth])
+        self.app.on_shutdown.append(self._close_streams)
+        self.app.add_routes([
+            web.get("/api/info", self._info),
+            web.get("/api/admin/state", self._get_state),
+            web.get("/api/admin/events", self._events),
+            web.post("/api/admin/overrides/extra", self._extra),
+            web.post("/api/admin/overrides/unlimited", self._unlimited),
+            web.post("/api/admin/overrides/block", self._block),
+            web.post("/api/admin/overrides/stop", self._stop),
+            web.delete("/api/admin/overrides/today", self._clear),
+            web.get("/api/kid/profiles", self._kid_profiles),
+            web.get("/api/kid/home", self._kid_home),
+            web.get("/api/kid/shows/{show_id}", self._kid_show),
+            web.get("/api/kid/state", self._kid_state),
+            web.post("/api/kid/play", self._kid_play),
+            web.post("/api/kid/pause", self._kid_pause),
+            web.post("/api/kid/resume", self._kid_resume),
+            web.get("/img/{kind}/{item}.jpg", self._image),
+        ])
+
+    # ------------------------------------------------------------------ driving the mock
+
+    @property
+    def state(self) -> dict[str, Any]:
+        """The current AdminState payload (mutable; call `push()` after changing it)."""
+        return self._state
+
+    def set_state(self, state: dict[str, Any]) -> None:
+        """Replace the state and push it to the event streams."""
+        self._state = copy.deepcopy(state)
+        self.push()
+
+    def push(self) -> None:
+        """Send the current state to every open event stream."""
+        payload = json.dumps(self._state)
+        for queue in self._subscribers:
+            queue.put_nowait(payload)
+
+    async def start(self, host: str = "127.0.0.1", port: int = 0) -> str:
+        """Listen on host:port (0 = any free port) and return the base URL."""
+        self._runner = web.AppRunner(self.app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, host, port)
+        await site.start()
+        actual = self._runner.addresses[0][1]
+        return f"http://{host}:{actual}"
+
+    async def stop(self) -> None:
+        if self._runner is not None:
+            await self._runner.cleanup()
+            self._runner = None
+
+    # ------------------------------------------------------------------ middleware
+
+    @web.middleware
+    async def _record(self, request: web.Request, handler: Handler) -> web.StreamResponse:
+        entry: dict[str, Any] = {"method": request.method, "path": request.path, "query": dict(request.query),
+                                 "json": None}
+        entry["json"] = await self._json(request)
+        self.calls.append(entry)
+        return await handler(request)
+
+    @web.middleware
+    async def _auth(self, request: web.Request, handler: Handler) -> web.StreamResponse:
+        if request.path.startswith("/api/admin/"):
+            header = request.headers.get("Authorization", "")
+            token = header[7:] if header.startswith("Bearer ") else ""
+            if token not in self.tokens | self.read_tokens:
+                resp = _json_error(401, "unauthorized")
+                resp.headers["WWW-Authenticate"] = "Bearer"
+                return resp
+            if request.method != "GET" and token not in self.tokens:
+                return _json_error(403, "forbidden")
+        return await handler(request)
+
+    # ------------------------------------------------------------------ admin API
+
+    async def _info(self, request: web.Request) -> web.Response:
+        s = self._state
+        return web.json_response({"instance_id": s["instance_id"], "version": s["version"], "api": 1,
+                                  "capabilities": ["state", "events", "overrides", "profiles"]})
+
+    async def _get_state(self, request: web.Request) -> web.Response:
+        return web.json_response(self._state)
+
+    async def _events(self, request: web.Request) -> web.StreamResponse:
+        resp = web.StreamResponse(headers={"Content-Type": "text/event-stream", "Cache-Control": "no-cache"})
+        await resp.prepare(request)
+        queue: asyncio.Queue[str | None] = asyncio.Queue()
+        queue.put_nowait(json.dumps(self._state))
+        self._subscribers.add(queue)
+        try:
+            while True:
+                try:
+                    payload = await asyncio.wait_for(queue.get(), self.keepalive_s)
+                except TimeoutError:
+                    await resp.write(b": keepalive\n\n")
+                    continue
+                if payload is None:
+                    break
+                await resp.write(f"data: {payload}\n\n".encode())
+        except ConnectionResetError:
+            pass
+        finally:
+            self._subscribers.discard(queue)
+        return resp
+
+    async def _close_streams(self, app: web.Application) -> None:
+        for queue in list(self._subscribers):
+            queue.put_nowait(None)
+
+    async def _ids(self, request: web.Request, body: Any) -> list[int] | web.Response:
+        """The profiles an override applies to, or a 422 response."""
+        if not isinstance(body, dict):
+            return _json_error(422, "body must be a JSON object")
+        ids = body.get("profile_ids")
+        everyone = [p["id"] for p in self._state["profiles"]]
+        if ids is None:
+            return everyone
+        if (not isinstance(ids, list) or not 1 <= len(ids) <= 20 or len(set(ids)) != len(ids)
+                or not all(isinstance(i, int) and not isinstance(i, bool) for i in ids)):
+            return _json_error(422, "profile_ids must be 1-20 distinct ids")
+        if any(i not in everyone for i in ids):
+            return _json_error(422, "unknown profile id")
+        return ids
+
+    @staticmethod
+    async def _json(request: web.Request) -> Any:
+        """The JSON body; None when absent or malformed (`read()` caches, so it can run twice)."""
+        raw = await request.read()
+        try:
+            return json.loads(raw) if raw else None
+        except ValueError:
+            return None
+
+    async def _body(self, request: web.Request) -> Any:
+        """The JSON body of an override or kid POST; an empty body counts as `{}`, junk as None."""
+        raw = await request.read()
+        return {} if not raw else await self._json(request)
+
+    def _profiles(self, ids: list[int]) -> list[dict[str, Any]]:
+        return [p for p in self._state["profiles"] if p["id"] in ids]
+
+    def _refresh(self, watchers: list[int] | None = None) -> None:
+        """Recompute each profile and the group the way the timer would."""
+        state = self._state
+        for p in state["profiles"]:
+            if p["blocked"]:
+                p["remaining_s"], p["can_start"], p["reason"] = 0, False, "blocked"
+            elif p["unlimited"]:
+                p["remaining_s"], p["can_start"], p["reason"] = None, True, None
+            else:
+                left = max(p["allowance_s"] + (p["extra_s"] or 0) - (p["used_s"] or 0), 0)
+                p["remaining_s"], p["can_start"] = left, left > 0
+                p["reason"] = None if left > 0 else "allowance"
+            p["last_five"] = p["remaining_s"] is not None and 0 < p["remaining_s"] <= _LAST_FIVE_S
+        if watchers is None:
+            watchers = (state.get("now_playing") or {}).get("profile_ids", [])
+        group = [p for p in state["profiles"] if p["id"] in watchers]
+        if not group:
+            return
+        finite = [p["remaining_s"] for p in group if p["remaining_s"] is not None]
+        remaining = min(finite) if finite else None
+        blocked = any(p["blocked"] for p in group)
+        out = any(p["can_start"] is False for p in group)
+        g = state["group"]
+        g["remaining_s"] = remaining
+        g["time_up"] = out
+        g["last_five"] = remaining is not None and 0 < remaining <= _LAST_FIVE_S
+        g["reason"] = "blocked" if blocked else ("allowance" if out else None)
+        g["action"] = "stop_now" if blocked else ("finish_then_stop" if out else "continue")
+
+    def _stop_playback(self) -> None:
+        self._state["now_playing"] = None
+        for p in self._state["profiles"]:
+            p["watching"] = False
+
+    async def _apply(self, request: web.Request, change: Callable[[list[dict[str, Any]], Any], None],
+                     *, needs_ids: bool = True, body: Any = None) -> web.Response:
+        if body is None:
+            body = await self._body(request)
+        ids: list[int] | web.Response = await self._ids(request, body) if needs_ids else []
+        if isinstance(ids, web.Response):
+            return ids
+        watchers = list((self._state.get("now_playing") or {}).get("profile_ids", []))
+        change(self._profiles(ids), body)
+        self._refresh(watchers)
+        self.push()
+        return web.json_response(self._state)
+
+    async def _extra(self, request: web.Request) -> web.Response:
+        body = await self._body(request)
+        minutes = body.get("minutes") if isinstance(body, dict) else None
+        if isinstance(minutes, bool) or not isinstance(minutes, int) or not 1 <= minutes <= 240:
+            return _json_error(422, "minutes must be an integer from 1 to 240")
+
+        def change(profiles: list[dict[str, Any]], _: Any) -> None:
+            for p in profiles:
+                p["extra_s"] = (p["extra_s"] or 0) + minutes * 60
+
+        return await self._apply(request, change)
+
+    async def _unlimited(self, request: web.Request) -> web.Response:
+        def change(profiles: list[dict[str, Any]], _: Any) -> None:
+            for p in profiles:
+                p["unlimited"] = True
+
+        return await self._apply(request, change)
+
+    async def _block(self, request: web.Request) -> web.Response:
+        def change(profiles: list[dict[str, Any]], _: Any) -> None:
+            blocked = {p["id"] for p in profiles}
+            for p in profiles:
+                p["blocked"] = True
+            playing = self._state.get("now_playing")
+            if playing and blocked & set(playing["profile_ids"]):
+                self._stop_playback()
+
+        return await self._apply(request, change)
+
+    async def _stop(self, request: web.Request) -> web.Response:
+        return await self._apply(request, lambda _p, _b: self._stop_playback(), needs_ids=False)
+
+    async def _clear(self, request: web.Request) -> web.Response:
+        raw = request.query.get("profile_ids")
+        body: dict[str, Any] = {}
+        if raw:
+            try:
+                body["profile_ids"] = [int(i) for i in raw.split(",")]
+            except ValueError:
+                return _json_error(422, "bad profile_ids")
+
+        def change(profiles: list[dict[str, Any]], _: Any) -> None:
+            for p in profiles:
+                p["unlimited"] = p["blocked"] = False
+
+        return await self._apply(request, change, body=body)
+
+    # ------------------------------------------------------------------ kid API
+
+    def _group(self, request: web.Request) -> list[int] | web.Response:
+        raw = request.query.get("profiles")
+        everyone = [p["id"] for p in self._state["profiles"]]
+        if raw is None:
+            return everyone[:1]
+        try:
+            ids = [int(i) for i in raw.split(",")]
+        except ValueError:
+            return _json_error(400, "bad_profiles")
+        if not 1 <= len(ids) <= 20 or len(set(ids)) != len(ids) or any(i not in everyone for i in ids):
+            return _json_error(400, "bad_profiles")
+        return ids
+
+    def _kid_state_dict(self) -> dict[str, Any]:
+        s = self._state
+        playing = s.get("now_playing")
+        profiles = {}
+        for p in s["profiles"]:
+            allowance = p["allowance_s"] + (p["extra_s"] or 0)
+            fraction = None if p["remaining_s"] is None else round(p["remaining_s"] / allowance, 3) if allowance else 0
+            profiles[str(p["id"])] = {"fraction_left": fraction, "last_five": p["last_five"],
+                                      "unlimited": p["unlimited"], "time_up": p["can_start"] is False}
+        return {
+            "tv": "ok" if s["tv"]["reachable"] else "unreachable",
+            "now_playing": None if not playing else {
+                "episode_id": playing["episode_id"], "show_id": playing["show_id"],
+                "thumb": f"/img/episode/{playing['episode_id']}.jpg", "title": playing["title"],
+                "state": playing["state"]},
+            "watching": list(playing["profile_ids"]) if playing else [],
+            "sky": {"fraction_left": None, "last_five": s["group"]["last_five"], "unlimited": False},
+            "time_up": s["group"]["time_up"], "profiles": profiles, "day": s["day"]["date"],
+        }
+
+    @staticmethod
+    def _tile(episode_id: int) -> dict[str, Any]:
+        e = _EPISODES[episode_id]
+        return {"episode_id": episode_id, "show_id": e["show_id"], "thumb": f"/img/episode/{episode_id}.jpg",
+                "title": e["title"], "progress": None, "finished": False}
+
+    async def _kid_profiles(self, request: web.Request) -> web.Response:
+        return web.json_response([
+            {"profile_id": p["id"], "name": p["name"], "picture": None, "avatar": p["avatar"],
+             "time_up": p["can_start"] is False, "fraction_left": None, "last_five": p["last_five"],
+             "unlimited": p["unlimited"]}
+            for p in self._state["profiles"]])
+
+    async def _kid_home(self, request: web.Request) -> web.Response:
+        group = self._group(request)
+        if isinstance(group, web.Response):
+            return group
+        return web.json_response({
+            "continue": [{**self._tile(5), "kind": "next"}],
+            "shows": [{"show_id": i, "artwork": f"/img/show/{i}.jpg", "title": t} for i, t in _SHOWS.items()]})
+
+    async def _kid_show(self, request: web.Request) -> web.Response:
+        group = self._group(request)
+        if isinstance(group, web.Response):
+            return group
+        try:
+            show_id = int(request.match_info["show_id"])
+        except ValueError:
+            return _json_error(404, "not_found")
+        if show_id not in _SHOWS:
+            return _json_error(404, "not_found")
+        return web.json_response({
+            "show_id": show_id, "artwork": f"/img/show/{show_id}.jpg", "title": _SHOWS[show_id],
+            "episodes": [self._tile(i) for i, e in _EPISODES.items() if e["show_id"] == show_id]})
+
+    async def _kid_state(self, request: web.Request) -> web.Response:
+        return web.json_response(self._kid_state_dict())
+
+    async def _kid_play(self, request: web.Request) -> web.Response:
+        body = await self._body(request)
+        if not isinstance(body, dict):
+            return _json_error(400, "bad_request")
+        ids, episode_id = body.get("profile_ids"), body.get("episode_id")
+        everyone = [p["id"] for p in self._state["profiles"]]
+        if (not isinstance(ids, list) or not 1 <= len(ids) <= 20 or len(set(ids)) != len(ids)
+                or any(i not in everyone for i in ids)):
+            return _json_error(400, "bad_profiles")
+        if episode_id not in _EPISODES:
+            return _json_error(404, "not_found")
+        if not self._state["tv"]["reachable"]:
+            return web.json_response(self._kid_state_dict(), status=503)
+        if any(p["can_start"] is False for p in self._profiles(ids)):
+            return web.json_response(self._kid_state_dict(), status=409)
+        e = _EPISODES[episode_id]
+        self._state["now_playing"] = {
+            "episode_id": episode_id, "show_id": e["show_id"], "title": e["title"], "show": _SHOWS[e["show_id"]],
+            "state": "playing", "position_s": 0, "duration_s": e["duration_s"], "profile_ids": ids}
+        for p in self._state["profiles"]:
+            p["watching"] = p["id"] in ids
+        self._refresh(ids)
+        self.push()
+        return web.json_response(self._kid_state_dict())
+
+    async def _set_playback(self, state: str) -> web.Response:
+        if not self._state["tv"]["reachable"]:
+            return web.json_response(self._kid_state_dict(), status=503)
+        if self._state.get("now_playing"):
+            self._state["now_playing"]["state"] = state
+            self.push()
+        return web.json_response(self._kid_state_dict())
+
+    async def _kid_pause(self, request: web.Request) -> web.Response:
+        return await self._set_playback("paused")
+
+    async def _kid_resume(self, request: web.Request) -> web.Response:
+        return await self._set_playback("playing")
+
+    async def _image(self, request: web.Request) -> web.Response:
+        return web.Response(body=_PLACEHOLDER_IMAGE, content_type="image/gif")
+
+
+async def _serve(host: str, port: int, mock: MockTellybox) -> None:
+    url = await mock.start(host, port)
+    print(f"Mock Tellybox listening on {url}")  # noqa: T201
+    try:
+        await asyncio.Event().wait()
+    finally:
+        await mock.stop()
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="python -m pytellybox.mock", description="Run a mock Tellybox server.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8099)
+    parser.add_argument("--token", default="tbx_dev", help="token with the control scope")
+    parser.add_argument("--read-token", action="append", default=[], help="token with the read scope only")
+    parser.add_argument("--keepalive", type=float, default=15.0, help="seconds between SSE keepalives")
+    args = parser.parse_args(argv)
+    mock = MockTellybox(token=args.token, read_tokens=args.read_token, keepalive_s=args.keepalive)
+    try:
+        asyncio.run(_serve(args.host, args.port, mock))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

pytellybox/models.py

@@ -0,0 +1,267 @@
+"""Typed views of the Tellybox API payloads.
+
+Admin types follow Tellybox's `docs/admin-api.md` (API version 1); kid types follow `docs/kid-api.md`.
+Every `from_dict` tolerates unknown extra keys (newer servers) and keeps the original payload in `raw`
+where it matters, so callers can reach fields this version doesn't model yet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any
+
+LAST_FIVE_S = 300
+
+
+def _dt(value: str | None) -> datetime | None:
+    return datetime.fromisoformat(value) if value else None
+
+
+def _date(value: str | None) -> date | None:
+    return date.fromisoformat(value) if value else None
+
+
+# --------------------------------------------------------------------------- admin API
+
+
+@dataclass(frozen=True)
+class Info:
+    """`GET /api/info` (HA-6), no auth needed."""
+
+    instance_id: str
+    version: str
+    api: int
+    capabilities: tuple[str, ...]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Info:
+        return cls(d["instance_id"], d["version"], int(d["api"]), tuple(d.get("capabilities", ())))
+
+
+@dataclass(frozen=True)
+class Day:
+    date: date | None  # the timer day (WT-1); None before the first cast state
+    resets_at: datetime | None  # the next daily reset
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Day:
+        return cls(_date(d.get("date")), _dt(d.get("resets_at")))
+
+
+@dataclass(frozen=True)
+class TV:
+    connection: str  # the cast state's connection, or "unreachable" when the cast service is down
+    reachable: bool
+    device: str | None  # the Chromecast's name
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> TV:
+        return cls(d["connection"], bool(d["reachable"]), d.get("device"))
+
+
+@dataclass(frozen=True)
+class NowPlaying:
+    episode_id: int
+    show_id: int
+    title: str
+    show: str | None
+    state: str  # loading | playing | paused | buffering
+    position_s: int | None
+    duration_s: int | None
+    profile_ids: tuple[int, ...]
+
+    @property
+    def thumb_path(self) -> str:
+        """The episode thumbnail on the kid API (no auth): `/img/episode/{id}.jpg`."""
+        return f"/img/episode/{self.episode_id}.jpg"
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> NowPlaying:
+        return cls(
+            int(d["episode_id"]), int(d["show_id"]), d.get("title") or "", d.get("show"), d["state"],
+            d.get("position_s"), d.get("duration_s"), tuple(d.get("profile_ids") or ()),
+        )
+
+
+@dataclass(frozen=True)
+class Group:
+    """The current watchers, as the cast service's timer describes them."""
+
+    remaining_s: int | None  # None = all unlimited (or unknown)
+    time_up: bool
+    last_five: bool
+    action: str | None  # continue | finish_then_stop | stop_now
+    reason: str | None  # allowance | session_max | blocked
+    grace_ends_at: datetime | None
+    session_started_at: datetime | None
+    session_elapsed_s: int | None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Group:
+        return cls(
+            d.get("remaining_s"), bool(d.get("time_up")), bool(d.get("last_five")), d.get("action"),
+            d.get("reason"), _dt(d.get("grace_ends_at")), _dt(d.get("session_started_at")),
+            d.get("session_elapsed_s"),
+        )
+
+
+@dataclass(frozen=True)
+class Profile:
+    """One kid. Timer fields are None on a cold start, before Tellybox has seen the cast state."""
+
+    id: int
+    name: str
+    avatar: str | None
+    allowance_s: int
+    extra_s: int | None
+    used_s: int | None
+    remaining_s: int | None  # None = unlimited today (when `unlimited`) or unknown
+    unlimited: bool
+    blocked: bool
+    mode: str  # ignore_pauses | wall_clock
+    max_session_s: int | None
+    session_elapsed_s: int | None
+    can_start: bool | None
+    reason: str | None
+    watching: bool
+    last_five: bool
+
+    @property
+    def time_up(self) -> bool:
+        """This kid may not start a pick now (out of time, blocked or past the session max)."""
+        return self.can_start is False
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Profile:
+        return cls(
+            int(d["id"]), d["name"], d.get("avatar"), int(d["allowance_s"]), d.get("extra_s"), d.get("used_s"),
+            d.get("remaining_s"), bool(d.get("unlimited")), bool(d.get("blocked")), d.get("mode", "ignore_pauses"),
+            d.get("max_session_s"), d.get("session_elapsed_s"), d.get("can_start"), d.get("reason"),
+            bool(d.get("watching")), bool(d.get("last_five")),
+        )
+
+
+@dataclass(frozen=True)
+class Jobs:
+    queued: int
+    running: int
+    failed: int
+    held_ready: int  # downloads waiting for approval
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Jobs:
+        return cls(int(d.get("queued", 0)), int(d.get("running", 0)), int(d.get("failed", 0)),
+                   int(d.get("held_ready", 0)))
+
+
+@dataclass(frozen=True)
+class Disk:
+    media_bytes: int
+    free_bytes: int | None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Disk:
+        return cls(int(d.get("media_bytes", 0)), d.get("free_bytes"))
+
+
+@dataclass(frozen=True)
+class AdminState:
+    """`GET /api/admin/state`, each `/api/admin/events` event and every override response (HA-2)."""
+
+    instance_id: str
+    version: str
+    api: int
+    day: Day
+    tv: TV
+    now_playing: NowPlaying | None
+    group: Group
+    profiles: tuple[Profile, ...]  # in the admin's order
+    jobs: Jobs
+    disk: Disk
+    raw: dict[str, Any] = field(repr=False, compare=False, default_factory=dict)
+
+    def profile(self, profile_id: int) -> Profile | None:
+        return next((p for p in self.profiles if p.id == profile_id), None)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AdminState:
+        np = d.get("now_playing")
+        return cls(
+            d["instance_id"], d["version"], int(d.get("api", 1)), Day.from_dict(d.get("day") or {}),
+            TV.from_dict(d["tv"]), NowPlaying.from_dict(np) if np else None, Group.from_dict(d.get("group") or {}),
+            tuple(Profile.from_dict(p) for p in d.get("profiles", ())), Jobs.from_dict(d.get("jobs") or {}),
+            Disk.from_dict(d.get("disk") or {}), d,
+        )
+
+
+# --------------------------------------------------------------------------- kid API (browse and play)
+
+
+@dataclass(frozen=True)
+class KidProfile:
+    """`GET /api/kid/profiles` item."""
+
+    profile_id: int
+    name: str
+    picture: str | None  # path of the uploaded photo, e.g. /img/profile/1.jpg
+    avatar: str | None  # built-in avatar key: /static/avatars/{avatar}.svg
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> KidProfile:
+        return cls(int(d["profile_id"]), d["name"], d.get("picture"), d.get("avatar"))
+
+
+@dataclass(frozen=True)
+class Tile:
+    episode_id: int
+    show_id: int
+    thumb: str  # path, e.g. /img/episode/4.jpg
+    title: str
+    progress: float | None
+    finished: bool
+    kind: str | None = None  # resume | next (continue watching only)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Tile:
+        return cls(int(d["episode_id"]), int(d["show_id"]), d["thumb"], d.get("title") or "", d.get("progress"),
+                   bool(d.get("finished")), d.get("kind"))
+
+
+@dataclass(frozen=True)
+class ShowRef:
+    show_id: int
+    artwork: str  # path, e.g. /img/show/2.jpg
+    title: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ShowRef:
+        return cls(int(d["show_id"]), d["artwork"], d.get("title") or "")
+
+
+@dataclass(frozen=True)
+class Home:
+    """`GET /api/kid/home`."""
+
+    continue_watching: tuple[Tile, ...]
+    shows: tuple[ShowRef, ...]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Home:
+        return cls(tuple(Tile.from_dict(t) for t in d.get("continue", ())),
+                   tuple(ShowRef.from_dict(s) for s in d.get("shows", ())))
+
+
+@dataclass(frozen=True)
+class Show:
+    """`GET /api/kid/shows/{id}`."""
+
+    show_id: int
+    artwork: str
+    title: str
+    episodes: tuple[Tile, ...]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Show:
+        return cls(int(d["show_id"]), d["artwork"], d.get("title") or "",
+                   tuple(Tile.from_dict(t) for t in d.get("episodes", ())))

pytellybox-0.1.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: pytellybox
+Version: 0.1.0
+Summary: Async client for the Tellybox admin and kid APIs (used by the Home Assistant integration)
+Project-URL: Homepage, https://github.com/sandermvanvliet/pytellybox
+Project-URL: Tellybox, https://github.com/sandermvanvliet/Tellybox
+Author: Sander van Vliet
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Provides-Extra: test
+Requires-Dist: aioresponses>=0.7; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pytellybox
+
+An async Python client for [Tellybox](https://github.com/sandermvanvliet/Tellybox), the self-hosted app that lets young kids pick parent-approved videos for the TV within a daily time allowance. It is the library behind the [Home Assistant integration](https://github.com/sandermvanvliet/ha-tellybox).
+
+- **Admin API** (bearer token from Tellybox's *Integrations* page): live state and its event stream, and the parent overrides (extra time, unlimited today, block today, stop now, clear today) for everyone or for chosen kids.
+- **Kid API** (no token): browse shows and episodes, play, pause and resume. A play is refused when someone is out of time, because Tellybox's timer always decides.
+
+```python
+import aiohttp
+from pytellybox import TellyboxClient
+
+async with aiohttp.ClientSession() as session:
+    tellybox = TellyboxClient("https://tellybox.example", "tbx_…", session)
+    state = await tellybox.state()
+    for kid in state.profiles:
+        print(kid.name, kid.remaining_s)
+    await tellybox.add_time(15, profile_ids=[1])
+    async for state in tellybox.events():  # the current state first, then one per change
+        print(state.group.remaining_s)
+```
+
+For development without a Tellybox, run the mock server: `python -m pytellybox.mock --port 8099 --token tbx_dev` (add `--read-token tbx_ro` for a read-only token). Tests can use `MockTellybox` from `pytellybox.mock` with aiohttp's `TestServer`.
+
+The API contract is Tellybox's [`docs/admin-api.md`](https://github.com/sandermvanvliet/Tellybox/blob/main/docs/admin-api.md) and [`docs/kid-api.md`](https://github.com/sandermvanvliet/Tellybox/blob/main/docs/kid-api.md). Tellybox is for the LAN and Tailscale only; use HTTPS behind your reverse proxy, and keep tokens out of logs.
+
+## Development
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/python -m pytest -q
+```
+
+Releases are published to PyPI by GitHub Actions when a `v*` tag is pushed (trusted publishing).
+
+Licensed under Apache-2.0.

pytellybox-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pytellybox/__init__.py,sha256=v2oUAgGnBdVCXWrMlyS1zkV0OiwkT-CcsAiR0oEXR48,1008
+pytellybox/admin_state.json,sha256=DyunpjBoi4iEVIT6Ktr7SgmLrgCUJPALxAd1M5EPGRY,1454
+pytellybox/client.py,sha256=ZyPPTg2-iMqVTG6TJma-BPBJtiNH9gdBk7xZdwmJ0Oo,10642
+pytellybox/errors.py,sha256=hLe23ExMOzY32qXn7ZpWk89lv4GbTObNsQKbRNGCZr4,1159
+pytellybox/mock.py,sha256=O3dGPkQSQUA-SQpvZYRuWHyqlLLPSrJfkvnNPg5neu4,20462
+pytellybox/models.py,sha256=tg4gD4Tl0a-i9EDqKM0uXtsZ88iz9k26zwdz9osuqMo,8281
+pytellybox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytellybox-0.1.0.dist-info/METADATA,sha256=LLb4cJcauQDCUaQ57evi-KzuMRIetXv63pUtdf0ZSGA,2825
+pytellybox-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pytellybox-0.1.0.dist-info/licenses/LICENSE,sha256=_DMpHboiA8TTPB3jrnYlmyWoJFhBCXXoYXKnGmQyiI8,11347
+pytellybox-0.1.0.dist-info/RECORD,,

pytellybox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pytellybox-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sander van Vliet
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+