feat(blueprints): add fountain drink counter, anomaly alerts, and stats package

[fredrik-lindseth]

Part of an ongoing effort to make the PetKit app and cloud optional for daily fountain monitoring. This PR covers drink tracking and anomaly alerts. It pairs with #203 (local BLE reads) and #202 (BLE writes for mode/LED/DND).

📝 Proposed Change / Description

Adds four importable HA blueprints and a package YAML for tracking fountain drinks locally and alerting on anomalies.

Blueprints

Blueprint	What it does
fountain_drink_counter	Increments a counter on each off/on transition of the Pet drinking binary sensor, with an optional daily reset.
fountain_no_drinks_alert	Fires when the sensor has stayed off for X hours (default 12).
fountain_low_drinks_alert	Fires once a day at 20:00 if today's count is below 30% of the 7-day median.
fountain_high_drinks_alert	Fires once a day at 20:00 if today's count is above 200% of the 7-day median.

Package

docs/examples/petkit_fountain_stats.yaml wires up the supporting infrastructure: a non-resetting lifetime counter, daily/weekly/monthly utility_meter cycles, two history_stats sensors for drink time, a trigger-template snapshot sensor that captures today's count at 23:55, and a statistics sensor that takes the 7-day median over those snapshots. The alert blueprints default to reading from this package's entities.

docs/automations.md covers a quick-start (counter only), full setup (counter + meters + alerts), troubleshooting, the calibration period for statistical alerts, and multi-fountain notes.

No Python changes.

Fixes: n/a

---

🔖 Type of change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 🔧 Refactor / code cleanup (no functional change)
• 📚 Documentation update
• 🔒 Security fix
• ⬆️ Dependency update

---

🐾 Affected devices

The blueprints target the Pet drinking binary sensor (occupancy device class) registered for the Fountain platform. Works regardless of whether detect_status comes from cloud-relay or local BLE.

• 🌐 All devices

Specific type:

• Litter boxes :
• Feeders :
• Fountains : CTW3 / Eversweet Max 2 verified. Structurally applies to any fountain that exposes the Pet drinking sensor.
• Purifiers :

---

🧪 How has this been tested?

• Tested locally with a real PetKit device
• Tested with Home Assistant version: 2026.4.4

Device(s) tested on:

PetKit Eversweet Max 2 Cordless (CTW3UV).

Other devices you own when the test was done:

None.

Test procedure:

1. Imported all four blueprints into HA.
2. Dropped petkit_fountain_stats.yaml into <config>/packages/, replaced the binary_sensor placeholder.
3. Restarted HA. Verified all entities appeared (counter, daily/weekly/monthly meters, drink-time, daily snapshot, 7-day median).
4. Created automations from each blueprint. All loaded with state: on.
5. Counter test: triggered drink events (off/on/off transitions). Counter incremented, utility meters baselined and tracked, history_stats reflected uptime. Values survived a Home Assistant restart.
6. Alert test: manually triggered automation.fountain_no_drinks_alert via automation.trigger. Action ran without errors. Statistical alerts can't be end-to-end tested without 7 days of history; their structure (templates, conditions, blueprint inputs) is validated via blueprint loading and pre-commit run -a.

---

✅ Checklist

• Code follows project style : pre-commit run -a hooks and all checks pass
• No new linting/type errors introduced
• Documentation updated (if needed)
• Branch is up-to-date with main

---

📸 Screenshots / Logs (optional)

Entity snapshot after restart with all blueprints loaded:

counter.petkit_fountain_drinks_total            = 2
sensor.petkit_fountain_drinks_today             = 1
sensor.petkit_fountain_drinks_this_week         = 1
sensor.petkit_fountain_drinks_this_month        = 1
sensor.petkit_fountain_drink_time_today         = 0.0
sensor.petkit_fountain_drink_time_this_week    = 12.41
sensor.petkit_fountain_drinks_final_today       = unknown   (fires at 23:55)
sensor.petkit_fountain_drinks_median            = unknown   (needs at least one snapshot)
automation.fountain_drink_counter               = on
automation.fountain_no_drinks_alert             = on
automation.fountain_low_drinks_alert            = on
automation.fountain_high_drinks_alert           = on

---

ℹ️ Additional context

• Independent of feat: native local BLE support for water fountains (issue #31) #203 (local BLE reads) and feat: add water fountain controls - working mode, LED brightness, DND (closes #94) #202 (BLE writes). Only needs binary_sensor.X_pet_drinking, which already exists on main.
• Default thresholds (12h, <30%, >200% of median) are guesses tuned for a single-cat household. All exposed as blueprint inputs.
• Low/high alerts have a 7-day calibration period. "No drinks" alert works from day one.
• .pre-commit-config.yaml excludes ^blueprints/ from check-yaml (HA's !input tag isn't a standard YAML constructor).
• Could later move to a HACS-installable companion repo (category: blueprint) for auto-updates.

---

⚠️ Breaking Changes

• No breaking changes.
• Warning: This PR introduces breaking changes.

---

Thanks for the helping paw! 🐾

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Jezza34000]

Hi @fredrik-lindseth
Thanks for the PR and adding the blueprints.
Just one question regarding the counter for when the animal drinks.
Currently, this information is retrieved from the API and is available on HA?
Don't you have that sensor?

[fredrik-lindseth]

Hi @Jezza34000, thanks for checking. Yes, sensor.drink_times exists and exposes len(device_records). The blueprint solves a different problem:

1. drink_times is cumulative (lifetime, no daily/weekly cycle).
2. It depends on cloud device_records, which isn't available for users running local BLE only.
3. It's a diagnostic sensor (hidden by default), and TOTAL state class doesn't pair with utility_meter for daily reset.

The blueprint counts off->on transitions on binary_sensor.pet_drinking (works for both cloud and local BLE) and pairs it with utility_meter cycles plus a 7-day median statistics sensor for the anomaly alerts.

If you'd prefer, I can update the docs to point cloud-only users at sensor.drink_times as a simpler alternative when they only want a cumulative number, and reserve the blueprint for users who need daily/weekly cycles or anomaly detection.

[Jezza34000]

Yes you're right !
I hadn't actually thought of those points.
That's all good for me, I approve.