# Streaming Overseer: A Telegram Monitoring Tool

This tool monitors specified Telegram channels for messages that contain certain keywords and forwards them to a private channel. It's built using Python and Telethon, a Telegram client library.

## Features

- Monitors multiple channels.
- Searches for messages with specified keywords.
- Forwards matching messages to a private channel.

## Prerequisites

Before you can use this tool, you need to set up a few things:

1. **Python 3.8+** (Tested on 3.10+)
2. **Telethon Library**
3. **A Telegram API key and API Hash**
4. **A Telegram Bot**
5. **A Private Telegram Channel**

### Installing Python

Download and install Python from [python.org](https://www.python.org/downloads/).

## Setup Instructions

### Obtaining Telegram API ID and Hash

1. **Login to your Telegram account** at [Telegram Core](https://my.telegram.org).
2. Go to `API development tools` and fill out the form.
3. You will get an `api_id` and `api_hash` which are needed for the tool.

### Creating a Telegram Bot

1. **Open Telegram** and search for [BotFather](https://t.me/botfather).
2. Send `/newbot` and follow the instructions to create your bot.
3. **Copy the token** provided by BotFather.

### Setting Up a Private Channel

1. **Create a new channel** in Telegram.
2. **Switch the channel's privacy to private** in the channel settings.
3. **Add your bot as an administrator** to the channel.

## Configuration Files

The script uses several files for configuration:

- `credentials.json`: Automatically created if not present. It stores API keys, bot token, and private channel ID.
- `keywords.txt`: Contains keywords to monitor. Supports special modifiers for dynamic matching:
  - `*` at the end allows up to three additional characters.
  - `**` allows up to six additional characters.
  - `#` at the start includes numeric characters (up to three).
  - `##` includes numeric characters (up to six).

  **Note: Separate keywords using commas. Keywords can span multiple lines for readability; newlines are ignored.**
- `channels.txt`: List of channel usernames (the part after `t.me/`) to monitor
- Separate channel names with commas, and feel free to list them across multiple lines for better readability. Newlines between names are ignored.

  **Note: Ensure you have joined any channel you wish to monitor.**

### Examples

- `keywords.txt`
  ```
  hello*, world**, #123,
  ##123456, #or_any_combination**
  ```
- `channels.txt`
  ```
  python, daily_news,
  target3, target4
  ```


## Running the CLI Tool

```bash
python streaming_overseer.py
```

## Web Control Panel (FastAPI + Vue)

The project now ships with a FastAPI backend (`backend/`) and a Vue 3 dashboard (`frontend/`) so you can update credentials, manage keywords/channels, and watch matches in real time.

### Authentication

- All API routes (except `/api/auth/token`) are protected with JWT. The default credentials are `admin / admin123` and are stored in `users.json`.
- After the first login, use the UI “change password” endpoint (or call `POST /api/auth/change-password`) to update the password. The JWT expires after 60 minutes.
- Include the bearer token in the `Authorization` header for REST calls; the frontend handles this automatically after you log in from the new login page.

### Backend

```
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r ../requirements.txt
uvicorn app.main:app --reload
```

The API is exposed on `http://localhost:8000/api`. Important endpoints:

- `POST /api/auth/token`, `GET /api/auth/me`, `POST /api/auth/change-password`
- `GET /api/credentials` (list), `POST /api/credentials` (create), `PUT /api/credentials/{id}` (update), `DELETE /api/credentials/{id}`, `POST /api/credentials/{id}/activate`, `GET /api/credentials/active`
- `GET/PUT /api/keywords`
- `GET/PUT /api/channels`
- `POST /api/scanner/start|stop`, `GET /api/scanner/status`
- `GET /api/matches`, `GET /api/matches/stream`

### Frontend

```
cd frontend
npm install
npm run dev
```

Set `VITE_API_BASE` in a `.env` file if your backend is not running on `http://localhost:8000/api`. Once the dev server starts, visit `http://localhost:5173/login`, log in with the admin user, and the dashboard will become available.

### Production Notes

- FastAPI already enables permissive CORS for local development; tighten it for production.
- Ensure `credentials.json`, `keywords.txt`, `channels.txt`, and `users.json` are stored securely; the API reads/writes the same files as the CLI script.
- The Telethon scanner still forwards matching messages to the configured Telegram channel while also streaming match metadata to the dashboard.

### Managing multiple credentials

- The “凭据配置”页面 now supports multiple Telegram API credentials. Each record stores API ID/API Hash/手机号/Bot Token/频道 ID，列表中可一键设为当前使用的账号。
- 新建或编辑凭据后，点击“设为当前”即可让扫描器切换到该账号运行；激活状态会同步到 `credentials.json` 中的 `active` 字段。