Metadata-Version: 2.4
Name: andro-cfw
Version: 0.1.0
Summary: Run Telegram bots from filtered/restricted regions via your own Cloudflare Worker proxy (no VPN required).
Author: andro-cfw contributors
License: MIT
Keywords: telegram,telegram-bot,cloudflare,cloudflare-workers,proxy,iran,filter-bypass
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0
Provides-Extra: telebot
Requires-Dist: pyTelegramBotAPI>=4.14; extra == "telebot"
Provides-Extra: ptb
Requires-Dist: python-telegram-bot>=20.0; extra == "ptb"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# andro-cfw

Run your Telegram bot from countries where Telegram is network-filtered
(e.g. Iran) **without a VPN on the server**, by routing Bot API traffic
through a Cloudflare Worker reverse proxy that **you** own and deploy to
**your own** Cloudflare account.

Cloudflare's edge network is reachable from these regions even when
`api.telegram.org` is not, so the worker acts as a transparent relay:
`your bot -> your Cloudflare Worker -> api.telegram.org`.

## How it works

1. `andro-cfw init` opens your browser and runs Cloudflare's official
   `wrangler login` OAuth flow. You never share a password with this
   library — Cloudflare authenticates you directly.
2. Once authorized, andro-cfw generates a small TypeScript Worker
   (a transparent proxy to `api.telegram.org`) and deploys it to your
   account with `wrangler deploy`.
3. The resulting worker URL is saved, **encrypted**, in a `cfw.session`
   file in your project directory (encryption key stored in
   `~/.andro_cfw/key`, outside your repo).
4. In your bot code, load the session and point your Telegram library
   (telebot, python-telegram-bot, aiogram, ...) at the worker URL instead
   of `api.telegram.org`. Everything else about your bot stays the same.

This works identically on your laptop and on a server — the only
requirement is Node.js (for `wrangler`) at `init` time. Once deployed,
your bot's Python runtime needs no Node.js and no VPN at all.

## Installation

```bash
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install andro-cfw
```

Requires [Node.js](https://nodejs.org) (for the one-time `andro-cfw init`
step only — it shells out to Cloudflare's official `wrangler` CLI via `npx`).

## Quick start

```bash
cd your-bot-project/
andro-cfw init
```

This will:
- open your browser for Cloudflare login,
- deploy a worker named `andro-cfw-xxxxxxxx` (or `--name <custom-name>`),
- create `cfw.session` in the current directory.

### Using it with `pyTelegramBotAPI` (telebot)

```python
import telebot
from andro_cfw import CFWSession

session = CFWSession.load()
telebot.apihelper.API_URL = session.telebot_api_url()
telebot.apihelper.FILE_URL = session.telebot_file_url()

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "Hello from behind the filter! 🎉")

bot.infinity_polling()
```

### Using it with `python-telegram-bot` (v20+)

```python
from telegram.ext import ApplicationBuilder, CommandHandler
from andro_cfw import CFWSession

session = CFWSession.load()

app = (
    ApplicationBuilder()
    .token("YOUR_BOT_TOKEN")
    .base_url(session.ptb_base_url())
    .base_file_url(session.ptb_base_file_url())
    .build()
)

async def start(update, context):
    await update.message.reply_text("Hello from behind the filter! 🎉")

app.add_handler(CommandHandler("start", start))
app.run_polling()
```

### Using it with `aiogram` (v3+)

```python
from aiogram import Bot
from aiogram.client.telegram import TelegramAPIServer
from aiogram.client.session.aiohttp import AiohttpSession
from andro_cfw import CFWSession

session = CFWSession.load()
api_server = TelegramAPIServer(**session.aiogram_server_url())

bot = Bot(
    token="YOUR_BOT_TOKEN",
    session=AiohttpSession(api=api_server),
)
```

## CLI reference

| Command                     | Description                                             |
|------------------------------|----------------------------------------------------------|
| `andro-cfw init`             | Log into Cloudflare and deploy the proxy worker.          |
| `andro-cfw init --name foo`  | Deploy with a custom worker name.                         |
| `andro-cfw init --force`     | Redeploy and overwrite an existing `cfw.session`.         |
| `andro-cfw status`           | Show the worker name/URL saved for this project.          |
| `andro-cfw remove`           | Delete the deployed worker and local `cfw.session`.       |

## Security notes

- `cfw.session` is encrypted with Fernet (AES128-CBC + HMAC). The key is
  stored in `~/.andro_cfw/key`, **not** inside the project, so committing
  `cfw.session` to git by accident does not by itself expose your worker
  URL to someone without the key. Still, **add `cfw.session` to
  `.gitignore`** — treat it like any other credential file.
- The generated worker is a pure pass-through proxy: it does not log,
  store, or inspect bot tokens, updates, or file contents.
- andro-cfw never asks for or stores your Cloudflare password — all
  authentication is delegated to Cloudflare's own `wrangler login` OAuth
  flow.
- You are deploying to **your own** Cloudflare account (free tier is
  sufficient for most bots), so you retain full control and can delete
  the worker at any time with `andro-cfw remove`.

## Requirements

- Python 3.9+
- Node.js (only for `andro-cfw init` / `andro-cfw remove`)
- A free [Cloudflare](https://dash.cloudflare.com/sign-up) account

## License

MIT
