Skill: email-digest-builder

# Skill: email-digest-builder

Use email-digest-builder to manage feeds, topics, and digest delivery through the REST API.

---

## Base URL

```
http://localhost:4400
```

Dashboard at `http://localhost:4401`.

---

## Feed Management

### List feeds

```bash
curl http://localhost:4400/api/feeds
```

### Add a feed

```bash
curl -X POST http://localhost:4400/api/feeds \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com/rss",
    "title": "Hacker News",
    "fetch_interval": 60,
    "enabled": 1
  }'
```

Fields:
- `url` - RSS or Atom feed URL (required)
- `title` - display name (auto-populated if omitted)
- `fetch_interval` - minutes between fetches (default: 60)
- `enabled` - 1 to start fetching immediately (default: 1)

### Trigger an immediate fetch

```bash
curl -X POST http://localhost:4400/api/feeds/feed_abc123/fetch
```

### Update a feed

```bash
curl -X PUT http://localhost:4400/api/feeds/feed_abc123 \
  -H "Content-Type: application/json" \
  -d '{"fetch_interval": 30, "enabled": 0}'
```

---

## Topic Management

### List topics

```bash
curl http://localhost:4400/api/topics
```

### Create a topic

```bash
curl -X POST http://localhost:4400/api/topics \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI",
    "description": "Artificial intelligence, machine learning, LLMs, and AI tools.",
    "color": "#3b82f6",
    "keywords": "AI, LLM, GPT, Claude, neural network"
  }'
```

The `description` is sent to the LLM classifier as context. Write it clearly and specifically.

### Update topic sort order

```bash
curl -X PUT http://localhost:4400/api/topics/topic_abc \
  -H "Content-Type: application/json" \
  -d '{"sort_order": 1}'
```

Topics appear in the digest in `sort_order` order.

---

## Feed Items

### List all items

```bash
curl "http://localhost:4400/api/items?topic_id=topic_ai&read=0&limit=50"
```

Query parameters:
- `topic_id` - filter by topic
- `feed_id` - filter by feed
- `read` - 0 (unread) or 1 (read)
- `bookmarked` - 0 or 1
- `since` - ISO timestamp (items published after this time)
- `limit` - max items (default 50, max 200)
- `offset` - pagination offset

### Mark an item read

```bash
curl -X PATCH http://localhost:4400/api/items/item_xyz \
  -H "Content-Type: application/json" \
  -d '{"read": 1}'
```

### Bookmark an item

```bash
curl -X PATCH http://localhost:4400/api/items/item_xyz \
  -H "Content-Type: application/json" \
  -d '{"bookmarked": 1}'
```

---

## Digest Generation

### Generate a digest

```bash
curl -X POST http://localhost:4400/api/digests \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your Morning Digest - Jan 16",
    "topic_ids": ["topic_ai", "topic_engineering", "topic_tools"],
    "lookback_hours": 24
  }'
```

If `topic_ids` is omitted, all topics are included.

### Preview a digest

```bash
curl http://localhost:4400/api/digests/digest_xyz/preview
```

Returns rendered HTML suitable for display in an iframe or browser.

### Send a digest

```bash
curl -X POST http://localhost:4400/api/digests/digest_xyz/send \
  -H "Content-Type: application/json" \
  -d '{"recipient": "alice@example.com"}'
```

---

## Schedules

### Create a schedule

```bash
curl -X POST http://localhost:4400/api/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Digest",
    "cron_expr": "0 7 * * *",
    "timezone": "America/New_York",
    "recipient_email": "alice@example.com",
    "topic_ids": ["topic_ai", "topic_engineering"],
    "lookback_hours": 24,
    "enabled": 1
  }'
```

Cron expressions use standard 5-field format. Run the schedule immediately:

```bash
curl -X POST http://localhost:4400/api/schedules/sched_abc/run
```

---

## Settings

### Update SMTP settings

```bash
curl -X PATCH http://localhost:4400/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_secure": "starttls",
    "smtp_user": "alice@gmail.com",
    "smtp_password": "your-app-password",
    "smtp_from": "alice@gmail.com"
  }'
```

### Update LLM settings

```bash
curl -X PATCH http://localhost:4400/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "llm_api_key": "sk-ant-api03-...",
    "llm_model": "claude-3-haiku-20240307",
    "llm_batch_size": 50
  }'
```

`smtp_password` and `llm_api_key` are encrypted with AES-256-GCM before storage.

---

## API Reference

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/feeds | List feeds |
| POST | /api/feeds | Add feed |
| GET | /api/feeds/:id | Get feed |
| PUT | /api/feeds/:id | Update feed |
| DELETE | /api/feeds/:id | Delete feed |
| POST | /api/feeds/:id/fetch | Fetch feed now |
| GET | /api/feeds/:id/items | Items for feed |
| GET | /api/items | All items (with filters) |
| PATCH | /api/items/:id | Update item (read/bookmarked) |
| GET | /api/topics | List topics |
| POST | /api/topics | Create topic |
| PUT | /api/topics/:id | Update topic |
| DELETE | /api/topics/:id | Delete topic |
| GET | /api/digests | List digests |
| POST | /api/digests | Generate digest |
| GET | /api/digests/:id | Get digest |
| GET | /api/digests/:id/preview | Get rendered HTML |
| POST | /api/digests/:id/send | Send digest via SMTP |
| GET | /api/schedules | List schedules |
| POST | /api/schedules | Create schedule |
| PUT | /api/schedules/:id | Update schedule |
| DELETE | /api/schedules/:id | Delete schedule |
| POST | /api/schedules/:id/run | Run schedule now |
| GET | /api/settings | Get settings |
| PATCH | /api/settings | Update settings |
| GET | /health | Health check |

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| DIGEST_PORT | 4400 | API server port |
| DIGEST_DASHBOARD_PORT | 4401 | Dashboard port |
| DIGEST_DATA_DIR | ~/.email-digest-builder | SQLite directory |
| DIGEST_ENCRYPTION_KEY | required | 32-byte hex for encryption |
| DIGEST_LOG_LEVEL | info | debug / info / warn / error |
| DIGEST_DEV | 0 | 1 = development mode |

---

## Troubleshooting

**Feed fetches fail repeatedly**: Check that the URL returns valid RSS or Atom XML. Try `curl -L <url>` to see the raw response. After 5 consecutive errors the feed is automatically disabled.

**Items stay unclassified**: Ensure at least one topic exists with a clear description. Run the classifier manually via `POST /api/topics/classify`. Check LLM API key in settings.

**Digest generates 0 items**: Verify the `lookback_hours` covers the time period when items were fetched. Check that the selected `topic_ids` have classified items in that window.

**SMTP delivery fails**: Use the "Test connection" button in settings. For Gmail, you must use an App Password (not your account password). Enable "Less secure app access" or use OAuth2.