# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Project Does

**Tele2Bale** — transfers files from a Telegram bot to Bale messenger's Saved Messages via a Userbot. Supports files up to 2GB by bypassing Bale's 50MB bot limit through Userbot authentication. Features a file-based queue system, real-time progress updates, Safe Mode (AES-encrypted ZIP before upload), and direct URL downloading.

## Running the Project

**Install dependencies:**
```bash
pip install -r requirements.txt
```

**First-time Bale login** (interactive — required once to create `session.bale`):
```bash
python3 bale.py
```

**Run the application:**
```bash
python3 main.py
```

## Architecture

`main.py` spawns `telebot.py` and `bale.py` as separate subprocesses and waits for both. The two components communicate exclusively via files in `queue/`.

### telebot.py (Telegram Bot — Pyrogram)
- Receives files/URLs from users via Telegram bot
- Downloads Telegram media immediately to `downloads/` using `pyrogram`
- Writes tasks to `queue/tasks.jsonl` (JSONL, append-only)
- Watches `queue/status.jsonl` via `status_watcher()` coroutine and edits Telegram messages to reflect upload progress
- Handles `/del`, `/delall`, `/safemode` commands; cancellations written to `queue/cancelled.jsonl`

### bale.py (Bale Userbot Worker — aiobale)
- Pops tasks from `queue/tasks.jsonl` one at a time (`pop_first_task()` reads and rewrites the file)
- For `direct_url` tasks: downloads via `requests` streaming to `downloads/url/`
- For `local_file` tasks: uses the already-downloaded path
- If Safe Mode: wraps file in AES-encrypted ZIP via `pyzipper`, then deletes the original
- Uploads to Bale via `aiobale.Client.send_document()` with retry logic (up to 5 attempts, 30-minute timeout)
- Writes progress/status updates to `queue/status.jsonl` which `telebot.py` picks up

### Queue File Protocol
| File | Purpose |
|------|---------|
| `queue/tasks.jsonl` | Pending tasks; `telebot.py` appends, `bale.py` pops from front |
| `queue/status.jsonl` | Append-only status updates from `bale.py`; consumed by `telebot.py` |
| `queue/processing.json` | Single-task file; current in-flight task |
| `queue/deleted.jsonl` | Deleted task records for dedup |
| `queue/cancelled.jsonl` | Cancellation signals keyed by `job_id` |
| `queue/failed.jsonl` | Failed tasks with error messages |

## Configuration (.env)

```env
API_ID=          # Telegram API ID (from my.telegram.org)
API_HASH=        # Telegram API Hash
BOT_TOKEN=       # Telegram bot token
BALE_TARGET_ID=  # Bale UID to send files to (Saved Messages ID)
```

The `BALE_PHONE` in `.env` is used during the interactive first-run session setup for `aiobale`.

## Key Constraints

- **Userbot required**: Bale bot API limits files to 50MB; the Userbot (`session.bale`) bypasses this.
- **Sequential processing**: `bale.py` processes one task at a time to avoid Bale rate limiting/crashes.
- `UPLOAD_TIMEOUT` is 1800s (30 min) — tune based on server speed and file sizes.
- All user-facing messages in the bot are in Persian (Farsi).