Metadata-Version: 2.4
Name: teli-lib
Version: 0.1.0
Summary: Telegram bot toolkit: named connections, long-polling, send/receive, and a wavi-compatible driver
Project-URL: Homepage, https://github.com/josetabuyo/teli
Project-URL: Source, https://github.com/josetabuyo/teli
Project-URL: Issues, https://github.com/josetabuyo/teli/issues
Author-email: José Tabuyo <josetabuyo@gmail.com>
License: MIT
License-File: LICENSE
Keywords: automation,bot,cli,driver,long-polling,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: python-dotenv>=1.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: user
Requires-Dist: telethon>=1.36; extra == 'user'
Description-Content-Type: text/markdown

# teli — Telegram bot toolkit

**teli** is a Python library and CLI for managing Telegram bots: named connections, async long-polling, message handlers, and a wavi-compatible driver interface for drop-in use alongside WhatsApp automation.

## Install

```bash
pip install teli
# with user-client support (Telethon):
pip install "teli[user]"
```

## Quick start — CLI

```bash
# Register a bot
teli add mybot --token 123456:ABC...

# Discover your chat_id (send /start to the bot, look at output)
teli listen mybot

# Lock down allowed chats
teli update mybot --allow 987654321

# Send a message
teli send mybot 987654321 "Hello from teli!"
```

## Quick start — Python

```python
from teli.bot import Bot

async with Bot.from_connection("mybot") as bot:
    await bot.send_message(987654321, "Hello!")
```

Long-polling daemon with handlers:

```python
bot = Bot.from_connection("mybot")

@bot.on_command("start")
async def handle_start(msg):
    await bot.send_message(msg["chat"]["id"], "Hi! I'm running on teli.")

await bot.start()
# ... keep alive ...
await bot.stop()
```

## Driver interface (wavi-compatible)

`teli.driver` exposes the same 7-function interface as `wavi_driver`, so Pulpo and other orchestrators can treat Telegram and WhatsApp interchangeably:

```python
import teli.driver as td

await td.connect("mybot")                          # start bot
await td.send("mybot", "987654321", "Hola!")       # contact = chat_id
print(await td.status("mybot"))                    # {"daemon_running": True, ...}
print(td.list_session_names())                     # ["mybot"]
await td.stop("mybot")
```

| Function | Returns | Notes |
|---|---|---|
| `connect(session, new)` | `{"ok": bool, "qr_page": None, ...}` | `new` is a no-op (no QR for bots) |
| `check_updates(session)` | `{"status": "ok", "new_inbound": []}` | no-op — Telegram is push |
| `send(session, contact, text)` | `{"ok": bool, ...}` | `contact` = chat_id |
| `status(session)` | `{"daemon_running": bool, "authenticated": bool, ...}` | |
| `list_session_names()` | `list[str]` | sync |
| `stop(session)` | `{"ok": bool, ...}` | |
| `daemon_running_by_pid(session)` | `bool` | sync |

## Named connections

Connections are stored in `data/connections.json` (or `$TELI_DATA_DIR/connections.json`):

```json
{
  "connections": [
    {
      "name": "mybot",
      "token": "123456:ABC...",
      "allowed_chats": ["987654321"]
    }
  ]
}
```

## User client (Telethon)

The optional `[user]` extra enables a user-account listener (receive messages sent to your bot from your own Telegram account):

```bash
teli user setup mybot --api-id 12345 --api-hash abc123 --bot-username mybotname
teli user connect mybot
teli user listen mybot
```

## License

MIT — see [LICENSE](LICENSE).
