bilkatogo 0.2.0__tar.gz

bilkatogo-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Nissen
+
+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.

bilkatogo-0.2.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: bilkatogo
+Version: 0.2.0
+Summary: Async client and CLI for tracking BilkaToGo orders.
+Keywords: bilka,bilkatogo,danish,groceries,api,async
+Author: Nick Nissen
+Author-email: Nick Nissen <nickknissen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: AsyncIO
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tzdata ; sys_platform == 'win32'
+Requires-Dist: typer>=0.27.3,<0.28 ; extra == 'cli'
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/nickknissen/bilkatogo
+Project-URL: Repository, https://github.com/nickknissen/bilkatogo
+Project-URL: Issues, https://github.com/nickknissen/bilkatogo/issues
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+# bilkatogo
+
+Track your [BilkaToGo](https://www.bilkatogo.dk) grocery orders: an async Python library, a
+command line tool and a Home Assistant integration that follow your order from the moment it is
+placed until you pick it up, including which products Bilka substituted.
+
+> **Unofficial.** This project is not affiliated with or endorsed by Bilka or Salling Group. It
+> uses the same private web API as the bilkatogo.dk website, logging in with your email and
+> password. That API can change or break at any time.
+
+The library, the CLI and the Home Assistant integration are released together and always share
+the same version.
+
+## Installation
+
+Library only (it depends on httpx, plus tzdata on Windows):
+
+```sh
+pip install bilkatogo
+```
+
+With the command line tool:
+
+```sh
+pip install 'bilkatogo[cli]'
+```
+
+Or run the CLI without installing it:
+
+```sh
+uvx --from 'bilkatogo[cli]' bilkatogo --help
+```
+
+Home Assistant: add the integration from the Home Assistant Marketplace (HACS) by searching
+for **BilkaToGo**, or add `https://github.com/nickknissen/bilkatogo` as a custom repository of
+type Integration. Restart Home Assistant afterwards.
+
+## Command line
+
+```sh
+bilkatogo login                 # log in and store the session
+bilkatogo orders --limit 10     # list your most recent orders
+bilkatogo order                 # show the Current Order with its details
+bilkatogo order 900000000001    # show one order by Order Number
+bilkatogo pickup-points         # list Pickup Points and their Store, * marks your Cart's
+bilkatogo search skyr           # Products with Price, stock and Offer at your Cart's Store
+bilkatogo search skyr --pickup-point "Bilka Vejle" --limit 5
+```
+
+Every command accepts `--json` for machine-readable output.
+
+Credentials are looked up in this order:
+
+1. `--email` and `--password`
+2. the `BILKATOGO_EMAIL` and `BILKATOGO_PASSWORD` environment variables
+3. `config.json` (with `email` and `password` keys) in the user config directory
+   (`~/.config/bilkatogo` on Linux, `%APPDATA%\bilkatogo` on Windows,
+   `~/Library/Application Support/bilkatogo` on macOS); set `BILKATOGO_CONFIG_DIR` to use
+   another directory
+4. an interactive prompt
+
+The session is stored as `session.json` in the same directory, so later commands don't log in
+again.
+
+The Current Order is the unfinished order with the earliest pickup slot or, when every order
+is finished, the most recently finished one.
+
+## Library
+
+```python
+import asyncio
+
+from bilkatogo import BilkaToGoClient, FileTokenStorage
+
+
+async def main() -> None:
+    async with BilkaToGoClient(
+        "you@example.com",
+        "your-password",
+        token_storage=FileTokenStorage("session.json"),
+    ) as client:
+        for order in await client.get_orders(limit=5):
+            print(order.order_number, order.status, order.pickup_slot)
+
+        current = await client.get_current_order()
+        if current:
+            if current.pickup_code:
+                print("Pickup Code:", current.pickup_code.code)
+            for substitution in current.substitutions:
+                print(substitution.original_product, "->", substitution.replacement_product)
+
+
+asyncio.run(main())
+```
+
+- `BilkaToGoClient(email, password, *, token_storage=None, httpx_client=None)` is an async
+  context manager. Pass your own `httpx.AsyncClient` to control timeouts or proxies; the
+  client only closes clients it created itself.
+- `login()`, `get_orders(limit=5)`, `get_order(order_number)` and `get_current_order()` are the
+  public operations. The client logs in on demand, refreshes the session before it expires and
+  logs in again when Bilka rejects it.
+- `token_storage` is any `TokenStorage` (async `load()` and `save(data)`). `FileTokenStorage`
+  stores the session in a JSON file.
+- Errors derive from `BilkaToGoError`: `InvalidCredentialsError`, `BilkaUnreachableError` and
+  `UnexpectedResponseError`.
+- `Order.status` is an `OrderStatus` (Processing, Received, Packed, Picked Up, Not Collected,
+  Cancelled, Sold Out, Unknown), using the same words as the website. The raw Bilka status code
+  is kept in `status_code`. The mapping is listed in [GLOSSARY.md](GLOSSARY.md).
+- `PickupSlot.starts_at` and `ends_at` are timezone-aware datetimes in Europe/Copenhagen.
+- Amounts are `Decimal` kroner.
+- `OrderDetails.order_total` is the Order Total, broken down into `deposit`, `service_fee`,
+  `packaging`, `delivery_fee` and `discount`. `ordered_total` is what the Order cost when it was
+  placed, looked up in the order history (`None` when it is not among the latest 20 Orders).
+  Pass an `Order` to `get_order` instead of its number to skip that lookup.
+
+## Home Assistant
+
+1. Install the integration (see [Installation](#installation)) and restart Home Assistant.
+2. Go to **Settings > Devices & services > Add integration** and pick **BilkaToGo**.
+3. Sign in with the email and password you use on bilkatogo.dk. Add the integration once per
+   account.
+
+If the password changes, Home Assistant asks you to sign in again.
+
+The integration polls Bilka every 60 minutes, and every 5 minutes from 3 hours before the
+pickup slot starts until the order is picked up, not collected or cancelled.
+
+### Entities
+
+All entities describe the Current Order.
+
+| Entity | State | Attributes |
+|---|---|---|
+| Order Status | Processing, Received, Packed, Picked Up, Not Collected, Cancelled, Sold Out or Unknown | Bilka status code |
+| Substitutions | Number of substituted products | List of Original Product, Replacement Product and the Replacement Product's quantity |
+| Missing Items | Number of products packed short without a replacement | List of Product, Article Number, ordered and missing quantity |
+| Order Total | What you pay for the order now (DKK) | Order Number, Ordered Total, difference from the Ordered Total (negative when you pay less), Deposit, Service Fee, Packaging, Delivery Fee, Discount |
+| Pickup Slot | Start of the pickup slot (timestamp, Europe/Copenhagen) | Order Number, Order Total (DKK), Pickup Slot end |
+| Pickup Code | The code you enter at check-in | Order Number, Order Total (DKK) |
+| Pickup Point | The Bilka store you pick up from | Order Number, Order Total (DKK) |
+
+Substitutions, Missing Items, the Pickup Code and the Order Total breakdown (Deposit, Service
+Fee, Packaging, Delivery Fee, Discount) are fetched once the order is packed. Before that the
+Order Total is Bilka's estimate from the order history.
+
+An Order Status of Unknown (`unrecognized`) means Bilka sent a status code the integration does
+not know yet; the code is in the attribute. Without any order the entities have no state.
+
+### Event `bilkatogo_substitution`
+
+Fired once for every new substitution, with this data:
+
+| Field | Example |
+|---|---|
+| `order_number` | `900000000001` |
+| `original_product` | `Arla minimælk 1 l` |
+| `replacement_product` | `Øko minimælk 1 l` |
+| `quantity` | `2` |
+
+Substitutions that already fired are remembered across restarts and reloads. An automation
+that sends a notification:
+
+```yaml
+automation:
+  - alias: BilkaToGo substitution
+    triggers:
+      - trigger: event
+        event_type: bilkatogo_substitution
+    actions:
+      - action: notify.notify
+        data:
+          message: >
+            {{ trigger.event.data.original_product }} was replaced by
+            {{ trigger.event.data.replacement_product }}
+            ({{ trigger.event.data.quantity }}).
+```
+
+### Event `bilkatogo_missing_item`
+
+Fired once for every new Missing Item, with this data:
+
+| Field | Example |
+|---|---|
+| `order_number` | `900000000003` |
+| `product` | `Skyr` |
+| `article_number` | `932058` |
+| `ordered_quantity` | `4` |
+| `missing_quantity` | `2` |
+
+Missing Items that already fired are remembered across restarts and reloads. An automation
+that sends a notification:
+
+```yaml
+automation:
+  - alias: BilkaToGo missing item
+    triggers:
+      - trigger: event
+        event_type: bilkatogo_missing_item
+    actions:
+      - action: notify.notify
+        data:
+          message: >
+            {{ trigger.event.data.product }}: {{ trigger.event.data.missing_quantity }}
+            of {{ trigger.event.data.ordered_quantity }} missing.
+```
+
+## Development
+
+Library and CLI:
+
+```sh
+uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest
+```
+
+Home Assistant tests use their own dependency group, because
+`pytest-homeassistant-custom-component` pins its own pytest and httpx. Keep them in a
+separate virtual environment so the library environment stays untouched:
+
+```sh
+UV_PROJECT_ENVIRONMENT=.venv-ha uv run --no-default-groups --group ha pytest tests/ha
+UV_PROJECT_ENVIRONMENT=.venv-ha uv run --no-default-groups --group ha ty check custom_components tests/ha
+```
+
+Home Assistant does not run on Windows; use Linux, WSL or CI for these.
+
+The Home Assistant tests run the real library against the fake Bilka backend in
+`tests/fake_bilka.py`. The integration creates its httpx client with Home Assistant's
+`create_async_httpx_client`, and `tests/ha/conftest.py` routes every request at the
+transport level to the fake backend with `respx`, so nothing in the integration is patched.
+
+Releasing is described in [AGENTS.md](AGENTS.md#releasing).
+
+## License
+
+MIT

bilkatogo-0.2.0/README.md

@@ -0,0 +1,235 @@
+# bilkatogo
+
+Track your [BilkaToGo](https://www.bilkatogo.dk) grocery orders: an async Python library, a
+command line tool and a Home Assistant integration that follow your order from the moment it is
+placed until you pick it up, including which products Bilka substituted.
+
+> **Unofficial.** This project is not affiliated with or endorsed by Bilka or Salling Group. It
+> uses the same private web API as the bilkatogo.dk website, logging in with your email and
+> password. That API can change or break at any time.
+
+The library, the CLI and the Home Assistant integration are released together and always share
+the same version.
+
+## Installation
+
+Library only (it depends on httpx, plus tzdata on Windows):
+
+```sh
+pip install bilkatogo
+```
+
+With the command line tool:
+
+```sh
+pip install 'bilkatogo[cli]'
+```
+
+Or run the CLI without installing it:
+
+```sh
+uvx --from 'bilkatogo[cli]' bilkatogo --help
+```
+
+Home Assistant: add the integration from the Home Assistant Marketplace (HACS) by searching
+for **BilkaToGo**, or add `https://github.com/nickknissen/bilkatogo` as a custom repository of
+type Integration. Restart Home Assistant afterwards.
+
+## Command line
+
+```sh
+bilkatogo login                 # log in and store the session
+bilkatogo orders --limit 10     # list your most recent orders
+bilkatogo order                 # show the Current Order with its details
+bilkatogo order 900000000001    # show one order by Order Number
+bilkatogo pickup-points         # list Pickup Points and their Store, * marks your Cart's
+bilkatogo search skyr           # Products with Price, stock and Offer at your Cart's Store
+bilkatogo search skyr --pickup-point "Bilka Vejle" --limit 5
+```
+
+Every command accepts `--json` for machine-readable output.
+
+Credentials are looked up in this order:
+
+1. `--email` and `--password`
+2. the `BILKATOGO_EMAIL` and `BILKATOGO_PASSWORD` environment variables
+3. `config.json` (with `email` and `password` keys) in the user config directory
+   (`~/.config/bilkatogo` on Linux, `%APPDATA%\bilkatogo` on Windows,
+   `~/Library/Application Support/bilkatogo` on macOS); set `BILKATOGO_CONFIG_DIR` to use
+   another directory
+4. an interactive prompt
+
+The session is stored as `session.json` in the same directory, so later commands don't log in
+again.
+
+The Current Order is the unfinished order with the earliest pickup slot or, when every order
+is finished, the most recently finished one.
+
+## Library
+
+```python
+import asyncio
+
+from bilkatogo import BilkaToGoClient, FileTokenStorage
+
+
+async def main() -> None:
+    async with BilkaToGoClient(
+        "you@example.com",
+        "your-password",
+        token_storage=FileTokenStorage("session.json"),
+    ) as client:
+        for order in await client.get_orders(limit=5):
+            print(order.order_number, order.status, order.pickup_slot)
+
+        current = await client.get_current_order()
+        if current:
+            if current.pickup_code:
+                print("Pickup Code:", current.pickup_code.code)
+            for substitution in current.substitutions:
+                print(substitution.original_product, "->", substitution.replacement_product)
+
+
+asyncio.run(main())
+```
+
+- `BilkaToGoClient(email, password, *, token_storage=None, httpx_client=None)` is an async
+  context manager. Pass your own `httpx.AsyncClient` to control timeouts or proxies; the
+  client only closes clients it created itself.
+- `login()`, `get_orders(limit=5)`, `get_order(order_number)` and `get_current_order()` are the
+  public operations. The client logs in on demand, refreshes the session before it expires and
+  logs in again when Bilka rejects it.
+- `token_storage` is any `TokenStorage` (async `load()` and `save(data)`). `FileTokenStorage`
+  stores the session in a JSON file.
+- Errors derive from `BilkaToGoError`: `InvalidCredentialsError`, `BilkaUnreachableError` and
+  `UnexpectedResponseError`.
+- `Order.status` is an `OrderStatus` (Processing, Received, Packed, Picked Up, Not Collected,
+  Cancelled, Sold Out, Unknown), using the same words as the website. The raw Bilka status code
+  is kept in `status_code`. The mapping is listed in [GLOSSARY.md](GLOSSARY.md).
+- `PickupSlot.starts_at` and `ends_at` are timezone-aware datetimes in Europe/Copenhagen.
+- Amounts are `Decimal` kroner.
+- `OrderDetails.order_total` is the Order Total, broken down into `deposit`, `service_fee`,
+  `packaging`, `delivery_fee` and `discount`. `ordered_total` is what the Order cost when it was
+  placed, looked up in the order history (`None` when it is not among the latest 20 Orders).
+  Pass an `Order` to `get_order` instead of its number to skip that lookup.
+
+## Home Assistant
+
+1. Install the integration (see [Installation](#installation)) and restart Home Assistant.
+2. Go to **Settings > Devices & services > Add integration** and pick **BilkaToGo**.
+3. Sign in with the email and password you use on bilkatogo.dk. Add the integration once per
+   account.
+
+If the password changes, Home Assistant asks you to sign in again.
+
+The integration polls Bilka every 60 minutes, and every 5 minutes from 3 hours before the
+pickup slot starts until the order is picked up, not collected or cancelled.
+
+### Entities
+
+All entities describe the Current Order.
+
+| Entity | State | Attributes |
+|---|---|---|
+| Order Status | Processing, Received, Packed, Picked Up, Not Collected, Cancelled, Sold Out or Unknown | Bilka status code |
+| Substitutions | Number of substituted products | List of Original Product, Replacement Product and the Replacement Product's quantity |
+| Missing Items | Number of products packed short without a replacement | List of Product, Article Number, ordered and missing quantity |
+| Order Total | What you pay for the order now (DKK) | Order Number, Ordered Total, difference from the Ordered Total (negative when you pay less), Deposit, Service Fee, Packaging, Delivery Fee, Discount |
+| Pickup Slot | Start of the pickup slot (timestamp, Europe/Copenhagen) | Order Number, Order Total (DKK), Pickup Slot end |
+| Pickup Code | The code you enter at check-in | Order Number, Order Total (DKK) |
+| Pickup Point | The Bilka store you pick up from | Order Number, Order Total (DKK) |
+
+Substitutions, Missing Items, the Pickup Code and the Order Total breakdown (Deposit, Service
+Fee, Packaging, Delivery Fee, Discount) are fetched once the order is packed. Before that the
+Order Total is Bilka's estimate from the order history.
+
+An Order Status of Unknown (`unrecognized`) means Bilka sent a status code the integration does
+not know yet; the code is in the attribute. Without any order the entities have no state.
+
+### Event `bilkatogo_substitution`
+
+Fired once for every new substitution, with this data:
+
+| Field | Example |
+|---|---|
+| `order_number` | `900000000001` |
+| `original_product` | `Arla minimælk 1 l` |
+| `replacement_product` | `Øko minimælk 1 l` |
+| `quantity` | `2` |
+
+Substitutions that already fired are remembered across restarts and reloads. An automation
+that sends a notification:
+
+```yaml
+automation:
+  - alias: BilkaToGo substitution
+    triggers:
+      - trigger: event
+        event_type: bilkatogo_substitution
+    actions:
+      - action: notify.notify
+        data:
+          message: >
+            {{ trigger.event.data.original_product }} was replaced by
+            {{ trigger.event.data.replacement_product }}
+            ({{ trigger.event.data.quantity }}).
+```
+
+### Event `bilkatogo_missing_item`
+
+Fired once for every new Missing Item, with this data:
+
+| Field | Example |
+|---|---|
+| `order_number` | `900000000003` |
+| `product` | `Skyr` |
+| `article_number` | `932058` |
+| `ordered_quantity` | `4` |
+| `missing_quantity` | `2` |
+
+Missing Items that already fired are remembered across restarts and reloads. An automation
+that sends a notification:
+
+```yaml
+automation:
+  - alias: BilkaToGo missing item
+    triggers:
+      - trigger: event
+        event_type: bilkatogo_missing_item
+    actions:
+      - action: notify.notify
+        data:
+          message: >
+            {{ trigger.event.data.product }}: {{ trigger.event.data.missing_quantity }}
+            of {{ trigger.event.data.ordered_quantity }} missing.
+```
+
+## Development
+
+Library and CLI:
+
+```sh
+uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest
+```
+
+Home Assistant tests use their own dependency group, because
+`pytest-homeassistant-custom-component` pins its own pytest and httpx. Keep them in a
+separate virtual environment so the library environment stays untouched:
+
+```sh
+UV_PROJECT_ENVIRONMENT=.venv-ha uv run --no-default-groups --group ha pytest tests/ha
+UV_PROJECT_ENVIRONMENT=.venv-ha uv run --no-default-groups --group ha ty check custom_components tests/ha
+```
+
+Home Assistant does not run on Windows; use Linux, WSL or CI for these.
+
+The Home Assistant tests run the real library against the fake Bilka backend in
+`tests/fake_bilka.py`. The integration creates its httpx client with Home Assistant's
+`create_async_httpx_client`, and `tests/ha/conftest.py` routes every request at the
+transport level to the fake backend with `respx`, so nothing in the integration is patched.
+
+Releasing is described in [AGENTS.md](AGENTS.md#releasing).
+
+## License
+
+MIT

bilkatogo-0.2.0/pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "bilkatogo"
+version = "0.2.0"
+description = "Async client and CLI for tracking BilkaToGo orders."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "bilka",
+    "bilkatogo",
+    "danish",
+    "groceries",
+    "api",
+    "async",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: AsyncIO",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "httpx>=0.28.1",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[[project.authors]]
+name = "Nick Nissen"
+email = "nickknissen@gmail.com"
+
+[project.optional-dependencies]
+cli = ["typer>=0.27.3,<0.28"]
+
+[project.scripts]
+bilkatogo = "bilkatogo.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/nickknissen/bilkatogo"
+Repository = "https://github.com/nickknissen/bilkatogo"
+Issues = "https://github.com/nickknissen/bilkatogo/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+default-groups = ["dev"]
+conflicts = [[
+    { group = "dev" },
+    { group = "ha" },
+]]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+extend-exclude = [
+    ".worktrees",
+    "*.md",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "LOG",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[tool.ty.src]
+include = [
+    "src/",
+    "tests/",
+    "release.py",
+]
+exclude = ["tests/ha/"]
+
+[tool.ty.rules]
+division-by-zero = "warn"
+
+[[tool.ty.overrides]]
+include = ["tests/"]
+
+[tool.ty.overrides.rules]
+invalid-assignment = "ignore"
+
+[dependency-groups]
+dev = [
+    "bilkatogo[cli]",
+    "pytest>=9.0.0",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.16.1",
+    "ty>=0.0.92",
+]
+ha = [
+    "pytest-homeassistant-custom-component==0.13.316",
+    "respx>=0.22.0",
+    "ty>=0.0.92",
+]