bonbon-bot

A Crystal-based Telegram bot that manages birthdays in channels, greets users on their birthdays with configurable language support, and includes characteristic phrases from "aunt Norma Bon". Includes CSV import functionality, automated encouragement messages, advanced admin controls, and dynamic multi-language support.

Installation

#. Install Crystal (>=1.17.1) from https://crystal-lang.org/install/. #. Clone the repository: git clone <repo-url>. #. Install dependencies: shards install.

Quick Start

#. Create a bot via @BotFather <https://t.me/botfather>_ on Telegram and get the token. #. Copy the environment template: cp .env.example .env #. Edit .env with your bot token and configuration. #. Run the bot: crystal run src/bonbon-bot.cr

Systemd Service Installation

For production deployment, use the built-in installation targets:

**User Installation (recommended for development/testing):**

.. code-block:: bash

   make install-user
   systemctl --user daemon-reload
   systemctl --user enable bonbon-bot.service
   systemctl --user start bonbon-bot.service

**System Installation (for production servers):**

.. code-block:: bash

   sudo make install
   sudo systemctl daemon-reload
   sudo systemctl enable bonbon-bot.service
   sudo systemctl start bonbon-bot.service

Configuration
-------------

The bot uses environment variables for configuration. Copy ``.env.example`` to ``.env`` and edit the values:

* ``BOT_TOKEN``: Your Telegram bot token from @BotFather (required).
* ``DB_URI``: Database URI, default "bonbon.db" (SQLite). Supports PostgreSQL, MySQL, etc.
* ``GREETING_TIME``: Daily birthday greeting time, default "09:00".
* ``ADMIN_IDS``: Comma-separated list of admin Telegram user IDs.
* ``BOT_USERNAME``: Your bot's username (optional, for mention detection).
* ``LOG_LEVEL``: Logging verbosity (DEBUG, INFO, WARN, ERROR, FATAL, OFF).

For systemd installations, the bot automatically expands ``$HOME`` variables in the database URI.

  .. note::
     The bot uses crystal-db for database abstraction. To switch to a different database (e.g., PostgreSQL), install the appropriate
     shard and update ``DB_URI``.

#. Add the bot to your channel as an administrator.
#. Use ``/setlang <code>`` to set the channel language (e.g., ``/setlang es`` or ``/setlang fr``).
#. Users can set birthdays with ``/setbirthday DD/MM/YYYY``.
#. Admins can import birthdays via CSV with ``/import_birthdays``.
#. Configure automated encouragement messages with ``/set_encouragement``.

Commands
~~~~~~~~

**User Commands:**

* ``/start`` or ``/inicio``: Welcome message.
* ``/help`` or ``/ayuda``: Show available commands.
* ``/setbirthday DD/MM/YYYY`` or ``/micumple DD/MM/YYYY``: Set your birthday.
* ``/mybirthday`` or ``/vercumple``: View your set birthday.
* ``/birthdays`` or ``/vercumples``: View all birthdays in channel.
* ``/testbday`` or ``/testcumple``: Test birthday greeting message.
* ``/exportcsv``: Export birthdays as CSV.

**Admin Commands:**

* ``/setlang <code>`` or ``/configidioma <code>``: Configure channel language (e.g., ``/setlang es``, ``/setlang fr``).
* ``/import_csv <URL>`` or ``/importarcsv <URL>``: Import birthdays from CSV file.
* ``/toggle_encouragement on|off [days]`` or ``/alternaraliento on|off [dias]``: Configure encouragement messages.
* ``/stats`` or ``/estadisticas``: View bot statistics.
* ``/broadcast <message>`` or ``/difundir <message>``: Send admin message to channel.
* ``/send_announcement <message>`` or ``/enviaranuncio <message>``: Send birthday announcement.
* ``/add_phrase <lang> <key> <text>`` or ``/agregarfrase <lang> <key> <text>``: Add new greeting phrase.
* ``/add_lang <code> <name>`` or ``/agregaridioma <code> <name>``: Add new language.
* ``/remove_lang <code>`` or ``/removeridioma <code>``: Remove language.
* ``/list_langs`` or ``/listaridiomas``: List available languages.
* ``/add_admin @user`` or ``/agregaradmin @user``: Add channel administrator.
* ``/remove_admin @user`` or ``/removeradmin @user``: Remove channel administrator.
* ``/list_admins`` or ``/listaradmins``: List channel administrators.
* ``/add_lang <code> <name>``: Add a new language (e.g., ``/add_lang fr French``).
* ``/remove_lang <code>``: Remove/deactivate a language.
* ``/list_langs``: List all available languages.

Development
-----------

The project includes a comprehensive GNUmakefile with all essential development tasks:

**Core Commands:**

* ``make all``: Run format, lint, test, and build
* ``make check``: Run format, lint, and test (recommended before commits)
* ``make test``: Run the full test suite (22 tests)
* ``make build``: Build development version
* ``make release``: Build optimized release version

**Code Quality:**

* ``make format``: Format all Crystal code with ``crystal tool format``
* ``make lint``: Run all linters (ameba, yamllint, rstcheck)
* ``make unreachable``: Check for unreachable code

**Dependencies & Maintenance:**

* ``make deps``: Update all Crystal dependencies
* ``make clean``: Clean build artifacts
* ``make distclean``: Clean everything including dependencies
* ``make docs``: Generate API documentation

**Installation:**

* ``make install-user``: Install for current user with systemd service
* ``make install``: System-wide installation (requires sudo)
* ``make uninstall-user``: Uninstall user installation
* ``make uninstall``: Uninstall system installation

**Quality Assurance:**

All code passes:
- ✅ Crystal formatting standards
- ✅ Ameba linting (0 issues)
- ✅ YAML validation
- ✅ RST documentation checks
- ✅ 22/22 tests passing
- ✅ Zero unreachable code

Contributing
------------

#. Fork it.
#. Create your feature branch.
#. Commit your changes.
#. Push to the branch.
#. Create a new Pull Request.

Contributors
------------

* Rénich Bon Ćirić - creator and maintainer