flan
22e6499a8e
Move the authenticated drift check into the repository as tools/compat_auth.py, run daily by .github/workflows/compat-auth.yml on the maintainer's forge only. Credentials come from FH_EMAIL and FH_PASSWORD, the output is pass/fail labels only because the run log is public, and a failed run pushes the report to ntfy. Exit 5 means all hold, 10 drift, anything else that it could not run. Point compat.yml, tools/compat.py and the docs at it, add a README section, and cut 0.5.1.
169 lines
6.5 KiB
Markdown
169 lines
6.5 KiB
Markdown
<p align="center">
|
|
<img src="docs/logo.svg" alt="Fresh Harvest" width="480">
|
|
</p>
|
|
|
|
# ha-freshharvest
|
|
|
|
[](https://git.arch.fyi/flan/ha-freshharvest/actions)
|
|
|
|
Unofficial Home Assistant integration for [Fresh Harvest](https://freshharvest.com/),
|
|
the Georgia local-produce delivery subscription.
|
|
|
|
Reports what is arriving, what is in the box, what it costs — broken down per
|
|
line so you can automate on any single part — and how long you have left to
|
|
change the next order.
|
|
|
|
## Installation
|
|
|
|
### HACS (custom repository)
|
|
|
|
This is not in the HACS default list. Add it yourself:
|
|
|
|
1. HACS → ⋮ → **Custom repositories**
|
|
2. Repository `https://github.com/sudolulo/ha-freshharvest`, category **Integration**
|
|
3. Install **Fresh Harvest**, then restart Home Assistant
|
|
4. **Settings → Devices & Services → Add Integration → Fresh Harvest**
|
|
|
|
### Manual
|
|
|
|
Copy `custom_components/freshharvest/` into your Home Assistant
|
|
`config/custom_components/` directory and restart, then add the integration as
|
|
above.
|
|
|
|
Credentials are your normal freshharvest.com email and password.
|
|
|
|
## Entities
|
|
|
|
The next delivery and the *open* order are usually two different deliveries.
|
|
Once an order passes its cutoff it locks for packing, and the cart you can still
|
|
edit is the following week's — so both are exposed separately.
|
|
|
|
Three things arrive in a delivery and only one is a list you edit:
|
|
|
|
| | What it is | Entity |
|
|
| --- | --- | --- |
|
|
| **Produce box** | Chosen, not assembled. Ten options. | `select.fresh_harvest_produce_box` |
|
|
| **Box contents** | Fresh Harvest fills it; read-only. | `produce` attr of `..._next_delivery_items` |
|
|
| **Add-ons** | Yours to add and remove. | `todo.fresh_harvest_add_ons` |
|
|
|
|
### Controls
|
|
|
|
| Entity | Notes |
|
|
| --- | --- |
|
|
| `select.fresh_harvest_produce_box` | Switches the **next delivery only**, not the standing order |
|
|
| `switch.fresh_harvest_skip_next_order` | Skip, and turn back off to restore |
|
|
| `button.fresh_harvest_donate_next_order` | Donates the box. **Not reversible** |
|
|
| `todo.fresh_harvest_add_ons` | Add/remove items; names resolve via the site's search index |
|
|
|
|
Home Assistant's built-in conversation agent can drive the to-do list through
|
|
`HassListAddItem`, so no bespoke voice work is needed.
|
|
|
|
### The order arriving next
|
|
|
|
| Entity | Example |
|
|
| --- | --- |
|
|
| `sensor.fresh_harvest_next_delivery` | `2026-08-04` |
|
|
| `sensor.fresh_harvest_next_delivery_total` | `66.16` |
|
|
| `sensor.fresh_harvest_next_delivery_subtotal` | `58.42` |
|
|
| `sensor.fresh_harvest_next_delivery_box_price` | `33.00` |
|
|
| `sensor.fresh_harvest_next_delivery_add_ons` | `25.42` |
|
|
| `sensor.fresh_harvest_next_delivery_tax` | `1.75` |
|
|
| `sensor.fresh_harvest_next_delivery_fee` | `5.99` |
|
|
| `sensor.fresh_harvest_next_delivery_items` | `11` |
|
|
|
|
### The order you can still change
|
|
|
|
| Entity | Example |
|
|
| --- | --- |
|
|
| `binary_sensor.fresh_harvest_order_open` | `on` |
|
|
| `sensor.fresh_harvest_open_order_delivery` | `2026-08-11` |
|
|
| `sensor.fresh_harvest_open_order_total` | `38.99` |
|
|
| `sensor.fresh_harvest_open_order_free_delivery_remaining` | `11.58` |
|
|
| `sensor.fresh_harvest_shopping_window` | `Shop tomorrow` |
|
|
|
|
`binary_sensor.fresh_harvest_order_open` is the one to automate on: it turns off
|
|
when the cutoff passes, the last moment to change the box.
|
|
|
|
### The account
|
|
|
|
| Entity | Example |
|
|
| --- | --- |
|
|
| `sensor.fresh_harvest_delivery_day` | `Tuesdays` |
|
|
| `sensor.fresh_harvest_subscriptions` | `1`, with each standing order in attributes |
|
|
| `sensor.fresh_harvest_vacation_holds` | `0`, with ranges in attributes |
|
|
|
|
## Events
|
|
|
|
Every write action fires `freshharvest_action` with `action`, `success`,
|
|
`target` and `detail`, so an automation can notify on an add succeeding or a
|
|
skip failing.
|
|
|
|
## Dashboard
|
|
|
|
[examples/dashboard-view.yaml](examples/dashboard-view.yaml) is a ready-made tab
|
|
— a countdown heading ("Arriving tomorrow"), tiles for the cost breakdown, the
|
|
full box contents rendered from the attributes, and the still-changeable order.
|
|
Paste it under `views:` in the raw configuration editor.
|
|
|
|
## Requirements
|
|
|
|
Home Assistant 2025.2 or newer. Developed and running against 2026.7. The
|
|
bundled brand images (the logo in Settings → Devices & Services) need 2026.3
|
|
or newer; older versions simply keep the generic placeholder.
|
|
|
|
## Troubleshooting
|
|
|
|
**Everything shows `unavailable`.** The session expired and could not be
|
|
renewed — usually a changed password. Reload the integration, or remove and
|
|
re-add it.
|
|
|
|
**A count reads `0` when you know it should not.** Fresh Harvest changed their
|
|
site. That is drift, not your configuration; please open an issue.
|
|
|
|
**Adding an item fails.** The item is not orderable for the open delivery. The
|
|
site only offers an add control for things it can actually deliver, so this is
|
|
the same answer you would get on the website.
|
|
|
|
**The box shows the wrong contents.** Contents are assigned a few days before
|
|
delivery; an order that has not been filled yet legitimately has none.
|
|
|
|
## Contributing
|
|
|
|
Implementation notes, the endpoints this uses, and the markup traps worth
|
|
knowing are in [docs/internals.md](docs/internals.md).
|
|
|
|
```
|
|
pip install beautifulsoup4 pytest yarl
|
|
pytest tests/
|
|
```
|
|
|
|
## Scheduled sign-in check
|
|
|
|
Every break so far has been behind the login, and every one was silent: a
|
|
sensor reading a plausible `0` rather than going unavailable. So once a day
|
|
[tools/compat_auth.py](tools/compat_auth.py) signs in to a real account,
|
|
read-only, and checks the markup the sensors and controls are parsed from:
|
|
the dashboard, subscriptions, vacation holds, and the popups behind skip,
|
|
donate and add. When something has moved, the run fails and the maintainer
|
|
gets a push naming the broken assumption and what it would break.
|
|
|
|
It runs only on the maintainer's own forge, where the account credentials
|
|
are, and is skipped on the GitHub mirror and on forks. Its log is public, so
|
|
it prints a pass or fail per assumption and nothing about the account. To run
|
|
it yourself, set the four secrets listed at the top of
|
|
[.github/workflows/compat-auth.yml](.github/workflows/compat-auth.yml) and
|
|
change the job's `if:`.
|
|
|
|
## Disclaimer
|
|
|
|
Unofficial and unaffiliated — not endorsed by or supported by Fresh Harvest.
|
|
The Fresh Harvest name and logo belong to Fresh Harvest and are used here only
|
|
to identify the service this integrates with.
|
|
Please do not lower the six-hour poll interval: this is a small business's
|
|
website, not an API.
|
|
|
|
## Support
|
|
|
|
If ha-freshharvest is useful to you, consider supporting development via
|
|
[GitHub Sponsors](https://github.com/sponsors/sudolulo) or [Ko-fi](https://ko-fi.com/sudolulo).
|