source-integrations

# source-integrations skill

This skill covers setting up the GitHub and Slack integrations from scratch, including creating the OAuth2 app, configuring credentials, and troubleshooting common sync failures.

## GitHub integration

### Create the GitHub OAuth App

1. Go to GitHub > Settings > Developer settings > OAuth Apps > New OAuth App.
2. Fill in:
   - Application name: `notification-hub` (or any name)
   - Homepage URL: `http://localhost:3000`
   - Authorization callback URL: `http://localhost:3000/auth/github/callback`
3. Click "Register application".
4. Copy the **Client ID** and generate a **Client Secret**.
5. Set in your environment:

```bash
GITHUB_CLIENT_ID=Ov23liXXXXXXXXXX
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_CALLBACK_URL=http://localhost:3000/auth/github/callback
```

For production replace `localhost:3000` with your public URL.

### OAuth2 flow (passport-github2)

The flow is handled by `src/integrations/github/oauth.ts`. The strategy is registered at startup:

```
GET /auth/github          - redirect to GitHub
GET /auth/github/callback - exchange code for token, store encrypted, redirect to /sources
```

The access token is encrypted with AES-256-GCM before writing to the `sources.access_token_enc` column:

```
NOTIFICATION_HUB_ENCRYPTION_KEY must be exactly 64 hex characters (32 bytes)
```

Generate a key:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

### GitHub sync

After connection, the poller in `src/integrations/github/sync.ts` runs on the `SYNC_INTERVAL_MS` schedule. It calls:

```
GET /notifications?all=false&participating=false&since=<last_sync>
```

Each notification is upserted into the `notifications` table using the GitHub `id` field as the external ID to prevent duplicates. Mute rules are evaluated at ingest time.

### Configuring watched repositories

After OAuth, the user selects repos in the UI. Only notifications from those repos are stored. Update via API:

```bash
curl -X PATCH http://localhost:3000/api/sources/:id \
  -H 'Content-Type: application/json' \
  -d '{"config": {"repos": ["owner/repo1","owner/repo2"]}}'
```

Pass an empty array to watch all repos:

```bash
curl -X PATCH http://localhost:3000/api/sources/:id \
  -H 'Content-Type: application/json' \
  -d '{"config": {"repos": []}}'
```

### GitHub notification types

| GitHub reason       | Displayed as              |
|---------------------|---------------------------|
| `review_requested`  | PR review                 |
| `mention`           | Mention                   |
| `assign`            | Issue assignment          |
| `ci_activity`       | CI status                 |
| `subscribed`        | Subscribed                |
| `team_mention`      | Team mention              |

### GitHub troubleshooting

**Token expired or revoked**

The source status will show `error`. Disconnect and reconnect via OAuth.

**Rate limit hit**

GitHub REST API allows 5000 requests/hour for authenticated users. The poller backs off automatically when the `X-RateLimit-Remaining` header is below 100.

**Callback URL mismatch**

If GitHub returns `redirect_uri_mismatch`, the `GITHUB_CALLBACK_URL` env var must exactly match the callback URL registered in the OAuth App settings.

---

## Slack integration

### Create the Slack App

1. Go to https://api.slack.com/apps > Create New App > From scratch.
2. Name: `notification-hub`. Pick your workspace.
3. Under **OAuth and Permissions** > **Scopes** > **Bot Token Scopes**, add:
   - `channels:history`
   - `channels:read`
   - `groups:history`
   - `groups:read`
   - `users:read`
4. Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
5. Do NOT set `SLACK_CLIENT_ID`/`SLACK_CLIENT_SECRET` unless you want the full OAuth flow. For a single-workspace personal setup, only the bot token is required.

### Connecting with a bot token

In the notification-hub web UI:

1. Sources > Add Source > Slack.
2. Paste the `xoxb-...` token.
3. The server calls `auth.test` to validate and fetch the workspace info.
4. Select channels to watch from the list returned by `conversations.list`.

The token is stored encrypted at rest (same AES-256-GCM scheme as GitHub).

### Slack sync

`src/integrations/slack/sync.ts` polls each watched channel using `conversations.history` with a `oldest` cursor equal to the last sync timestamp. New messages are stored as notifications. Direct mentions (`<@UXXXXXXXX>`) are given higher priority automatically.

### Configuring watched channels

```bash
# Get channel IDs
curl http://localhost:3000/api/sources/:id/channels

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

### Slack troubleshooting

**`invalid_auth` error**

The token has been revoked or the app was uninstalled. Generate a new bot token in the Slack app settings and update via disconnect/reconnect.

**`not_in_channel` error**

The bot must be invited to private channels. In Slack: `/invite @notification-hub` in the channel.

**Missing messages**

`conversations.history` only returns messages from public channels and private channels where the bot is a member. Threads are fetched separately with `conversations.replies` if `thread_ts` is present.

**Rate limits**

Slack Tier 3 methods (conversations.history) allow ~50 requests/minute. The poller automatically adds delays between channel polls when multiple channels are watched.

---

## Encryption key rotation

If you need to rotate the `NOTIFICATION_HUB_ENCRYPTION_KEY`:

1. Set the new key as `NOTIFICATION_HUB_ENCRYPTION_KEY_NEW`.
2. Run the migration script:

```bash
pnpm run migrate:rotate-keys
```

This re-encrypts all stored tokens with the new key. After the script completes, rename `ENCRYPTION_KEY_NEW` to `ENCRYPTION_KEY` and restart the server.

---

## Testing integrations locally

Use ngrok or a similar tunnel to expose `localhost:3000` for OAuth callbacks during development:

```bash
ngrok http 3000
# Copy the https URL, e.g. https://abc123.ngrok.io
```

Set `GITHUB_CALLBACK_URL=https://abc123.ngrok.io/auth/github/callback` and update the GitHub OAuth App callback URL to match.