# Home Assistant Integration

EverShelf integrates natively with [Home Assistant](https://www.home-assistant.io/) to bring your pantry data into your smart-home automations.

**Capabilities:**
- 📡 **REST sensors** — expose pantry counts as HA sensor entities (expiring, expired, shopping list, total items)
- 🔔 **Webhooks** — trigger HA automations on pantry events (expiry alerts, shopping additions, stock updates)
- 📣 **Push notifications** — send alerts to your phone via any HA `notify.*` service
- 🔊 **TTS on smart speakers** — read recipe steps aloud on any HA `media_player` entity
- ⚙️ **In-app config panel** — configure everything from Settings → 🏠 tab (no need to edit `.env` manually)

---

## Quick Setup

1. **Generate a Long-Lived Access Token** in Home Assistant:
   - Open HA → your **Profile** (bottom-left avatar) → **Security** → **Long-Lived Access Tokens** → **Create Token**
   - Copy the generated token — you won't see it again.

2. **Open EverShelf Settings** → tab **🏠 Home Assistant**.

3. Fill in **Home Assistant URL** (e.g. `http://homeassistant.local:8123`) and paste the token.

4. Click **Test connection** — you should see ✅.

5. Enable the features you want (TTS, Webhooks, REST Sensors) and click **Save HA settings**.

---

## REST Sensors

Add EverShelf pantry data as native HA sensor entities that update automatically.

### Endpoints

| URL | Returns | Sensor |
|-----|---------|--------|
| `/api/?action=ha_sensor` | Items expiring soon (≤3 days) | `sensor.evershelf_overview` |
| `/api/?action=ha_sensor&sensor=expired` | Expired items count | `sensor.evershelf_expired` |
| `/api/?action=ha_sensor&sensor=shopping` | Shopping list item count | `sensor.evershelf_shopping` |
| `/api/?action=ha_sensor&sensor=total` | Total pantry items | `sensor.evershelf_total` |

### Generate & Copy YAML

In Settings → 🏠 Home Assistant → **REST Sensors** card, click **Copy YAML** to get a ready-to-paste `configuration.yaml` block that already contains your EverShelf URL.

### Manual YAML example

```yaml
# configuration.yaml
sensor:
  - platform: rest
    name: "EverShelf Overview"
    unique_id: evershelf_overview
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor"
    scan_interval: 300        # seconds
    value_template: "{{ value_json.state }}"
    json_attributes:
      - expiring_soon
      - expiring_3d
      - expired_items
      - total_items
      - shopping_items
      - expiring_list
      - last_updated
    unit_of_measurement: "items"

  - platform: rest
    name: "EverShelf Shopping Count"
    unique_id: evershelf_shopping
    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=shopping"
    scan_interval: 180
    value_template: "{{ value_json.state }}"
    unit_of_measurement: "items"
```

Restart Home Assistant after editing `configuration.yaml`.

---

## Webhook Automations

EverShelf fires an HTTP POST to your HA webhook URL when pantry events occur.

### Create the HA Webhook Automation

1. HA → **Settings** → **Automations & Scenes** → **Create Automation**
2. Click **Add Trigger** → choose **Webhook**
3. HA generates a **Webhook ID** — copy it
4. Paste the ID into **Settings → 🏠 Home Assistant → Webhook ID**
5. Select which events should trigger the webhook

### Supported Events

| Event key | When it fires |
|-----------|--------------|
| `expiry` | Daily cron — items expiring within `HA_EXPIRY_DAYS` days |
| `shopping_add` | Item added to the shopping list |
| `stock_update` | Inventory quantity changed |
| `barcode_scan` | (reserved for future use) |

### Webhook Payload (POST body)

```json
{
  "event": "expiry_alert",
  "timestamp": "2025-06-12T08:00:00+00:00",
  "data": {
    "type": "expiring_soon",
    "count": 3,
    "days": 3,
    "summary": "3 products expiring within 3 days",
    "items": [
      { "name": "Milk", "expiry_date": "2025-06-14", "quantity": 1, "unit": "l" }
    ]
  }
}
```

### Example: Expiry Alert → Telegram

```yaml
alias: EverShelf Expiry Alert
trigger:
  - platform: webhook
    webhook_id: "evershelf_webhook_abc123"   # ← your Webhook ID
action:
  - service: notify.telegram_bot
    data:
      message: >
        🥫 EverShelf: {{ trigger.json.data.summary }}
        {% for item in trigger.json.data.items %}
        — {{ item.name }} (expires {{ item.expiry_date }})
        {% endfor %}
```

---

## Push Notifications

If you prefer to receive push alerts without using webhooks, configure a **HA notify service** directly:

1. Find your notify service name in HA: **Developer Tools → Services** → search `notify`
2. Paste it into **Settings → 🏠 → Notify service** (e.g. `notify.mobile_app_my_phone`)
3. Save

EverShelf will call this service from the cron job whenever expiry alerts fire.

---

## TTS on Smart Speakers

Read recipe steps aloud on an Amazon Echo, Google Home, Sonos, or any HA `media_player`.

### Configuration

1. Enter the **Entity ID** of your media player (e.g. `media_player.kitchen_display`)
   - Find it in HA: **Developer Tools → States**
2. Click **Apply HA preset to TTS tab** — this auto-fills the TTS tab with the correct HA endpoint and auth headers
3. Save settings

### How it Works

When recipe step TTS is triggered, EverShelf calls:

```
POST /api/services/tts/speak
Authorization: Bearer <HA_TOKEN>
{
  "entity_id": "media_player.kitchen_display",
  "message": "Add 200 g of flour and mix well."
}
```

The request is proxied through the EverShelf PHP backend (avoids CORS / mixed-content issues).

---

## Environment Variables Reference

All settings are configurable from `.env` or from the in-app Settings panel.

| Variable | Default | Description |
|----------|---------|-------------|
| `HA_ENABLED` | `false` | Master switch for all HA features |
| `HA_URL` | _(empty)_ | Base URL of HA instance, no trailing slash |
| `HA_TOKEN` | _(empty)_ | Long-Lived Access Token |
| `HA_TTS_ENTITY` | _(empty)_ | `media_player` entity for TTS |
| `HA_WEBHOOK_ID` | _(empty)_ | Webhook trigger ID from HA automation |
| `HA_WEBHOOK_EVENTS` | `expiry,shopping_add,stock_update` | Comma-separated list of events |
| `HA_NOTIFY_SERVICE` | _(empty)_ | HA notify service (e.g. `notify.mobile_app_phone`) |
| `HA_EXPIRY_DAYS` | `3` | Days before expiry to trigger the daily alert |

---

## Troubleshooting

**Test shows ❌ "Connection failed"**
- Verify the URL is reachable from the EverShelf server (not just your browser)
- If using HTTPS with a self-signed certificate, the server-side cURL request may fail — use HTTP on the local network instead
- Check that port 8123 (or your custom port) is open on the HA host

**Test shows ❌ "bad_token"**
- The Long-Lived Access Token may have expired or been revoked — generate a new one in HA Profile

**Webhook not firing**
- Confirm HA_ENABLED=true and the Webhook ID is exactly as shown in HA
- Check the EverShelf cron is running (`/api/cron_smart_shopping.php` every 5 minutes)
- For shopping/stock events: verify the event name is in `HA_WEBHOOK_EVENTS`

**TTS not speaking**
- Ensure the media player entity is online in HA (check its state in Developer Tools)
- Try the "Apply HA preset to TTS tab" button and send a test from the TTS tab
- Check HA logs for `tts.speak` errors (some platforms require `tts_options`)

**Sensors show unavailable in HA**
- The EverShelf URL must be reachable from the HA host
- If running EverShelf behind a reverse proxy, ensure `/api/` is accessible
- Use `scan_interval` ≥ 60 to avoid hammering the server