# Alert Configuration Guide

ScarpShield supports alerting across five channels. This guide walks you through configuring each one.

---

## Console (Default, Always On)

The console channel requires no setup. All alerts are printed directly to the terminal where ScarpShield is running.

```
[ALERT] Transfer | USDC Treasury | Ethereum
  From: 0x1234...abcd
  To:   0x5678...ef01
  Value: 1,250.00 USDC
```

Console alerts cannot be disabled. They serve as a reliable fallback when other channels fail.

---

## Email (SMTP)

### Prerequisites

- Access to an SMTP server (Gmail, Outlook, or a custom server)
- For Gmail: a Google account with 2-Factor Authentication enabled

### Gmail Setup

1. Enable **2-Factor Authentication** on your Google account: https://myaccount.google.com/security
2. Go to **App passwords**: https://myaccount.google.com/apppasswords
3. Generate a new app password for "Mail"
4. Copy the 16-character password (e.g., `abcd efgh ijkl mnop`)

> **Important:** Use the app password, NOT your regular Google password.

### Step-by-Step Configuration

Run the setup wizard:

```bash
python main.py setup-email
```

The CLI will prompt you for the following values:

| Prompt | Example Value |
|--------|---------------|
| SMTP Host | `smtp.gmail.com` |
| SMTP Port | `587` (TLS) or `465` (SSL) |
| Username | `your.email@gmail.com` |
| Password | `abcd efgh ijkl mnop` (app password) |
| From Address | `your.email@gmail.com` |
| To Address | `alerts@yourdomain.com` |

### Environment Variable Alternative

Instead of using the wizard, you can set these in your `.env` file:

```env
SCARPSHIELD_SMTP_HOST=smtp.gmail.com
SCARPSHIELD_SMTP_PORT=587
SCARPSHIELD_SMTP_USER=your.email@gmail.com
SCARPSHIELD_SMTP_PASSWORD=your_app_password
SCARPSHIELD_SMTP_FROM=your.email@gmail.com
SCARPSHIELD_SMTP_TO=alerts@yourdomain.com
```

Environment variables override values stored in `config.json` at runtime.

### Testing

After configuration, verify email delivery:

```bash
python main.py test-alerts
```

You should receive a test alert email within a few seconds.

### Troubleshooting

| Error | Cause | Fix |
|-------|-------|-----|
| `Authentication failed` | Wrong password or app password not used | Generate a fresh app password |
| `Connection refused` | Wrong host or port | Double-check `smtp.gmail.com:587` |
| `STARTTLS extension not supported` | Port mismatch | Use 587 for TLS, 465 for SSL |
| Emails in spam folder | Sender reputation | Add sender to contacts or whitelist |

---

## Discord

### Prerequisites

- A Discord server where you have **Manage Webhooks** permission

### Step 1: Create a Webhook

1. Open your Discord server
2. Go to **Server Settings** → **Integrations** → **Webhooks**
3. Click **New Webhook**
4. Choose the channel where alerts should be posted
5. Give it a name like "ScarpShield Alerts"

### Step 2: Copy the Webhook URL

1. Click **Copy Webhook URL**
2. The URL looks like:
   ```
   https://discord.com/api/webhooks/1234567890123456789/abcdefghijklmnopqrstuvwxyz
   ```

### Step 3: Configure ScarpShield

Run the setup wizard:

```bash
python main.py setup-discord
```

Paste the webhook URL when prompted.

### Environment Variable Alternative

```env
SCARPSHIELD_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1234567890123456789/abcdefghijklmnopqrstuvwxyz
```

### Message Limits

Discord messages auto-truncate at **2000 characters**. If an alert exceeds this limit, ScarpShield splits it into multiple messages or sends a summarized version with a link to the full details.

### Testing

```bash
python main.py test-alerts
```

A test message should appear in your Discord channel immediately.

---

## Slack

### Prerequisites

- Admin access to a Slack workspace

### Step 1: Create a Slack App

1. Go to https://api.slack.com/apps
2. Click **Create New App** → **From scratch**
3. Name it "ScarpShield" and select your workspace

### Step 2: Enable Incoming Webhooks

1. In the left sidebar, go to **Incoming Webhooks**
2. Toggle **Activate Incoming Webhooks** to **On**
3. Click **Add New Webhook to Workspace**
4. Choose the channel where alerts should be posted
5. Click **Allow**

### Step 3: Copy the Webhook URL

1. The webhook URL will be displayed:
   ```
   https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
   ```
2. Copy this URL

### Step 4: Configure ScarpShield

Run the setup wizard:

```bash
python main.py setup-slack
```

Paste the webhook URL when prompted.

### Environment Variable Alternative

```env
SCARPSHIELD_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
```

### Testing

```bash
python main.py test-alerts
```

A test message should appear in your Slack channel.

---

## Telegram

### Prerequisites

- A Telegram account

### Step 1: Create a Bot

1. Open Telegram and message **@BotFather**
2. Send `/newbot`
3. Follow the prompts to name your bot (e.g., "ScarpShieldBot")
4. Copy the **bot token** provided:
   ```
   123456789:ABCdefGHIjklMNOpqrSTUvwxyz
   ```

### Step 2: Add the Bot to a Chat

1. Create a group or channel (or use an existing one)
2. Add your new bot to the group/channel
3. Send at least one message in the chat so the bot can see it

### Step 3: Get the Chat ID

Use the Telegram API to find your chat ID. Replace `<TOKEN>` with your bot token:

```bash
curl https://api.telegram.org/bot<TOKEN>/getUpdates
```

Look for the `chat` object in the response:

```json
{
  "message": {
    "chat": {
      "id": -123456789,
      "title": "ScarpShield Alerts"
    }
  }
}
```

The `id` field is your **chat ID**. For groups, it is typically negative.

### Step 4: Configure ScarpShield

Run the setup wizard:

```bash
python main.py setup-telegram
```

Enter the bot token and chat ID when prompted.

### Environment Variable Alternative

```env
SCARPSHIELD_TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxyz
SCARPSHIELD_TELEGRAM_CHAT_ID=-123456789
```

### Testing

```bash
python main.py test-alerts
```

A test message should appear in your Telegram chat.

---

## Security Best Practice

**Always use environment variables (`.env` file) for credentials instead of storing them in `config.json`.**

The `.env` file is listed in `.gitignore` by default, so your secrets will never be committed to version control. Credentials stored in `config.json` may accidentally be checked into your repository.

### Recommended `.env` Pattern

```env
# SMTP
SCARPSHIELD_SMTP_USER=your.email@gmail.com
SCARPSHIELD_SMTP_PASSWORD=your_app_password

# Discord
SCARPSHIELD_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Slack
SCARPSHIELD_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Telegram
SCARPSHIELD_TELEGRAM_BOT_TOKEN=123456789:...
SCARPSHIELD_TELEGRAM_CHAT_ID=-123456789
```

Load the `.env` file before starting ScarpShield:

```bash
# On Windows (PowerShell)
$env:SCARPSHIELD_SMTP_USER = "your.email@gmail.com"

# Or use python-dotenv (installed automatically)
python main.py start
```

### File Permissions

On Unix systems, restrict `.env` file access:

```bash
chmod 600 .env
```

On Windows, the file is not executable by default. Keep it in a secure location and avoid sharing it.