117 Commits
Author SHA1 Message Date
rick b4f0b23c4a Add conclusion to DISCOVERY.md: why this succeeded where others failed
Made-with: Cursor
2026-04-13 11:14:13 +02:00
rick 869058e8eb Fix MALFORMED_ARGUMENT: curly braces in description parsed as translation placeholders
Made-with: Cursor
2026-04-12 17:52:26 +02:00
rick 3d8f4b93e6 Add entity name translations so sensors show individual names
Made-with: Cursor
2026-04-12 17:39:34 +02:00
rick b3fdf2fc97 Fix translation error: remove newlines from description strings
Made-with: Cursor
2026-04-12 17:36:49 +02:00
rick 56ea7711f0 Simplify config flow: paste-token instead of external step
The reCAPTCHA external step has domain validation issues (HA's
hostname isn't in the allowed list for any reCAPTCHA key). Instead,
the config flow now asks the user to:

1. Open perfectdraft.com/en-gb/customer/account/login
2. Run one console command to generate a token
3. Paste the token into the HA config flow

Clear instructions are shown in the flow description. The token
expires in 2 minutes, and the error message tells the user to
try again with a fresh token if it fails.

Removed the external step, HTML page, and HTTP views entirely.
Much simpler code, no moving parts.

Made-with: Cursor
2026-04-12 17:27:29 +02:00
rick 846604838d Add DISCOVERY.md documenting the full reverse-engineering journey
Chronological account of every approach tried, what failed, why,
and how the working solution was eventually found. Includes the
exec summary of what actually works at the top.

Made-with: Cursor
2026-04-12 17:20:45 +02:00
rick 34a23a2814 Working integration with real API data
Breakthrough: discovered the web reCAPTCHA Enterprise key
(6LcZQiUo...) from perfectdraft.com with action "Magento/login"
is accepted by the /authentication/sign-in API endpoint when
generated from a real browser. Token refresh works via direct
AWS Cognito InitiateAuth (bypasses API gateway, no reCAPTCHA).

Cognito details extracted from JWT:
  Pool: eu-west-1_UXWVyvlHR
  Client: 57ddq2ppqg2jcpup06r2g1deur

Real API response fields mapped:
  /api/me → perfectdraftMachines[].id
  /api/perfectdraft_machines/{id} → details.temperature,
    details.kegVolume, details.connectedState, details.doorClosed,
    details.numberOfPoursSinceStartup, details.volumeOfLastPour,
    details.firmwareVersion, details.serialNumber, setting.mode

Changes:
- api.py: Cognito direct refresh, correct sign-in endpoint
- config_flow.py: external step with web reCAPTCHA on HA page
- const.py: Cognito config, web reCAPTCHA key
- coordinator.py: real field name extraction
- sensor.py: 8 sensors with real field mappings (temperature,
  keg remaining %, connection, door, pours, last pour, firmware, mode)
- Removed image.py (API doesn't expose keg images)
- Restored static/recaptcha.html with Enterprise JS

Made-with: Cursor
2026-04-12 17:18:03 +02:00
rick 3ec4b68824 Add apk_decompiled/ to gitignore
Decompiled PerfectDraft APK kept locally for reference.
Emulator approach failed: ARM64 native libs can't run on x86_64
emulator, and ARM64 emulation isn't supported by Android emulator
on x86_64 hosts.

Made-with: Cursor
2026-04-12 13:46:46 +02:00
rick fcba32fecd Replace reCAPTCHA auth with token-bootstrap flow
The Android reCAPTCHA Enterprise key cannot be used from any
non-Android context (browser, server, headless). Certificate
pinning prevents MITM token capture. Every approach to bypass
reCAPTCHA has been exhausted.

New approach: user provides UserId + RefreshToken (one-time
extraction from the PerfectDraft app via HTTP Toolkit or similar).
The integration validates by calling /auth/renewaccesstokens,
which does NOT require reCAPTCHA, then refreshes forever.

Changes:
- config_flow.py: two-step flow (email, then tokens), validates
  via refresh endpoint, reauth asks for fresh tokens
- api.py: refresh_access_token() calls /auth/renewaccesstokens
  with {UserId, RefreshToken}, removed authenticate() method,
  added x-api-key header to all authenticated requests
- const.py: added CONF_USER_ID, removed reCAPTCHA constants
- __init__.py: passes user_id to client.set_tokens()
- strings.json + translations: updated for new flow steps
- Deleted recaptcha.py and static/recaptcha.html
- test_harness.py: updated for refresh-based flow

Made-with: Cursor
2026-04-12 12:26:12 +02:00
rick b383fdc20a gitignore: add swap files and zip artifacts
Made-with: Cursor
2026-04-12 05:14:35 +02:00
rick e6f5af9771 APK analysis: map full API surface and discover refresh endpoint
Decompiled PerfectDraft APK (Expo/React Native + Hermes bytecode).
Key discoveries:

API has TWO auth systems:
- /authentication/sign-in (Cognito + Lambda trigger) — old
- /auth/signin (.NET backend) — new, same reCAPTCHA gate

Critical find: /auth/renewaccesstokens accepts POST with
{UserId, RefreshToken} and does NOT require reCAPTCHA.

Full API surface discovered:
- /auth/signin, /auth/renewaccesstokens, /auth/signout
- /auth/changepassword, /auth/confirmsignup
- /api/perfectdraft_machines/, /api/perfectdraft_machines/{id}
- /api/perfectdraft_machine_kegs
- /api/pda_machines/add
- /api/countries, /api/customer_product_ratings

reCAPTCHA is Android Enterprise key — cannot generate valid
high-score tokens from any non-Android context. Both /auth/signin
and /authentication/sign-in require it. But refresh does not.

Strategy: one-time token capture, then refresh forever.
Made-with: Cursor
2026-04-12 05:14:26 +02:00
rick 17c0551711 Switch to PerfectDraft web reCAPTCHA key
The Android key (6LdrqmAp...) only works with the Android SDK —
it rejects all web-based token generation with "Invalid domain."

Discovered that perfectdraft.com's web login uses a separate
Enterprise web key (6LcZQiUo...) with action "Magento/login".
Testing confirmed the API at api.perfectdraft.com accepts tokens
from this web key. The only remaining requirement is a high
reCAPTCHA score, which a real user's browser will provide.

The external step flow now uses:
- Enterprise JS (recaptcha/enterprise.js)
- Web site key: 6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV
- Action: Magento/login

Removed server-side token generation attempt from config flow
since it cannot produce high-score tokens.

Made-with: Cursor
2026-04-11 21:04:56 +02:00
rick 43d6dc5bff Add local test harness and findings from API probing
test_harness.py exercises the full API flow without HA.
Credentials go in .credentials.json (gitignored).

Key findings from testing:
- reCAPTCHA is Enterprise, not standard v3
- Server-side anchor/reload tokens work but carry wrong action
- Playwright tokens carry correct action but get low trust score
- API validates both action string AND score threshold
- The exact action string is "Android_recaptchaThatWorks/login"
- Auth endpoint: POST /authentication/sign-in returns
  AccessToken, IdToken, RefreshToken on success

Made-with: Cursor
2026-04-11 20:58:27 +02:00
rick 74163b1ff1 Add server-side reCAPTCHA token generation
The browser-based reCAPTCHA approach fails with "Invalid domain"
because PerfectDraft's site key is registered for their domains,
not for the HA instance hostname.

New approach: generate the token server-side via the reCAPTCHA
anchor/reload HTTP endpoints, bypassing domain validation entirely.
Falls back to browser-based external step if server-side fails.

Also adds better error logging in the auth step.

Made-with: Cursor
2026-04-11 20:47:29 +02:00
rick 1706a10ccb Fix config flow external step for reCAPTCHA
The external step mechanism requires a specific flow:
1. async_external_step() pauses the flow
2. Callback stashes token in hass.data and calls async_configure()
   with no user_input to signal completion
3. HA calls async_step_recaptcha_done() which picks up the token
4. async_external_step_done() transitions to async_step_finish()
5. async_step_finish() does the actual API authentication

Previously tried to resume the flow by passing user_input directly
to async_configure(), which doesn't work with external steps.

Made-with: Cursor
2026-04-11 20:32:46 +02:00
rick c24e3678a7 Implement PerfectDraft Pro HA integration (tasks 1–7)
Complete custom_components/perfectdraft/ with:
- Async API client (auth, refresh, machine polling)
- Config flow with reCAPTCHA v3 external step
- DataUpdateCoordinator for shared polling
- Sensor entities (temperature, % remaining, days to expiry, keg name)
- Image entity for keg artwork
- HACS-compliant packaging (manifest.json, hacs.json, translations)
- Configurable polling interval via OptionsFlow
- Reauth flow for expired refresh tokens

Group 8 (manual testing) deferred — requires live HA instance.

Made-with: Cursor
2026-04-11 19:09:44 +02:00
rick 0bddd99241 Initial project setup with openspec change artifacts
Scaffolds the repo with agent workflow config (AGENTS.md, .gitignore),
openspec tooling, and the perfectdraft-integration change proposal
with design, specs (api-client, config-flow, entities, hacs-packaging),
and implementation tasks — ready for apply phase.

Made-with: Cursor
2026-04-11 19:02:16 +02:00