Metadata-Version: 2.4
Name: vibecodedbot
Version: 0.1.2
Summary: A entirely vibecoded dependency-free Telegram bot library
Author: vibebot contributors
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary

# vibebot

A dependency-free Python Telegram bot library with a route-based syntax.

## Install

```
pip install vibecodedbot
```

## Quick Start

```python
import os

from vibebot import VibeBot

bot = VibeBot(os.environ["TELEGRAM_BOT_TOKEN"])

bot.on_command("start").reply("Hello from vibebot.")
bot.on_text("ping", contains=True).reply("pong")
bot.on_media("photo").reply("Nice photo.")


@bot.on_message().act
def echo(event):
    return event.text


bot.start()
```

Run the included example:

## Routes

Routes return a `Route` object. Use `.reply(...)` for simple replies and `.act` when you need a function.

```python
bot.on_command("help").reply("Available commands: /start, /help")
bot.on_text("hello").reply("Hi")
bot.on_text("urgent", contains=True).reply("I saw urgent.")
bot.on_media().reply("Got media.")


@bot.on_media("document").act
def handle_document(event):
    return f"Document file id: {event.media.file_id}"
```

Available route helpers:

- `bot.on_command("start")`
- `bot.on_text("hello")`
- `bot.on_text("hello", contains=True)`
- `bot.on_media()`
- `bot.on_media("photo")`
- `bot.on_message()`
- `bot.on(...)` for generic routing

## TelegramEvent

Handlers receive a `TelegramEvent`.

```python
@bot.on_command("start").act
def start(event):
    event.reply(f"Chat id: {event.chat_id}")
```

Useful properties:

- `event.text`
- `event.caption`
- `event.command`
- `event.chat_id`
- `event.message`
- `event.update`
- `event.media`
- `event.media_kind`
- `event.photos`
- `event.photo`

Useful reply helpers:

- `event.reply("text")`
- `event.say("text")`
- `event.reply_photo(...)`
- `event.reply_video(...)`
- `event.reply_document(...)`
- `event.reply_audio(...)`
- `event.reply_voice(...)`
- `event.reply_animation(...)`
- `event.reply_sticker(...)`

Returning a string from an `.act` handler automatically sends it back to the chat.

## Sending Media

```python
bot.send_photo(chat_id, "photo.jpg", caption="Photo")
bot.send_video(chat_id, "video.mp4", caption="Video")
bot.send_document(chat_id, "report.pdf")
bot.send_audio(chat_id, "song.mp3")
bot.send_voice(chat_id, "voice.ogg")
bot.send_animation(chat_id, "animation.gif")
bot.send_sticker(chat_id, "sticker-file-id")
```

Media values can be Telegram `file_id`s, public URLs, local paths, `Path` objects, or open binary file objects.

Media groups are supported with Telegram media dictionaries:

```python
bot.send_media_group(
    chat_id,
    [
        {"type": "photo", "media": "photo-file-id-1"},
        {"type": "photo", "media": "photo-file-id-2"},
    ],
)
```

## Files

```python
file_info = bot.get_file("telegram-file-id")
download_url = bot.file_url("telegram-file-id")
```

## Low-Level API

`Bot` is available when you want raw Telegram Bot API calls:

```python
from vibebot import Bot

bot = Bot("TOKEN")
result = bot.request("sendMessage", chat_id=123, text="Hello")
```

## Running

These are equivalent polling entry points:

```python
bot.start()
bot.listen()
bot.open()
```

## Exports

Main public exports:

- `VibeBot`
- `Bot`
- `Route`
- `TelegramEvent`
- `MediaFile`
- `Message`
- `Update`
- `Chat`
- `User`
- `TelegramError`
