pycellarion 0.1.0__tar.gz

pycellarion-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Keeps the pinned actions current.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly

pycellarion-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e ".[test]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+
+  tests:
+    name: tests (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[test]"
+      - run: pytest -q --cov --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

pycellarion-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+# Runs when a GitHub release is published. Uses PyPI trusted publishing
+# (OpenID Connect): no API token is stored anywhere. The PyPI project must
+# list this repository + workflow as a trusted publisher first.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1, 2026-09

pycellarion-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+.venv/

pycellarion-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jagduvi1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycellarion-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: pycellarion
+Version: 0.1.0
+Summary: Async client for the Cellarion wine-cellar API
+Project-URL: Homepage, https://github.com/jagduvi1/pycellarion
+Project-URL: Issues, https://github.com/jagduvi1/pycellarion/issues
+Project-URL: Cellarion, https://cellarion.app
+Author: Johan Eklund
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,cellar,cellarion,home-assistant,wine
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: test
+Requires-Dist: mypy>=1.11; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pycellarion
+
+[![PyPI](https://img.shields.io/pypi/v/pycellarion)](https://pypi.org/project/pycellarion/)
+[![CI](https://github.com/jagduvi1/pycellarion/actions/workflows/ci.yml/badge.svg)](https://github.com/jagduvi1/pycellarion/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Async Python client for the [Cellarion](https://cellarion.app) wine-cellar
+API. It is the library behind the
+[Home Assistant integration](https://github.com/jagduvi1/ha-cellarion), and
+usable on its own by anything that wants to read a cellar or mark a bottle
+as consumed.
+
+- **Async, typed, small.** One dependency (`aiohttp`), `py.typed`, no I/O
+  outside the calls you make.
+- **Two credentials.** A personal API token (`cel_…`, created in Cellarion
+  under *Settings → API tokens*), or email and password used once to mint
+  such a token. Passwords are never kept beyond the login they were given for.
+- **Push events.** Parses the server's `text/event-stream` and yields event
+  names, so callers can refresh on change instead of polling.
+- **Honest errors.** Status codes map to a small exception hierarchy:
+  `CellarionAuthError` (re-authenticate), `CellarionScopeError` (the token
+  lacks a scope), `CellarionTokensNotSupported` and
+  `CellarionPushNotSupported` (older servers), `CellarionPushForbidden`,
+  and `CellarionApiError` for everything else.
+
+## Install
+
+```bash
+pip install pycellarion
+```
+
+## Use
+
+```python
+import aiohttp
+from pycellarion import CellarionClient
+
+async with aiohttp.ClientSession() as session:
+    client = CellarionClient(session, "https://cellarion.app", token="cel_…")
+
+    stats = await client.get_stats_overview()
+    print(stats["stats"]["overview"]["totalBottles"])
+
+    async for event in client.events_stream():
+        if event == "_connected":
+            continue
+        print("something changed:", event)
+```
+
+Minting a token from email and password:
+
+```python
+client = CellarionClient(session, "https://cellarion.app", "me@example.com", "secret")
+await client.authenticate()
+token = await client.async_create_api_token("My script", ["read", "consume"])
+# keep `token`; the password is not needed again
+```
+
+## API
+
+| Method | Purpose |
+|---|---|
+| `authenticate()` | Log in with email and password (session JWT); raises `CellarionAuthError` on bad credentials |
+| `async_create_api_token(name, scopes)` | Mint a personal API token (password login required) |
+| `get_stats_overview()` / `get_cellars()` / `get_notifications()` / `get_peak_bottles(limit)` / `get_health()` | Reads |
+| `get_account_id()` | Stable account id from `/api/auth/whoami`, or `None` on servers without it |
+| `consume_bottle(bottle_id, reason, rating, note)` | Mark a bottle as consumed |
+| `events_stream()` | Async iterator of push event names; yields `"_connected"` first |
+| `revoke_own_token()` | Ask the server to revoke the client's own API token (Cellarion 1.220+) |
+
+Responses are returned as plain `dict`s (`JsonDict`); bodies over
+`MAX_BODY_BYTES` (4 MiB) are refused.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+ruff check . && ruff format --check . && mypy src
+pytest --cov
+```
+
+Releases are published to PyPI from GitHub releases through
+[trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+## License
+
+MIT

pycellarion-0.1.0/README.md

@@ -0,0 +1,87 @@
+# pycellarion
+
+[![PyPI](https://img.shields.io/pypi/v/pycellarion)](https://pypi.org/project/pycellarion/)
+[![CI](https://github.com/jagduvi1/pycellarion/actions/workflows/ci.yml/badge.svg)](https://github.com/jagduvi1/pycellarion/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Async Python client for the [Cellarion](https://cellarion.app) wine-cellar
+API. It is the library behind the
+[Home Assistant integration](https://github.com/jagduvi1/ha-cellarion), and
+usable on its own by anything that wants to read a cellar or mark a bottle
+as consumed.
+
+- **Async, typed, small.** One dependency (`aiohttp`), `py.typed`, no I/O
+  outside the calls you make.
+- **Two credentials.** A personal API token (`cel_…`, created in Cellarion
+  under *Settings → API tokens*), or email and password used once to mint
+  such a token. Passwords are never kept beyond the login they were given for.
+- **Push events.** Parses the server's `text/event-stream` and yields event
+  names, so callers can refresh on change instead of polling.
+- **Honest errors.** Status codes map to a small exception hierarchy:
+  `CellarionAuthError` (re-authenticate), `CellarionScopeError` (the token
+  lacks a scope), `CellarionTokensNotSupported` and
+  `CellarionPushNotSupported` (older servers), `CellarionPushForbidden`,
+  and `CellarionApiError` for everything else.
+
+## Install
+
+```bash
+pip install pycellarion
+```
+
+## Use
+
+```python
+import aiohttp
+from pycellarion import CellarionClient
+
+async with aiohttp.ClientSession() as session:
+    client = CellarionClient(session, "https://cellarion.app", token="cel_…")
+
+    stats = await client.get_stats_overview()
+    print(stats["stats"]["overview"]["totalBottles"])
+
+    async for event in client.events_stream():
+        if event == "_connected":
+            continue
+        print("something changed:", event)
+```
+
+Minting a token from email and password:
+
+```python
+client = CellarionClient(session, "https://cellarion.app", "me@example.com", "secret")
+await client.authenticate()
+token = await client.async_create_api_token("My script", ["read", "consume"])
+# keep `token`; the password is not needed again
+```
+
+## API
+
+| Method | Purpose |
+|---|---|
+| `authenticate()` | Log in with email and password (session JWT); raises `CellarionAuthError` on bad credentials |
+| `async_create_api_token(name, scopes)` | Mint a personal API token (password login required) |
+| `get_stats_overview()` / `get_cellars()` / `get_notifications()` / `get_peak_bottles(limit)` / `get_health()` | Reads |
+| `get_account_id()` | Stable account id from `/api/auth/whoami`, or `None` on servers without it |
+| `consume_bottle(bottle_id, reason, rating, note)` | Mark a bottle as consumed |
+| `events_stream()` | Async iterator of push event names; yields `"_connected"` first |
+| `revoke_own_token()` | Ask the server to revoke the client's own API token (Cellarion 1.220+) |
+
+Responses are returned as plain `dict`s (`JsonDict`); bodies over
+`MAX_BODY_BYTES` (4 MiB) are refused.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+ruff check . && ruff format --check . && mypy src
+pytest --cov
+```
+
+Releases are published to PyPI from GitHub releases through
+[trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+## License
+
+MIT

pycellarion-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pycellarion"
+version = "0.1.0"
+description = "Async client for the Cellarion wine-cellar API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Johan Eklund" }]
+keywords = ["cellarion", "wine", "cellar", "home-assistant", "asyncio"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/jagduvi1/pycellarion"
+Issues = "https://github.com/jagduvi1/pycellarion/issues"
+Cellarion = "https://cellarion.app"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-cov>=5", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pycellarion"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["pycellarion"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "ASYNC", "D"]
+ignore = ["E501", "D203", "D213", "D105", "D107"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true

pycellarion-0.1.0/src/pycellarion/__init__.py

@@ -0,0 +1,26 @@
+"""pycellarion — async client for the Cellarion wine-cellar API."""
+
+from .client import MAX_BODY_BYTES, CellarionClient, JsonDict
+from .exceptions import (
+    CellarionApiError,
+    CellarionAuthError,
+    CellarionPushForbidden,
+    CellarionPushNotSupported,
+    CellarionScopeError,
+    CellarionTokensNotSupported,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MAX_BODY_BYTES",
+    "CellarionApiError",
+    "CellarionAuthError",
+    "CellarionClient",
+    "CellarionPushForbidden",
+    "CellarionPushNotSupported",
+    "CellarionScopeError",
+    "CellarionTokensNotSupported",
+    "JsonDict",
+    "__version__",
+]

pycellarion-0.1.0/src/pycellarion/client.py

@@ -0,0 +1,390 @@
+"""Async client for the Cellarion wine-cellar API.
+
+The client is deliberately thin: it maps HTTP status codes to a small
+exception hierarchy, retries one expired session once, parses the
+server-sent event stream, and returns JSON objects as plain dicts.
+It never stores a password beyond the login it was created for.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+from urllib.parse import quote
+
+import aiohttp
+
+from .exceptions import (
+    CellarionApiError,
+    CellarionAuthError,
+    CellarionPushForbidden,
+    CellarionPushNotSupported,
+    CellarionScopeError,
+    CellarionTokensNotSupported,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+JsonDict = dict[str, Any]
+
+# Largest response body the client will read. The stats and bottle lists the
+# integration asks for are a few kilobytes; anything past this is a proxy
+# error page or a misbehaving server, not data worth holding in memory.
+MAX_BODY_BYTES = 4 * 1024 * 1024
+
+
+async def _read_json(resp: aiohttp.ClientResponse, what: str) -> JsonDict:
+    """Decode a JSON object body, mapping a non-JSON answer to an API error.
+
+    A reverse proxy or SPA fallback can answer a 200 with an HTML page; that
+    must surface as a normal (retryable) API error, not an unhandled
+    exception that marks the whole update as "unexpected".
+    """
+    try:
+        data = await resp.json()
+    except (aiohttp.ClientError, ValueError) as err:
+        raise CellarionApiError(f"{what} response was not JSON") from err
+    return data if isinstance(data, dict) else {}
+
+
+class CellarionClient:
+    """Async API client for Cellarion."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        email: str | None = None,
+        password: str | None = None,
+        token: str | None = None,
+    ) -> None:
+        self._session = session
+        self._url = url.rstrip("/")
+        self._email = email
+        self._password = password
+        # Personal API token (cel_...) — static, never refreshed via login
+        self._api_token = token
+        self._token: str | None = token
+
+    async def authenticate(self) -> bool:
+        """Authenticate and store JWT token."""
+        if self._api_token:
+            # Static API token: there is nothing to refresh. Reaching this
+            # means the server rejected it — revoked or invalid.
+            raise CellarionAuthError("API token rejected (revoked or invalid)")
+
+        login_url = f"{self._url}/api/auth/login"
+        _LOGGER.debug("Authenticating to %s", login_url)
+        try:
+            resp = await self._session.post(
+                login_url,
+                # The Cellarion login endpoint takes "username", which matches
+                # against both username and email.
+                json={"username": self._email, "password": self._password},
+                timeout=aiohttp.ClientTimeout(total=15),
+                # Never re-send the password body to a redirect target
+                allow_redirects=False,
+            )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            _LOGGER.error("Connection to %s failed: %s", login_url, err)
+            raise CellarionApiError(f"Connection failed: {err}") from err
+
+        if 300 <= resp.status < 400:
+            raise CellarionApiError(
+                f"Login was redirected (status {resp.status}); configure the final instance URL"
+            )
+        if resp.status in (400, 401):
+            raise CellarionAuthError("Invalid email or password")
+        if resp.status == 403:
+            raise CellarionAuthError("Account not verified or access denied")
+        if resp.status == 429:
+            raise CellarionApiError("Rate limited by Cellarion, try again later")
+        if resp.status != 200:
+            raise CellarionApiError(f"Login failed with status {resp.status}")
+
+        data = await _read_json(resp, "Login")
+        self._token = data.get("token")
+        if not self._token:
+            raise CellarionApiError("No token in login response")
+        return True
+
+    async def _send(self, method: str, path: str, json: JsonDict | None) -> aiohttp.ClientResponse:
+        """Issue one request, mapping transport errors to CellarionApiError."""
+        try:
+            return await self._session.request(
+                method,
+                f"{self._url}{path}",
+                headers={"Authorization": f"Bearer {self._token}"},
+                json=json,
+                timeout=aiohttp.ClientTimeout(total=30),
+            )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise CellarionApiError(f"Request failed: {err}") from err
+
+    async def _request(self, method: str, path: str, json: JsonDict | None = None) -> JsonDict:
+        """Make an authenticated API request with auto-retry on 401."""
+        if not self._token:
+            await self.authenticate()
+
+        resp = await self._send(method, path, json)
+        # Always release the connection back to the pool, even on error paths.
+        try:
+            if resp.status == 401:
+                # Token expired — re-authenticate and retry once
+                _LOGGER.debug("Token expired, re-authenticating")
+                resp.close()
+                await self.authenticate()
+                resp = await self._send(method, path, json)
+                if resp.status == 401:
+                    raise CellarionAuthError("Authentication rejected after retry")
+
+            if resp.status == 403 and self._api_token:
+                # Valid token, missing scope — a config error; re-login won't help
+                raise CellarionScopeError(f"API token lacks the scope for {method} {path}")
+
+            # Accept the 2xx success range: action endpoints (e.g. consume) may
+            # answer 201/204 rather than 200.
+            if not 200 <= resp.status < 300:
+                detail = ""
+                try:
+                    detail = (await resp.json()).get("error", "")
+                except Exception:  # best-effort error body
+                    detail = ""
+                raise CellarionApiError(
+                    f"{method} {path} returned status {resp.status}"
+                    + (f": {detail}" if detail else "")
+                )
+
+            # getattr keeps this working against test doubles that don't
+            # implement content_length; real aiohttp always provides it.
+            length = getattr(resp, "content_length", None)
+            if resp.status == 204 or length == 0:
+                return {}
+            if length is not None and length > MAX_BODY_BYTES:
+                raise CellarionApiError(
+                    f"{method} {path} answered with {length} bytes; refusing to read it"
+                )
+            try:
+                data = await resp.json()
+            except (aiohttp.ClientError, ValueError):
+                # No/!JSON body on a success status — nothing to return
+                return {}
+            return data if isinstance(data, dict) else {}
+        finally:
+            resp.close()
+
+    async def get_stats_overview(self) -> JsonDict:
+        """Fetch collection statistics."""
+        return await self._request("GET", "/api/stats/overview")
+
+    async def get_cellars(self) -> JsonDict:
+        """Fetch user's cellars."""
+        return await self._request("GET", "/api/cellars")
+
+    async def get_account_id(self) -> str | None:
+        """Return a stable account id for the credential, or None.
+
+        Reads the scoped identity endpoint /api/auth/whoami, which returns
+        just {"id": ...}. Returns None when the server or credential can't
+        provide one — an older server without the endpoint (404), or a token
+        whose scope doesn't include it (403). Callers treat None as "unknown"
+        and skip the check, never as an error. The nested "user" fallback keeps
+        it working against the fuller /api/auth/me shape too.
+        """
+        try:
+            data = await self._request("GET", "/api/auth/whoami")
+        except CellarionApiError:
+            return None
+        user = data.get("user")
+        user = user if isinstance(user, dict) else {}
+        account_id = data.get("id") or user.get("id") or user.get("_id")
+        return str(account_id) if account_id else None
+
+    async def get_notifications(self) -> JsonDict:
+        """Fetch notifications with unread count."""
+        return await self._request("GET", "/api/notifications")
+
+    async def async_create_api_token(self, name: str, scopes: list[str]) -> str:
+        """Mint a personal API token. Requires password-based login.
+
+        The Cellarion endpoint requires the account password in the body as
+        confirmation; the caller stores only the returned token.
+        """
+        if not self._password:
+            raise CellarionApiError("Password login required to mint a token")
+        if not self._token:
+            await self.authenticate()
+
+        try:
+            resp = await self._session.post(
+                f"{self._url}/api/tokens",
+                headers={"Authorization": f"Bearer {self._token}"},
+                json={
+                    "name": name,
+                    "scopes": scopes,
+                    "password": self._password,
+                },
+                timeout=aiohttp.ClientTimeout(total=15),
+                allow_redirects=False,
+            )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise CellarionApiError(f"Token creation failed: {err}") from err
+
+        if 300 <= resp.status < 400:
+            raise CellarionApiError(
+                f"Token creation was redirected (status {resp.status}); "
+                "configure the final instance URL"
+            )
+        if resp.status in (404, 405, 501):
+            raise CellarionTokensNotSupported("Server does not support API tokens")
+        if resp.status in (401, 403):
+            raise CellarionAuthError("Password confirmation rejected")
+        if resp.status == 429:
+            raise CellarionApiError("Rate limited by Cellarion, try again later")
+        if resp.status not in (200, 201):
+            raise CellarionApiError(f"Token creation returned status {resp.status}")
+
+        data = await _read_json(resp, "Token creation")
+        token = data.get("token")
+        if not token:
+            raise CellarionApiError("No token in creation response")
+        return str(token)
+
+    async def get_peak_bottles(self, limit: int = 10) -> JsonDict:
+        """Fetch bottles currently in their peak drink window."""
+        return await self._request("GET", f"/api/bottles?maturity=peak&limit={int(limit)}")
+
+    async def consume_bottle(
+        self,
+        bottle_id: str,
+        reason: str = "drank",
+        rating: float | None = None,
+        note: str | None = None,
+    ) -> JsonDict:
+        """Mark a bottle as consumed (drank/gifted/sold/other)."""
+        body: JsonDict = {"reason": reason}
+        if rating is not None:
+            body["rating"] = rating
+        if note:
+            body["note"] = note
+        # The id is validated upstream; quoting keeps a stray "/", "?" or "#"
+        # from steering the request to another path regardless.
+        return await self._request(
+            "POST", f"/api/bottles/{quote(bottle_id, safe='')}/consume", json=body
+        )
+
+    async def events_stream(self) -> AsyncIterator[str]:
+        """Yield push event names from the server's SSE stream.
+
+        Yields the sentinel "_connected" once the stream is open, then one
+        item per server-sent event. Raises CellarionPushNotSupported when
+        the server has no stream endpoint (integration falls back to
+        polling only).
+        """
+        if not self._token:
+            await self.authenticate()
+
+        url = f"{self._url}/api/events/stream"
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "text/event-stream",
+        }
+        # sock_read=90 → three missed 25s server heartbeats = dead stream
+        timeout = aiohttp.ClientTimeout(total=None, connect=15, sock_read=90)
+
+        try:
+            resp = await self._session.get(url, headers=headers, timeout=timeout)
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise CellarionApiError(f"Push stream connection failed: {err}") from err
+
+        if resp.status == 401:
+            resp.close()
+            await self.authenticate()
+            headers["Authorization"] = f"Bearer {self._token}"
+            try:
+                resp = await self._session.get(url, headers=headers, timeout=timeout)
+            except (aiohttp.ClientError, TimeoutError) as err:
+                raise CellarionApiError(f"Push stream retry failed: {err}") from err
+            if resp.status == 401:
+                resp.close()
+                raise CellarionAuthError("Push stream rejected credentials")
+
+        if resp.status == 403:
+            # API token without the 'read' scope — a configuration error the
+            # user must fix; retrying or falling back silently would hide it
+            resp.close()
+            raise CellarionPushForbidden("Credential lacks the 'read' scope for the event stream")
+        if resp.status in (404, 405, 501):
+            resp.close()
+            raise CellarionPushNotSupported("Server has no /api/events/stream")
+        if resp.status != 200:
+            status = resp.status
+            resp.close()
+            raise CellarionApiError(f"Push stream returned status {status}")
+        if not resp.content_type.startswith("text/event-stream"):
+            # A proxy or SPA fallback answered instead of the stream route
+            resp.close()
+            raise CellarionPushNotSupported(f"Expected text/event-stream, got {resp.content_type}")
+
+        try:
+            yield "_connected"
+            event_name: str | None = None
+            async for raw in resp.content:
+                line = raw.decode("utf-8", "ignore").rstrip("\r\n")
+                if not line:
+                    if event_name:
+                        yield event_name
+                    event_name = None
+                    continue
+                if line.startswith(":"):  # heartbeat comment
+                    continue
+                if line.startswith("event:"):
+                    event_name = line[6:].strip()
+                elif line.startswith("data:") and event_name is None:
+                    event_name = "message"
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise CellarionApiError(f"Push stream read failed: {err}") from err
+        except ValueError as err:
+            # aiohttp raises ValueError for a line over its 64 KiB limit —
+            # a proxy error page mid-stream, not a transport error
+            raise CellarionApiError(f"Push stream sent malformed data: {err}") from err
+        finally:
+            resp.close()
+
+    async def revoke_own_token(self) -> bool:
+        """Ask the server to revoke the API token this client authenticates with.
+
+        Best effort, never raises: this runs while the integration is being
+        deleted, and nothing the user can do at that point would change the
+        outcome. Returns True when the token is gone — a 200 (revoked now) or
+        a 401 (already revoked or invalid). Anything else means it may still
+        be valid: a 403 from a server older than Cellarion 1.220 that has no
+        self-revoke route, or an outage. Password-based clients have no token
+        of their own and return False.
+        """
+        if not self._api_token:
+            return False
+        try:
+            resp = await self._send("DELETE", "/api/tokens/self", None)
+        except CellarionApiError as err:
+            _LOGGER.debug("Token self-revocation failed: %s", err)
+            return False
+        try:
+            if resp.status in (200, 401):
+                return True
+            _LOGGER.debug("Token self-revocation answered %s", resp.status)
+            return False
+        finally:
+            resp.close()
+
+    async def get_health(self) -> JsonDict:
+        """Fetch service health (no auth required, but we use it anyway)."""
+        try:
+            resp = await self._session.get(
+                f"{self._url}/api/health",
+                timeout=aiohttp.ClientTimeout(total=10),
+            )
+            return await _read_json(resp, "Health")
+        except (aiohttp.ClientError, TimeoutError, CellarionApiError):
+            return {"status": "unreachable"}

pycellarion-0.1.0/src/pycellarion/exceptions.py

@@ -0,0 +1,27 @@
+"""Exceptions raised by the Cellarion client."""
+
+from __future__ import annotations
+
+
+class CellarionApiError(Exception):
+    """Base exception for Cellarion API errors."""
+
+
+class CellarionAuthError(CellarionApiError):
+    """Authentication failed."""
+
+
+class CellarionPushNotSupported(CellarionApiError):
+    """The server does not offer the push event stream."""
+
+
+class CellarionPushForbidden(CellarionApiError):
+    """The credential lacks the scope required for the push stream."""
+
+
+class CellarionScopeError(CellarionApiError):
+    """The API token is valid but lacks a required scope."""
+
+
+class CellarionTokensNotSupported(CellarionApiError):
+    """The server does not support personal API tokens."""

pycellarion-0.1.0/tests/test_client.py

@@ -0,0 +1,441 @@
+"""Tests for the client: stream parser, retries, error mapping, self-revocation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+import aiohttp
+import pytest
+
+from pycellarion import (
+    CellarionApiError,
+    CellarionAuthError,
+    CellarionClient,
+    CellarionPushForbidden,
+    CellarionPushNotSupported,
+    CellarionScopeError,
+    CellarionTokensNotSupported,
+)
+
+BASE_URL = "http://cellarion.local"
+TEST_TOKEN = "cel_" + "a" * 64
+
+
+class FakeResponse:
+    """Just enough of aiohttp.ClientResponse for the client."""
+
+    def __init__(
+        self,
+        status: int = 200,
+        json: Any = None,
+        *,
+        content_type: str = "application/json",
+        lines: Iterable[bytes] = (),
+        read_error: Exception | None = None,
+        content_length: int | None = None,
+    ) -> None:
+        self.status = status
+        self._json = json
+        self.content_type = content_type
+        self._lines = list(lines)
+        self._read_error = read_error
+        self.content_length = content_length
+        self.closed = False
+
+    async def json(self) -> Any:
+        if self._json is None:
+            raise ValueError("not json")
+        return self._json
+
+    def close(self) -> None:
+        self.closed = True
+
+    @property
+    def content(self) -> FakeResponse:
+        return self
+
+    def __aiter__(self) -> FakeResponse:
+        self._iter = iter(self._lines)
+        return self
+
+    async def __anext__(self) -> bytes:
+        try:
+            return next(self._iter)
+        except StopIteration:
+            if self._read_error:
+                err, self._read_error = self._read_error, None
+                raise err from None
+            raise StopAsyncIteration from None
+
+
+class FakeSession:
+    """Hands out scripted responses in order and records every call."""
+
+    def __init__(self, responses: Iterable[FakeResponse | Exception]) -> None:
+        self._responses = list(responses)
+        self.calls: list[tuple[str, str, dict[str, Any]]] = []
+
+    def _next(self, method: str, url: str, kwargs: dict[str, Any]) -> FakeResponse:
+        self.calls.append((method, url, kwargs))
+        item = self._responses.pop(0)
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> FakeResponse:
+        return self._next(method, url, kwargs)
+
+    async def get(self, url: str, **kwargs: Any) -> FakeResponse:
+        return self._next("GET", url, kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> FakeResponse:
+        return self._next("POST", url, kwargs)
+
+
+def token_client(*responses: FakeResponse | Exception) -> tuple[CellarionClient, FakeSession]:
+    session = FakeSession(responses)
+    return CellarionClient(session, BASE_URL, token=TEST_TOKEN), session  # type: ignore[arg-type]
+
+
+def password_client(
+    *responses: FakeResponse | Exception,
+) -> tuple[CellarionClient, FakeSession]:
+    session = FakeSession(responses)
+    return CellarionClient(session, BASE_URL, "user@example.com", "pw"), session  # type: ignore[arg-type]
+
+
+SSE_BODY = [
+    b": heartbeat\n",
+    b"\n",
+    b"event: stats_changed\n",
+    b"data: {}\n",
+    b"\n",
+    b"data: bare-data-event\n",
+    b"\n",
+    b"event: ignored-without-blank-line\n",
+]
+
+
+async def collect(client: CellarionClient) -> list[str]:
+    return [event async for event in client.events_stream()]
+
+
+# ── SSE stream ───────────────────────────────────────────────────────
+
+
+async def test_stream_parses_events_and_heartbeats() -> None:
+    """Named events, bare data lines and heartbeats map to the right yields."""
+    client, session = token_client(
+        FakeResponse(200, content_type="text/event-stream", lines=SSE_BODY)
+    )
+    assert await collect(client) == ["_connected", "stats_changed", "message"]
+    assert session.calls[0][2]["headers"]["Accept"] == "text/event-stream"
+
+
+async def test_stream_401_relogs_once_for_password_clients() -> None:
+    """A rejected JWT triggers one login and a retry; a second 401 is fatal."""
+    client, session = password_client(
+        FakeResponse(200, {"token": "jwt-1"}),  # initial login
+        FakeResponse(401),  # stream rejects
+        FakeResponse(200, {"token": "jwt-2"}),  # re-login
+        FakeResponse(200, content_type="text/event-stream", lines=[]),
+    )
+    assert await collect(client) == ["_connected"]
+    assert session.calls[-1][2]["headers"]["Authorization"] == "Bearer jwt-2"
+
+    client, _ = password_client(
+        FakeResponse(200, {"token": "jwt-1"}),
+        FakeResponse(401),
+        FakeResponse(200, {"token": "jwt-2"}),
+        FakeResponse(401),
+    )
+    with pytest.raises(CellarionAuthError):
+        await collect(client)
+
+
+@pytest.mark.parametrize(
+    ("response", "expected"),
+    [
+        (FakeResponse(403), CellarionPushForbidden),
+        (FakeResponse(404), CellarionPushNotSupported),
+        (FakeResponse(501), CellarionPushNotSupported),
+        (FakeResponse(200, content_type="text/html"), CellarionPushNotSupported),
+        (FakeResponse(500), CellarionApiError),
+        (aiohttp.ClientError("down"), CellarionApiError),
+    ],
+)
+async def test_stream_status_mapping(response: Any, expected: type[Exception]) -> None:
+    """Every non-stream answer maps to the exception the listener expects."""
+    client, _ = token_client(response)
+    with pytest.raises(expected):
+        await collect(client)
+
+
+async def test_stream_read_errors_become_api_errors() -> None:
+    """Transport errors and over-long lines both surface as CellarionApiError."""
+    for err in (aiohttp.ClientPayloadError("cut"), ValueError("Line is too long")):
+        client, _ = token_client(
+            FakeResponse(
+                200,
+                content_type="text/event-stream",
+                lines=[b"event: a\n", b"\n"],
+                read_error=err,
+            )
+        )
+        got: list[str] = []
+        with pytest.raises(CellarionApiError):
+            async for event in client.events_stream():
+                got.append(event)
+        assert got == ["_connected", "a"]
+
+
+# ── Authenticated requests ───────────────────────────────────────────
+
+
+async def test_request_relogs_once_on_401_for_password_clients() -> None:
+    """An expired JWT is refreshed transparently, exactly once."""
+    client, session = password_client(
+        FakeResponse(200, {"token": "jwt-1"}),
+        FakeResponse(401),
+        FakeResponse(200, {"token": "jwt-2"}),
+        FakeResponse(200, {"stats": {}}),
+    )
+    assert await client.get_stats_overview() == {"stats": {}}
+    assert [c[0] for c in session.calls] == ["POST", "GET", "POST", "GET"]
+    assert session.calls[-1][2]["headers"]["Authorization"] == "Bearer jwt-2"
+
+
+async def test_request_error_body_detail_is_included() -> None:
+    client, _ = token_client(FakeResponse(500, {"error": "boom"}))
+    with pytest.raises(CellarionApiError, match="status 500: boom"):
+        await client.get_cellars()
+
+
+@pytest.mark.parametrize(
+    "response",
+    [
+        FakeResponse(204),
+        FakeResponse(200, content_length=0),
+        FakeResponse(200, content_type="text/plain"),  # non-JSON success body
+        FakeResponse(200, ["not", "a", "dict"]),
+    ],
+)
+async def test_request_empty_or_odd_success_bodies_give_empty_dict(response: FakeResponse) -> None:
+    client, _ = token_client(response)
+    assert await client.consume_bottle("6a50805b785f507654afdc51") == {}
+    assert response.closed
+
+
+async def test_scope_error_only_for_api_tokens() -> None:
+    """403 is a scope error with a token, a plain API error with a password."""
+    client, _ = token_client(FakeResponse(403, {"error": "scope"}))
+    with pytest.raises(CellarionScopeError):
+        await client.get_cellars()
+
+    client, _ = password_client(
+        FakeResponse(200, {"token": "jwt"}), FakeResponse(403, {"error": "no"})
+    )
+    with pytest.raises(CellarionApiError) as excinfo:
+        await client.get_cellars()
+    assert not isinstance(excinfo.value, CellarionScopeError)
+
+
+@pytest.mark.parametrize(
+    ("body", "expected"),
+    [
+        ({"id": "A"}, "A"),
+        ({"user": {"id": "B"}}, "B"),
+        ({"user": {"_id": "C"}}, "C"),
+        ({"user": "not-a-dict"}, None),
+        ({}, None),
+    ],
+)
+async def test_get_account_id_shapes(body: dict[str, Any], expected: str | None) -> None:
+    client, _ = token_client(FakeResponse(200, body))
+    assert await client.get_account_id() == expected
+
+
+# ── Login and token minting ──────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("status", "expected"),
+    [
+        (400, CellarionAuthError),
+        (403, CellarionAuthError),
+        (429, CellarionApiError),
+        (502, CellarionApiError),
+    ],
+)
+async def test_login_status_mapping(status: int, expected: type[Exception]) -> None:
+    client, _ = password_client(FakeResponse(status, {"error": "x"}))
+    with pytest.raises(expected):
+        await client.authenticate()
+
+
+async def test_login_without_token_in_body() -> None:
+    client, _ = password_client(FakeResponse(200, {"user": {}}))
+    with pytest.raises(CellarionApiError, match="No token"):
+        await client.authenticate()
+
+
+async def test_login_connection_error() -> None:
+    client, _ = password_client(aiohttp.ClientError("refused"))
+    with pytest.raises(CellarionApiError, match="Connection failed"):
+        await client.authenticate()
+
+
+@pytest.mark.parametrize(
+    ("response", "expected"),
+    [
+        (FakeResponse(401), CellarionAuthError),
+        (FakeResponse(403), CellarionAuthError),
+        (FakeResponse(405), CellarionTokensNotSupported),
+        (FakeResponse(429), CellarionApiError),
+        (FakeResponse(500), CellarionApiError),
+        (FakeResponse(307), CellarionApiError),
+        (FakeResponse(201, {"id": "t1"}), CellarionApiError),  # no token in body
+        (FakeResponse(201, content_type="text/html"), CellarionApiError),
+        (aiohttp.ClientError("down"), CellarionApiError),
+    ],
+)
+async def test_create_token_error_mapping(response: Any, expected: type[Exception]) -> None:
+    client, session = password_client(FakeResponse(200, {"token": "jwt"}), response)
+    with pytest.raises(expected):
+        await client.async_create_api_token("HA", ["read"])
+    if session.calls[1:]:
+        # The credential-bearing POST never follows a redirect
+        assert session.calls[1][2]["allow_redirects"] is False
+
+
+async def test_create_token_needs_a_password() -> None:
+    client, _ = token_client()
+    with pytest.raises(CellarionApiError, match="Password login required"):
+        await client.async_create_api_token("HA", ["read"])
+
+
+async def test_create_token_success_returns_string() -> None:
+    client, session = password_client(
+        FakeResponse(200, {"token": "jwt"}), FakeResponse(201, {"token": "cel_new"})
+    )
+    assert await client.async_create_api_token("HA", ["read", "consume"]) == "cel_new"
+    assert session.calls[1][2]["json"]["scopes"] == ["read", "consume"]
+
+
+async def test_health_non_json_is_unreachable() -> None:
+    client, _ = token_client(FakeResponse(200, content_type="text/html"))
+    assert await client.get_health() == {"status": "unreachable"}
+
+
+# ── Self-revocation ──────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("status", [200, 401])
+async def test_revoke_own_token_done_on_200_or_401(status: int) -> None:
+    """200 = revoked now, 401 = already revoked; both mean the token is gone."""
+    client, session = token_client(FakeResponse(status, {"message": "Token revoked"}))
+    assert await client.revoke_own_token() is True
+    method, url, kwargs = session.calls[0]
+    assert (method, url) == ("DELETE", f"{BASE_URL}/api/tokens/self")
+    assert kwargs["headers"]["Authorization"] == f"Bearer {TEST_TOKEN}"
+
+
+@pytest.mark.parametrize(
+    "response",
+    [
+        FakeResponse(403, {"error": "scope"}),
+        FakeResponse(404),
+        FakeResponse(500),
+        aiohttp.ClientError("down"),
+    ],
+)
+async def test_revoke_own_token_is_best_effort(response: Any) -> None:
+    """A pre-1.220 server (403), odd answers and outages mean 'maybe still valid'."""
+    client, _ = token_client(response)
+    assert await client.revoke_own_token() is False
+
+
+async def test_revoke_own_token_needs_an_api_token() -> None:
+    """A password-based client has no token of its own and sends nothing."""
+    client, session = password_client()
+    assert await client.revoke_own_token() is False
+    assert session.calls == []
+
+
+async def test_oversized_body_is_refused() -> None:
+    """A response far larger than any real payload is an error, not a read."""
+    client, _ = token_client(FakeResponse(200, {"stats": {}}, content_length=50_000_000))
+    with pytest.raises(CellarionApiError, match="refusing to read"):
+        await client.get_stats_overview()
+
+
+# ── Remaining branches ───────────────────────────────────────────────
+
+
+async def test_token_client_401_is_fatal_without_retry() -> None:
+    """A static API token cannot be refreshed: one 401 is a revoked token."""
+    client, session = token_client(FakeResponse(401))
+    with pytest.raises(CellarionAuthError, match="revoked or invalid"):
+        await client.get_cellars()
+    assert len(session.calls) == 1
+
+
+async def test_login_redirect_is_refused() -> None:
+    client, session = password_client(FakeResponse(302))
+    with pytest.raises(CellarionApiError, match="redirected"):
+        await client.authenticate()
+    assert session.calls[0][2]["allow_redirects"] is False
+
+
+async def test_password_client_second_401_is_fatal() -> None:
+    client, _ = password_client(
+        FakeResponse(200, {"token": "jwt-1"}),
+        FakeResponse(401),
+        FakeResponse(200, {"token": "jwt-2"}),
+        FakeResponse(401),
+    )
+    with pytest.raises(CellarionAuthError, match="after retry"):
+        await client.get_cellars()
+
+
+async def test_error_without_json_body_still_reports_status() -> None:
+    client, _ = token_client(FakeResponse(502, content_type="text/html"))
+    with pytest.raises(CellarionApiError, match=r"status 502$"):
+        await client.get_cellars()
+
+
+async def test_get_account_id_on_api_error_is_none() -> None:
+    client, _ = token_client(FakeResponse(500, {"error": "x"}))
+    assert await client.get_account_id() is None
+
+
+async def test_read_helpers_hit_their_paths() -> None:
+    client, session = token_client(
+        FakeResponse(200, {"notifications": [], "unreadCount": 0}),
+        FakeResponse(200, {"bottles": {"items": []}}),
+    )
+    await client.get_notifications()
+    await client.get_peak_bottles(limit=3)
+    assert session.calls[0][1].endswith("/api/notifications")
+    assert session.calls[1][1].endswith("/api/bottles?maturity=peak&limit=3")
+
+
+async def test_consume_body_carries_rating_and_note() -> None:
+    client, session = token_client(FakeResponse(200, {"ok": True}))
+    await client.consume_bottle(
+        "6a50805b785f507654afdc51", reason="gifted", rating=92, note="lovely"
+    )
+    assert session.calls[0][2]["json"] == {"reason": "gifted", "rating": 92, "note": "lovely"}
+
+
+async def test_stream_retry_connection_error() -> None:
+    """A transport error on the post-login retry is a normal API error."""
+    client, _ = password_client(
+        FakeResponse(200, {"token": "jwt-1"}),
+        FakeResponse(401),
+        FakeResponse(200, {"token": "jwt-2"}),
+        aiohttp.ClientError("gone"),
+    )
+    with pytest.raises(CellarionApiError, match="retry failed"):
+        await collect(client)