teli-lib 0.1.0__py3-none-any.whl

teli/__init__.py

@@ -0,0 +1,6 @@
+"""teli — Telegram bot toolkit."""
+
+from teli.bot import Bot
+
+__all__ = ["Bot"]
+__version__ = "0.1.0"

teli/bot.py

@@ -0,0 +1,219 @@
+"""Async Telegram bot — long-polling, send, handlers."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Awaitable, Callable
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_TG = "https://api.telegram.org/bot{token}/{method}"
+
+# msg dict → None (async)
+Handler = Callable[[dict], Awaitable[None]]
+
+
+class Bot:
+    """
+    Telegram bot with long-polling and handler registration.
+
+    Two usage modes:
+
+    1. One-shot (CLI / scripts) — async context manager:
+         async with Bot.from_connection("name") as bot:
+             await bot.send_message(chat_id, "hola")
+
+    2. Background task (FastAPI lifespan):
+         bot = Bot.from_connection("name")
+         bot.on_command("enchufe")(my_handler)
+
+         # in lifespan:
+         await bot.start()
+         yield
+         await bot.stop()
+    """
+
+    def __init__(self, token: str, allowed_chats: list[str] | None = None):
+        self._token = token
+        self._allowed: set[str] = {str(c) for c in (allowed_chats or [])}
+        self._handlers: list[Handler] = []
+        self._client: httpx.AsyncClient | None = None
+        self._task: asyncio.Task | None = None
+
+    # ── HTTP helpers ──────────────────────────────────────────────────────────
+
+    def _url(self, method: str) -> str:
+        return _TG.format(token=self._token, method=method)
+
+    async def _call(self, method: str, **kwargs) -> dict:
+        assert self._client, "Bot not started — use 'async with bot' or 'await bot.start()'"
+        r = await self._client.post(self._url(method), json={k: v for k, v in kwargs.items() if v is not None})
+        r.raise_for_status()
+        data = r.json()
+        if not data.get("ok"):
+            raise RuntimeError(f"Telegram API error: {data.get('description', data)}")
+        return data.get("result")
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    async def get_me(self) -> dict:
+        """Return bot identity (username, id, etc.)."""
+        return await self._call("getMe")
+
+    async def send_message(self, chat_id: str | int, text: str, parse_mode: str = "HTML", **kwargs) -> dict:
+        return await self._call("sendMessage", chat_id=chat_id, text=text, parse_mode=parse_mode, **kwargs)
+
+    async def send_photo(self, chat_id: str | int, photo: bytes, caption: str | None = None) -> dict:
+        assert self._client
+        data: dict = {"chat_id": str(chat_id)}
+        if caption:
+            data["caption"] = caption
+        r = await self._client.post(
+            self._url("sendPhoto"),
+            data=data,
+            files={"photo": ("photo.jpg", photo, "image/jpeg")},
+            timeout=30,
+        )
+        r.raise_for_status()
+        return r.json().get("result", {})
+
+    async def send_document(self, chat_id: str | int, content: bytes, filename: str, caption: str | None = None) -> dict:
+        assert self._client
+        data: dict = {"chat_id": str(chat_id)}
+        if caption:
+            data["caption"] = caption
+        r = await self._client.post(
+            self._url("sendDocument"),
+            data=data,
+            files={"document": (filename, content, "application/octet-stream")},
+            timeout=30,
+        )
+        r.raise_for_status()
+        return r.json().get("result", {})
+
+    # ── Handler registration ──────────────────────────────────────────────────
+
+    def on_message(self, handler: Handler) -> Handler:
+        """Register a catch-all handler called for every allowed message."""
+        self._handlers.append(handler)
+        return handler
+
+    def on_command(self, command: str):
+        """Decorator: handle messages starting with /<command>."""
+        cmd_lower = command.lower().lstrip("/")
+
+        def decorator(fn: Handler) -> Handler:
+            async def wrapper(msg: dict) -> None:
+                text = msg.get("text", "").strip()
+                if not text.startswith("/"):
+                    return
+                first = text.split()[0].lstrip("/").split("@")[0].lower()
+                if first == cmd_lower:
+                    await fn(msg)
+
+            self._handlers.append(wrapper)
+            return fn
+
+        return decorator
+
+    def on_text(self, pattern: str | None = None, flags: int = re.IGNORECASE):
+        """Decorator: handle text messages matching an optional regex pattern."""
+        rx = re.compile(pattern, flags) if pattern else None
+
+        def decorator(fn: Handler) -> Handler:
+            async def wrapper(msg: dict) -> None:
+                text = msg.get("text", "")
+                if rx is None or rx.search(text):
+                    await fn(msg)
+
+            self._handlers.append(wrapper)
+            return fn
+
+        return decorator
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    async def start(self) -> None:
+        """Open HTTP client and start background polling task."""
+        self._client = httpx.AsyncClient(timeout=35)
+        self._task = asyncio.create_task(self._poll_loop(), name=f"teli-poll")
+        logger.info("teli: polling started")
+
+    async def stop(self) -> None:
+        """Cancel polling task and close HTTP client."""
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+        logger.info("teli: polling stopped")
+
+    # Async context manager (one-shot use)
+    async def __aenter__(self) -> "Bot":
+        self._client = httpx.AsyncClient(timeout=35)
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    async def _poll_loop(self) -> None:
+        offset = 0
+        while True:
+            try:
+                updates = await self._call("getUpdates", offset=offset, timeout=30, limit=10)
+                for update in updates or []:
+                    offset = update["update_id"] + 1
+                    msg = update.get("message") or update.get("edited_message")
+                    if msg:
+                        await self._dispatch(msg)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.warning("teli poll error: %s", e)
+                await asyncio.sleep(5)
+
+    async def _dispatch(self, msg: dict) -> None:
+        # Telegram Mini Apps send commands via sendData(); normalise to text so handlers work unchanged.
+        if "web_app_data" in msg and "text" not in msg:
+            msg["text"] = msg["web_app_data"].get("data", "")
+        chat_id = str(msg.get("chat", {}).get("id", ""))
+        if self._allowed and chat_id not in self._allowed:
+            logger.debug("teli: ignored message from chat %s (not in allowed list)", chat_id)
+            return
+        for handler in self._handlers:
+            try:
+                await handler(msg)
+            except Exception as e:
+                logger.error("teli handler error: %s", e)
+
+    # ── Constructors ──────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_connection(cls, name: str, data_dir=None) -> "Bot":
+        """Load a named connection from data/connections.json."""
+        from teli.connection import load_connection
+
+        conn = load_connection(name, data_dir)
+        return cls(token=conn["token"], allowed_chats=conn.get("allowed_chats", []))
+
+    @classmethod
+    def from_env(cls) -> "Bot":
+        """Load from TELEGRAM_BOT_TOKEN + TELEGRAM_ALLOWED_CHATS env vars."""
+        import os
+
+        token = os.environ["TELEGRAM_BOT_TOKEN"]
+        raw = os.getenv("TELEGRAM_ALLOWED_CHATS", "")
+        chats = [c.strip() for c in raw.split(",") if c.strip()]
+        return cls(token=token, allowed_chats=chats)

teli/cli.py

@@ -0,0 +1,350 @@
+"""teli — Telegram bot CLI.
+
+Commands:
+  teli add <name> --token TOKEN [--allow CHAT_ID...]   Register a named connection
+  teli update <name> [--allow CHAT_ID...]              Update allowed chat IDs
+  teli list                                             List all connections
+  teli remove <name>                                    Remove a connection
+  teli whoami <name>                                    Get bot identity (getMe)
+  teli send <name> <chat_id> <message>                 Send a text message
+  teli listen <name> [--webhook URL]                   Run long-polling daemon
+"""
+from __future__ import annotations
+
+import asyncio
+import importlib
+import json
+import logging
+import sys
+
+import click
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@click.group()
+def main():
+    """teli — Telegram bot management."""
+
+
+# ── add ───────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+@click.option("--token", required=True, help="Bot token from @BotFather (123456:ABC...)")
+@click.option("--allow", multiple=True, metavar="CHAT_ID", help="Allowed chat IDs (repeat for multiple). Leave empty to allow all.")
+def add(name: str, token: str, allow: tuple[str, ...]) -> None:
+    """Register a named bot connection.
+
+    Run 'teli listen <name>' then send /start to the bot to discover
+    your chat_id, then run 'teli update <name> --allow <chat_id>'.
+    """
+    from teli.connection import save_connection
+
+    conn = {"name": name, "token": token, "allowed_chats": list(allow)}
+    save_connection(conn)
+    chats_str = ", ".join(allow) if allow else "all (unrestricted — add --allow to lock it down)"
+    click.echo(f"Connection '{name}' saved.")
+    click.echo(f"  allowed_chats: {chats_str}")
+    if not allow:
+        click.echo("\nTip: run 'teli listen <name>', send /start to the bot,")
+        click.echo("     then 'teli update <name> --allow <your_chat_id>'.")
+
+
+# ── update ────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+@click.option("--allow", multiple=True, metavar="CHAT_ID", help="Replace allowed chat IDs (empty = allow all).")
+@click.option("--token", default=None, help="Update bot token.")
+def update(name: str, allow: tuple[str, ...], token: str | None) -> None:
+    """Update a connection's token or allowed chat IDs."""
+    from teli.connection import load_connection, save_connection
+
+    conn = load_connection(name)
+    if token:
+        conn["token"] = token
+    if allow or token:
+        if allow:
+            conn["allowed_chats"] = list(allow)
+        save_connection(conn)
+        chats_str = ", ".join(conn["allowed_chats"]) or "all (unrestricted)"
+        click.echo(f"Connection '{name}' updated.")
+        click.echo(f"  allowed_chats: {chats_str}")
+    else:
+        click.echo(f"Nothing to update. Pass --allow or --token.")
+
+
+# ── list ──────────────────────────────────────────────────────────────────────
+
+@main.command("list")
+def list_connections() -> None:
+    """List all registered connections."""
+    from teli.connection import load_connections
+
+    conns = load_connections()
+    if not conns:
+        click.echo("No connections. Use 'teli add <name> --token <TOKEN>'.")
+        return
+    for c in conns:
+        chats = ", ".join(c.get("allowed_chats", [])) or "all (unrestricted)"
+        token_hint = c["token"][:12] + "..."
+        click.echo(f"  {c['name']:<20s}  token={token_hint}  chats={chats}")
+
+
+# ── remove ────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+def remove(name: str) -> None:
+    """Remove a named connection."""
+    from teli.connection import delete_connection
+
+    try:
+        delete_connection(name)
+        click.echo(f"Connection '{name}' removed.")
+    except KeyError as e:
+        click.echo(str(e), err=True)
+        sys.exit(1)
+
+
+# ── whoami ────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+def whoami(name: str) -> None:
+    """Get bot identity (getMe) for a named connection."""
+    from teli.bot import Bot
+
+    async def _go() -> None:
+        async with Bot.from_connection(name) as bot:
+            info = await bot.get_me()
+        click.echo(json.dumps(info, indent=2, ensure_ascii=False))
+
+    asyncio.run(_go())
+
+
+# ── send ──────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+@click.argument("chat_id")
+@click.argument("message")
+def send(name: str, chat_id: str, message: str) -> None:
+    """Send a text message via a named connection.
+
+    \b
+    Example:
+      teli send smarthome 123456789 "Hola desde la Mac"
+    """
+    from teli.bot import Bot
+
+    async def _go() -> None:
+        async with Bot.from_connection(name) as bot:
+            result = await bot.send_message(chat_id, message)
+        click.echo(f"Sent. message_id={result.get('message_id')} chat_id={chat_id}")
+
+    asyncio.run(_go())
+
+
+# ── listen ────────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("name")
+@click.option("--webhook", default=None, metavar="URL",
+              help="Forward incoming messages as JSON POST to this URL.")
+@click.option("--verbose", "-v", is_flag=True, help="Show raw update JSON.")
+def listen(name: str, webhook: str | None, verbose: bool) -> None:
+    """Run a long-polling daemon for a named connection (Ctrl+C to stop).
+
+    Without --webhook, prints incoming messages to stdout.
+    With --webhook, POSTs each message dict to the given URL.
+
+    \b
+    Example:
+      teli listen smarthome
+      teli listen smarthome --webhook http://localhost:9000/api/telegram
+    """
+    import urllib.error as _urlerr
+    import urllib.request as _urlreq
+
+    from teli.bot import Bot
+
+    logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(name)s %(message)s")
+
+    bot = Bot.from_connection(name)
+
+    if webhook:
+        @bot.on_message
+        async def _forward(msg: dict) -> None:
+            payload = json.dumps({"message": msg}, ensure_ascii=False).encode()
+            try:
+                _urlreq.urlopen(
+                    _urlreq.Request(
+                        webhook,
+                        data=payload,
+                        headers={"Content-Type": "application/json"},
+                    ),
+                    timeout=5,
+                )
+            except _urlerr.URLError as e:
+                click.echo(f"[webhook error] {e}", err=True)
+
+        click.echo(f"Listening on '{name}' → forwarding to {webhook}")
+    else:
+        @bot.on_message
+        async def _print(msg: dict) -> None:
+            chat = msg.get("chat", {})
+            sender = msg.get("from", {})
+            chat_id = chat.get("id", "?")
+            chat_type = chat.get("type", "?")
+            name_parts = [sender.get("first_name", ""), sender.get("last_name", "")]
+            sender_name = " ".join(p for p in name_parts if p) or sender.get("username", "?")
+            media = next((k for k in ("photo", "document", "voice", "sticker") if k in msg), "non-text")
+            text = msg.get("text") or f"[{media}]"
+            click.echo(f"[{chat_id}/{chat_type}] {sender_name}: {text}")
+            if verbose:
+                click.echo(json.dumps(msg, indent=2, ensure_ascii=False))
+
+        click.echo(f"Listening on '{name}'... (Ctrl+C to stop)")
+        click.echo("Tip: send /start to discover your chat_id.")
+
+    async def _run() -> None:
+        await bot.start()
+        try:
+            while True:
+                await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await bot.stop()
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+    click.echo("\nStopped.")
+
+
+def _require_user_listener():
+    try:
+        from teli.user import UserListener
+        return UserListener
+    except ImportError:
+        click.echo("Falta telethon. Instalá con: pip install 'teli[user]'", err=True)
+        raise SystemExit(1)
+
+
+# ── user group ────────────────────────────────────────────────────────────────
+
+@main.group("user")
+def user_group():
+    """Comandos de cliente de usuario Telegram (Telethon)."""
+
+
+@user_group.command("setup")
+@click.argument("name")
+@click.option("--api-id",       required=True, help="API ID de my.telegram.org")
+@click.option("--api-hash",     required=True, help="API hash de my.telegram.org")
+@click.option("--bot-username", required=True, help="Username del bot (sin @)")
+def user_setup(name: str, api_id: str, api_hash: str, bot_username: str) -> None:
+    """Agrega api_id / api_hash a una conexión existente para el cliente de usuario.
+
+    \b
+    Pasos previos:
+      1. Ir a https://my.telegram.org → 'API development tools'
+      2. Crear una app (nombre cualquiera) → copiar App api_id y api_hash
+      3. Ejecutar este comando
+
+    \b
+    Ejemplo:
+      teli user setup punto_a_punto_bot --api-id 12345678 --api-hash abc123... --bot-username punto_a_punto_bot
+    """
+    from teli.connection import load_connection, save_connection
+
+    try:
+        conn = load_connection(name)
+    except KeyError:
+        click.echo(f"Conexión '{name}' no encontrada. Creala primero con 'teli add'.", err=True)
+        raise SystemExit(1)
+
+    conn["api_id"]       = int(api_id)
+    conn["api_hash"]     = api_hash
+    conn["bot_username"] = bot_username.lstrip("@")
+    save_connection(conn)
+    click.echo(f"Conexión '{name}' actualizada con credenciales de usuario.")
+    click.echo(f"Ahora ejecutá: teli user connect {name}")
+
+
+@user_group.command("connect")
+@click.argument("name")
+def user_connect(name: str) -> None:
+    """Autentica tu cuenta de Telegram (una vez). Guarda la sesión localmente.
+
+    Telegram va a pedir tu número de teléfono y el código que te manda.
+    La sesión queda guardada en data/sessions/ — no necesitás repetir esto.
+    """
+    UserListener = _require_user_listener()
+    ul = UserListener.from_connection(name)
+    display = asyncio.run(ul.authenticate())
+    click.echo(f"Autenticado como: {display}")
+
+
+@user_group.command("send")
+@click.argument("name")
+@click.argument("recipient")
+@click.argument("message")
+def user_send(name: str, recipient: str, message: str) -> None:
+    """Manda un mensaje desde tu cuenta a cualquier contacto o username.
+
+    \b
+    Ejemplo:
+      teli user send punto_a_punto_bot Luganense "Hola, ¿hay algún monumento?"
+      teli user send punto_a_punto_bot @username "Hola!"
+    """
+    UserListener = _require_user_listener()
+    ul = UserListener.from_connection(name)
+    asyncio.run(ul.send(recipient, message))
+    click.echo(f"Mensaje enviado a '{recipient}'.")
+
+
+@user_group.command("listen")
+@click.argument("name")
+@click.option("--handler", default=None, metavar="MODULE:FUNC",
+              help="Handler externo a cargar (ej: smart_home.user_handler:handle).")
+def user_listen(name: str, handler: str | None) -> None:
+    """Corre el daemon de usuario: escucha mensajes del bot y ejecuta comandos.
+
+    \b
+    Ejemplo sin handler (solo imprime mensajes recibidos):
+      teli user listen punto_a_punto_bot
+
+    \b
+    Ejemplo con handler del Smart Home:
+      teli user listen punto_a_punto_bot --handler smart_home.user_handler:handle
+    """
+    UserListener = _require_user_listener()
+    ul = UserListener.from_connection(name)
+
+    if handler:
+        module_path, func_name = handler.rsplit(":", 1)
+        if "" not in sys.path:
+            sys.path.insert(0, "")
+        mod = importlib.import_module(module_path)
+        fn  = getattr(mod, func_name)
+        ul.on_bot_message(fn)
+        click.echo(f"Handler cargado: {handler}")
+    else:
+        @ul.on_bot_message
+        async def _print(event) -> None:
+            click.echo(f"[bot→vos] {event.text!r}")
+
+    click.echo(f"Escuchando mensajes del bot '{name}'... (Ctrl+C para detener)")
+    logging.basicConfig(level=logging.WARNING)
+
+    try:
+        asyncio.run(ul.run())
+    except KeyboardInterrupt:
+        pass
+    click.echo("\nStopped.")

teli/connection.py

@@ -0,0 +1,59 @@
+"""Named connection management — reads/writes data/connections.json."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+_DEFAULT_DATA_DIR = Path(__file__).parent.parent / "data"
+
+
+def _data_dir(override: str | Path | None = None) -> Path:
+    if override:
+        return Path(override)
+    env = os.getenv("TELI_DATA_DIR")
+    if env:
+        return Path(env)
+    return _DEFAULT_DATA_DIR
+
+
+def _file(data_dir=None) -> Path:
+    return _data_dir(data_dir) / "connections.json"
+
+
+def load_connections(data_dir=None) -> list[dict]:
+    f = _file(data_dir)
+    if not f.exists():
+        return []
+    return json.loads(f.read_text(encoding="utf-8")).get("connections", [])
+
+
+def load_connection(name: str, data_dir=None) -> dict:
+    for conn in load_connections(data_dir):
+        if conn["name"] == name:
+            return conn
+    raise KeyError(f"Connection '{name}' not found in {_file(data_dir)}")
+
+
+def save_connection(conn: dict, data_dir=None) -> None:
+    f = _file(data_dir)
+    f.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        data = json.loads(f.read_text(encoding="utf-8")) if f.exists() else {"connections": []}
+    except Exception:
+        data = {"connections": []}
+    data["connections"] = [c for c in data["connections"] if c["name"] != conn["name"]]
+    data["connections"].append(conn)
+    f.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def delete_connection(name: str, data_dir=None) -> None:
+    f = _file(data_dir)
+    if not f.exists():
+        raise KeyError(f"No connections file at {f}")
+    data = json.loads(f.read_text(encoding="utf-8"))
+    before = len(data["connections"])
+    data["connections"] = [c for c in data["connections"] if c["name"] != name]
+    if len(data["connections"]) == before:
+        raise KeyError(f"Connection '{name}' not found")
+    f.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")

teli/driver.py

@@ -0,0 +1,200 @@
+"""
+Wavi-compatible async driver interface for teli (Telegram bots).
+
+Exact same contract as wavi_driver.py — Pulpo can swap transports with no
+orchestration changes:
+
+    import teli.driver as td        # PyPI install
+    # or
+    import teli_driver as td        # local shim (re-exports this module)
+
+    await td.connect("my_bot")
+    await td.send("my_bot", "123456789", "Hola!")
+    print(await td.status("my_bot"))   # {"session": ..., "daemon_running": True, ...}
+    await td.stop("my_bot")
+
+Mapping to wavi concepts:
+  session              → teli connection name (data/connections.json)
+  contact              → Telegram chat_id
+  new (connect)        → ignored (bots are stateless, no QR flow)
+  qr_page (connect)   → always None (Telegram needs no QR scan)
+  check_updates        → no-op / returns empty list (long-polling is push)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _Session:
+    bot: object
+    loop: asyncio.AbstractEventLoop
+    thread: threading.Thread
+    _stop: threading.Event = field(default_factory=threading.Event)
+    ready: bool = False
+
+
+_sessions: dict[str, _Session] = {}
+_lock = threading.Lock()
+
+
+# ── Public interface ──────────────────────────────────────────────────────────
+
+
+async def connect(session: str, new: bool = False) -> dict:
+    """Start a bot for the named teli connection.
+
+    `new` is a no-op — Telegram bots have no QR flow.
+    Idempotent: calling on an already-running session returns ok immediately.
+
+    Returns: {"ok": bool, "stdout": str, "stderr": str, "qr_page": None}
+    """
+    from teli.bot import Bot
+
+    with _lock:
+        existing = _sessions.get(session)
+        if existing and existing.ready:
+            return {"ok": True, "stdout": "already running", "stderr": "", "qr_page": None}
+
+    try:
+        bot = Bot.from_connection(session)
+    except KeyError as e:
+        return {"ok": False, "stdout": "", "stderr": str(e), "qr_page": None}
+
+    loop = asyncio.new_event_loop()
+    entry = _Session(bot=bot, loop=loop, thread=None)  # type: ignore[arg-type]
+
+    def _run() -> None:
+        asyncio.set_event_loop(loop)
+        try:
+            loop.run_until_complete(_lifecycle(entry))
+        except Exception:
+            logger.exception("teli driver: session '%s' crashed", session)
+        finally:
+            entry.ready = False
+            if not loop.is_closed():
+                loop.close()
+
+    t = threading.Thread(target=_run, daemon=True, name=f"teli-{session}")
+    entry.thread = t
+
+    with _lock:
+        _sessions[session] = entry
+
+    t.start()
+
+    # Wait up to 10 s for the bot to become ready.
+    for _ in range(100):
+        if entry.ready:
+            return {"ok": True, "stdout": f"Bot '{session}' started", "stderr": "", "qr_page": None}
+        await asyncio.sleep(0.1)
+
+    return {"ok": False, "stdout": "", "stderr": f"Bot '{session}' did not become ready in time", "qr_page": None}
+
+
+async def check_updates(session: str, reset: bool = False) -> dict:
+    """No-op for Telegram (long-polling push delivers messages automatically).
+
+    Returns the wavi-compatible shape so Pulpo's poller can call this
+    without transport-specific branches.
+
+    Returns: {"status": "ok", "new_inbound": []}
+    """
+    return {"status": "ok", "new_inbound": []}
+
+
+async def send(session: str, contact: str, text: str) -> dict:
+    """Send `text` to `contact` (Telegram chat_id) via the named session.
+
+    Returns: {"ok": bool, "stdout": str, "stderr": str}
+    """
+    with _lock:
+        entry = _sessions.get(session)
+    if not entry or not entry.ready:
+        return {"ok": False, "stdout": "", "stderr": f"Session '{session}' not running — call connect() first."}
+    fut = asyncio.run_coroutine_threadsafe(
+        entry.bot.send_message(contact, text),
+        entry.loop,
+    )
+    try:
+        await asyncio.wrap_future(fut)
+        return {"ok": True, "stdout": "", "stderr": ""}
+    except Exception as e:
+        logger.warning("teli driver: send %s/%s error: %s", session, contact, e)
+        return {"ok": False, "stdout": "", "stderr": str(e)}
+
+
+async def status(session: str) -> dict:
+    """Return daemon and authentication status for the named session.
+
+    Returns: {"session": str, "daemon_running": bool, "authenticated": bool, "raw": str}
+    """
+    with _lock:
+        entry = _sessions.get(session)
+    running = entry is not None and entry.ready
+    return {
+        "session": session,
+        "daemon_running": running,
+        "authenticated": running,
+        "raw": "ready" if running else "stopped",
+    }
+
+
+def list_session_names() -> list[str]:
+    """Return connection names of all currently active bot sessions."""
+    with _lock:
+        return [name for name, e in _sessions.items() if e.ready]
+
+
+async def stop(session: str) -> dict:
+    """Gracefully stop and remove the named bot session.
+
+    Returns: {"ok": bool, "stdout": str}
+    """
+    with _lock:
+        entry = _sessions.pop(session, None)
+    if not entry:
+        return {"ok": True, "stdout": f"Session '{session}' was not running."}
+    entry._stop.set()
+    loop = asyncio.get_running_loop()
+    await loop.run_in_executor(None, lambda: entry.thread.join(timeout=15))
+    return {"ok": True, "stdout": f"Bot '{session}' stopped."}
+
+
+def daemon_running_by_pid(session: str) -> bool:
+    """Return True if the session's bot is active (equivalent to 'ready' state)."""
+    with _lock:
+        entry = _sessions.get(session)
+    return entry is not None and entry.ready
+
+
+def add_handler(session: str, handler) -> None:
+    """Register an additional async message handler on an already-running session.
+
+    The handler signature is the same as Bot.on_message: async (msg: dict) -> None.
+    Thread-safe — can be called from any thread after connect() resolves ok.
+    """
+    with _lock:
+        entry = _sessions.get(session)
+    if not entry or not entry.ready:
+        raise RuntimeError(f"Session '{session}' not running — call connect() first.")
+    entry.bot._handlers.append(handler)
+
+
+# ── Internal ──────────────────────────────────────────────────────────────────
+
+
+async def _lifecycle(entry: _Session) -> None:
+    """Runs inside the session's dedicated event loop thread."""
+    await entry.bot.start()
+    entry.ready = True
+    try:
+        while not entry._stop.is_set():
+            await asyncio.sleep(0.5)
+    finally:
+        await entry.bot.stop()

teli/user.py

@@ -0,0 +1,151 @@
+"""Telethon user client — escucha mensajes del bot en tu cuenta y responde al bot.
+
+Flujo:
+  HTML → bot.sendMessage(user_chat_id, cmd)
+  → Telegram entrega el msg a tu cuenta
+  → UserListener.on_bot_message handler corre
+  → handler ejecuta acción y llama user.reply(texto)
+  → user.reply manda el msg de tu cuenta al bot
+  → HTML.getUpdates() lo ve y actualiza la UI
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_SESSION_DIR = Path(__file__).parent.parent / "data" / "sessions"
+
+Handler = Callable[["UserEvent"], Awaitable[None]]
+
+
+class UserEvent:
+    """Wrapper de evento Telethon con helper reply()."""
+
+    def __init__(self, raw_event, client, bot_username: str):
+        self._ev = raw_event
+        self._client = client
+        self._bot = bot_username
+        self.text: str = raw_event.message.text or ""
+        self.chat_id: int = raw_event.chat_id
+
+    async def reply(self, text: str) -> None:
+        """Manda una respuesta de tu cuenta al bot (lo ve getUpdates de la HTML)."""
+        await self._client.send_message(self._bot, text)
+
+
+class UserListener:
+    """
+    Cliente Telethon que escucha mensajes del bot en tu cuenta de usuario.
+
+    Uso en otro proyecto:
+        from teli.user import UserListener
+
+        ul = UserListener.from_connection("punto_a_punto_bot")
+        ul.on_bot_message(my_handler)
+        asyncio.run(ul.run())
+    """
+
+    def __init__(self, api_id: int, api_hash: str, bot_username: str, session_path: str | Path):
+        self._api_id = api_id
+        self._api_hash = api_hash
+        self._bot = bot_username.lstrip("@")
+        self._session = str(session_path)
+        self._handlers: list[Handler] = []
+        self._client = None
+
+    # ── Handlers ──────────────────────────────────────────────────────────────
+
+    def on_bot_message(self, handler: Handler) -> Handler:
+        """Registra un handler para mensajes recibidos del bot."""
+        self._handlers.append(handler)
+        return handler
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    async def authenticate(self) -> str:
+        """Authenticate once (prompts for phone + code if no session), return display name."""
+        from telethon import TelegramClient
+
+        client = TelegramClient(self._session, self._api_id, self._api_hash)
+        await client.start()
+        me = await client.get_me()
+        await client.disconnect()
+        return f"{me.first_name} (@{me.username or me.id})"
+
+    async def run(self) -> None:
+        """Autentica (si es necesario) y empieza a escuchar. Corre indefinidamente."""
+        from telethon import TelegramClient, events
+
+        self._client = TelegramClient(self._session, self._api_id, self._api_hash)
+
+        await self._client.start()
+        me = await self._client.get_me()
+        logger.info("teli user: conectado como @%s", me.username or me.id)
+
+        @self._client.on(events.NewMessage(from_users=self._bot))
+        async def _dispatch(ev):
+            event = UserEvent(ev, self._client, self._bot)
+            for handler in self._handlers:
+                try:
+                    await handler(event)
+                except Exception as e:
+                    logger.error("teli user handler error: %s", e)
+
+        logger.info("teli user: escuchando mensajes de @%s", self._bot)
+        await self._client.run_until_disconnected()
+
+    async def send(self, recipient: str, text: str) -> None:
+        """Manda un mensaje desde tu cuenta a cualquier contacto o username."""
+        from telethon import TelegramClient
+
+        client = TelegramClient(self._session, self._api_id, self._api_hash)
+        await client.start()
+        await client.send_message(recipient, text)
+        await client.disconnect()
+
+    async def send_to_bot(self, text: str) -> None:
+        """Manda un mensaje de tu cuenta al bot (útil para testing)."""
+        assert self._client, "Llamá a run() primero"
+        await self._client.send_message(self._bot, text)
+
+    async def stop(self) -> None:
+        if self._client:
+            await self._client.disconnect()
+
+    # ── Constructors ──────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_connection(cls, connection_name: str, data_dir=None) -> "UserListener":
+        """
+        Carga un UserListener desde la configuración de una conexión nombrada.
+
+        La conexión necesita tener además de token: api_id, api_hash, bot_username.
+        Esos campos se agregan con: teli user setup <name>
+        """
+        from teli.connection import load_connection
+
+        conn = load_connection(connection_name, data_dir)
+        api_id   = conn.get("api_id")
+        api_hash = conn.get("api_hash")
+        bot_username = conn.get("bot_username") or connection_name
+
+        if not api_id or not api_hash:
+            raise RuntimeError(
+                f"La conexión '{connection_name}' no tiene api_id/api_hash. "
+                "Ejecutá: teli user setup <name>"
+            )
+
+        session_dir = Path(data_dir) / "sessions" if data_dir else _DEFAULT_SESSION_DIR
+        session_dir.mkdir(parents=True, exist_ok=True)
+        session_path = session_dir / connection_name
+
+        return cls(
+            api_id=int(api_id),
+            api_hash=api_hash,
+            bot_username=bot_username,
+            session_path=session_path,
+        )

teli_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+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).

teli_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+teli/__init__.py,sha256=knqHbBlL8L-7BS-trei3N0UxpNsVTi254ooCzcsBK30,104
+teli/bot.py,sha256=TLKJxDqHeTN1CVtCdkYLSSygTvY1VvDW7dsi_C9pyO0,8759
+teli/cli.py,sha256=0ViAeyNeDm-LcV1158E18AzoUJLiSoVjP2xNPZVZX_g,13245
+teli/connection.py,sha256=b89n4oFHdlQ8fEG_e05m0mN5LeQgxY4-mukP1V-Ovrk,1955
+teli/driver.py,sha256=CukEQF4WyEdwqVJ7x8kn2KZ8nHEY_Osml0FYTpvx_CM,6793
+teli/user.py,sha256=cfh7G74W1KqRPjPyQbWHlAqmiQ9FKoS3tDtpjxX6IqQ,5881
+teli_lib-0.1.0.dist-info/METADATA,sha256=7Qyn0uN1jqcvRNErX_L1aPW0vE9EG05A-pSupo7kOOU,4133
+teli_lib-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+teli_lib-0.1.0.dist-info/entry_points.txt,sha256=qsnVyZSTlluHFPTGDZGlU_OZ_y4LQeCXxGo3H09cL9M,39
+teli_lib-0.1.0.dist-info/licenses/LICENSE,sha256=A5dm6gP-Zs_ygdXYEazAJowsIsJoZOpfZ8iKyBbgwAk,1069
+teli_lib-0.1.0.dist-info/RECORD,,

teli_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

teli_lib-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+teli = teli.cli:main

teli_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Tabuyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.