Metadata-Version: 2.4
Name: echosonar
Version: 0.1.4
Summary: Telegram Monitoring User Bot
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon>=1.43.2
Requires-Dist: typer
Requires-Dist: confuse
Requires-Dist: pyyaml
Requires-Dist: pytest>=9.0.3
Requires-Dist: pygments>=2.20.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.9.0; extra == "dev"
Requires-Dist: types-pyyaml; extra == "dev"
Dynamic: license-file

# 🛰️ EchoSonar

Enterprise-grade Telegram monitoring user bot built with [Telethon](https://telethon.dev). It acts as an automated bridge, monitoring your private or public channels for specific keywords and instantly copying and re-uploading content to a destination of your choice.

[![PyPI version](https://shields.io)](https://pypi.org)
[![License: MIT](https://shields.io)](https://opensource.org)


## 🛠️ Prerequisites
* Python >= 3.10
* Telegram account with active App credentials (`api_id`, `api_hash`) from [my.telegram.org](https://telegram.org).
* An execution environment (Local Machine or Linux VPS).


---

## ✨ Key Features

*   **🛡️ Content Protection Bypass:** Automatically downloads and re-uploads media from restricted channels where "Saving Content" is disabled.
*   **📂 Full Album Support:** Intelligently gathers media groups (albums) and forwards them as a single cohesive unit.
*   **👤 Human-Like Behavior:** Implements randomized delays (3-8s) and manual re-upload flows to mimic human activity and reduce account flagging risks.
*   **🔄 Hot-Reloading:** Update keywords, monitored channels, or destinations via CLI without restarting the running bot.
*   **🕵️ Private Channel Support:** Easily monitor private channels using internal numeric IDs.

---

## 🚀 Installation & Usage

Echosonar is designed to be installed in an isolated environment, choose the installation method that fits your environment best:

### Option 1: Docker (Recommended for Servers & Continuous Running)
Run the bot as an isolated background service:
```bash
docker compose up -d
```

👉 **Follow our dedicated [Docker Deployment & Management Guide](DOCKER_GUIDE.md) to set up your runtime container and configure hot-reloading keys.**

### Option 2: UV / Pipx (Recommended for Local CLI Management)
You can execute the application instantly from PyPI without downloading the source code, or install it permanently into its own isolated environment on your device:

* **Execute instantly with UV:**
  ```bash
  uvx echosonar run
  ```

* **Install permanently with Pipx:**
  ```bash
  pipx install echosonar
  ```

--- 

## 🛠️ Quick Start

### 1. Configuration
Run the setup command to input your Telegram API credentials (get them at [my.telegram.org](https://telegram.org)):
```bash
echosonar setup
```

### 2. Find Private IDs
If you need to monitor private channels, use the following command to see all your joined chats and their internal IDs:
```bash
echosonar list-ids
```

### 3. Add Monitoring Targets
```bash
# Add a public channel by username
echosonar channels add "@PublicChannel"

# Add a private channel by numeric ID (use -- to handle negative numbers)
echosonar channels add -- "-1001234567890"

# Add keywords
echosonar keywords add "urgent"
```

### 4. Run & Authenticate
Start the bot once in your terminal to complete the one-time Telegram login:
```bash
echosonar run
```

---

## 🏠 Running Live 24/7

### On a Server (Linux/VPS)
The professional way to run EchoSonar on a server is using **systemd**. This ensures the bot starts on boot and restarts automatically if it crashes.

1. **Create the service file:**
   `sudo nano /etc/systemd/system/echosonar.service`

2. **Paste configuration:** (Replace `youruser` with your Linux username)
   ```ini
   [Unit]
   Description=EchoSonar Telegram Bot
   After=network.target

   [Service]
   User=youruser
   ExecStart=/home/youruser/.local/bin/echosonar run
   Restart=always
   RestartSec=10
   WorkingDirectory=/home/youruser

   [Install]
   WantedBy=multi-user.target
   ```

3. **Start the service:**
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable --now echosonar
   ```

### On a Personal Computer
For local background execution, use a terminal multiplexer like **Screen** or **TMUX**:
```bash
# Create a new session
screen -S echosonar

# Run the bot
echosonar run

# Detach (Press Ctrl+A then D)
# The bot will continue running in the background.
```

---

## 📖 Detailed Documentation
For a full list of all available commands and advanced usage, see [COMMANDS.md](./COMMANDS.md).

## ⚖️ Disclaimer
This tool is for personal automation and research purposes. Please respect Telegram's [Terms of Service](https://telegram.org) and the copyright of content creators. Use of user bots carries a risk of account restriction if used for spam or malicious activity.
