16 Commits
Author SHA1 Message Date
rick d5f32d956e Merge agent/add-french-translation: French translation by aurel (PR #14), v0.4.6 2026-11-07 18:42:52 +01:00
rickandCursor 529894688b openspec(add-french-translation): apply progress (PR #14 commit, 0.4.6)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 18:36:01 +01:00
rickandCursor c77029188f PROJECT_HYGIENE: UI strings need English and French
PR #14 adds fr.json and a key-parity test; record the rule so agents write the French string instead of relaxing the test.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 18:36:01 +01:00
rickandCursor 9a81654579 Version 0.4.6: French translation
Ships the French translation contributed by aurel in PR #14 (704f55e).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 18:35:46 +01:00
rickandCursor 2050051f66 openspec(add-french-translation): propose artifacts
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 18:35:09 +01:00
aurel 704f55e595 feat(i18n): add complete French translation (fr.json) 2026-11-07 13:23:59 +01:00
rickandCursor 851ec3a495 openspec: archive add-oktoberfest-keg-art
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:37:25 +01:00
rick 1309cff411 Merge agent/add-oktoberfest-keg-art: Löwenbräu Oktoberfestbier spelling, v0.4.5 2026-11-07 12:37:15 +01:00
rickandCursor 5e1f790420 openspec(add-oktoberfest-keg-art): ship without on-device check 4.1 (maintainer decision)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:36:07 +01:00
rickandCursor 7f7ac13fda openspec(add-oktoberfest-keg-art): apply progress (rename, card artwork, 0.4.5)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:35:35 +01:00
rickandCursor 1598e7b031 Spell keg 29745 as Löwenbräu Oktoberfestbier; version 0.4.5
The catalog had the umlauts stripped, unlike its own 454 entry (Löwenbräu) and the companion card. Product ID and position are unchanged. Issue #8; ships with card 0.4.5, which adds keg artwork for both Oktoberfestbier kegs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:34:20 +01:00
rickandCursor 88dc717833 openspec(add-oktoberfest-keg-art): propose artifacts
Issue #8: keg artwork for Löwenbräu (29745) and Spaten (33918) Oktoberfestbier on the card, and the integration's 29745 name spelled with umlauts. Joint 0.4.5 release.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:32:48 +01:00
rickandCursor d0bbda6b51 PROJECT_HYGIENE: note pre-existing main-spec format failures
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:26:48 +01:00
rickandCursor 89783da7af openspec: archive add-keg-48180, sync specs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:26:10 +01:00
rickandCursor 8f2bced6ee openspec: archive fix-cognito-signin, sync specs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:26:10 +01:00
rickandCursor 82062da60c openspec: archive add-keg-47792, sync specs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-07 12:26:10 +01:00
34 changed files with 408 additions and 15 deletions
+3 -1
View File
@@ -192,12 +192,14 @@ When the user corrects your approach, append a one-line rule here before ending
- **`numberOfPoursSinceStartup` resets to 0 on a machine power cycle** (confirmed 2026-06-01: power-cycled the machine at pours=16, reloaded the integration, Pours read 0). It counts since machine startup, NOT since keg insertion. Do not base keg-change detection on the pour counter — a power cycle (outage, unplug, firmware update) would false-trigger it. `kegVolume` (Keg Remaining) was confirmed unchanged across the same power cycle/reload, so a power cycle produces no spurious volume jump — volume-jump signals (b/c) and the manual button are the power-cycle-safe detectors; prefer them.
- **TODO — verification debt, do this when the next keg is fitted: confirm the keg-freshness baseline survives a reauth.** `fix-reauth-flow` (archived 2026-09-06) was verified on-device for the reauth flow itself, but the machine had no keg in the tap, so there was no freshness countdown to preserve and task 6.6 could not be checked. The fix uses `async_update_reload_and_abort`, which reloads the config entry — the exact moment a `RestoreEntity` baseline could be lost. After the next keg change, trigger a reauth (or reload the integration) and confirm Keg Freshness keeps its countdown instead of resetting to unknown. If it resets, that is a real regression in `PerfectDraftKegFreshnessSensor`'s restore path, not in the config flow.
- **Never add a non-numeric key to `keg_catalog.json`.** `_load_keg_catalog` in `sensor.py` builds `{int(k): v for k, v in raw.items()}` and catches `ValueError` by returning `{}`. A single `_meta` or `_source` key therefore disables the *entire* catalog — every keg reports no name — and says so only at debug level. Recording provenance or attribution inside that file requires changing the loader first. `tests/test_keg_catalog.py::test_keys_are_numeric` guards this.
- **Every UI string change needs English and French (since 0.4.6, 2026-11-07).** When you add, rename or remove a key in `strings.json`, make the same change to `translations/en.json` and `translations/fr.json` in the same commit, keeping each `{placeholder}` name. Write a real French string: no English placeholder, and do not relax `tests/test_translations.py`, which fails on any key mismatch. The maintainer chose strict parity over Home Assistant's English fallback so French never silently falls behind. Keep button and entity names short; they display in narrow UI space.
- **A new integration catalog ID is not done until the card maps it.** The companion card joins on `kegId` against `scripts/keg-catalog.reference.json`. Adding a row to `keg_catalog.json` without binding the card entry (and re-syncing that snapshot) ships a named **Keg** sensor that the card still treats as unknown. The card may already have the beer under a slug with no `kegId` — check before adding a duplicate entry.
- **TODO — verification debt from `backport-keg-catalog` (archived 2026-09-06), clear this after installing v0.3.2 via HACS: confirm the `Keg` sensor still resolves the fitted keg.** The catalog file was replaced wholesale (86 → 114 entries) and verified statically only: exact diff shape, 114 int keys through the loader, and format guards in `tests/test_keg_catalog.py`. What was never exercised is the live path. On-device checks were impossible at the time — no HA on the dev host, and `.credentials.json`'s refresh token had expired (`NotAuthorizedException: Refresh Token has expired`), so even `test_harness.py` could not reach the API. Task group 5 in the archived change lists the four checks.
- **`test_harness.py` is stale: it reads `user_id` from `.credentials.json`, which now holds `email` / `access_token` / `id_token` / `refresh_token`.** It exits before doing anything useful. Fix the key names (and refresh the token per the README's reCAPTCHA step) before relying on it.
- **All five files in `openspec/specs/` fail `openspec validate --specs`** for a missing `## Purpose` section. Pre-existing and repo-wide as of 2026-09-06, so a failing spec validation is not necessarily caused by your change — check whether the error is only the Purpose one before chasing it.
- **TODO — verification debt from `fix-cognito-signin` (v0.4.4 shipped without on-device checks, maintainer decision 2026-11-07).** The Cognito direct sign-in was verified only by the automated suite (stdlib API tests and pytest config-flow tests) and the README token was checked in Firefox and Chromium; no sign-in reached the live service from Home Assistant. When there is time for a reinstall: (1) add the integration from scratch with a README token and confirm sensors populate; (2) a wrong password must return to the email/password form with `invalid_credentials` and Cognito's reason, and a token older than 2 minutes must stay on the token step with `token_rejected`; (3) trigger a reauth and confirm it succeeds (with a keg fitted, this also clears the Keg Freshness TODO above). Details in the archived change's `tasks.md`, section "Deferred".
- **TODO — verification debt from `add-keg-48180` (card 0.4.4 shipped without an on-device check, maintainer decision 2026-11-07).** Do it together with the `fix-cognito-signin` checks above: on a dashboard with card 0.4.4, confirm the card editor's beer picker lists Camden Stout with its artwork; with a 48180 keg fitted, confirm the Keg sensor reads "Camden Stout" and the card brands it.
- **TODO — verification debt from `add-keg-48180` and `add-oktoberfest-keg-art` (card 0.4.4 and 0.4.5 shipped without on-device checks, maintainer decisions 2026-11-07).** Do it together with the `fix-cognito-signin` checks above, on integration and card 0.4.5 or later: confirm the card editor's beer picker shows artwork for Camden Stout, Löwenbräu Oktoberfestbier and Spaten Oktoberfestbier, and that the two Oktoberfest images are sharp in the `hero` layout. With a 48180 keg fitted, confirm the Keg sensor reads "Camden Stout" and the card brands it. With a 29745 keg fitted, the sensor must read "Löwenbräu Oktoberfestbier" (with umlauts).
- **TODO — main specs fail `openspec validate --specs --strict` (all 5, pre-existing; seen 2026-11-07).** None of `openspec/specs/*/spec.md` has the `## Purpose` / `## Requirements` headers the current CLI requires; requirements start directly at `### Requirement:`. Archiving still works, but sync tooling and validation expect the headers. Fix in one housekeeping commit: add a short `## Purpose` and a `## Requirements` heading to each spec, then re-run strict validation.
- **TODO — own OpenSpec change: persist Cognito-refreshed tokens back to the config entry.** `PerfectDraftApiClient.refresh_access_token()` updates `_access_token`/`_id_token` in memory only, so every HA restart reloads the stale access token and burns a wasted 401-plus-refresh round trip before the first successful poll. Harmless today because the refresh token is what actually gates reauth and Cognito's `REFRESH_TOKEN_AUTH` never issues a new one, so nothing is lost — just wasteful. Deferred out of `fix-reauth-flow` to keep that diff surgical.
- **TODO — housekeeping, after `fix-cognito-signin` / `add-keg-48180` ship: take the GitHub token out of the `github` remote URLs** in both this repo and `Hassio-PerfectDraftPro-Component`. Not a leak (never committed; `.git/` is untracked), but `git remote -v` prints it. Order matters: first change `credential.helper` to an **absolute** path (`store --file=/home/rick/Lab/Dev/<repo>/.git/credentials`) — the current relative `.git/credentials` resolves against the worktree root, where `.git` is a file, so pushes from `.worktree/<topic>` only reach `github` (whose URL carries the token); pushing to `origin` from a worktree fails with "unable to open .git/credentials: Not a directory". Until fixed, push agent branches from the main checkout: `git push origin agent/<topic>` (no branch switch needed). Then strip the URL, run `git ls-remote github` from a worktree to prove auth, and update the `AGENTS.md` helper command to the absolute form.
- **Config-flow tests run in `.venv-test` (main checkout) on the system Python 3.14** with `pytest-homeassistant-custom-component==0.13.375` (core 2026.10.4). Run them from a worktree as `../../.venv-test/bin/pytest tests/`. Do not pin a harness that needs Python 3.12: there is no 3.12 and no C compiler on the dev host, so old numpy cannot build.
@@ -21,7 +21,7 @@
"2565": "Hoegaarden Rose",
"3550": "Leffe Winter",
"9156": "Leffe Royal Cascade",
"29745": "Lowenbrau Oktoberfestbier",
"29745": "Löwenbräu Oktoberfestbier",
"29775": "Goose Island Midway",
"29896": "Kwak",
"29974": "Spaten",
+1 -1
View File
@@ -1,7 +1,7 @@
{
"domain": "perfectdraft",
"name": "PerfectDraft",
"version": "0.4.4",
"version": "0.4.6",
"documentation": "https://github.com/Falkvinge/hassio-integration-perfectdraft-pro",
"issue_tracker": "https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/issues",
"codeowners": ["@Falkvinge"],
@@ -0,0 +1,70 @@
{
"config": {
"step": {
"user": {
"title": "Compte PerfectDraft",
"description": "Entrez vos identifiants de l'application PerfectDraft.",
"data": {
"email": "Adresse e-mail",
"password": "Mot de passe"
}
},
"token": {
"title": "Jeton de vérification",
"description": "Collez le jeton de vérification depuis le site PerfectDraft. Consultez les [instructions d'installation](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro#step-2-verification-token) pour le guide pas à pas de 30 secondes. Le jeton expire en 2 minutes, générez-le juste avant de le coller.",
"data": {
"recaptcha_token": "Jeton de vérification"
}
},
"reauth_confirm": {
"title": "Réauthentification PerfectDraft",
"description": "Votre session a expiré. Veuillez saisir à nouveau vos identifiants.",
"data": {
"email": "Adresse e-mail",
"password": "Mot de passe"
}
}
},
"error": {
"invalid_auth": "Échec de l'authentification : {reason}. Réessayez avec un nouveau jeton.",
"invalid_credentials": "PerfectDraft a rejeté l'adresse e-mail ou le mot de passe : {reason}.",
"token_rejected": "PerfectDraft a rejeté le jeton de vérification : {reason}. Générez un nouveau jeton et collez-le sous 2 minutes.",
"cannot_connect": "Impossible de se connecter au service PerfectDraft.",
"unknown": "Une erreur inattendue s'est produite."
},
"abort": {
"already_configured": "Ce compte PerfectDraft est déjà configuré.",
"reauth_successful": "Réauthentification réussie.",
"reauth_account_mismatch": "Ces identifiants correspondent à un autre compte PerfectDraft. Réauthentifiez-vous avec le compte initial de cette intégration, ou supprimez l'intégration et ajoutez l'autre compte séparément.",
"already_in_progress": "La configuration pour ce compte PerfectDraft est déjà en cours. Terminez ou annulez la configuration en attente dans Paramètres > Appareils et services."
}
},
"entity": {
"sensor": {
"temperature": { "name": "Température" },
"keg_remaining": { "name": "Niveau du fût" },
"keg_product_id": { "name": "ID du fût" },
"keg_name": { "name": "Fût" },
"connection": { "name": "Connexion" },
"door": { "name": "Porte" },
"pours": { "name": "Tirages" },
"last_pour": { "name": "Dernier tirage" },
"firmware": { "name": "Firmware" },
"mode": { "name": "Mode" },
"keg_freshness": { "name": "Fraîcheur du fût" }
},
"button": {
"mark_keg_changed": { "name": "Marquer le fût changé" }
}
},
"options": {
"step": {
"init": {
"title": "Options PerfectDraft",
"data": {
"scan_interval": "Intervalle d'actualisation (secondes)"
}
}
}
}
}
@@ -0,0 +1,35 @@
## Context
PR #14 is one commit, `704f55e` by aurel <aurelien.ruat@hotmail.fr>, whose parent is the current `master` head (`851ec3a`). GitHub reports it mergeable with no conflicts. Checked before this change:
- `fr.json` has exactly the key set of `strings.json` and `en.json`, which also match each other.
- Every `{reason}` placeholder and the README link in the token step are carried over.
- The full suite passes on the PR branch: 77 tests, 587 subtests, including the new `test_translations.py`.
`git fetch github pull/14/head` makes the commit available locally.
## Goals / Non-Goals
**Goals:**
- Ship the contribution byte-for-byte, with aurel as the commit author, and have GitHub show PR #14 as merged.
**Non-Goals:**
- Editing the French wording or the contributed test (style, unittest vs pytest, hardcoded `("en", "fr")`).
## Decisions
**Merge the original commit, not a squash or a re-applied diff.** The worktree branch `agent/add-french-translation` starts at `master` and fast-forwards to `704f55e`; the version bump is a separate maintainer commit on top. When the branch is later merged into `master` and pushed to `github`, `704f55e` is reachable from the PR's base branch, so GitHub marks PR #14 merged and attributes the commit to aurel. Squashing or cherry-picking would change the hash, lose that link, and need a manual PR close.
**Integration-only patch release (0.4.6).** The card has no translation files, so it is unchanged. The versioning rule in `PROJECT_HYGIENE.md` allows a diverging patch.
**Keep the test strict.** Home Assistant falls back to English for missing keys, so partial translations would work at runtime. The maintainer chose exact parity instead, so French never falls silently behind. The cost is one more file to touch per string change, recorded in `PROJECT_HYGIENE.md`.
## Risks / Trade-offs
- [A future agent adds a string to `strings.json` and `en.json` only] → The test fails in that change; the `PROJECT_HYGIENE.md` note tells the agent to write the French entry rather than relax the test.
- [The new strings are shown on a narrow UI and truncate] → Not seen in testing, and the contributor runs it live. Fix in a follow-up only if a user reports it.
- [No on-device check on the dev host] → As with 0.4.4 and 0.4.5, there is no Home Assistant on the dev host. The contributor's own instance is the live check; the static checks above cover the files.
## Migration Plan
None. Updating via HACS and restarting Home Assistant picks up `fr.json`. Rollback is reinstalling 0.4.5.
@@ -0,0 +1,34 @@
## Why
[PR #14](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/14) from @Aurel004 (aurel) adds a complete French translation, so French-language Home Assistant installs show the config flow, errors and entity names in French instead of English. The contributor runs it on his own instance and checked the AI-generated strings by hand; the maintainer had a native French speaker look at it too. It is a first contribution, so it ships exactly as submitted, with his authorship kept.
## What Changes
- Merge the PR's single commit (`704f55e`, authored by aurel) unchanged. It adds:
- `custom_components/perfectdraft/translations/fr.json`, covering every key in `strings.json`.
- `tests/test_translations.py`, which fails when `en.json` or `fr.json` has a different key structure from `strings.json`.
- No wording edits. "Marquer le fût changé" stays as submitted; it is correct, and shorter text suits the button label.
- Bump the integration to 0.4.6. The card has no translations and stays at 0.4.5, which the versioning rule allows (shared major.minor, patch may diverge).
- Record in `PROJECT_HYGIENE.md` that from now on every new or renamed UI string needs an English and a French entry, because the new test enforces exact key parity.
- Release v0.4.6 crediting @Aurel004.
Not in scope:
- Translated entity states or attributes. `strings.json` defines none, so there is nothing to translate.
- Other languages, or loosening the parity test to allow partial translations.
## Capabilities
### New Capabilities
None.
### Modified Capabilities
- `hacs-packaging`: the "Translations" requirement covers English only. It now also requires a French translation and exact key parity between `strings.json` and every shipped translation file.
## Impact
- Users with Home Assistant set to French see French labels after updating. Existing entity IDs are kept in the entity registry and don't change; only display names do. Everyone else is unaffected.
- Contributors and agents: any change to `strings.json` must update `translations/en.json` and `translations/fr.json` in the same commit, or `tests/test_translations.py` fails.
- Files: `custom_components/perfectdraft/translations/fr.json` (new), `tests/test_translations.py` (new), `custom_components/perfectdraft/manifest.json` (version), `PROJECT_HYGIENE.md` (main checkout).
@@ -0,0 +1,19 @@
## MODIFIED Requirements
### Requirement: Translations
The integration SHALL provide English and French UI strings for all config flow steps, errors, abort reasons, options, and entity names. Every shipped translation file SHALL have exactly the same key structure as `strings.json`.
#### Scenario: Translation files
- **WHEN** HA renders the integration UI
- **THEN** `strings.json` and `translations/en.json` SHALL provide labels for all steps, fields, errors, and entity names
- **THEN** descriptions SHALL not contain curly braces (parsed as translation placeholders) or newlines (cause MALFORMED_ARGUMENT)
#### Scenario: French UI
- **WHEN** HA renders the integration UI with its language set to French
- **THEN** `translations/fr.json` SHALL provide French labels for all steps, fields, errors, abort reasons, options, and entity names
- **THEN** each French string SHALL use the same `{placeholder}` names as its English counterpart
#### Scenario: Key parity
- **WHEN** a key is added to, renamed in, or removed from `strings.json`
- **THEN** `translations/en.json` and `translations/fr.json` SHALL be updated to the same key structure in the same change
- **THEN** the test suite SHALL fail if any of the three files has a key the others lack
@@ -0,0 +1,23 @@
## 1. Worktree and contribution
- [x] 1.1 `scripts/agent-worktree.sh create add-french-translation`; verify `.worktree/add-french-translation/.agent-lock` exists and `git worktree list` shows branch `agent/add-french-translation` at `master`
- [x] 1.2 `git fetch github pull/14/head`, then put the worktree branch on `704f55e5958717899fea2265f1a3c627dd4cde9d`; verify `git log -1 --format='%H %an'` shows `704f55e…` by aurel and `git diff 851ec3a --stat` lists only `translations/fr.json` and `tests/test_translations.py`
- `master` had moved on by the proposal commit (`2050051`, `openspec/` only), so `--ff-only` was impossible. The fresh branch had no commits of its own, so it was reset to `704f55e` (parent `851ec3a`) instead; the commit is unchanged. Diff vs `851ec3a`: the two files, 109 insertions
- [x] 1.3 Verify the contribution against the spec: `fr.json` key set equals `strings.json`, and every string uses the same `{placeholder}` names as `strings.json`; then `../../.venv-test/bin/pytest tests/` from the worktree passes, including `test_translations.py`
- 34 keys match, no placeholder mismatches; 77 passed, 587 subtests passed
## 2. Version
- [x] 2.1 Bump `custom_components/perfectdraft/manifest.json` to 0.4.6 and commit as the maintainer; verify `git diff HEAD~1` is the single version line and the full suite still passes. Record the commit hash here
- Commit `9a81654` on `agent/add-french-translation`, on top of `704f55e`; one-line diff; 77 passed, 587 subtests passed
## 3. Project hygiene
- [x] 3.1 Add a line to `PROJECT_HYGIENE.md` section 11 (main checkout): every new, renamed or removed key in `strings.json` must be mirrored in `translations/en.json` and `translations/fr.json` in the same commit, with a French string written rather than an English placeholder or a relaxed test; `tests/test_translations.py` enforces it. Commit in the main checkout; verify with `git log -1 -- PROJECT_HYGIENE.md`
## Workflow follow-up
- Archive per `AGENTS.md`: merge `agent/add-french-translation` into `master` with `--no-ff` (keeps `704f55e` intact), push `master` to `origin` and `github`, sync the `hacs-packaging` delta into `openspec/specs/`, archive, remove the worktree and branch.
- After the push, confirm via the GitHub API that PR #14 reports `merged: true`. If it doesn't, close it with a comment linking the merge commit.
- Tag `v0.4.6` and publish the GitHub release "v0.4.6 — French translation" in the format of v0.4.5: French UI for setup, errors and entity names; thanks to @Aurel004 for [#14](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/14); note that the card stays at 0.4.5, no breaking changes, no re-configuration.
- Comment on PR #14 with a thank-you and the release link.
@@ -1,7 +1,8 @@
## 1. Name and worktrees
- [ ] 1.1 Ask MThomas564 on PR #10 whether the keg or the PerfectDraft app calls 48180 "Camden Stout" or "Camden Nitro Stout"; record the answer (or "no reply by release, shipping Camden Stout") in this file
- Asked 2026-11-07: https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/10#issuecomment-6706008826 — awaiting reply; implementation proceeds with "Camden Stout"
- [x] 1.1 Ask MThomas564 on PR #10 whether the keg or the PerfectDraft app calls 48180 "Camden Stout" or "Camden Nitro Stout"; record the answer (or "no reply by release, shipping Camden Stout") in this file
- Asked 2026-11-07: https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/pull/10#issuecomment-6706008826
- Answer 2026-11-07 11:13 UTC: the PerfectDraft app shows "Camden Stout" (the store lists "Camden Nitro Stout"); the catalog follows the app, so "Camden Stout" stands
- [x] 1.2 `scripts/agent-worktree.sh create add-keg-48180` in the integration repo, and an equivalent `.worktree/add-keg-48180` on branch `agent/add-keg-48180` in `Hassio-PerfectDraftPro-Component`; confirm `.agent-lock` in both
## 2. Integration catalog
@@ -0,0 +1,3 @@
schema: spec-driven
created: 2026-11-07
skip_specs: true
@@ -0,0 +1,42 @@
## Context
See proposal.md for why. The card resolves a fitted keg by product ID through `getBeerByKegId` and keeps its own curated name when the ID matches. So the integration's name for `29745` only reaches the **Keg** sensor state, never the card label. `npm run check:catalog` compares IDs only, not names, but `scripts/keg-catalog.reference.json` is meant to be a faithful snapshot of the integration catalog (`_upstreamCommit` is currently `8b2c4418`).
Existing keg art is WebP, capped at 800 px (`spaten.webp` is 800×800, about 25 KB), as set by the card's `card-layouts-and-imagery` design. The two sources, checked 2026-11-07:
| Beer | Source image | Size |
|---|---|---|
| Löwenbräu Oktoberfestbier | `media/catalog/product/k/e/kegs--lowenbrau--oktoberfest2023.png` | 1200×1200 PNG |
| Spaten Oktoberfestbier | `media/catalog/product/s/p/spaten_oktoberfest_6l_keg_1_1.png` | 700×700 PNG |
Both are under `https://www.perfectdraft.com/`, from the DE product pages linked in issue #8. The page thumbnails carry Magento resize parameters (`?optimize=medium&…&width=265`). Drop those to get the originals above.
## Goals / Non-Goals
**Goals:**
- Both Oktoberfest kegs render their keg photo on the card, sharp in `hero` and `vessel`.
- The integration and the card spell Löwenbräu the same way.
**Non-Goals:**
- Changing any card entry field other than `imagePath`.
- A new image pipeline or script. This is two one-off conversions.
## Decisions
**Slugs as file names.** The files are `lowenbrau-oktoberfest.webp` and `spaten-oktoberfest.webp`, so `kegImage(slug)` resolves them with no special case, as for every other entry.
**Encode to match the existing art: WebP, longest edge at most 800 px, no upscaling.** Löwenbräu goes from 1200 to 800 px. Spaten stays at its native 700 px, because upscaling adds bytes without adding detail, and CSS scales it anyway. The conversion uses Pillow (WebP support confirmed on the dev host); `cwebp` is not installed. Pick a quality setting that keeps each file in the range of the existing art (about 25–40 KB), then check it by eye at hero size. Keep the source PNGs out of the repo.
**Rename to the brand's spelling, "Löwenbräu Oktoberfestbier".** This matches the integration's own `454` entry, the card entry, the storefront page and the issue. The catalog's observation rule applies to which ID maps to which beer, and that is unchanged: the reporter's machine reports `29745` for this keg. The alternative was leaving the name alone, since the card ignores it. It was rejected because the sensor state is user-visible and inconsistent with `454`.
**Order: integration commit first, then card.** The card's reference snapshot records the integration commit (`_upstreamCommit`) and must contain the new name. Because it cites the commit, the integration commit has to exist on `agent/add-oktoberfest-keg-art` first. Re-check the hash after any rebase or merge that rewrites it.
**Versions: both packages go to 0.4.5.** Both change, so this is a joint release under the numbering rule in `PROJECT_HYGIENE.md`. The integration bumps `manifest.json`. The card bumps `package.json`, `CARD_VERSION` and `EDITOR_VERSION`, and regenerates `package-lock.json` with `npm install --package-lock-only`.
## Risks / Trade-offs
- [The Löwenbräu source file is named `oktoberfest2023`, so it may show an older keg design than the one shipping now] → The DE storefront itself shows it, so it is what owners will recognise. Swapping it later is a one-file change.
- [Users with automations matching the string "Lowenbrau Oktoberfestbier"] → Unlikely, since the card matches on ID. Call out the rename in the release notes.
- [HACS users update only one package] → Card only: artwork appears, and the sensor keeps the old spelling. Integration only: the spelling is fixed, and the card still shows the silhouette. Neither breaks anything. The release notes say to update both.
@@ -0,0 +1,39 @@
## Why
[Issue #8](https://github.com/Falkvinge/hassio-integration-perfectdraft-pro/issues/8): reimargithub reports that the card shows no keg picture for Löwenbräu Oktoberfestbier (`29745`), and asks about Spaten Oktoberfestbier, which he has since fitted. He gave its product ID, `33918`, in a follow-up comment.
Both beers are already known to both packages. The integration's `keg_catalog.json` names both IDs, and the card has `lowenbrau-oktoberfest` and `spaten-oktoberfest` entries bound to them by `kegId`. What is missing is the artwork. Neither card entry has an `imagePath`, so the card falls back to the generated silhouette. One small inconsistency comes along with this: the integration names `29745` "Lowenbrau Oktoberfestbier", without the umlauts that its own `454` entry ("Löwenbräu") and the card both use.
## What Changes
- Companion card:
- Add `src/assets/kegs/lowenbrau-oktoberfest.webp` and `src/assets/kegs/spaten-oktoberfest.webp`, sourced once from the PerfectDraft DE storefront pages linked in the issue.
- Set `imagePath: kegImage(...)` on the two existing entries. Name, ABV, style, colours and `kegId` stay unchanged; the storefront ABVs (6.1% and 5.9%) already match.
- Re-sync `scripts/keg-catalog.reference.json` to the integration commit with the rename.
- Bump the card to 0.4.5 and rebuild `dist/`.
- Integration:
- Rename `29745` to "Löwenbräu Oktoberfestbier" in `keg_catalog.json`. The key, its position and the count (117) stay the same.
- Bump to 0.4.5, so the joint release puts both packages on the same version.
- Close issue #8 with a thank-you and the release link.
Not in scope:
- Other card entries without artwork, such as `leffe-winter`.
- Other ASCII-only names in the integration catalog. None are known, and checking every name against the app is a separate job.
## Capabilities
### New Capabilities
None.
### Modified Capabilities
None. The integration's `entities` spec already requires catalog names to be the beer's name, and the floor of 117 IDs is unchanged. The card's own `beer-imagery` spec already requires bundled keg photos for currently-sold beers. This change brings both packages into line with requirements they already have, so it sets `skip_specs: true`.
## Impact
- The **Keg** sensor for `29745` reads "Löwenbräu Oktoberfestbier" instead of "Lowenbrau Oktoberfestbier". The entity ID doesn't change. History shows the new state from the update onwards, and automations comparing against the old string need updating. Such automations are unlikely, since the card matches on product ID.
- On the card, both Oktoberfest kegs show their keg photo in every layout, including the beer picker in the editor.
- Integration: `custom_components/perfectdraft/keg_catalog.json`, `custom_components/perfectdraft/manifest.json`.
- Card repo (`Hassio-PerfectDraftPro-Component`): `src/assets/kegs/` (two new files), `src/beer-catalog.ts`, `scripts/keg-catalog.reference.json`, `package.json`, `package-lock.json`, `CARD_VERSION`, `EDITOR_VERSION`, `dist/`.
@@ -0,0 +1,37 @@
## 1. Worktrees
- [x] 1.1 `scripts/agent-worktree.sh create add-oktoberfest-keg-art` in the integration repo, and an equivalent `.worktree/add-oktoberfest-keg-art` on branch `agent/add-oktoberfest-keg-art` in `Hassio-PerfectDraftPro-Component`; verify `.agent-lock` exists in both and `git worktree list` shows both branches
## 2. Integration rename
- [x] 2.1 Change `"29745"` in `custom_components/perfectdraft/keg_catalog.json` to `"Löwenbräu Oktoberfestbier"`, in place; verify `git diff` is a single-line change and the file is still UTF-8 (written as literal characters, like `454`, not `\u` escapes)
- [x] 2.2 Assert `catalog["29745"] == "Löwenbräu Oktoberfestbier"` in `tests/test_keg_catalog.py`, leaving `MINIMUM_ENTRIES` at 117; verify `python3 -m unittest tests.test_keg_catalog` passes
- [x] 2.3 Bump `manifest.json` to 0.4.5 and commit; record the commit hash here for 3.3
- Commit `1598e7b` on `agent/add-oktoberfest-keg-art`
## 3. Card artwork
Work in `Hassio-PerfectDraftPro-Component`.
- [x] 3.1 Download the two source PNGs listed in design.md (no resize query string) to a scratch directory outside the repo; verify 1200×1200 and 700×700
- Downloaded to `/tmp/oktoberfest-art/`: 1200×1200 and 700×700 RGBA PNGs
- [x] 3.2 Encode them with Pillow to `src/assets/kegs/lowenbrau-oktoberfest.webp` (800 px) and `src/assets/kegs/spaten-oktoberfest.webp` (700 px, not upscaled); verify the dimensions, a file size in the range of the existing art (about 25–40 KB), and a visual check of both files
- Pillow, WebP quality 80, method 6, alpha kept: Löwenbräu 800×800 (32 KB), Spaten 700×700 (25 KB); existing art is 700 or 800 px, 16–46 KB. Checked composited on a dark background: labels sharp, no fringing
- [x] 3.3 Add `imagePath: kegImage("lowenbrau-oktoberfest")` and `imagePath: kegImage("spaten-oktoberfest")` to the two existing entries, changing no other field; re-sync `scripts/keg-catalog.reference.json` from the commit in 2.3 and set `_upstreamCommit` to it; verify the snapshot diff is only the `29745` name and the commit hash
- Snapshot `_upstreamCommit` is `1598e7b0`; diff is that hash and the `29745` name only
- [x] 3.4 Bump `package.json`, `CARD_VERSION` and `EDITOR_VERSION` to 0.4.5; regenerate `package-lock.json` with `npm install --package-lock-only`
- Lockfile diff is the two version fields only
- [x] 3.5 `npm run lint`, `npm run check:catalog` (117/117, snapshot at the 2.3 commit) and `npm run build`; verify both `.webp` files are in `dist/kegs/`, then commit source and `dist/`
- Lint clean; `check:catalog` 117/117 @ `1598e7b0`; build copies both files to `dist/kegs/`; bundle has both `imagePath`s and no `0.4.4`. Card commit `a79173a`
## Deferred: shipping without on-device checks
Maintainer decision, 2026-11-07: ship integration and card 0.4.5 without this check, as with 0.4.4 (no Home Assistant on the dev host). Coverage at release: catalog unit tests (117 keys, the new 29745 name), `npm run lint`, `npm run check:catalog` (117/117), a clean `npm run build` with both images in `dist/kegs/`, and a visual check of both encoded images. The open TODO is in `PROJECT_HYGIENE.md`.
- 4.1 Install integration 0.4.5 and card 0.4.5 on Home Assistant; confirm the card editor's beer picker shows artwork for both Oktoberfest entries and that each renders sharply in the `hero` layout; with a 29745 or 33918 keg unavailable, also confirm `getBeerByKegId("29745")` and `getBeerByKegId("33918")` return entries with an `imagePath` in a browser console on the dashboard
## Workflow follow-up
- Joint release: integration v0.4.5 and card v0.4.5, published together. The release notes thank reimargithub, mention the 29745 rename for anyone matching the old string, and tell users to update both.
- After the release, close issue #8 with a thank-you and the release links.
- Archive per `AGENTS.md` in both repos (merge, push, archive, remove worktrees and branches). The change has no spec deltas to sync.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-07
+34 -4
View File
@@ -8,16 +8,46 @@ The integration SHALL provide an async API client class (`PerfectDraftApiClient`
- **THEN** it SHALL store the session and set the base URL to `https://api.perfectdraft.com`
### Requirement: Sign-in with reCAPTCHA token
The client SHALL authenticate by POSTing to `/authentication/sign-in` with email, password, recaptchaToken, and recaptchaAction fields. The `x-api-key` SHALL be sent as a header. The `recaptchaAction` SHALL be `Magento/login`.
The client SHALL authenticate by calling AWS Cognito `InitiateAuth` at `https://cognito-idp.eu-west-1.amazonaws.com/` with `AuthFlow: USER_PASSWORD_AUTH`, the Cognito client ID, and the email and password as `USERNAME` and `PASSWORD`. `ClientMetadata` SHALL carry `recaptchaToken`, `recaptchaAction: Magento/login`, and `domain: https://www.perfectdraft.com`, all three of which PerfectDraft's PreAuthentication check requires. The client SHALL NOT sign in through `api.perfectdraft.com/authentication/sign-in`, which does not forward `domain`.
#### Scenario: Successful sign-in
- **WHEN** the client calls `authenticate(email, password, recaptcha_token)`
- **THEN** it SHALL POST to `/authentication/sign-in` with the correct payload and `x-api-key` header
- **THEN** it SHALL store the returned `AccessToken`, `IdToken`, and `RefreshToken`
- **THEN** it SHALL POST an `InitiateAuth` request to Cognito with `Content-Type: application/x-amz-json-1.1` and `X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth`
- **THEN** the request SHALL carry the `ClientMetadata` fields listed above
- **THEN** it SHALL parse the response with `content_type=None` to accept `application/x-amz-json-1.1`
- **THEN** it SHALL store the `AccessToken`, `IdToken`, and `RefreshToken` from `AuthenticationResult`
#### Scenario: Challenge instead of tokens
- **WHEN** Cognito answers 200 without a complete `AuthenticationResult`, for example with a `ChallengeName`
- **THEN** the client SHALL raise `AuthenticationError`, carrying the challenge name as its error type when present
- **THEN** no stored token SHALL change
#### Scenario: Sign-in failure
- **WHEN** the API returns 400, 401, or 403
- **WHEN** Cognito returns 400, 401, or 403
- **THEN** the client SHALL raise `AuthenticationError` with the status and response body
- **THEN** the error SHALL expose the Cognito error type (`__type`, without any namespace prefix) and the human-readable message, when the body supplies them
#### Scenario: Rejection is classified
- **WHEN** a sign-in is rejected with error type `NotAuthorizedException` or `UserNotFoundException`
- **THEN** the error SHALL classify as a credentials failure
- **WHEN** a sign-in is rejected with error type `UserLambdaValidationException`
- **THEN** the error SHALL classify as a verification token failure
- **WHEN** a sign-in is rejected with any other error type, or none
- **THEN** the error SHALL classify as an other failure
#### Scenario: Unreadable rejection body
- **WHEN** a rejection body is not JSON, such as an HTML error page
- **THEN** the client SHALL still raise `AuthenticationError`, with no error type and a reason truncated to at most 200 characters
#### Scenario: Other sign-in failures
- **WHEN** Cognito returns any other non-200 status
- **THEN** the client SHALL raise `PerfectDraftApiError`
- **WHEN** the request fails due to `aiohttp.ClientError`
- **THEN** the client SHALL raise `PerfectDraftConnectionError`
#### Scenario: Secrets are not logged
- **WHEN** sign-in succeeds or fails
- **THEN** the password, the verification token, and the issued tokens SHALL NOT be logged
### Requirement: Token refresh via Cognito
The client SHALL refresh expired access tokens by calling AWS Cognito directly at `https://cognito-idp.eu-west-1.amazonaws.com/`, bypassing the API gateway and reCAPTCHA. The Cognito client ID is `57ddq2ppqg2jcpup06r2g1deur`.
+21 -5
View File
@@ -9,7 +9,7 @@ The config flow SHALL present a form requesting the user's PerfectDraft account
- **THEN** submitting SHALL advance to the token step
### Requirement: Token step collects verification token
The config flow SHALL present a form requesting a reCAPTCHA verification token as the second step, with instructions linking to the README.
The config flow SHALL present a form requesting a reCAPTCHA verification token as the second step, with instructions linking to the README. When authentication fails, the flow SHALL tell the user which input was rejected and show the server's reason.
#### Scenario: Token step display
- **WHEN** the user reaches the token step
@@ -24,8 +24,24 @@ The config flow SHALL present a form requesting a reCAPTCHA verification token a
- **THEN** it SHALL create a config entry storing email, access token, ID token, refresh token, and machine ID
#### Scenario: Invalid or expired token
- **WHEN** authentication fails
- **THEN** the flow SHALL show an error and allow the user to retry with a fresh token
- **WHEN** authentication fails as a verification token failure
- **THEN** the flow SHALL show the token form again with the `token_rejected` error, including the server's reason
- **THEN** the user SHALL be able to retry with a fresh token
#### Scenario: Wrong email or password
- **WHEN** authentication fails as a credentials failure
- **THEN** the flow SHALL show the credentials form again with the `invalid_credentials` error, including the server's reason
- **THEN** that form SHALL be the email and password form during setup, and the `reauth_confirm` form during reauth
- **THEN** after the user resubmits credentials, the flow SHALL ask for a fresh token
#### Scenario: Other authentication failure
- **WHEN** authentication fails for any other reason
- **THEN** the flow SHALL show the token form again with the `invalid_auth` error, including the server's reason
- **THEN** the user SHALL be able to retry with a fresh token
#### Scenario: Failure without a server reason
- **WHEN** authentication fails and the server supplied no reason
- **THEN** the error message SHALL still render, with a fixed fallback in place of the reason and no unfilled placeholder
#### Scenario: API unreachable
- **WHEN** the API is unreachable
@@ -78,8 +94,8 @@ The integration SHALL support Home Assistant's reauth mechanism when the refresh
- **THEN** the flow SHALL treat it as the same account and complete successfully
#### Scenario: Reauth authentication fails
- **WHEN** the verification token is expired or the credentials are wrong during reauth
- **THEN** the flow SHALL show the `invalid_auth` error on the token form and allow retry with a fresh token
- **WHEN** the verification token or the credentials are rejected during reauth
- **THEN** the flow SHALL show the same error, on the same form, as the matching failure during setup (`token_rejected`, `invalid_credentials` on the `reauth_confirm` form, or `invalid_auth`)
- **THEN** the existing config entry's tokens SHALL be left unchanged
#### Scenario: Machine ID lookup is skipped when already known
+1 -1
View File
@@ -59,7 +59,7 @@ The integration SHALL expose the numeric product ID of the keg currently fitted
- **THEN** the sensor SHALL report no value and SHALL NOT raise
### Requirement: Keg name sensor
The integration SHALL expose the name of the tapped beer, resolved from the keg product ID through a catalog bundled with the integration at `keg_catalog.json`. The catalog SHALL cover every keg the PerfectDraft app can select, including discontinued kegs that may still be fitted in a machine, and SHALL contain at least 115 product IDs.
The integration SHALL expose the name of the tapped beer, resolved from the keg product ID through a catalog bundled with the integration at `keg_catalog.json`. The catalog SHALL cover every keg the PerfectDraft app can select, including discontinued kegs that may still be fitted in a machine, and SHALL contain at least 117 product IDs.
Catalog entries SHALL be observed directly from a machine reporting that product ID rather than inferred from shop listings, because the product IDs cannot be queried in bulk from the API. Entry names SHALL be the beer's name only, excluding shop-listing artefacts such as pack size, "Short Date" prefixes, or best-before dates.
+1
View File
@@ -107,6 +107,7 @@ class TestKegCatalogContent(unittest.TestCase):
self.assertEqual(catalog["48050"], "Anheuser-Busch Bud")
self.assertEqual(catalog["47792"], "Camden Eazy")
self.assertEqual(catalog["48180"], "Camden Stout")
self.assertEqual(catalog["29745"], "Löwenbräu Oktoberfestbier")
if __name__ == "__main__":
+39
View File
@@ -0,0 +1,39 @@
"""Verify that translation files match strings.json key structure."""
import json
from pathlib import Path
import unittest
COMPONENT_DIR = Path(__file__).parent.parent / "custom_components" / "perfectdraft"
def _key_paths(obj, prefix=""):
paths = set()
if isinstance(obj, dict):
for k, v in obj.items():
full = f"{prefix}.{k}" if prefix else k
if isinstance(v, dict):
paths |= _key_paths(v, full)
else:
paths.add(full)
return paths
class TestTranslations(unittest.TestCase):
def test_en_and_fr_match_strings_json_keys(self):
strings = json.loads(
(COMPONENT_DIR / "strings.json").read_text(encoding="utf-8")
)
expected = _key_paths(strings)
for lang in ("en", "fr"):
with self.subTest(lang=lang):
data = json.loads(
(COMPONENT_DIR / "translations" / f"{lang}.json").read_text(
encoding="utf-8"
)
)
self.assertEqual(_key_paths(data), expected)
if __name__ == "__main__":
unittest.main()