python-appie 0.1.0__tar.gz

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

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Ruff format check
+        run: uv run ruff format --check .
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Pyright
+        run: uv run pyright
+      - name: Pytest
+        run: uv run pytest
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Build docs
+        run: uv run mkdocs build --strict

python_appie-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Build docs
+        run: uv run mkdocs build --strict
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

python_appie-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,47 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Build package
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-appie-dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/python-appie
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-appie-dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_appie-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+.coverage
+htmlcov/
+site/

python_appie-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format .
+        language: system
+        pass_filenames: false
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check .
+        language: system
+        pass_filenames: false
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+      - id: mkdocs-build
+        name: mkdocs build
+        entry: uv run mkdocs build --strict
+        language: system
+        pass_filenames: false

python_appie-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,186 @@
+# 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/docs/authentication.md

@@ -0,0 +1,21 @@
+# Authentication
+
+## Login flow
+
+The package uses a browser-assisted login flow exposed through `appie-login`.
+
+The CLI:
+
+- opens a Chrome window
+- waits for the AH redirect to `appie://login-exit?code=...`
+- exchanges that code for tokens
+- stores tokens in `~/.config/appie/tokens.json`
+
+## Token refresh
+
+Access tokens are refreshed automatically when they are close to expiry. Under normal usage, you should only need to run `appie-login` again when the stored refresh token is no longer valid.
+
+## Notes
+
+- This is not an official AH integration.
+- AH may change login requirements at any time.

python_appie-0.1.0/docs/cli.md

@@ -0,0 +1,11 @@
+# CLI
+
+## `appie-login`
+
+Authenticate and store tokens locally:
+
+```bash
+uv run appie-login
+```
+
+The CLI is intended as a one-time or occasional setup step. Day-to-day usage should normally rely on stored tokens and automatic refresh.

python_appie-0.1.0/docs/development.md

@@ -0,0 +1,28 @@
+# Development
+
+## Setup
+
+```bash
+uv sync --extra dev
+pre-commit install
+```
+
+## Quality checks
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+uv run mkdocs build
+```
+
+## Pre-commit
+
+This repository uses pre-commit hooks for:
+
+- `ruff format`
+- `ruff check`
+- `pyright`
+- `pytest`
+- `mkdocs build`

python_appie-0.1.0/docs/getting-started.md

@@ -0,0 +1,47 @@
+# Getting Started
+
+## Install
+
+```bash
+uv add python-appie
+```
+
+Or:
+
+```bash
+pip install python-appie
+```
+
+For local development in this repository:
+
+```bash
+uv sync --extra dev
+```
+
+## Login
+
+Run:
+
+```bash
+uv run appie-login
+```
+
+This opens Chrome and captures the AH login redirect code automatically. Tokens are stored in `~/.config/appie/tokens.json`.
+
+## First request
+
+```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())
+```

python_appie-0.1.0/docs/index.md

@@ -0,0 +1,29 @@
+# python-appie
+
+`python-appie` is an unofficial async Python client for the Albert Heijn API.
+
+It currently supports:
+
+- browser-based login via `appie-login`
+- token persistence and refresh
+- product search and product detail lookup
+- receipt summary listing
+- receipt detail retrieval with line items
+- shopping-list item creation
+
+## Current status
+
+This package talks to an unofficial API. That means:
+
+- the API may change without notice
+- fields and endpoints can break at any time
+- conservative usage is recommended
+
+## Read next
+
+- [Getting Started](getting-started.md)
+- [Authentication](authentication.md)
+- [Products](products.md)
+- [Receipts](receipts.md)
+- [Shopping Lists](lists.md)
+- [Development](development.md)