pycellarion 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+pycellarion/__init__.py,sha256=Gqrv3JqzDaSg69E55T0y7Iyh6MViv_fxrY84mfeTQNg,619
+pycellarion/client.py,sha256=6-2Ly9mvUqmiWpuTVL3On93y4E25sn7toKtrNiziZVU,16551
+pycellarion/exceptions.py,sha256=eYsg4JkFo_r8tZMVpj_xmKVRdn9NLLZgJ3lzZ3nZTqM,713
+pycellarion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycellarion-0.1.0.dist-info/METADATA,sha256=t5q6ukk4Ke_wc-kqLToqJPicYiO1FVHYSlIoXXr4YTM,4444
+pycellarion-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pycellarion-0.1.0.dist-info/licenses/LICENSE,sha256=7PFYEXLX-TFOo_uYa_FYHwdJkwPl9jOAuud4szTv7ys,1065
+pycellarion-0.1.0.dist-info/RECORD,,

pycellarion-0.1.0.dist-info/WHEEL

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

pycellarion-0.1.0.dist-info/licenses/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.