# ntfy.sh Push Notifications Setup

CheddahBot sends push notifications to your phone and desktop via [ntfy.sh](https://ntfy.sh) when tasks complete, reports are ready, or errors occur.

## 1. Install the ntfy App

- **Android:** [Play Store](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
- **iOS:** [App Store](https://apps.apple.com/us/app/ntfy/id1625396347)
- **Desktop:** Open [ntfy.sh](https://ntfy.sh) in your browser and enable browser notifications when prompted

## 2. Pick Topic Names

Topics are like channels. Anyone who knows the topic name can subscribe, so use random strings:

```
cheddahbot-a8f3k9x2m7
cheddahbot-errors-p4w2j6n8
```

Generate your own — any random string works. No account or registration needed.

## 3. Subscribe to Your Topics

**Phone app:**
1. Open the ntfy app
2. Tap the + button
3. Enter your topic name (e.g. `cheddahbot-a8f3k9x2m7`)
4. Server: `https://ntfy.sh` (default)
5. Repeat for your errors topic

**Browser:**
1. Go to [ntfy.sh](https://ntfy.sh)
2. Click "Subscribe to topic"
3. Enter the same topic names
4. Allow browser notifications when prompted

## 4. Add Topics to .env

Add these lines to your `.env` file in the CheddahBot root:

```
NTFY_TOPIC_HUMAN_ACTION=cheddahbot-a8f3k9x2m7
NTFY_TOPIC_ERRORS=cheddahbot-errors-p4w2j6n8
```

Replace with your actual topic names.

## 5. Restart CheddahBot

Kill the running instance and restart:

```bash
uv run python -m cheddahbot
```

You should see in the startup logs:

```
ntfy notifier initialized with 2 channel(s): human_action, errors
ntfy notifier subscribed to notification bus
```

## What Gets Notified

### human_action channel (high priority)
Notifications where you need to do something:
- Cora report finished and ready
- Press release completed
- Content outline ready for review
- Content optimization completed
- Link building pipeline finished
- Cora report distributed to inbox

### errors channel (urgent priority)
Notifications when something went wrong:
- ClickUp task failed or was skipped
- AutoCora job failed
- Link building pipeline error
- Content pipeline error
- Missing ClickUp field matches
- File copy failures

## Configuration

Channel routing is configured in `config.yaml` under the `ntfy:` section. Each channel has:

- `topic_env_var` — which env var holds the topic name
- `categories` — notification categories to listen to (`clickup`, `autocora`, `linkbuilding`, `content`)
- `include_patterns` — regex patterns the message must match (at least one)
- `exclude_patterns` — regex patterns that reject the message (takes priority over include)
- `priority` — ntfy priority level: `min`, `low`, `default`, `high`, `urgent`
- `tags` — emoji shortcodes shown on the notification (e.g. `white_check_mark`, `rotating_light`)

### Adding a New Channel

1. Add a new entry under `ntfy.channels` in `config.yaml`
2. Add the topic env var to `.env`
3. Subscribe to the topic in your ntfy app
4. Restart CheddahBot

### Privacy

The public ntfy.sh server has no authentication by default. Your topic name is the only security — use a long random string to make it unguessable. Alternatively:

- Create a free ntfy.sh account and set read/write ACLs on your topics
- Self-host ntfy (single binary) and set `server: http://localhost:8080` in config.yaml

### Disabling

Set `enabled: false` in the `ntfy:` section of `config.yaml`, or remove the env vars from `.env`.