Skip to content

README.md

Latest commit

 

History

History
209 lines (152 loc) · 5.86 KB

README.md

File metadata and controls

209 lines (152 loc) · 5.86 KB

🦗 Grillo Telegram Bot

A Telegram bot for interacting with the WEEE-Open/grillo lab booking and management API.

Compatible with: main branch of WEEE-Open/grillo

Features

  • Check status - See who's in the lab and upcoming bookings
  • Clock in/out - Track your lab time with audits
  • Auto-reload - Development mode with automatic restart on file changes

Prerequisites

  • Python 3.11 or higher
  • A Telegram Bot Token (from @BotFather)
  • A Grillo API Token (from the Grillo web UI settings)

Quick Start

1. Get Credentials

Telegram Bot Token:

  1. Message @BotFather on Telegram
  2. Send /newbot and follow the prompts
  3. Copy the token

Grillo API Token:

  1. Log in to the Grillo web interface
  2. Go to Settings → API Tokens → Create Token
  3. Set permissions to Read-Write
  4. Copy the token

2. Setup

git clone https://github.com/yourusername/grillo-bot.git
cd grillo-bot
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your tokens
python dev.py  # Development mode with auto-reload

Environment Variables (.env):

TELEGRAM_BOT_TOKEN=your_bot_token_here
GRILLO_API_TOKEN=your_api_token_here
GRILLO_API_URL=http://localhost:3000/api/v1

3. Run

# Development mode (auto-reloads on file changes)
python dev.py

# Production mode
python bot.py

4. Use the Bot

  1. Find your bot on Telegram
  2. Send /start
  3. Your account will be auto-linked if your Telegram ID is in LDAP
  4. Use /help to see available commands

Bot Commands

Command Description
/start Welcome message - auto-links your account if Telegram ID is in LDAP
/help Show available commands
/status [location] Check who's in the lab and upcoming bookings
/clockin [location] Clock in to the lab
/clockout <summary> Clock out with work summary

Note: The bot automatically links your Telegram account on /start if your Telegram ID is configured in the Grillo LDAP server.

Project Structure

grillo-bot/
├── bot.py              # Main bot with command handlers
├── dev.py              # Development runner with auto-reload
├── grillo_client.py    # Grillo API client
├── user_mapper.py      # Telegram ↔ LDAP user mapping
├── config.py           # Configuration management
├── utils.py            # Utility functions
├── requirements.txt    # Python dependencies
├── .env.example        # Environment template
├── .env                # Your config (gitignored)
├── user_mapping.json   # User mappings (gitignored, auto-created)
└── README.md           # This file

How Authentication Works

The bot uses a hybrid authentication system:

  1. Auto-Discovery: When you send /start, the bot queries the Grillo API endpoint /user?telegram_id=YOUR_ID
  2. User Mapping: If found, your Telegram account is automatically linked to your LDAP user
  3. Session Generation: The bot generates a session cookie for authenticated operations
  4. UID Tracking: All API requests include your user ID for proper tracking

Requirements:

  • Your Telegram ID must be configured in the Grillo LDAP server
  • The bot needs an admin API token to query user information

Mappings are stored locally in user_mapping.json (gitignored).

Development

Auto-Reload

Use dev.py for development - it automatically restarts the bot when you modify any Python file:

python dev.py

Features:

  • Watches all .py files for changes
  • Automatic bot restart on save
  • Debouncing (1s delay to prevent rapid restarts)
  • Crash recovery
  • Clean shutdown with Ctrl+C

Adding Commands

  1. Add handler function in bot.py:
async def mycommand(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    grillo = get_user_client_by_telegram(update.effective_user.id)
    # Your logic here
    await update.message.reply_text("Response")
  1. Register in main():
handlers = [start, help, status, clockin, clockout, mycommand]

Adding API Methods

Add to GrilloClient in grillo_client.py:

def my_method(self, param: str) -> Dict[str, Any]:
    return self._make_request("GET", f"/endpoint/{param}")

Code Style

  • Follow PEP 8
  • Use type hints
  • Add docstrings to functions
  • Handle errors gracefully

Grillo API Endpoints Used

Endpoint Method Purpose
/user?telegram_id=<id> GET Auto-discover user by Telegram ID
/locations/:id GET Get location details with people/bookings
/audits GET Get audit entries (time tracking)
/audits POST Clock in to lab
/audits PATCH Clock out from lab
/session POST Generate user session cookie

See the Grillo API source for complete documentation.

Troubleshooting

Bot not responding:

  • Verify TELEGRAM_BOT_TOKEN in .env
  • Check bot is running: ps aux | grep bot.py
  • Look for errors in terminal output

Auto-linking fails:

  • Ensure your Telegram ID is in the Grillo LDAP server
  • Check GRILLO_API_TOKEN has proper permissions
  • Verify GRILLO_API_URL is correct and accessible

License

MIT

Contributing

Pull requests welcome! For major changes, please open an issue first.

License

MIT

Related Projects

Authors