python-appie 0.1.0__py3-none-any.whl

appie/__init__.py

@@ -0,0 +1,29 @@
+"""Public package exports and CLI entrypoints for python-appie."""
+
+from __future__ import annotations
+
+import asyncio
+
+from appie.auth import AHAuthClient
+from appie.client import AHClient
+from appie.mock import MockAHClient
+
+__all__ = ["AHAuthClient", "AHClient", "MockAHClient", "login_cli"]
+
+
+def login_cli() -> None:
+    """Run the interactive login CLI."""
+    asyncio.run(_login_cli_async())
+
+
+async def _login_cli_async() -> None:  # pragma: no cover - exercised via manual browser login
+    async with AHClient() as client:
+        try:
+            code = await client.capture_login_code()
+        except RuntimeError as exc:
+            print(f"Automatic login capture failed: {exc}")
+            print(f"Open this URL in your browser:\n{client.authorize_url}\n")
+            redirect_or_code = input("Paste the redirect URL or raw code: ").strip()
+            code = client._extract_code(redirect_or_code)
+        await client.auth.login_with_code(code)
+        print("✓ Logged in successfully")

appie/auth.py

@@ -0,0 +1,159 @@
+"""Authentication helpers for the Albert Heijn API client."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import httpx
+
+from appie.models import StoredToken, TokenResponse
+
+BASE_URL = "https://api.ah.nl"
+DEFAULT_CLIENT_ID = "appie-ios"
+DEFAULT_CLIENT_VERSION = "9.28"
+DEFAULT_USER_AGENT = "Appie/9.28 (iPhone17,3; iPhone; CPU OS 26_1 like Mac OS X)"
+DEFAULT_TOKEN_PATH = Path.home() / ".config" / "appie" / "tokens.json"
+REFRESH_SKEW_SECONDS = 60
+
+
+class AHAuthClient:
+    """Manage AH access tokens, refresh tokens, and token persistence."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient | None = None,
+        token_path: Path | None = None,
+    ) -> None:
+        self._client = http_client or httpx.AsyncClient(base_url=BASE_URL)
+        self._owns_client = http_client is None
+        self.token_path = token_path or DEFAULT_TOKEN_PATH
+        self._stored_token: StoredToken | None = self.load_tokens()
+
+    async def __aenter__(self) -> AHAuthClient:
+        """Return the auth client in async context-manager usage."""
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        """Close owned resources at context-manager exit."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client when this instance owns it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    @property
+    def access_token(self) -> str | None:
+        """Return the current access token if one is loaded."""
+        if self._stored_token is None:
+            return None
+        return self._stored_token.access_token
+
+    @property
+    def refresh_token_value(self) -> str | None:
+        """Return the current refresh token if one is loaded."""
+        if self._stored_token is None:
+            return None
+        return self._stored_token.refresh_token
+
+    @property
+    def token(self) -> TokenResponse | None:
+        """Return the current stored token as a public token model."""
+        if self._stored_token is None:
+            return None
+        return self._stored_token.to_token_response()
+
+    def load_tokens(self) -> StoredToken | None:
+        """Load persisted tokens from disk when available."""
+        if not self.token_path.exists():
+            return None
+        payload = json.loads(self.token_path.read_text())
+        return StoredToken.model_validate(payload)
+
+    def save_tokens(self, token: TokenResponse) -> StoredToken:
+        """Persist tokens to disk and cache the stored token in memory."""
+        expires_at = datetime.now(UTC) + timedelta(seconds=token.expires_in)
+        stored = StoredToken.from_token_response(token, expires_at=expires_at)
+        self.token_path.parent.mkdir(parents=True, exist_ok=True)
+        self.token_path.write_text(stored.model_dump_json(indent=2))
+        self._stored_token = stored
+        return stored
+
+    def token_is_expiring(self) -> bool:
+        """Return whether the current access token should be refreshed soon."""
+        if self._stored_token is None:
+            return True
+        refresh_deadline = datetime.now(UTC) + timedelta(seconds=REFRESH_SKEW_SECONDS)
+        return self._stored_token.expires_at <= refresh_deadline
+
+    async def ensure_valid_token(self) -> TokenResponse:
+        """Return a usable token, refreshing it when necessary."""
+        if self._stored_token is None:
+            raise RuntimeError("No stored tokens found. Run login() or login_cli() first.")
+        if self.token_is_expiring():
+            return await self.refresh_token(self._stored_token.refresh_token)
+        return self._stored_token.to_token_response()
+
+    async def get_anonymous_token(self) -> TokenResponse:
+        """Fetch an anonymous bootstrap token."""
+        response = await self._post_json(
+            "/mobile-auth/v1/auth/token/anonymous",
+            {"clientId": DEFAULT_CLIENT_ID},
+        )
+        self._raise_for_status(response, "Failed to get anonymous token")
+        return TokenResponse.model_validate(response.json())
+
+    async def login_with_code(self, code: str) -> TokenResponse:
+        """Exchange an authorization code for persisted user tokens."""
+        response = await self._post_json(
+            "/mobile-auth/v1/auth/token",
+            {
+                "clientId": DEFAULT_CLIENT_ID,
+                "code": code,
+            },
+        )
+        self._raise_for_status(response, "Failed to exchange authorization code")
+        token = TokenResponse.model_validate(response.json())
+        self.save_tokens(token)
+        return token
+
+    async def refresh_token(self, refresh_token: str) -> TokenResponse:
+        """Refresh a persisted token set using the refresh token."""
+        response = await self._post_json(
+            "/mobile-auth/v1/auth/token/refresh",
+            {
+                "clientId": DEFAULT_CLIENT_ID,
+                "refreshToken": refresh_token,
+            },
+        )
+        self._raise_for_status(response, "Failed to refresh token")
+        token = TokenResponse.model_validate(response.json())
+        self.save_tokens(token)
+        return token
+
+    async def _post_json(self, url: str, payload: dict[str, str]) -> httpx.Response:
+        return await self._client.post(
+            url,
+            headers={
+                "User-Agent": DEFAULT_USER_AGENT,
+                "x-client-name": DEFAULT_CLIENT_ID,
+                "x-client-version": DEFAULT_CLIENT_VERSION,
+                "x-application": "AHWEBSHOP",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            json=payload,
+        )
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response, context: str) -> None:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            body = response.text.strip()
+            detail = f"{context}: {exc}"
+            if body:
+                detail = f"{detail}\nResponse body: {body}"
+            raise RuntimeError(detail) from exc

appie/client.py

@@ -0,0 +1,248 @@
+"""Main async client for interacting with Albert Heijn endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+import httpx
+
+from appie.auth import (
+    BASE_URL,
+    DEFAULT_CLIENT_ID,
+    DEFAULT_CLIENT_VERSION,
+    DEFAULT_USER_AGENT,
+    AHAuthClient,
+)
+
+
+class AHClient:
+    """High-level async client that exposes products, receipts, and lists APIs."""
+
+    user_agent = DEFAULT_USER_AGENT
+    graphql_url = f"{BASE_URL}/graphql"
+    authorize_url = (
+        "https://login.ah.nl/login"
+        f"?client_id={DEFAULT_CLIENT_ID}&redirect_uri=appie://login-exit&response_type=code"
+    )
+
+    def __init__(
+        self,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        auth_client: AHAuthClient | None = None,
+    ) -> None:
+        default_headers = {
+            "User-Agent": self.user_agent,
+            "x-client-name": DEFAULT_CLIENT_ID,
+            "x-client-version": DEFAULT_CLIENT_VERSION,
+            "x-application": "AHWEBSHOP",
+            "Content-Type": "application/json",
+        }
+        self._client = http_client or httpx.AsyncClient(base_url=BASE_URL, headers=default_headers)
+        if http_client is not None:
+            self._client.headers.update(default_headers)
+        self._owns_client = http_client is None
+        self.auth = auth_client or AHAuthClient(http_client=self._client)
+
+        from appie.lists import ListsAPI
+        from appie.products import ProductsAPI
+        from appie.receipts import ReceiptsAPI
+
+        self.receipts = ReceiptsAPI(self)
+        self.products = ProductsAPI(self)
+        self.lists = ListsAPI(self)
+
+    async def __aenter__(self) -> AHClient:
+        """Return the client in async context-manager usage."""
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        """Close owned resources at context-manager exit."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the auth and HTTP clients when owned by this instance."""
+        await self.auth.aclose()
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def login(self) -> None:
+        """Run the browser-assisted login flow and persist the resulting tokens."""
+        code = await self.capture_login_code()
+        await self.auth.login_with_code(code)
+
+    async def capture_login_code(
+        self,
+        timeout_seconds: float = 300,
+    ) -> str:  # pragma: no cover - exercised via manual browser login
+        """Open a browser, capture the AH redirect code, and return it."""
+        async_playwright, playwright_error = self._load_playwright()
+        try:
+            return await self._capture_login_code_in_browser(async_playwright, timeout_seconds)
+        except playwright_error as exc:
+            raise RuntimeError(
+                "Automatic browser login could not start. Ensure Google Chrome is installed, "
+                "or fall back to entering the raw code manually."
+            ) from exc
+
+    @staticmethod
+    def _load_playwright() -> tuple[Any, type[Exception]]:  # pragma: no cover
+        try:
+            from playwright.async_api import Error as PlaywrightError
+            from playwright.async_api import async_playwright
+        except ImportError as exc:
+            raise RuntimeError(
+                "Playwright is not installed. Install project dependencies again and ensure the "
+                "Playwright browser runtime is available."
+            ) from exc
+        return async_playwright, PlaywrightError
+
+    async def _capture_login_code_in_browser(
+        self,
+        async_playwright: Any,
+        timeout_seconds: float,
+    ) -> str:  # pragma: no cover - browser integration helper
+        """Capture the login code from the browser redirect target."""
+        async with async_playwright() as playwright:
+            browser = await playwright.chromium.launch(channel="chrome", headless=False)
+            context = await browser.new_context()
+            page = await context.new_page()
+
+            code_future: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+            self._register_login_capture_handlers(page, code_future)
+            await page.goto(self.authorize_url, wait_until="domcontentloaded")
+            print(
+                "A Chrome window was opened for AH login. Complete the login there; "
+                "the auth code will be captured automatically."
+            )
+
+            try:
+                return await asyncio.wait_for(code_future, timeout=timeout_seconds)
+            finally:
+                await context.close()
+                await browser.close()
+
+    def _register_login_capture_handlers(
+        self,
+        page: Any,
+        code_future: asyncio.Future[str],
+    ) -> None:  # pragma: no cover - browser integration helper
+        """Attach event handlers that resolve when the app redirect is seen."""
+        page.on(
+            "framenavigated",
+            lambda frame: self._resolve_code_future(
+                code_future,
+                self._extract_code_from_redirect_target(frame.url),
+            ),
+        )
+        page.on(
+            "request",
+            lambda request: self._resolve_code_future(
+                code_future,
+                self._extract_code_from_redirect_target(request.url),
+            ),
+        )
+        page.on(
+            "requestfailed",
+            lambda request: self._resolve_code_future(
+                code_future,
+                self._extract_code_from_redirect_target(request.url),
+            ),
+        )
+        page.on(
+            "response",
+            lambda response: asyncio.create_task(
+                self._handle_login_response(response, code_future)
+            ),
+        )
+
+    @staticmethod
+    def _resolve_code_future(
+        code_future: asyncio.Future[str],
+        candidate: str | None,
+    ) -> None:  # pragma: no cover - browser integration helper
+        """Resolve the login-code future once a valid code is seen."""
+        if candidate and not code_future.done():
+            code_future.set_result(candidate)
+
+    async def _handle_login_response(
+        self,
+        response: Any,
+        code_future: asyncio.Future[str],
+    ) -> None:  # pragma: no cover - browser integration helper
+        """Inspect response headers for the redirect target."""
+        try:
+            headers = await response.all_headers()
+        except Exception:
+            return
+        self._resolve_code_future(
+            code_future,
+            self._extract_code_from_redirect_target(headers.get("location")),
+        )
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        auth_required: bool = True,
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Send an HTTP request with default headers and optional bearer auth."""
+        merged_headers = dict(headers or {})
+        if auth_required:
+            token = await self.auth.ensure_valid_token()
+            merged_headers["Authorization"] = f"{token.token_type} {token.access_token}"
+        response = await self._client.request(method, url, headers=merged_headers, **kwargs)
+        response.raise_for_status()
+        return response
+
+    async def graphql(
+        self,
+        query: str,
+        variables: Mapping[str, object] | None = None,
+    ) -> dict:
+        """Send a GraphQL request and return the `data` payload."""
+        response = await self.request(
+            "POST",
+            self.graphql_url,
+            json={"query": query, "variables": dict(variables or {})},
+        )
+        payload = response.json()
+        if "errors" in payload:
+            raise RuntimeError(f"GraphQL request failed: {payload['errors']}")
+        return payload["data"]
+
+    @staticmethod
+    def _extract_code(value: str) -> str:
+        """Extract an auth code from a redirect URL or raw code string."""
+        code = AHClient._extract_code_from_text(value)
+        if not code:
+            raise ValueError("Input did not contain an authorization code.")
+        return code
+
+    @staticmethod
+    def _extract_code_from_text(value: str) -> str | None:
+        """Extract a code from a raw string or URL query string."""
+        stripped = value.strip()
+        if stripped and "://" not in stripped and "?" not in stripped and "=" not in stripped:
+            return stripped
+        parsed = urlparse(stripped)
+        code = parse_qs(parsed.query).get("code", [None])[0]
+        return code
+
+    @staticmethod
+    def _extract_code_from_redirect_target(value: str | None) -> str | None:
+        """Extract a code only from the expected `appie://login-exit` redirect target."""
+        if not value:
+            return None
+        parsed = urlparse(value.strip())
+        if parsed.scheme != "appie":
+            return None
+        if parsed.netloc != "login-exit" and parsed.path != "/login-exit":
+            return None
+        return parse_qs(parsed.query).get("code", [None])[0]

appie/lists.py

@@ -0,0 +1,78 @@
+"""Shopping-list operations for the Albert Heijn API client."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from appie.models import ShoppingListItem
+
+ADD_ITEM_MUTATION = """
+mutation AddToShoppingList($input: ShoppingListItemInput!) {
+  addShoppingListItem(input: $input) {
+    id
+    description
+    quantity
+    productId
+  }
+}
+"""
+
+
+class GraphQLClient(Protocol):
+    """Protocol for clients that can execute GraphQL requests."""
+
+    async def graphql(self, query: str, variables: dict[str, Any] | None = None) -> dict:
+        """Execute a GraphQL request."""
+        ...
+
+
+class ListsAPI:
+    """High-level shopping-list operations."""
+
+    def __init__(self, client: GraphQLClient) -> None:
+        self._client = client
+
+    async def get_list(self) -> list[ShoppingListItem]:
+        """Return the current shopping list when the query shape is confirmed."""
+        raise NotImplementedError(
+            "Shopping-list query shape is not confirmed yet. "
+            "The public method is reserved for a future verified GraphQL query."
+        )
+
+    async def add_item(
+        self,
+        description: str,
+        quantity: int = 1,
+        product_id: int | None = None,
+    ) -> ShoppingListItem:
+        """Add an item to the shopping list."""
+        data = await self._client.graphql(
+            ADD_ITEM_MUTATION,
+            {
+                "input": {
+                    "description": description,
+                    "quantity": quantity,
+                    "productId": product_id,
+                }
+            },
+        )
+        return self._map_item(data["addShoppingListItem"])
+
+    async def remove_item(self, item_id: str) -> None:
+        """Remove an item from the shopping list when the mutation is confirmed."""
+        raise NotImplementedError(
+            f"Shopping-list remove mutation is not confirmed yet for item {item_id}."
+        )
+
+    async def clear(self) -> None:
+        """Clear the shopping list when the mutation is confirmed."""
+        raise NotImplementedError("Shopping-list clear mutation is not confirmed yet.")
+
+    @staticmethod
+    def _map_item(payload: dict) -> ShoppingListItem:
+        return ShoppingListItem(
+            id=str(payload["id"]),
+            description=payload["description"],
+            quantity=int(payload.get("quantity", 1)),
+            product_id=payload.get("productId"),
+        )

appie/mock.py

@@ -0,0 +1,211 @@
+"""Mock client implementations for local development and testing."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import UTC, datetime
+
+from appie.models import Product, Receipt, ReceiptProduct, ShoppingListItem
+
+
+def _default_products() -> list[Product]:
+    return [
+        Product(
+            id=1525,
+            title="AH Halfvolle melk",
+            brand="AH",
+            price=1.29,
+            unit_size="1 l",
+            image_url="https://example.test/ah-halfvolle-melk.jpg",
+        ),
+        Product(
+            id=441199,
+            title="Campina Halfvolle melk voordeelverpakking",
+            brand="Campina",
+            price=1.99,
+            unit_size="1,5 l",
+            image_url="https://example.test/campina-halfvolle-melk.jpg",
+        ),
+        Product(
+            id=987654,
+            title="AH Pindakaas",
+            brand="AH",
+            price=2.49,
+            unit_size="600 g",
+            image_url="https://example.test/ah-pindakaas.jpg",
+        ),
+    ]
+
+
+def _default_receipts() -> list[Receipt]:
+    return [
+        Receipt(
+            id="mock-receipt-2",
+            datetime=datetime(2026, 3, 21, 14, 16, tzinfo=UTC),
+            store_name="Albert Heijn Mockstraat",
+            total=17.78,
+            products=[
+                ReceiptProduct(
+                    id=1525,
+                    name="AH Halfvolle melk",
+                    quantity=2,
+                    price_per_unit=1.29,
+                    total_price=2.58,
+                ),
+                ReceiptProduct(
+                    id=987654,
+                    name="AH Pindakaas",
+                    quantity=1,
+                    price_per_unit=2.49,
+                    total_price=2.49,
+                ),
+            ],
+        ),
+        Receipt(
+            id="mock-receipt-1",
+            datetime=datetime(2026, 3, 7, 10, 20, tzinfo=UTC),
+            store_name="Albert Heijn Mockstraat",
+            total=24.82,
+            products=[
+                ReceiptProduct(
+                    id=441199,
+                    name="Campina Halfvolle melk voordeelverpakking",
+                    quantity=2,
+                    price_per_unit=1.99,
+                    total_price=3.98,
+                ),
+                ReceiptProduct(
+                    id=987654,
+                    name="AH Pindakaas",
+                    quantity=3,
+                    price_per_unit=2.49,
+                    total_price=7.47,
+                ),
+            ],
+        ),
+    ]
+
+
+class MockProductsAPI:
+    """In-memory mock implementation of the products API."""
+
+    def __init__(self, products: list[Product]) -> None:
+        """Store the in-memory product catalog."""
+        self._products = products
+
+    async def search(self, query: str, limit: int = 10) -> list[Product]:
+        """Return products whose title or brand contains the query."""
+        lowered = query.lower()
+        matches = [
+            product
+            for product in self._products
+            if lowered in product.title.lower() or lowered in (product.brand or "").lower()
+        ]
+        return matches[:limit]
+
+    async def get(self, product_id: int) -> Product:
+        """Return a product by ID."""
+        for product in self._products:
+            if product.id == product_id:
+                return product
+        raise LookupError(f"Mock product {product_id} was not found.")
+
+
+class MockReceiptsAPI:
+    """In-memory mock implementation of the receipts API."""
+
+    def __init__(self, receipts: list[Receipt]) -> None:
+        """Store the in-memory receipt list."""
+        self._receipts = receipts
+
+    async def list_pos_receipts(self, limit: int = 50) -> list[Receipt]:
+        """Return receipt summaries without line items."""
+        return [self._to_summary(receipt) for receipt in self._receipts[:limit]]
+
+    async def get_pos_receipt(self, receipt_id: str) -> Receipt:
+        """Return a detailed receipt by ID."""
+        for receipt in self._receipts:
+            if receipt.id == receipt_id:
+                return receipt.model_copy(deep=True)
+        raise LookupError(f"Mock receipt {receipt_id} was not found.")
+
+    async def list_all(self, limit: int = 50) -> list[Receipt]:
+        """Return receipt summaries sorted by datetime descending."""
+        summaries = await self.list_pos_receipts(limit=limit)
+        return sorted(summaries, key=lambda receipt: receipt.datetime, reverse=True)
+
+    @staticmethod
+    def _to_summary(receipt: Receipt) -> Receipt:
+        return Receipt(
+            id=receipt.id,
+            datetime=receipt.datetime,
+            store_name=receipt.store_name,
+            total=receipt.total,
+            products=[],
+        )
+
+
+class MockListsAPI:
+    """In-memory mock implementation of the shopping-list API."""
+
+    def __init__(self) -> None:
+        """Initialize an empty in-memory shopping list."""
+        self._items: list[ShoppingListItem] = []
+
+    async def get_list(self) -> list[ShoppingListItem]:
+        """Return the current in-memory shopping list."""
+        return [item.model_copy(deep=True) for item in self._items]
+
+    async def add_item(
+        self,
+        description: str,
+        quantity: int = 1,
+        product_id: int | None = None,
+    ) -> ShoppingListItem:
+        """Add an item to the in-memory shopping list."""
+        item = ShoppingListItem(
+            id=f"mock-item-{len(self._items) + 1}",
+            description=description,
+            quantity=quantity,
+            product_id=product_id,
+        )
+        self._items.append(item)
+        return item.model_copy(deep=True)
+
+    async def remove_item(self, item_id: str) -> None:
+        """Remove an item from the in-memory shopping list."""
+        self._items = [item for item in self._items if item.id != item_id]
+
+    async def clear(self) -> None:
+        """Clear the in-memory shopping list."""
+        self._items.clear()
+
+
+class MockAHClient:
+    """Drop-in async mock client for local development and tests."""
+
+    def __init__(
+        self,
+        *,
+        products: list[Product] | None = None,
+        receipts: list[Receipt] | None = None,
+    ) -> None:
+        """Initialize the mock APIs with optional custom fixture data."""
+        product_fixtures = deepcopy(products) if products is not None else _default_products()
+        receipt_fixtures = deepcopy(receipts) if receipts is not None else _default_receipts()
+        self.products = MockProductsAPI(product_fixtures)
+        self.receipts = MockReceiptsAPI(receipt_fixtures)
+        self.lists = MockListsAPI()
+
+    async def __aenter__(self) -> MockAHClient:
+        """Return the mock client in async context-manager usage."""
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        """Allow use in async context-manager blocks."""
+
+    async def aclose(self) -> None:
+        """Match the real client interface without external cleanup."""
+
+    async def login(self) -> None:
+        """Match the real client interface without external auth."""

appie/models.py

@@ -0,0 +1,82 @@
+"""Pydantic models used by the appie client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class TokenResponse(BaseModel):
+    """Public token payload returned by AH auth endpoints."""
+
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    token_type: str = "Bearer"
+
+
+class StoredToken(BaseModel):
+    """Persisted token payload with an absolute expiry timestamp."""
+
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    token_type: str = "Bearer"
+    expires_at: datetime
+
+    model_config = ConfigDict(extra="ignore")
+
+    @classmethod
+    def from_token_response(cls, token: TokenResponse, expires_at: datetime) -> StoredToken:
+        """Create a stored token from a public token payload."""
+        return cls(**token.model_dump(), expires_at=expires_at)
+
+    def to_token_response(self) -> TokenResponse:
+        """Convert a stored token back to the public token model."""
+        return TokenResponse(
+            access_token=self.access_token,
+            refresh_token=self.refresh_token,
+            expires_in=self.expires_in,
+            token_type=self.token_type,
+        )
+
+
+class Product(BaseModel):
+    """Normalized product information."""
+
+    id: int
+    title: str
+    brand: str | None = None
+    price: float | None = None
+    unit_size: str | None = None
+    image_url: str | None = None
+
+
+class ReceiptProduct(BaseModel):
+    """A single line item on a receipt."""
+
+    id: int
+    name: str
+    quantity: float
+    price_per_unit: float
+    total_price: float
+
+
+class Receipt(BaseModel):
+    """A normalized receipt summary or detailed receipt."""
+
+    id: str
+    datetime: datetime
+    store_name: str | None = None
+    total: float
+    products: list[ReceiptProduct]
+
+
+class ShoppingListItem(BaseModel):
+    """A shopping-list item."""
+
+    id: str
+    description: str
+    quantity: int = 1
+    product_id: int | None = None

appie/products.py

@@ -0,0 +1,99 @@
+"""Product search and lookup operations."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import httpx
+
+from appie.models import Product
+
+
+class RequestingClient(Protocol):
+    """Protocol for clients that can make authenticated HTTP requests."""
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send an HTTP request."""
+        ...
+
+
+class ProductsAPI:
+    """High-level product operations."""
+
+    def __init__(self, client: RequestingClient) -> None:
+        self._client = client
+
+    async def search(self, query: str, limit: int = 10) -> list[Product]:
+        """Search products by free-text query."""
+        response = await self._client.request(
+            "GET",
+            "/mobile-services/product/search/v2",
+            params={"query": query, "sortOn": "RELEVANCE", "size": limit, "page": 0},
+        )
+        payload = response.json()
+        products = payload.get("products") or payload.get("data") or []
+        return [self._map_product(item) for item in products]
+
+    async def get(self, product_id: int) -> Product:
+        """Fetch a single product by its webshop identifier."""
+        response = await self._client.request(
+            "GET",
+            f"/mobile-services/product/detail/v4/fir/{product_id}",
+        )
+        payload = response.json()
+        product_card = payload.get("productCard")
+        if not isinstance(product_card, dict):
+            raise LookupError(f"Product {product_id} detail payload did not contain productCard.")
+        return self._map_product(product_card)
+
+    @staticmethod
+    def _map_product(payload: dict) -> Product:
+        return Product(
+            id=int(ProductsAPI._extract_product_id(payload)),
+            title=ProductsAPI._extract_title(payload),
+            brand=payload.get("brand"),
+            price=ProductsAPI._extract_price(payload),
+            unit_size=ProductsAPI._extract_unit_size(payload),
+            image_url=ProductsAPI._extract_image_url(payload),
+        )
+
+    @staticmethod
+    def _extract_product_id(payload: dict) -> int:
+        product_id = payload.get("id", payload.get("webshopId"))
+        if product_id is None:
+            raise KeyError("Product payload did not contain id or webshopId")
+        return int(product_id)
+
+    @staticmethod
+    def _extract_title(payload: dict) -> str:
+        title = payload.get("title") or payload.get("description")
+        if not title:
+            raise KeyError("Product payload did not contain title or description")
+        return title
+
+    @staticmethod
+    def _extract_price(payload: dict) -> float | None:
+        price = (
+            payload.get("currentPrice") or payload.get("priceBeforeBonus") or payload.get("price")
+        )
+        if isinstance(price, dict):
+            price = price.get("amount")
+        return float(price) if price is not None else None
+
+    @staticmethod
+    def _extract_unit_size(payload: dict) -> str | None:
+        return (
+            payload.get("unitSize")
+            or payload.get("salesUnitSize")
+            or payload.get("unitPriceDescription")
+        )
+
+    @staticmethod
+    def _extract_image_url(payload: dict) -> str | None:
+        image_url = payload.get("imageUrl")
+        images = payload.get("images")
+        if image_url is None and isinstance(images, list) and images:
+            first_image = images[0]
+            if isinstance(first_image, dict):
+                image_url = first_image.get("url")
+        return image_url

appie/receipts.py

@@ -0,0 +1,106 @@
+"""Receipt listing and detail operations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+from appie.models import Receipt, ReceiptProduct
+
+POS_RECEIPTS_QUERY = """
+query FetchPosReceipts($offset: Int!, $limit: Int!) {
+  posReceiptsPage(pagination: {offset: $offset, limit: $limit}) {
+    posReceipts {
+      id
+      dateTime
+      totalAmount { amount }
+    }
+  }
+}
+"""
+
+POS_RECEIPT_DETAILS_QUERY = """
+query FetchReceipt($id: String!) {
+  posReceiptDetails(id: $id) {
+    id
+    memberId
+    products {
+      id
+      quantity
+      name
+      price { amount }
+      amount { amount }
+    }
+  }
+}
+"""
+
+
+class GraphQLClient(Protocol):
+    """Protocol for clients that can execute GraphQL requests."""
+
+    async def graphql(self, query: str, variables: dict[str, Any] | None = None) -> dict:
+        """Execute a GraphQL request."""
+        ...
+
+
+class ReceiptsAPI:
+    """High-level receipt operations."""
+
+    def __init__(self, client: GraphQLClient) -> None:
+        self._client = client
+
+    async def list_pos_receipts(self, limit: int = 50) -> list[Receipt]:
+        """Return POS receipt summaries without line items."""
+        data = await self._client.graphql(POS_RECEIPTS_QUERY, {"offset": 0, "limit": limit})
+        receipts = (data.get("posReceiptsPage") or {}).get("posReceipts", [])
+        return [self._map_receipt_summary(item) for item in receipts]
+
+    async def get_pos_receipt(self, receipt_id: str) -> Receipt:
+        """Return a single POS receipt including product line items."""
+        data = await self._client.graphql(POS_RECEIPT_DETAILS_QUERY, {"id": receipt_id})
+        receipt = data["posReceiptDetails"]
+        summary = await self._get_receipt_summary(receipt_id)
+        return self._map_receipt_detail(receipt, summary=summary)
+
+    async def list_all(self, limit: int = 50) -> list[Receipt]:
+        """Return receipt summaries sorted by datetime descending."""
+        receipts = await self.list_pos_receipts(limit=limit)
+        return sorted(receipts, key=lambda receipt: receipt.datetime, reverse=True)
+
+    @staticmethod
+    def _map_receipt_summary(payload: dict) -> Receipt:
+        return Receipt(
+            id=str(payload["id"]),
+            datetime=datetime.fromisoformat(payload["dateTime"]),
+            store_name=None,
+            total=float(payload["totalAmount"]["amount"]),
+            products=[],
+        )
+
+    @classmethod
+    def _map_receipt_detail(cls, payload: dict, summary: Receipt | None = None) -> Receipt:
+        products = [
+            ReceiptProduct(
+                id=int(line["id"]),
+                name=line["name"],
+                quantity=float(line["quantity"]),
+                price_per_unit=float((line.get("price") or {}).get("amount") or 0.0),
+                total_price=float(line["amount"]["amount"]),
+            )
+            for line in payload.get("products", [])
+        ]
+        return Receipt(
+            id=str(payload["id"]),
+            datetime=summary.datetime if summary else datetime.min,
+            store_name=summary.store_name if summary else None,
+            total=summary.total if summary else sum(product.total_price for product in products),
+            products=products,
+        )
+
+    async def _get_receipt_summary(self, receipt_id: str) -> Receipt | None:
+        receipts = await self.list_pos_receipts(limit=100)
+        for receipt in receipts:
+            if receipt.id == receipt_id:
+                return receipt
+        return None

python_appie-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: python-appie
+Version: 0.1.0
+Summary: Unofficial Python client for the Albert Heijn API.
+Project-URL: Homepage, https://github.com/tijnschouten/appie
+Project-URL: Documentation, https://tijnschouten.github.io/appie/
+Project-URL: Repository, https://github.com/tijnschouten/appie
+Project-URL: Issues, https://github.com/tijnschouten/appie/issues
+Author: Codex
+Requires-Python: >=3.11
+Requires-Dist: httpx
+Requires-Dist: playwright>=1.52.0
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.390; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-appie
+
+`python-appie` is an unofficial async Python client for the Albert Heijn API.
+
+Full documentation lives in [`docs/`](/Users/tijnschouten/repos/personal/appie/docs), is built from [`mkdocs.yml`](/Users/tijnschouten/repos/personal/appie/mkdocs.yml), and is intended to be published at [tijnschouten.github.io/appie](https://tijnschouten.github.io/appie/).
+
+Releases are intended to publish to PyPI as `python-appie` from version tags via GitHub Actions.
+
+## Install
+
+```bash
+uv add python-appie
+```
+
+Or:
+
+```bash
+pip install python-appie
+```
+
+For local development in this repository:
+
+```bash
+uv sync --extra dev
+pre-commit install
+```
+
+## Quick start
+
+Authenticate once:
+
+```bash
+uv run appie-login
+```
+
+This opens Chrome for an interactive AH login and captures the OAuth redirect code automatically. If automatic capture cannot start, the CLI falls back to asking for the redirect URL or raw code manually.
+
+Then use the client:
+
+```python
+import asyncio
+
+from appie import AHClient
+
+
+async def main() -> None:
+    async with AHClient() as client:
+        products = await client.products.search("melk", limit=3)
+        for product in products:
+            print(product)
+
+
+asyncio.run(main())
+```
+
+Tokens are stored in `~/.config/appie/tokens.json` and refreshed automatically when they are close to expiring.
+
+## Features
+
+### Authentication
+
+- `appie-login` CLI for browser-based login
+- automatic code capture from the AH redirect flow
+- token persistence in `~/.config/appie/tokens.json`
+- automatic token refresh using the stored refresh token
+
+### Products
+
+- search products via `client.products.search(query, limit=10)`
+- fetch a single product via `client.products.get(product_id)`
+
+Example:
+
+```python
+import asyncio
+
+from appie import AHClient
+
+
+async def main() -> None:
+    async with AHClient() as client:
+        product = await client.products.get(1525)
+        print(product)
+
+
+asyncio.run(main())
+```
+
+### Receipts
+
+- list in-store POS receipt summaries via `client.receipts.list_all(limit=50)`
+- fetch a receipt with line items via `client.receipts.get_pos_receipt(receipt_id)`
+
+Important:
+`list_all()` and `list_pos_receipts()` return receipt summaries. In those results, `products` is intentionally empty.
+To retrieve line items, call `get_pos_receipt()` with a receipt ID from the summary list.
+
+Example:
+
+```python
+import asyncio
+
+from appie import AHClient
+
+
+async def main() -> None:
+    async with AHClient() as client:
+        receipts = await client.receipts.list_all(limit=5)
+        detailed = await client.receipts.get_pos_receipt(receipts[0].id)
+        print(detailed)
+
+
+asyncio.run(main())
+```
+
+### Shopping lists
+
+- add an item via `client.lists.add_item(description, quantity=1, product_id=None)`
+- use `MockAHClient` for local development and tests without touching AH
+
+Example:
+
+```python
+import asyncio
+
+from appie import AHClient
+
+
+async def main() -> None:
+    async with AHClient() as client:
+        item = await client.lists.add_item("Halfvolle melk", quantity=2)
+        print(item)
+
+
+asyncio.run(main())
+```
+
+Current limitation:
+shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear()` still raise `NotImplementedError` until their live API shape is confirmed.
+
+## API overview
+
+### Main client
+
+- `AHClient()`
+- `MockAHClient()`
+- `await client.login()`
+- `await client.graphql(query, variables=None)`
+
+### Auth client
+
+- `AHAuthClient.get_anonymous_token()`
+- `AHAuthClient.login_with_code(code)`
+- `AHAuthClient.refresh_token(refresh_token)`
+
+### Sub-APIs
+
+- `client.products.search(query, limit=10)`
+- `client.products.get(product_id)`
+- `client.receipts.list_pos_receipts(limit=50)`
+- `client.receipts.list_all(limit=50)`
+- `client.receipts.get_pos_receipt(receipt_id)`
+- `client.lists.add_item(description, quantity=1, product_id=None)`
+- `client.lists.get_list()`
+- `client.lists.remove_item(item_id)`
+- `client.lists.clear()`
+
+## Development
+
+Run checks locally:
+
+```bash
+uv run ruff format .
+uv run --extra dev ruff check .
+uv run --extra dev pyright
+uv run --extra dev pytest
+uv run --extra dev mkdocs build --strict
+```
+
+## Notes
+
+- This client is unofficial and may break when Albert Heijn changes its backend.
+- Receipt support currently covers in-store POS receipts.
+- Shopping-list support only implements the verified add-item mutation; other operations raise explicit `NotImplementedError` until their GraphQL shape is confirmed.
+- Receipt summaries do not include line items; call `get_pos_receipt()` for a detailed receipt.
+- Endpoint discovery for this package is inspired by [gwillem/appie-go](https://github.com/gwillem/appie-go).

python_appie-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+appie/__init__.py,sha256=9BOqxGRrvx5Vyb5Y3bKziVGP3iDKiwfkVTwAyq-KfMI,1009
+appie/auth.py,sha256=l_yxwH9bvjyOKXxW10qbW2pkbwX38CtohJDdfgHibv4,6132
+appie/client.py,sha256=5EQFYfQgTpU1dr6qY7rFN9KeVz6ZcjuqFSCKjefI3fc,9140
+appie/lists.py,sha256=XaoNkcE9OLHJKahYmxwE5lhdkIoBksQNTWI8QScGiQU,2409
+appie/mock.py,sha256=ZxN7BZYA-odwGWUkf-mXb5Ky_hXJq-gVYPkOFSHPF7I,7078
+appie/models.py,sha256=AprEQVIA8wSZuoCeL9--wQlp_cFtvyvtFncBkZtAgAY,1959
+appie/products.py,sha256=Hk9loD7L-SPx7tZVzghBx6Q9pMtrEfZhZjHxX7POI4s,3530
+appie/receipts.py,sha256=KeLqJI1D3pIbV9qX1uiPKRLLBOjN4BvPrBxZe6_Naso,3526
+python_appie-0.1.0.dist-info/METADATA,sha256=KKx0B0eB28L_tEg581mffteZt0OWL6a0h94v04zhW40,5587
+python_appie-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_appie-0.1.0.dist-info/entry_points.txt,sha256=A8yGyh6r6ciUAoKrHDbCB2hMlim0P3RDdnaMgbDclCc,48
+python_appie-0.1.0.dist-info/RECORD,,

python_appie-0.1.0.dist-info/WHEEL

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

python_appie-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+appie-login = appie:login_cli