notification-hub

# notification-hub skill

notification-hub is a unified notification aggregator. It ingests notifications from GitHub, Slack, and Email, normalises them into a single feed, and lets you filter, mute, label, archive, and digest them through a web UI and REST API.

## Environment

The server listens on `PORT` (default `3000`). Set these variables before running:

```
NOTIFICATION_HUB_PORT=3000
NOTIFICATION_HUB_DB=./data/notifications.db
NOTIFICATION_HUB_ENCRYPTION_KEY=<32-byte hex>   # AES-256-GCM key for OAuth token storage
NOTIFICATION_HUB_SESSION_SECRET=<random>
GITHUB_CLIENT_ID=<app client id>
GITHUB_CLIENT_SECRET=<app client secret>
GITHUB_CALLBACK_URL=http://localhost:3000/auth/github/callback
SLACK_CLIENT_ID=<app client id>
SLACK_CLIENT_SECRET=<app client secret>
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerts@example.com
SMTP_PASS=<password>
DIGEST_RECIPIENT=you@example.com
```

## Starting the server

```bash
pnpm install
pnpm dev          # development with hot reload
pnpm build && pnpm start   # production
```

Or with Docker:

```bash
docker compose up
```

## REST API

All routes are prefixed `/api`. Authenticate with the session cookie or the API token via `Authorization: Bearer <token>`.

### Feed

```bash
# List notifications (most recent first)
curl http://localhost:3000/api/notifications

# Filter by source, read status, priority
curl "http://localhost:3000/api/notifications?source=github&unread=1&priority=high"

# Full-text search
curl "http://localhost:3000/api/notifications?q=auth+middleware"

# Get a single notification
curl http://localhost:3000/api/notifications/:id

# Mark as read
curl -X PATCH http://localhost:3000/api/notifications/:id \
  -H 'Content-Type: application/json' \
  -d '{"read": true}'

# Set priority
curl -X PATCH http://localhost:3000/api/notifications/:id \
  -H 'Content-Type: application/json' \
  -d '{"priority": "high"}'

# Archive
curl -X POST http://localhost:3000/api/notifications/:id/archive

# Bulk mark read
curl -X POST http://localhost:3000/api/notifications/bulk \
  -H 'Content-Type: application/json' \
  -d '{"ids": ["id1","id2"], "action": "read"}'

# Bulk archive
curl -X POST http://localhost:3000/api/notifications/bulk \
  -H 'Content-Type: application/json' \
  -d '{"ids": ["id1","id2"], "action": "archive"}'
```

### Sources

```bash
# List connected sources
curl http://localhost:3000/api/sources

# Get source detail
curl http://localhost:3000/api/sources/:id

# Trigger manual sync
curl -X POST http://localhost:3000/api/sources/:id/sync

# Disconnect a source
curl -X DELETE http://localhost:3000/api/sources/:id

# Update watched repos (GitHub)
curl -X PATCH http://localhost:3000/api/sources/:id \
  -H 'Content-Type: application/json' \
  -d '{"config": {"repos": ["acme/api-gateway","acme/frontend"]}}'

# Update watched channels (Slack)
curl -X PATCH http://localhost:3000/api/sources/:id \
  -H 'Content-Type: application/json' \
  -d '{"config": {"channels": ["C012ABCDE","C999FGHIJ"]}}'
```

### Mute rules

```bash
# List rules
curl http://localhost:3000/api/mute-rules

# Create a rule
curl -X POST http://localhost:3000/api/mute-rules \
  -H 'Content-Type: application/json' \
  -d '{
    "pattern": "repo:acme/billing-api",
    "source": "github",
    "expiresAt": null
  }'

# Create a time-limited rule
curl -X POST http://localhost:3000/api/mute-rules \
  -H 'Content-Type: application/json' \
  -d '{
    "pattern": "title:chore*",
    "source": "github",
    "expiresAt": "2026-04-01T00:00:00Z"
  }'

# Enable / disable a rule
curl -X PATCH http://localhost:3000/api/mute-rules/:id \
  -H 'Content-Type: application/json' \
  -d '{"enabled": false}'

# Delete a rule
curl -X DELETE http://localhost:3000/api/mute-rules/:id
```

Supported pattern prefixes: `repo:`, `channel:`, `title:`, `from:`, `type:`. Use `*` as a wildcard.

### Digest

```bash
# Get digest config
curl http://localhost:3000/api/digest/config

# Update digest config
curl -X PATCH http://localhost:3000/api/digest/config \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true, "deliveryTime": "08:00", "timezone": "UTC"}'

# Trigger an immediate digest
curl -X POST http://localhost:3000/api/digest/send

# List past digests
curl http://localhost:3000/api/digest/history
```

### Labels

```bash
# List labels
curl http://localhost:3000/api/labels

# Create a label
curl -X POST http://localhost:3000/api/labels \
  -H 'Content-Type: application/json' \
  -d '{"name": "incident", "color": "#dc2626"}'

# Apply a label to a notification
curl -X POST http://localhost:3000/api/notifications/:id/labels \
  -H 'Content-Type: application/json' \
  -d '{"labelId": "lbl_xyz"}'

# Remove a label
curl -X DELETE http://localhost:3000/api/notifications/:id/labels/:labelId
```

### Stats

```bash
# Get 30-day stats summary
curl http://localhost:3000/api/stats

# Get stats for a specific period
curl "http://localhost:3000/api/stats?from=2026-03-01&to=2026-03-31"
```

## Connecting GitHub

1. Go to Settings > Sources > Add Source > GitHub.
2. Click "Authorize with GitHub" to begin the OAuth2 flow (passport-github2).
3. After authorization, select the repositories to watch.
4. The OAuth access token is stored encrypted with AES-256-GCM using `NOTIFICATION_HUB_ENCRYPTION_KEY`.
5. GitHub notifications are polled every `SYNC_INTERVAL_MS` milliseconds (default 300000).

## Connecting Slack

1. Go to Settings > Sources > Add Source > Slack.
2. Enter your Slack Bot Token (`xoxb-...`). The token is validated immediately.
3. Select the channels to watch.
4. The bot token is stored encrypted at rest.
5. Messages are polled via the Slack Web API (`conversations.history`).

## Connecting Email (IMAP)

1. Go to Settings > Sources > Add Source > Email.
2. Enter your IMAP host, port, username, and password.
3. Credentials are stored encrypted at rest.

## Digest email

The daily digest is sent via nodemailer using the SMTP credentials in the environment. To test delivery without waiting for the scheduled time:

```bash
curl -X POST http://localhost:3000/api/digest/send
```

## API token rotation

```bash
curl -X POST http://localhost:3000/api/settings/api-token/rotate \
  -H 'Authorization: Bearer <current_token>'
```

Store the new token returned in the response. The old token is invalidated immediately.