Metadata-Version: 2.4
Name: codex-tgmember
Version: 1.0.0
Summary: A CLI tool to scrape and add members in Telegram groups using the Telethon library.
Author: K.NIRMAL
License: MIT
Project-URL: Homepage, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember
Project-URL: Bug Tracker, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember/issues
Keywords: telegram,scraper,members,telethon,group
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon>=1.34.0
Dynamic: license-file

# codex-tgmember 🔭

> **⚠️ For educational purposes only. Use responsibly and in compliance with [Telegram's Terms of Service](https://telegram.org/tos).**

A Python package to **scrape members** from Telegram groups and **add them** to your own group — powered by [Telethon](https://docs.telethon.dev/).

---

## ✨ Features

| Feature | Description |
|---|---|
| 📋 **Scrape Members** | Export all visible group members to a CSV file |
| ➕ **Add Members** | Bulk-add users from CSV by username or Telegram ID |
| 📂 **CSV Viewer** | Display any member CSV file in the terminal |
| 🔐 **2FA Support** | Handles two-step verification automatically |
| 🛡️ **Safe Fallback** | Falls back gracefully when admin rights are missing |

---

## 📦 Installation

### From PyPI *(after publishing)*
```bash
pip install codex-tgmember
```

### From source (local)
```bash
cd pack/
pip install .
```

---

## 🔑 Prerequisites

1. **Python 3.7+**
2. A **Telegram account** with a phone number
3. **API credentials** from [my.telegram.org](https://my.telegram.org):
   - Go to **API development tools**
   - Create an app → copy `api_id` and `api_hash`

---

## ⚙️ Configuration

### Option A — Use as a Python library

```python
from tg_member_tool import TelegramMemberTool

tool = TelegramMemberTool(
    api_id=12345678,           # your API ID
    api_hash='your_api_hash',  # your API Hash
    phone='+94707728716'       # your phone with country code
)

# Start interactive menu
tool.run()
```

### Option B — Edit `cli.py` and use the command line

Open `pack/tg_member_tool/cli.py` and fill in your credentials:

```python
API_ID   = 12345678
API_HASH = 'your_api_hash_here'
PHONE    = '+94707728716'
```

Then run:

```bash
tg-member-tool
```

---

## 🚀 Usage

### Interactive Menu

```
╔══════════════════════════════╗
║     Telegram Member Tool     ║
╚══════════════════════════════╝

  1. Scrape group members → CSV
  2. Add members from CSV
  3. Display CSV file

  Select option:
```

---

### 1️⃣ Scrape Members → CSV

```python
tool.scrape_members()
# or pass index directly (no prompt):
tool.scrape_members(group_index=5)
```

Output file: `members-groupname.csv`

```
username,user_id,access_hash,name,group,group_id
john_doe,123456789,9876543210987654321,John Doe,My Group,1001234567
```

---

### 2️⃣ Add Members from CSV

```python
tool.add_members('members-my-group.csv')
# or specify group and method directly:
tool.add_members('members.csv', group_index=2, method=1)
```

**CSV format required:**
```csv
username,user_id,access_hash
john_doe,123456789,9876543210987654321
jane_doe,987654321,1234567890123456789
```

**Add methods:**
- `1` — by **username** (more reliable, requires user to have a username)
- `2` — by **Telegram ID** (works even without a username)

---

### 3️⃣ Display CSV File

```python
tool.display_csv('members-my-group.csv')
```

---

## 📁 Package Structure

```
pack/
├── pyproject.toml              ← Package config & metadata
├── LICENSE
├── README.md
└── tg_member_tool/
    ├── __init__.py             ← Package entry, exports TelegramMemberTool
    ├── core.py                 ← Main TelegramMemberTool class
    └── cli.py                  ← `tg-member-tool` command entry point
```

---

## ⚠️ Common Errors & Fixes

| Error | Cause | Fix |
|---|---|---|
| `SessionPasswordNeededError` | 2FA is enabled | Enter your 2FA password when prompted |
| `ChatAdminRequiredError` | Not admin of the group | Choose a group where you are admin |
| `PeerFloodError` | Too many requests | Wait several hours before trying again |
| `UserPrivacyRestrictedError` | User has privacy on | User is skipped automatically |
| `AuthRestartError` | Telegram internal issue | Re-run the script |

---

## 🔐 Security Notes

- 🔑 **Never share** your `api_id`, `api_hash`, or `.session` file
- ❌ **Never commit** credentials to GitHub — add them to `.gitignore`
- ⏳ Respect Telegram's rate limits: [limits.tginfo.me](https://limits.tginfo.me/en)
- 👥 Only add users who have **consented** to join groups

---

## 📜 Disclaimer

This tool is provided **for educational purposes only**. The author is not responsible for:
- Account bans due to aggressive API use
- Privacy violations or spam complaints  
- Any misuse of this software

Always comply with [Telegram's Terms of Service](https://telegram.org/tos).

---

## 📄 License

MIT © K.NIRMAL
