rohlik-api 0.1.0__py3-none-any.whl

rohlik_api/__init__.py

@@ -0,0 +1,74 @@
+"""Rohlik.cz API Python Client.
+
+An async Python client for the Rohlik.cz API, built on aiohttp.
+"""
+
+from .auth import AuthManager
+from .client import RohlikAPI
+from .endpoints import BASE_URL, Endpoints
+from .errors import APIRequestFailedError, InvalidCredentialsError, RohlikAPIError
+from .helpers import format_price, mask_data
+from .http_client import HttpClient
+from .models import (
+    AISummary,
+    Allergens,
+    Cart,
+    CartItem,
+    DirectionSection,
+    DirectionStep,
+    IngredientGroup,
+    IngredientItem,
+    IngredientProduct,
+    IngredientProductGroup,
+    IngredientProducts,
+    NutritionalValue,
+    ProductComposition,
+    ProductPrice,
+    ProductSearchResult,
+    RecipeAuthor,
+    RecipeDetail,
+    RecipeSearchResults,
+    RecipeSummary,
+    SearchResults,
+    ShoppingList,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Main client (facade)
+    "RohlikAPI",
+    # Errors
+    "RohlikAPIError",
+    "InvalidCredentialsError",
+    "APIRequestFailedError",
+    # Models
+    "Cart",
+    "CartItem",
+    "SearchResults",
+    "ProductSearchResult",
+    "AISummary",
+    "ProductComposition",
+    "NutritionalValue",
+    "Allergens",
+    "ProductPrice",
+    "RecipeSearchResults",
+    "RecipeSummary",
+    "RecipeDetail",
+    "RecipeAuthor",
+    "IngredientGroup",
+    "IngredientItem",
+    "DirectionSection",
+    "DirectionStep",
+    "IngredientProducts",
+    "IngredientProductGroup",
+    "IngredientProduct",
+    "ShoppingList",
+    # Utilities
+    "mask_data",
+    "format_price",
+    # Advanced: low-level components
+    "HttpClient",
+    "AuthManager",
+    "Endpoints",
+    "BASE_URL",
+]

rohlik_api/auth.py

@@ -0,0 +1,173 @@
+"""Authentication manager for Rohlik.cz API."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .endpoints import Endpoints
+from .errors import APIRequestFailedError, InvalidCredentialsError, RohlikAPIError
+from .helpers import mask_data
+from .http_client import HTTP_ERRORS, HttpClient
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """Manages authentication state for Rohlik.cz API.
+
+    This class handles login, logout, and session management.
+
+    Args:
+        http_client: The HTTP client instance to use for requests
+        username: Email address used for Rohlik.cz login
+        password: Password for Rohlik.cz account
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        username: str,
+        password: str,
+    ):
+        if not username or not password:
+            raise ValueError("Username and password are required")
+
+        self._http = http_client
+        self._username = username
+        self._password = password
+
+        self._is_logged_in: bool = False
+        self._user_id: int | None = None
+        self._address_id: int | None = None
+        self._login_response: dict[str, Any] = {}
+
+    @property
+    def is_logged_in(self) -> bool:
+        """Check if currently logged in."""
+        return self._is_logged_in
+
+    @property
+    def user_id(self) -> int | None:
+        """Get the current user ID."""
+        return self._user_id
+
+    @property
+    def address_id(self) -> int | None:
+        """Get the current address ID."""
+        return self._address_id
+
+    async def login(self) -> dict[str, Any]:
+        """Authenticate with the Rohlik.cz service.
+
+        If already logged in, returns the cached login response from the most
+        recent successful login without making a new request.
+
+        Returns:
+            dict: The JSON response containing authentication data
+
+        Raises:
+            InvalidCredentialsError: If credentials are invalid
+            APIRequestFailedError: If the login request fails
+        """
+        if self._is_logged_in:
+            _LOGGER.debug("Already logged in, skipping login request")
+            return self._login_response
+
+        login_data = {"email": self._username, "password": self._password, "name": ""}
+
+        try:
+            response = await self._http.post(Endpoints.LOGIN, json=login_data)
+            login_response: dict[str, Any] = response.json()
+
+            if login_response.get("status") != 200:
+                messages = login_response.get("messages", [])
+                if login_response.get("status") == 401:
+                    error_msg = (
+                        messages[0].get("content", "Invalid credentials")
+                        if messages
+                        else "Invalid credentials"
+                    )
+                    raise InvalidCredentialsError(error_msg)
+                error_msg = (
+                    messages[0].get("content", "Unknown error") if messages else "Unknown error"
+                )
+                raise RohlikAPIError(f"Unknown error occurred during login: {error_msg}")
+
+            self._is_logged_in = True
+            self._login_response = login_response
+
+            # Extract user and address IDs. ``address`` may be explicitly null
+            # in the response, so guard with ``or {}``.
+            data = login_response.get("data", {})
+            self._user_id = data.get("user", {}).get("id")
+            self._address_id = (data.get("address") or {}).get("id")
+            if self._address_id is None:
+                _LOGGER.debug(
+                    "No address ID in login data. Login response: %s",
+                    mask_data(login_response),
+                )
+
+            return login_response
+
+        except HTTP_ERRORS as err:
+            raise APIRequestFailedError(
+                f"Cannot connect to website! Check your internet connection "
+                f"and try again: {err}"
+            ) from err
+
+    async def logout(self) -> None:
+        """Log out from the Rohlik.cz service.
+
+        Raises:
+            RohlikAPIError: If logout fails
+            APIRequestFailedError: If the request fails
+        """
+        if not self._is_logged_in:
+            _LOGGER.debug("Not logged in, skipping logout request")
+            return
+
+        try:
+            response = await self._http.post(Endpoints.LOGOUT)
+            logout_response = response.json()
+
+            if logout_response.get("status") != 200:
+                raise RohlikAPIError(f"Unknown error occurred during logout: {logout_response}")
+
+            self._reset_session()
+
+        except HTTP_ERRORS as err:
+            self._reset_session()  # Reset state even on error
+            raise APIRequestFailedError(
+                f"Cannot connect to website! Check your internet connection "
+                f"and try again: {err}"
+            ) from err
+
+    async def ensure_logged_in(self) -> None:
+        """Ensure the client is logged in, login if not."""
+        if not self._is_logged_in:
+            await self.login()
+
+    async def relogin(self) -> dict[str, Any]:
+        """Force a fresh login after a session expiry (HTTP 401).
+
+        Clears the cached session state so :meth:`login` performs a new request
+        instead of returning the stale cached response, then logs in again.
+
+        Returns:
+            dict: The JSON response from the new login.
+        """
+        self._reset_session()
+        return await self.login()
+
+    def _reset_session(self) -> None:
+        """Clear all session state so the next login re-fetches it.
+
+        User and address IDs are cleared too, so that reusing the same instance
+        across logins picks up a changed delivery address instead of keeping a
+        stale value.
+        """
+        self._is_logged_in = False
+        self._user_id = None
+        self._address_id = None
+        self._login_response = {}

rohlik_api/client.py

@@ -0,0 +1,250 @@
+"""Rohlik.cz API Client implementation."""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any
+
+import aiohttp
+
+from .auth import AuthManager
+from .endpoints import BASE_URL
+from .errors import APIRequestFailedError
+from .http_client import HTTP_ERRORS, HttpClient
+from .services import (
+    AccountService,
+    CartService,
+    DeliveryService,
+    OrderService,
+    ProductService,
+    RecipeService,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class RohlikAPI:
+    """Async client for interacting with the Rohlik.cz API.
+
+    The client is built on aiohttp and exposes a service-based API for all
+    operations. When used as an async context manager with ``auto_login=True``
+    (the default), it logs in on entry and logs out on exit.
+
+    Args:
+        username: Email address used for Rohlik.cz login (required).
+        password: Password for the Rohlik.cz account (required).
+        base_url: Base URL for the Rohlik.cz API. Defaults to https://www.rohlik.cz
+        timeout: Request timeout in seconds. Defaults to 30.0.
+        headers: Optional custom headers to include in all requests.
+        auto_login: If True (default), log in automatically when used as a
+            context manager.
+        session: Optional externally managed :class:`aiohttp.ClientSession` to
+            reuse (for example Home Assistant's shared session). When provided,
+            the session is not closed by this client.
+
+    Attributes:
+        cart (CartService): Cart operations (get_content, add_items, delete_item).
+        products (ProductService): Product search and details.
+        orders (OrderService): Order operations (get_next, get_last, get_delivered).
+        delivery (DeliveryService): Delivery info and timeslots.
+        account (AccountService): Account data (premium, bags, shopping lists).
+        recipes (RecipeService): Recipe search and ingredients (Rohlík Chef).
+
+    Example:
+        >>> async with RohlikAPI("user@example.com", "password") as client:
+        ...     cart = await client.cart.get_content()
+        ...     print(cart.total_price, cart.total_items)
+        ...     for item in cart.products:
+        ...         print(item.name, item.quantity, item.price)
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        auto_login: bool = True,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        # Credential validation is owned by AuthManager (constructed below),
+        # which raises ValueError on empty username/password.
+        self._auto_login = auto_login
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        # Initialize HTTP client
+        self._http = HttpClient(
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            session=session,
+        )
+
+        # Initialize auth manager
+        self._auth = AuthManager(
+            http_client=self._http,
+            username=username,
+            password=password,
+        )
+
+        # Wire up transparent re-authentication: when any request hits HTTP 401
+        # (expired session), the HTTP client re-logs in and retries once.
+        self._http.set_unauthorized_handler(self._auth.relogin)
+
+        # Initialize services
+        self._cart = CartService(self._http, self._auth)
+        self._products = ProductService(self._http, self._auth)
+        self._orders = OrderService(self._http, self._auth)
+        self._delivery = DeliveryService(self._http, self._auth)
+        self._account = AccountService(self._http, self._auth)
+        self._recipes = RecipeService(self._http, self._auth)
+
+    # -------------------------------------------------------------------------
+    # Service Properties
+    # -------------------------------------------------------------------------
+
+    @property
+    def cart(self) -> CartService:
+        """Access cart operations."""
+        return self._cart
+
+    @property
+    def products(self) -> ProductService:
+        """Access product operations."""
+        return self._products
+
+    @property
+    def orders(self) -> OrderService:
+        """Access order operations."""
+        return self._orders
+
+    @property
+    def delivery(self) -> DeliveryService:
+        """Access delivery operations."""
+        return self._delivery
+
+    @property
+    def account(self) -> AccountService:
+        """Access account operations."""
+        return self._account
+
+    @property
+    def recipes(self) -> RecipeService:
+        """Access recipe operations (Rohlík Chef)."""
+        return self._recipes
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        """Get or create the underlying aiohttp session."""
+        return self._http.session
+
+    @property
+    def is_logged_in(self) -> bool:
+        """Check if the client is currently logged in."""
+        return self._auth.is_logged_in
+
+    @property
+    def user_id(self) -> int | None:
+        """The authenticated user's ID, or None if not logged in."""
+        return self._auth.user_id
+
+    @property
+    def address_id(self) -> int | None:
+        """The authenticated user's delivery address ID, or None if not logged in."""
+        return self._auth.address_id
+
+    # -------------------------------------------------------------------------
+    # Authentication
+    # -------------------------------------------------------------------------
+
+    async def login(self) -> dict[str, Any]:
+        """Authenticate with the Rohlik.cz service.
+
+        Returns:
+            The JSON response containing authentication data.
+
+        Raises:
+            InvalidCredentialsError: If the credentials are invalid.
+            APIRequestFailedError: If the request fails.
+        """
+        return await self._auth.login()
+
+    async def logout(self) -> None:
+        """Log out from the Rohlik.cz service.
+
+        Raises:
+            RohlikAPIError: If logout fails.
+            APIRequestFailedError: If the request fails.
+        """
+        await self._auth.logout()
+
+    # -------------------------------------------------------------------------
+    # Context Manager
+    # -------------------------------------------------------------------------
+
+    async def __aenter__(self) -> RohlikAPI:
+        """Enter the context manager, logging in if ``auto_login`` is True."""
+        if self._auto_login:
+            await self._auth.login()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the context manager, logging out and releasing resources."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP client and release resources. Logs out if logged in."""
+        if self._auth.is_logged_in:
+            try:
+                await self._auth.logout()
+            except Exception as err:  # noqa: BLE001 - best-effort logout on close
+                _LOGGER.warning("Error during logout on close: %s", err)
+
+        await self._http.close()
+
+    # -------------------------------------------------------------------------
+    # Aggregated data retrieval
+    # -------------------------------------------------------------------------
+
+    async def get_data(self) -> dict[str, Any]:
+        """Retrieve account data from Rohlik.cz in a single aggregated call.
+
+        Returns:
+            A dictionary containing delivery info, orders, cart contents,
+            premium profile, announcements and more.
+
+        Raises:
+            APIRequestFailedError: If the underlying requests fail.
+        """
+        result: dict[str, Any] = {}
+
+        result["login"] = await self._auth.login()
+
+        try:
+            result["delivery"] = await self._delivery.get_info()
+            result["next_order"] = await self._orders.get_next()
+            result["last_order"] = await self._orders.get_last()
+            result["delivered_orders"] = await self._orders.get_delivered()
+            result["announcements"] = await self._account.get_announcements()
+            result["bags"] = await self._account.get_bags_info()
+            result["timeslot"] = await self._delivery.get_timeslot_reservation()
+            result["premium_profile"] = await self._account.get_premium_profile()
+            result["delivery_announcements"] = await self._delivery.get_announcements()
+            result["next_delivery_slot"] = await self._delivery.get_next_slots()
+            result["cart"] = await self._cart.get_content()
+
+            return result
+
+        except HTTP_ERRORS as err:
+            raise APIRequestFailedError(
+                f"Cannot connect to website! Check your internet connection "
+                f"and try again: {err}"
+            ) from err

rohlik_api/endpoints.py

@@ -0,0 +1,104 @@
+"""API endpoint definitions for Rohlik.cz."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+BASE_URL = "https://www.rohlik.cz"
+
+
+class Endpoints:
+    """API endpoint paths for Rohlik.cz."""
+
+    # Authentication
+    LOGIN = "/services/frontend-service/login"
+    LOGOUT = "/services/frontend-service/logout"
+
+    # Cart
+    CART = "/services/frontend-service/v2/cart"
+
+    # Products
+    SEARCH = "/services/frontend-service/search-metadata"
+
+    # Delivery
+    DELIVERY = "/services/frontend-service/first-delivery?reasonableDeliveryTime=true"
+    TIMESLOT_RESERVATION = "/services/frontend-service/v1/timeslot-reservation"
+    DELIVERY_ANNOUNCEMENTS = "/services/frontend-service/announcements/delivery"
+
+    # Orders
+    NEXT_ORDER = "/api/v3/orders/upcoming"
+    LAST_ORDER = "/api/v3/orders/delivered?offset=0&limit=1"
+
+    # Account
+    PREMIUM_PROFILE = "/services/frontend-service/premium/profile"
+    BAGS = "/api/v1/reusable-bags/user-info"
+    ANNOUNCEMENTS = "/services/frontend-service/announcements/top"
+
+    # Recipes
+    INGREDIENT_PRODUCTS = "/services/frontend-service/v1/chef/ingredients/products"
+
+    # -------------------------------------------------------------------------
+    # Builder methods for dynamic endpoints
+    # -------------------------------------------------------------------------
+
+    @classmethod
+    def recipe_search(cls, query: str, limit: int = 10, offset: int = 0) -> str:
+        """Build recipe search endpoint URL."""
+        encoded_query = quote(query)
+        return (
+            f"/services/frontend-service/recipe/search/{encoded_query}"
+            f"?offset={offset}&limit={limit}"
+        )
+
+    @classmethod
+    def recipe_detail(cls, recipe_id: int) -> str:
+        """Build recipe detail endpoint URL."""
+        return f"/services/frontend-service/recipe/{recipe_id}"
+
+    @classmethod
+    def order_detail(cls, order_id: int) -> str:
+        """Build order detail endpoint URL (full order including items)."""
+        return f"/api/v3/orders/{order_id}"
+
+    @classmethod
+    def product_detail(cls, product_id: int) -> str:
+        """Build product detail endpoint URL."""
+        return f"/api/v1/products/{product_id}"
+
+    @classmethod
+    def product_categories(cls, product_id: int) -> str:
+        """Build product category-hierarchy endpoint URL."""
+        return f"/api/v1/products/{product_id}/categories"
+
+    @classmethod
+    def product_ai_summary(cls, product_id: int) -> str:
+        """Build product AI summary endpoint URL."""
+        return f"/api/v1/products/{product_id}/ai-summary"
+
+    @classmethod
+    def product_composition(cls, product_id: int) -> str:
+        """Build product composition endpoint URL."""
+        return f"/api/v1/products/{product_id}/composition"
+
+    @classmethod
+    def product_price(cls, product_id: int) -> str:
+        """Build product price endpoint URL."""
+        return f"/api/v1/products/{product_id}/prices"
+
+    @classmethod
+    def shopping_list(cls, shopping_list_id: str) -> str:
+        """Build shopping list endpoint URL."""
+        return f"/api/v1/shopping-lists/id/{shopping_list_id}"
+
+    @classmethod
+    def delivered_orders(cls, limit: int = 50, offset: int = 0) -> str:
+        """Build delivered orders endpoint URL with pagination."""
+        return f"/api/v3/orders/delivered?offset={offset}&limit={limit}"
+
+    @classmethod
+    def timeslots(cls, user_id: int, address_id: int) -> str:
+        """Build timeslots endpoint URL with user and address IDs."""
+        return (
+            f"/services/frontend-service/timeslots-api/0"
+            f"?userId={user_id}&addressId={address_id}&reasonableDeliveryTime=true"
+        )

rohlik_api/errors.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for the Rohlik.cz API client."""
+
+
+class RohlikAPIError(Exception):
+    """Base exception for all Rohlik API errors."""
+
+
+class InvalidCredentialsError(RohlikAPIError):
+    """Raised when login credentials are invalid."""
+
+
+class APIRequestFailedError(RohlikAPIError):
+    """Raised when an API request fails (network or HTTP error)."""

rohlik_api/helpers.py

@@ -0,0 +1,57 @@
+"""Helper utilities for the Rohlik.cz API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def format_price(price_info: dict[str, Any] | None) -> str:
+    """Format a Rohlik price object into a ``"<amount> <currency>"`` string.
+
+    Args:
+        price_info: A price mapping with optional ``full`` and ``currency`` keys.
+
+    Returns:
+        A string like ``"29.90 Kč"``. Missing parts are rendered as empty.
+    """
+    price_info = price_info or {}
+    full = price_info.get("full", "")
+    currency = price_info.get("currency", "")
+    return f"{full} {currency}".strip()
+
+
+def mask_data(input_dict: Any) -> Any:
+    """Recursively mask all non-null values in a dictionary with ``"XXXXXXX"``.
+
+    Useful for logging API payloads without leaking personal data. ``None``
+    values are preserved so the shape of the data remains visible.
+
+    Args:
+        input_dict: The value to mask. Non-dict values are returned unchanged.
+
+    Returns:
+        A copy of the input with every non-null leaf value replaced by
+        ``"XXXXXXX"``.
+    """
+    if not isinstance(input_dict, dict):
+        return input_dict
+
+    result: dict[Any, Any] = {}
+    for key, value in input_dict.items():
+        if value is None:
+            result[key] = None
+        elif isinstance(value, dict):
+            result[key] = mask_data(value)
+        elif isinstance(value, list):
+            result[key] = [
+                (
+                    mask_data(item)
+                    if isinstance(item, dict)
+                    else "XXXXXXX" if item is not None else None
+                )
+                for item in value
+            ]
+        else:
+            result[key] = "XXXXXXX"
+
+    return result