├── src ├── __init__.py ├── config.py ├── database.py ├── client.py ├── users.py ├── channels.py ├── image_analysis.py ├── formatting.py ├── app.py ├── message_export.py ├── export.py └── media.py ├── requirements.txt ├── main.py ├── tools └── .gitignore ├── .env.example ├── .gitignore ├── LICENSE ├── docs ├── setup.md ├── contributing.md ├── faq.md ├── codebase.md ├── IMPLEMENTATION_PLAN.md └── SEARCH_REPLACE_FORMATTING.md ├── CLAUDE.md └── README.md /src/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | telethon 2 | cryptg 3 | python-dotenv 4 | requests -------------------------------------------------------------------------------- /main.py: -------------------------------------------------------------------------------- 1 | """ 2 | Telegram Channel Saver - Main entry point 3 | """ 4 | from src.app import main 5 | 6 | if __name__ == "__main__": 7 | main() -------------------------------------------------------------------------------- /tools/.gitignore: -------------------------------------------------------------------------------- 1 | # Virtual environment 2 | venv/ 3 | 4 | # Python cache 5 | __pycache__/ 6 | *.pyc 7 | *.pyo 8 | 9 | # Test outputs 10 | *.log 11 | *.tmp 12 | -------------------------------------------------------------------------------- /.env.example: -------------------------------------------------------------------------------- 1 | # Telegram API credentials (required) 2 | # Get these from https://my.telegram.org/ 3 | API_ID=your_api_id_here 4 | API_HASH=your_api_hash_here 5 | 6 | # OpenRouter API key (optional - for AI image analysis) 7 | # Get this from https://openrouter.ai/ 8 | OPENROUTER_API_KEY=your_openrouter_api_key_here -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Python 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | *.so 6 | .Python 7 | build/ 8 | develop-eggs/ 9 | dist/ 10 | downloads/ 11 | eggs/ 12 | .eggs/ 13 | lib/ 14 | lib64/ 15 | parts/ 16 | sdist/ 17 | var/ 18 | wheels/ 19 | *.egg-info/ 20 | .installed.cfg 21 | *.egg 22 | 23 | # Virtual Environment 24 | venv/ 25 | ENV/ 26 | env/ 27 | 28 | # IDE 29 | .idea/ 30 | .vscode/ 31 | *.swp 32 | *.swo 33 | 34 | # Project specific 35 | temp/ 36 | exports/ 37 | *.session 38 | *.session-journal 39 | .env 40 | database.json 41 | 42 | # OS specific 43 | .DS_Store 44 | Thumbs.db -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Sergey Bulaev 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /src/config.py: -------------------------------------------------------------------------------- 1 | """ 2 | Configuration settings for the Telegram Channel Saver. 3 | Contains constants and settings used throughout the application. 4 | """ 5 | import os 6 | import logging 7 | 8 | # Configure logging 9 | logging.basicConfig( 10 | format='[%(levelname) 5s/%(asctime)s] %(name)s: %(message)s', 11 | level=logging.INFO 12 | ) 13 | 14 | logger = logging.getLogger(__name__) 15 | 16 | # Batch size and timing settings 17 | MESSAGES_BATCH_SIZE = 100 # Number of messages to process in one batch 18 | BATCH_DELAY = 2 # Delay between batches in seconds 19 | SAVE_INTERVAL = 300 # Save database every 5 minutes 20 | MAX_RETRIES = 3 # Maximum retries for failed message fetches 21 | 22 | # Media download settings 23 | MEDIA_DOWNLOAD_DELAY = 3 # Delay between media downloads in seconds to avoid rate limits 24 | MEDIA_DOWNLOAD_TIMEOUT = 120 # Timeout for media downloads in seconds (2 minutes) 25 | MEDIA_DOWNLOAD_RETRY = 3 # Maximum number of retries for failed media downloads 26 | MEDIA_RETRY_DELAY_BASE = 5 # Base delay for retry backoff in seconds 27 | CHUNK_SIZE = 1024 * 1024 # 1MB chunk size for large downloads 28 | 29 | # Directory settings 30 | TEMP_DIR = 'temp/channel_saver' 31 | VIDEO_TEMP_DIR = 'temp/videos' # Directory for storing downloaded videos 32 | EXPORT_DIR = 'temp/exports' # Directory for storing exported message files 33 | 34 | # OpenRouter API settings 35 | OPENROUTER_API_KEY = os.getenv('OPENROUTER_API_KEY') 36 | OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1" 37 | OPENROUTER_MODEL = "openai/gpt-4o-mini" # Default model for image analysis 38 | OPENROUTER_TIMEOUT = 30 # Timeout for API requests in seconds 39 | 40 | # Create temp directories if they don't exist 41 | os.makedirs(TEMP_DIR, exist_ok=True) 42 | os.makedirs(VIDEO_TEMP_DIR, exist_ok=True) 43 | os.makedirs(EXPORT_DIR, exist_ok=True) -------------------------------------------------------------------------------- /src/database.py: -------------------------------------------------------------------------------- 1 | """ 2 | Database operations for the Telegram Channel Saver. 3 | Handles loading, saving, and managing the JSON database. 4 | """ 5 | import os 6 | import json 7 | import logging 8 | from datetime import datetime 9 | 10 | from src.config import TEMP_DIR 11 | 12 | logger = logging.getLogger(__name__) 13 | 14 | def load_database(db_path): 15 | """ 16 | Load database from JSON file or create new if doesn't exist 17 | 18 | Args: 19 | db_path: Path to the database file 20 | 21 | Returns: 22 | dict: Loaded database or new database structure 23 | """ 24 | if os.path.exists(db_path): 25 | try: 26 | with open(db_path, 'r') as f: 27 | return json.load(f) 28 | except json.JSONDecodeError: 29 | logger.warning("Corrupted database file, creating new") 30 | return create_new_database(db_path) 31 | return create_new_database(db_path) 32 | 33 | def create_new_database(db_path): 34 | """ 35 | Create new database structure 36 | 37 | Args: 38 | db_path: Path to save the new database 39 | 40 | Returns: 41 | dict: New empty database structure 42 | """ 43 | db = { 44 | 'users': {}, 45 | 'last_login': None, 46 | 'sessions': {}, 47 | 'active_channel': None, 48 | 'messages': {}, 49 | 'videos': {} 50 | } 51 | save_database(db_path, db) 52 | return db 53 | 54 | def save_database(db_path, db): 55 | """ 56 | Save database to JSON file 57 | 58 | Args: 59 | db_path: Path to save the database 60 | db: Database dictionary to save 61 | """ 62 | with open(db_path, 'w') as f: 63 | json.dump(db, f, indent=4, default=str) 64 | 65 | def get_db_path(): 66 | """ 67 | Get the path to the database file 68 | 69 | Returns: 70 | str: Path to the database file 71 | """ 72 | return os.path.join(TEMP_DIR, 'database.json') -------------------------------------------------------------------------------- /docs/setup.md: -------------------------------------------------------------------------------- 1 | # Telegram Channel Saver Setup Guide 2 | 3 | This document provides detailed instructions for setting up your development environment to work on the Telegram Channel Saver project. 4 | 5 | ## Prerequisites 6 | 7 | Before you begin, ensure that you have the following installed on your system: 8 | 9 | - Python 3.8 or higher 10 | - pip (Python package manager) 11 | - Git 12 | 13 | ## Installation Steps 14 | 15 | ### 1. Clone the Repository 16 | 17 | ```bash 18 | git clone https://github.com/yourusername/telegram-channel-saver.git 19 | cd telegram-channel-saver 20 | ``` 21 | 22 | ### 2. Create a Virtual Environment 23 | 24 | It's recommended to use a virtual environment to keep dependencies isolated: 25 | 26 | ```bash 27 | # Create a virtual environment 28 | python -m venv venv 29 | 30 | # Activate the virtual environment 31 | # On Windows: 32 | venv\Scripts\activate 33 | # On macOS/Linux: 34 | source venv/bin/activate 35 | ``` 36 | 37 | ### 3. Install Dependencies 38 | 39 | Install the required packages: 40 | 41 | ```bash 42 | pip install -r requirements.txt 43 | 44 | # For development, install additional packages 45 | pip install -r requirements-dev.txt # if available 46 | ``` 47 | 48 | ### 4. Telegram API Credentials 49 | 50 | To use the Telegram API, you need to obtain API credentials: 51 | 52 | 1. Visit [https://my.telegram.org/auth](https://my.telegram.org/auth) and log in with your Telegram account 53 | 2. Go to "API Development Tools" 54 | 3. Create a new application (if you haven't already) 55 | 4. Note your **API ID** and **API Hash** 56 | 57 | ### 5. Configuration 58 | 59 | 1. Create a copy of the example configuration file: 60 | 61 | ```bash 62 | cp config.example.ini config.ini 63 | ``` 64 | 65 | 2. Edit `config.ini` with your API credentials and other settings: 66 | 67 | ```ini 68 | [Telegram] 69 | api_id = YOUR_API_ID 70 | api_hash = YOUR_API_HASH 71 | phone = YOUR_PHONE_NUMBER # with country code, e.g., +12345678901 72 | 73 | [Storage] 74 | download_folder = downloads 75 | ``` 76 | 77 | ## Running the Application 78 | 79 | ### Running in Development Mode 80 | 81 | ```bash 82 | python main.py 83 | ``` 84 | 85 | ### Running Tests 86 | 87 | ```bash 88 | # Run all tests 89 | pytest 90 | 91 | # Run specific tests 92 | pytest tests/test_specific_feature.py 93 | 94 | # Run with coverage report 95 | pytest --cov=telegram_channel_saver 96 | ``` 97 | 98 | ## Development Tools 99 | 100 | ### Code Linting 101 | 102 | We use flake8 for linting: 103 | 104 | ```bash 105 | # Check code style 106 | flake8 telegram_channel_saver 107 | 108 | # Auto-format code (if using Black) 109 | black telegram_channel_saver 110 | ``` 111 | 112 | ### Type Checking 113 | 114 | We use mypy for type checking: 115 | 116 | ```bash 117 | mypy telegram_channel_saver 118 | ``` 119 | 120 | ## Project Structure 121 | 122 | Here's an overview of the key directories and files in the project: 123 | 124 | ``` 125 | telegram-channel-saver/ 126 | ├── telegram_channel_saver/ # Main package directory 127 | │ ├── __init__.py 128 | │ ├── main.py # Entry point 129 | │ ├── client.py # Telegram client implementation 130 | │ ├── downloader.py # Media downloading functionality 131 | │ └── utils/ # Utility functions 132 | ├── tests/ # Test files 133 | ├── docs/ # Documentation 134 | ├── requirements.txt # Production dependencies 135 | ├── requirements-dev.txt # Development dependencies 136 | └── config.example.ini # Example configuration file 137 | ``` 138 | 139 | ## Troubleshooting 140 | 141 | ### Common Issues 142 | 143 | #### Authentication Problems 144 | 145 | If you encounter authentication issues: 146 | - Verify your API credentials 147 | - Check your phone number format (include country code) 148 | - Ensure you have internet connectivity 149 | 150 | #### Import Errors 151 | 152 | If you see import errors: 153 | - Make sure you have activated the virtual environment 154 | - Verify all dependencies are installed correctly 155 | 156 | #### Rate Limiting 157 | 158 | If you encounter `FloodWaitError`: 159 | - Reduce the frequency of requests 160 | - Add delays between operations 161 | - Implement exponential backoff 162 | 163 | ### Getting Help 164 | 165 | If you encounter any issues that aren't covered here: 166 | 1. Check the [FAQ document](faq.md) 167 | 2. Search for similar issues in the GitHub repository 168 | 3. Open a new issue with a detailed description of the problem 169 | 170 | ## Additional Resources 171 | 172 | - [Telethon Documentation](https://docs.telethon.dev/en/stable/) - The Python Telegram client library used in this project 173 | - [Telegram API Documentation](https://core.telegram.org/api) - Official Telegram API documentation -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # Telegram Channel Saver 2 | 3 | ## Project Description 4 | Telegram Channel Saver is a Python tool for saving and analyzing Telegram channel content. The application connects to Telegram API using user credentials, allows browsing and selecting channels/groups, and provides functionality to download and store messages, track users, and search through saved content. 5 | 6 | ### Key Features 7 | - Save channel messages with reactions and media information 8 | - Track channel users and their activity 9 | - Search through saved messages by text, date, or ID 10 | - Support for multiple Telegram accounts 11 | - Message download with rate limiting and error handling 12 | - Detailed statistics about saved content 13 | 14 | ### File Structure 15 | ``` 16 | /telegram-channel-saver/ 17 | ├── LICENSE # MIT License 18 | ├── README.md # Project documentation 19 | ├── docs/ 20 | │ └── telethon.txt # Telethon library documentation 21 | ├── requirements.txt # Project dependencies 22 | ├── saver.py # Main application code 23 | ├── CLAUDE.md # Best practices and code guidelines 24 | ├── tools/ # Testing tools and utilities (Claude's workspace) 25 | │ ├── venv/ # Separate virtual environment for tools 26 | │ └── *.py # Test scripts and utilities 27 | └── temp/ # Storage directory for data and sessions 28 | └── channel_saver/ # Application data storage location 29 | ``` 30 | 31 | # Claude AI Development Rules 32 | 33 | ## API Documentation 34 | - **Always use context7** to get the most recent API documentation before implementing features 35 | - Do not rely on training data for library APIs - fetch current docs via context7 36 | - When working with Telethon, Telegram API, or any external library, query context7 first 37 | 38 | ## Tools Directory 39 | - Claude can create test tools and utilities in the `tools/` directory 40 | - Use the separate venv located at `tools/venv/` for running test scripts 41 | - Activate with: `source tools/venv/bin/activate` 42 | - Install dependencies in tools venv: `tools/venv/bin/pip install ` 43 | - Run tools with: `tools/venv/bin/python tools/