Metadata-Version: 2.4
Name: teli-lib
Version: 0.2.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 and personal Telegram accounts: named connections, async long-polling, message handlers, and a wavi-compatible driver interface.

## Install

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

## Quick start — Bot connections

```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 via the bot
teli send mybot 987654321 "Hello from teli!"

# Check what's registered
teli status
```

## Quick start — Personal user account

Send messages from your own Telegram account (no bot token needed):

```bash
# 1. Get API credentials at https://my.telegram.org → API development tools
# 2. Register your account
teli user add me --api-id 12345678 --api-hash abc123...

# 3. Authenticate once (asks for phone + code)
teli user connect

# 4. Send messages directly
teli user send Luganense "Hola!"
teli user send @username "Hola!"
teli user send 987654321 "Hola!"
```

## All commands

```
teli status                                      Show all connections + user accounts
teli add <name> --token TOKEN                    Register a bot
teli list                                        List bot connections
teli remove <name>                               Remove a bot
teli send <name> <chat_id> <message>             Send via bot
teli listen <name> [--webhook URL]               Long-poll incoming messages
teli whoami <name>                               Get bot identity

teli user add <name> --api-id ID --api-hash H    Register personal account
teli user accounts                               List personal accounts
teli user connect [name]                         Authenticate (once)
teli user send <recipient> <message>             Send from your account
teli user listen --bot <bot_username>            Listen for bot messages

teli install-skill                               Install Claude Code skill
```

## Claude Code skill

Install a skill that teaches Claude how to use teli:

```bash
teli install-skill
```

This copies `SKILL.md` to `~/.claude/skills/teli/`. After restarting Claude Code, you can invoke it as `/teli`.

## Python API

```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!")

await bot.start()
await bot.stop()
```

## Driver interface (wavi-compatible)

```python
import teli.driver as td

await td.connect("mybot")
await td.send("mybot", "987654321", "Hola!")
print(await td.status("mybot"))
await td.stop("mybot")
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
```
