{"id":28563535,"url":"https://github.com/jlvadell/pururu-bot","last_synced_at":"2025-06-10T13:02:37.815Z","repository":{"id":252823161,"uuid":"837739139","full_name":"jlvadell/pururu-bot","owner":"jlvadell","description":"Pururu Bot is a Discord bot designed for a specific server to manage attendance. It features automated tracking, clock-in and clock-out functions, and absence monitoring. Built using the discord.py library, it interfaces with the Discord API and employs Google Sheets API for data storage, using Google Sheets as its primary database.","archived":false,"fork":false,"pushed_at":"2025-04-07T13:48:48.000Z","size":690,"stargazers_count":7,"open_issues_count":10,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-07T14:26:21.847Z","etag":null,"topics":["absence-management","api-integration","attendance","attendance-management","data-management","discord","discord-bot","discord-py","google-sheets","google-sheets-api","productivity","python","side-project","time-tracker","time-tracking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlvadell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-03T22:00:07.000Z","updated_at":"2025-02-25T21:17:56.000Z","dependencies_parsed_at":"2024-10-27T01:24:02.241Z","dependency_job_id":null,"html_url":"https://github.com/jlvadell/pururu-bot","commit_stats":null,"previous_names":["jlvadell/pururu-bot"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlvadell%2Fpururu-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlvadell%2Fpururu-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlvadell%2Fpururu-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlvadell%2Fpururu-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlvadell","download_url":"https://codeload.github.com/jlvadell/pururu-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlvadell%2Fpururu-bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259080921,"owners_count":22802393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["absence-management","api-integration","attendance","attendance-management","data-management","discord","discord-bot","discord-py","google-sheets","google-sheets-api","productivity","python","side-project","time-tracker","time-tracking"],"created_at":"2025-06-10T13:02:19.115Z","updated_at":"2025-06-10T13:02:37.809Z","avatar_url":"https://github.com/jlvadell.png","language":"Python","funding_links":[],"categories":["Automated Time Tracking"],"sub_categories":[],"readme":"# Pururu Bot\n\n\u003cdiv\u003e\n\u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=jlvadell_pururu-bot\u0026metric=alert_status\"\u003e\n\u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=jlvadell_pururu-bot\u0026metric=coverage\"\u003e\n\u003cimg src=\"https://img.shields.io/github/languages/top/jlvadell/pururu-bot\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/jlvadell/pururu-bot\"\u003e\n\u003cimg src=\"https://img.shields.io/github/v/tag/jlvadell/pururu-bot\"\u003e\n\u003c/div\u003e\n\nThis is the repository for the Discord bot Pururu.\n\n![Pururu App](docs/img/dc_user_app.png)\n\nThis bot is a private project for a Discord server, and it is not intended to be used by other servers.\n\n## Purpose\n\nThe purpose of this bot is to provide a set of tools to the users of the server, such as:\n\n- Automatic Attendance Control\n- Clock in and out\n- Absences control\n\n## Dependencies\n\n### Discord API\n\nThe app is fully-dependent on the Discord API, hence, it\nuses [Discord.py](https://discordpy.readthedocs.io/en/latest/index.html) to interact with the API.\n\n### Google Sheets API\n\nThe app is designed to use a Google Sheet as the main database service, for this, it uses\nthe [Google Sheets API](https://developers.google.com/sheets/api).\n\nThe why of this is because originally everything was made by hand using a Google Sheet, so when I was planning this bot\nI wanted to preserve the easy way of visualizing and editing the data a Google Sheet provides.\n\n## How it works?\n\nHere is a flow diagram of how the bot works:\n\n![Flow diagram](docs/img/pururu_flow.png)\n\nIt only uses the `on_voice_state_update` event to track the users' attendance. After meting the conditions to start a\nnew Game (attendance check) it will start recording every event locally so when the game finishes it will be inserted to\nthe google sheet.\n\n### Attendance\n\nHere is an example of how the attendance sheet would look like:\n![Attendance Sheet](docs/img/attendance_sheet.png)\n\n### Clocking\n\nHere is an example of how the clocking sheet would look like:\n![Attendance Sheet](docs/img/clocking_sheet.png)\n\n### Event Logging\n\nHere is an example of how the event logging sheet would look like:\n![Attendance Sheet](docs/img/event_logging_sheet.png)\n\n## Bot Commands\n\n### Ping command (`/ping`)\n\nSend a ping to the bot, if the bot is online and responding the bot answers with a pong and his current version.\n\n### Stats command (`/stats`)\n\nWhen you call the stats command the bot will query your attendance data and will return a resume of your attendance.\nIn this resume you will see:\n- Total events\n- Total attendances and absences\n- Total justifications / injustifications\n\n## Deployment\n\nThe app is configured to be deployed in an EC2 instance from AWS, to do so, it uses the deployment workflow from GitHub\nActions.\n\n![Deployment Workflow](docs/img/pururu_deployment.png)\n\n## Installation\n\nTo be able to run this app you will need:\n\n- Python, this app is designed in Python 3.12\n- [Install dependencies](#install-dependencies)\n- Setup of the [basic configurations](#basic-configurations)\n- Discord bot, see [Setting up a bot](#setting-up-a-discord-bot)\n- Access to a google sheet, see [Enabling access to a Google Sheet](#enabling-access-to-a-google-sheet)\n\n### Install dependencies\n\n``pip install -r .\\src\\pururu\\requirements.txt``\n\n### Basic Configurations\n\nTo load the necessary configurations you can create a file called `.env.development` in the root of the project (use\n`.env.base` as reference).\n\n#### Required Configurations\n\nThe required configurations to run the app are:\n\n- `DISCORD_TOKEN`: The token of the discord bot. See [Setting up a bot](#setting-up-a-discord-bot)\n- `PLAYERS`: the name of the players that will be tracked by the bot, separated by a comma. The names should be\n  the [discord member.name](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member.name) that refers to the\n  unique username (`username#1234`) without the `#XXXX` part\n- `GUILD_ID`: The id of the guild where the bot will be used. You can get this id by right-clicking the server icon and\n  selecting `Copy ID` (you will need to have the developer mode enabled in the discord settings)\n- `GOOGLE_SHEETS_CREDENTIALS`: Refers to the location of the `google_credentials.json` file. This file is the credentials\n  to access the Google APIs as a service account.\n  See [Enabling access to a Google Sheet](#enabling-access-to-a-google-sheet)\n- `SPREADSHEET_ID`: The id of the Google sheet where the data will be stored. You can get this id from the URL of the\n  Google sheet. It is the part between the `/d/` and the `/edit` part of the URL.\n- `GS_ATTENDANCE_PLAYER_MAPPING`: a hash map that maps the discord member name to the column in the attendance sheet.\n  The\n  key should be the discord member name and the value should be the column in the attendance sheet. The column should be\n  the letter of the column in the sheet (e.g. `A`, `B`, `C`, etc.). As an example this config\n  `GS_ATTENDANCE_PLAYER_MAPPING='{\"member1\":\"C\",\"member2\":\"F\",...}'`will work for the [attendance example](#attendance)\n\n#### Customizations\n\nSome configurations can be customized to fit your needs:\n\n- `LOG_LEVEL`: The level of the logs that will be printed. The default is `INFO`, but you can change it to `DEBUG` to\n  see more detailed logs; [Available logging levels](https://docs.python.org/3/library/logging.html#logging-levels).\n- `ATTENDANCE_CHECK_DELAY`: Refers to time the app will wait to start a new attendance check after the conditions for\n  starting a new one are met. The default is 1800 seconds (30 minutes).\n- `MIN_ATTENDANCE_TIME`: Refers to the time a member should be in the voice channel to be considered as present. The\n  default is 1800 seconds (30 minutes).\n- `MIN_ATTENDANCE_MEMBERS`: Refers to the minimum number of members that should be in the voice channel to trigger the\n  creation of a new attendance check. The default is 3 members.\n\n### Setting up a discord bot\n\nTo be able to create a discord bot first you will need to go to\nthe [developer portal of discord](https://discord.com/developers/applications) and create a new Application.\nOnce you got the application, you will need 2 things:\n\n- Adding the bot to your desired server, remember that this app is designed to be used in only 1 server.\n- The bot token from the bot section of the application (`DISCORD_TOKEN`).\n\nNote: this app does not require any special permissions, just the basic ones.\n\n### Enabling access to a Google Sheet\n\nFirst thing you will need to do is going to the [Google Cloud Console](https://console.cloud.google.com/welcome), and\ncreate a new project. After that you will need to enable:\n\n- The [Drive API](https://console.cloud.google.com/apis/api/drive.googleapis.com/metrics).\n- The [Sheets API](https://console.cloud.google.com/apis/api/sheets.googleapis.com/metrics).\n\nOnce both APIs are enabled you will need to create a service account and download the `google_credentials.json`, to do\nso, go to the credentials section.\n\nAfter having created the Google service account you will need to share the Google sheet with the email of the service\naccount.\n\n## Contributing\n\nEven that this a private project for an specific needs, feel free to submit a pull request, every suggestion is welcome.\n\n## Versioning\n\nWe use [Semantic Versioning](http://semver.org/) for versioning. For the versions\navailable, see the [tags on this\nrepository](https://github.com/jlvadell/pururu-bot/tags).\n\n## Contributors\n\n- Author: **José Vadell** - [jlvadell](https://github.com/jlvadell)\n- Contributor: **Rubén Mariscal** - [rmariscal13](https://github.com/rmariscal13)\n- Contributor: **Julien Gillet** - [JulienyGillet](https://github.com/JulienyGillet)\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlvadell%2Fpururu-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlvadell%2Fpururu-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlvadell%2Fpururu-bot/lists"}