siahe

README

#+title: siahe
#+html: <img style="height: 30em;"src="https://i.imgur.com/mXwY95v.jpeg"/>

=siahe= is designed to help university clubs sell tickets for their events through the Telegram messaging platform. The bot provides a seamless ticket purchasing experience for users, allowing them to easily browse available events, select tickets, and sign up directly within the Telegram app.

** Build
1. Have the latest version of =go= installed in you path.
2. Clone this repository and change directory.
3. Build.
#+begin_src bash
go build .
#+end_src

** Run
=siahe= inputs a set of configuration entries. This entries can either be passed by environment variables, argument flags or =.env= file. To see the full list of flags either do =siahe --help= or check out [file:config.go] directly.

Here is an example usage of an =.env= file.
Generate the env file.
#+begin_src bash
cp .env.sample .env
#+end_src
Fill out the env file with specified parameters.
#+begin_src bash
$EDITOR .env
#+end_src
Run the program.
#+begin_src bash
siahe
#+end_src

*** Run by Docker
=siahe= [[https://github.com/dearrude/siahe/pkgs/container/siahe][images]] are built upon each commit on Github container registry (ghcr) with =latest= tag.

Generate the following =docker-compose.yml= file.
#+begin_src yaml
version: '3'
services:
    siahe:
    image: ghcr.io/dearrude/siahe:latest
    container_name: siahe
    volumes:
        - ./siahe_assets:/home/nonroot/assets
    environment:
        APPID: -
        APPHASH: -
        BOTTOKEN: -
        ADMINPASSWORD: -
        VARIFICATIONCHAT: -
        BACKUPCHAT: -
        SQLITEPATH: "/home/nonroot/assets/db.sqlite"
        SESSIONPATH: "/home/nonroot/assets/session.json"

#+end_src

Run the containers.
#+begin_src bash
docker compose up -d && docker compose logs -f
#+end_src

In case of updates, run the following the command to update and re-run the container:
#+begin_src bash
docker compose pull
docker compose up -d --force-recreate
docker compose logs -f
#+end_src

** Run
*Note*: ~<param>~ means a mandatory parameter while ~[param]~ means an optional parameter.

1. Make sure that the bot is running by sending ~/start~ command to it.
2. Make an account by ~/add_account~ command.
3. Change your status to *moderator* by ~/promote_me <admin_password>~. A moderator can _promote_ and _demote_ other *admin* aside from running admin commands.
4. Run other commands accordingly.

*** User commands
- ~/start~ boots the bot. Given a ~getTicket_<event_id>~ as parameter, it can be used to purchase ticket(s).
- ~/add_account~ add a permanent account to bot, similar to signing up to a website authentication.
- ~/get_account~ prints data about user's own account.
- ~/delete_account~ delete user's account.
- ~/available_events~ shows all available events to get tickets for

*** Admin commands
**** User handling
- ~/get_user <user_id>~ prints a user's info by theirs telegram user_id
- ~/delete_user <user_id>~ deletes a user's account.
- ~/export_users~ exports all users info into a CSV file.
- ~/message_all~ sends a message to all signed up users.

**** Place handling
A place is a database entity that events take place in. For more info, run ~/add_place~ command.

- ~/add_place~ add and define a place to database. This will generate a unique ~place_id~.
- ~/get_place <place_id>~ prints data about place.
- ~/get_places~ prints a minimal data about all places. This include their place_id and name. It is useful if you want to event a place id by its name.
- ~/delete_place <place_id>~ deletes a place by its id.

**** Event handling
An event is a database entity that users can get tickets for. For more info, run ~/add_event~ command.

- ~/add_event~ add and define a event to database. This will generate a unique ~event_id~.
- ~/get_event <event_id>~ prints data about event.
- ~/get_events~ prints a minimal data about all events. This include their event_id and name. It is useful if you want to find an event id by its name.
- ~/delete_event <event_id>~ deletes a place by its id.
- ~/activate_event <event_id>~ activating an event enables users to get ticket for it. Events are activated by default upon creation.
- ~/deactivate_event <event_id>~ deactivating an event disables users to get ticket for it.
- ~/flush_reserves <event_id>~ delete all reserved tickets for an event.
- ~/message_event~ sends a message to all who got a ticket for the event.

**** Ticket handling
A ticket is a sign for users that they can attend events. In order to get a ticket for the user, they can open a URL of such pattern: ~https://t.me/<bot_username>?start=getTicket_<event_id>~. For example if bot's username is ~@fumTheatreSignupBot~ and you want to generate a link for users to get tickets for event_id 1, according to schema the URL is: ~https://t.me/fumTheatreSignupBot?start=getTicket_1~. In order to show all available events, the following URL can be used: ~https://t.me/fumTheatreSignupBot?start=availableEvents~

- ~/get_ticket <ticket_id>~ shows info about a ticket and its owner. Used to check the validity of the ticket.
- ~/attend_ticket <ticket_id>~ changes the ticket _status_ from ~completed~ to ~attended~. Used to track who showed up if they got any ticket.
- ~/unattend_ticket <ticket_id>~ reverses the functionality of prior command.
- ~/delete_ticket <ticket_id>~ removes a ticket from database.
- ~/export_tickets <event_id>~ exports all tickets of an event to a CSV file.
- ~/preview_tickets <event_id>~ preview all tickets of an event to a telegram message.
- ~/print_tickets <event_id>~ generate a printable PDF of all tickets of an event.
- ~/count_tickets~ count all tickets in database. Since ticket code is a 4-digit code, its count shouldn't exceed 9999. Delete deactivated events for their tickets to be deleted and free up the ticket codes.

** Licence
AGPLv3+