badge-generator discord discord-bot-client discord-presence discord-python github-action-docker github-api github-profiles python3

Refactorization Notice

I have seem to notice that a few or so has interest on this small project. Please note that I will be doing code refactorization if ever I will pass off my final thesis starting June. Please refer to #12 for more information (will be updated).

Discord Activity Badge `(Initial Release)🌇`

A containerized action that bridges the Discord User's Activity and their Status State to a Representable Badge for their Special Repository (Github Profile) and soon, for open-sourced Discord Bots.

Powered by Docker and Python + AsyncIO + discord.py + aiohttp.

Why?

Because why not? If you ever wanted to show your status with context aside from your Github Status, or wanting to go beyond styling your README by adding some extra toppings, or wanting to let some birds (strangers) know what you are doing at some point in time, then this action workflow might be for you!

Disclaimer: I did this for fun. But that fun were took over my standards. Check out wiki for more information.

Steps

The following contains the steps needed to make this action work properly. Keep in mind that this is quite hectic but easy, the steps were alot because this is the cheapest way to do this thing.

Creating a Bot and obtaining its Token in Discord Developers
Inviting the Bot to a Guild
Preparing the Workflow
Repository Secrets
Workflow Dispatch

Creating a Bot and obtaining its Token in Discord Developers

Ever since I don't provide anything such as the Bot that I use for reading my activities, you have to make it on your own. You can go to Discord Developers and start ahead by creating a new application.

Once you have created a new application, you have to go to the sidebar or menu and go to the Bot settings, and add a bot. And then, copy the token and store it somewhere temporarily as we are going to use it later on in the next two steps.

As a side note, you have to enable the presence and server members intent on the same settings (Bot settings) to allow your bot to read your presence context and the members' states and other kinds of stuff about them.

Don't forget to save before proceeding to the next step!!!

Inviting the Bot to a Guild

Inviting the bot and having them in the guild is the only way to read User's Presence and their State, as per the limitation of Discord API.

Keep in mind that, you can either create your own guild or have someone else let the bot join on their guild as long as you are there.

To invite, you have to go to the OAuth2 settings and check the OAuth2 URL Generator. Look for Bot scope and check it, you will be given a generated link.

Once you have the link, you just have to paste it into the browser and open it.

And there you have it! Once you have done this part, the only thing left is to have a workflow in your repository.

Preparing the Workflow

Paste the following YAML on your (profile) repository under the directory .github/workflows and commit it.

name: Discord Rich Presence Activity Badge

on:
  schedule:                 # Scheduling with Github Actions is inconsistent.
    - cron: "5 0-23 * * *" # Construct your Cronjob Schedule at https://crontab.guru/.

  workflow_dispatch:        # Enables you to dispatch the workflow at your click.

jobs:
  BadgeUpdater:
    name: Static Badge Updater
    runs-on: ubuntu-latest

    steps:
      - name: Update README Discord Badge to Latest Upstream
        uses: CodexLink/discord-activity-badge@v1.0 # Choose your own version by picking a tag or a branch name. Using a tag is recommended.
        with: # Go to your Repository Secrets and fill those up!
          DISCORD_USER_ID: ${{ secrets.DISCORD_USER_ID }}
          DISCORD_BOT_TOKEN: ${{ secrets.DISCORD_BOT_TOKEN }}

This workflow will run once it has been dispatched (manually) or is scheduled to run for every 5 minutes per 0 to 23 hours to check for the user's status.

Repository Secrets

To be able to provide your information, you have to go to your repository > Settings > Secrets > New Repository.

In the end, you should have these two repository secrets. The token is from the one that we obtained in the Discord Developers Section, and the one is from you yourself in the Discord Client.

DISCORD_USER_ID can be obtained by the following.

Workflow Dispatch

When you finished all the steps, the last thing to do was to manually push it to see changes.

Post-Step

If you did the run for the first time, the badge wil appear on the top of your README, you can adjust it to somewhere else and the badge will be replaced by the script, no matter where it is.

And that's done! For further customizations, please read the other sub-sections below.

Workflow Parameters

The following sub-sections contain a set of possible inputs that you can integrate with this workflow.

Required (In-Need-of-Evaluation) Parameters

These inputs are required in order to run the Docker Container.

Inputs	Type + Defaults	Description
`BADGE_IDENTIFIER_NAME`	`str`: (Script) Discord Activity Badge	The name of the badge (in markdown form) that will be utilized to replace the badge state side's contents. If the identifier does not exist, it will proceed to create a new one and append it on the top of your README. You must arrange it right after.
`COMMIT_MESSAGE`	`str`: Discord Activity Badge Updated as of `datetime.datetime.now().strftime("%m/%d/%y — %I:%M:%S %p")` ***See constants.py	The commit message that will be invoked in the commit context when there's are some changes to push.
`DISCORD_BOT_TOKEN`	`str` (Required)	The token of your bot from Discord's Developer Page. Note that, you have to use your own bot! Go check Discord Developers.
`DISCORD_USER_ID`	`int` (Required)	An integer ID used to identify you in Discord.
`PROFILE_REPOSITORY`	`str`: `GITHUB_ACTOR/GITHUB_ACTOR`	The repository from where the commits will be pushed. Fill this up when you are indirectly deploying the script under a different repository.
`URL_TO_REDIRECT_ON_CLICK`	`str`: `PROFILE_REPOSITORY` value.	The URL to point when the badge has been clicked.
`WORKFLOW_TOKEN`	`str` (Required)	The token of the Github Workflow Instance used to authenticate commits deployed by the script. Fill this up if you want to test locally so that you aren't going to be rate limited. Using user-generated token can give 5000 API requests!

Parameters that are required have to be explicitly stated in the workflow. Otherwise, it will lead to an error. Regardless of the types, it will be resolved by the script, this is just an indicator that those will be explicitly converted to what has been told here.

Optional Parameters

These inputs are optional and have the capability to override the display of the badge and the commit message. Allowing extensibility and customization that allows you to render multiple ways of designing your badge.

Colors and Intentions

If you wanna change how things should be delivered (context) and how they should look like (color), then this set of parameters will help you modify the way how it looks. Keep in mind that the labels [n] in the parameters is a number, and is corresponding to a set of choices. Please check the options under the table.

Parameters	Description + Result
`str` `[1]_STRING` Note: Each state (as options) is almost the same context from output to choices.	Overrides `Discord Activity` (Subject String) and User State with the state of `Playing`, `Watching`, and `Listening` with custom strings; this avoids making the status longer and balanced. If this is a `CustomActivity`, it will append User's State [Online, Idle, DND, Offline] instead.
`str` `[2]_STATUS_STRING` Note: Please check fallback_values in elements/constants.py	Overrides the status output in online / idle / dnd / offline states.
`str` `[1]_COLOR` Note:HEX RGB only	Renders status badge color whenever there's a certain activity. Which renders the user's state color in the subject, if a certain activity has color specified. Leaving these settings by default (None) will result to render the user's state color. See example of `APPEND_STATE_ON_SUBJECT`. That should ignore `SHIFT_STATE_ACTIVITY_COLOR` if that is the case.
`str` `[2]_STATUS_COLOR` Note: HEX RGB only	Overrides the status color when the user is in online / idle / dnd / offline states.
`str` `STATIC_SUBJECT_STRING` Defaults to: None	Statically declare a certain string to display on the subject. If declared, []_ACTIVITY_STRING and []_STATUS_STRING will be ignored.

Options: CUSTOM_ACTIVITY, GAME_ACTIVITY, RICH_PRESENCE, STREAM_ACTIVITY, and SPOTIFY_ACTIVITY.

Options: ONLINE, IDLE, DND, and OFFLINE.

I separated the options along with the parameter to avoid confusion while reading it.

Context

Whenever you want to change the context of the badge, you can use this set of parameters for extending the context or shorten it.

Parameters	Description + Result (If there's any)
`str` `PREFERRED_PRESENCE_CONTEXT` Options: [DETAILS, STATE, CONTEXT_DISABLED]	Overrides additional information to append in the badge. So far, only `DETAILS` and `STATE` are allowed to be appended since it shows the other context of the application.
`str` `TIME_DISPLAY_OUTPUT` Options: [TIME_DISABLED, HOURS, HOURS_MINUTE, MINUTES, SECONDS]	Appends time (based on preference) after the application name or the detail of the activity when `APPEND_PRESENCE_CONTEXT` is True.
`str` `TIME_DISPLAY_ELAPSED_OVERRIDE_STRING` Defaults to: elapsed.	Overrides the string appended whenever the time is displayed for elapsed. This is effective only when SHOW_TIME_DURATION is True.
`str` `TIME_DISPLAY_REMAINING_OVERRIDE_STRING` Defaults to: remaining.	Overrides the string appended whenever the time is displayed for remaining. This is effective only when `TIME_TO_DISPLAY` is True.
`bool` `TIME_DISPLAY_SHORTHAND` Defaults to: False	Displays the time with hours and minutes shorthanded to h and m.

Preferences

Parameters	Description + Result
`str` `PREFERRED_ACTIVITY_TO_DISPLAY` Options: [CUSTOM_ACTIVITY, GAME_ACTIVITY, RICH_PRESENCE, STREAM_ACTIVITY, SPOTIFY_ACTIVITY]	Renders a particular activity as a prioritized activity. If the preferred activity does not exist, it will render any activity by default. There will be no demo since it only picks what activity should be displayed.
`bool` `SHIFT_STATE_ACTIVITY_COLORS` Defaults to: False	Interchange state and activity colors. This is useful only if you want to retain your state color position even though `APPEND_STATE_ON_SUBJECT` is true.
`str (char)` `SPOTIFY_INCLUDE_ALBUM_PLAYLIST_NAME` Defaults to: False	Displays the album or the playlist from where the song is being played. Enabling this will keep the badge long enough to capture one whole line of the README!
`str (char)` `STATUS_CONTEXT_SEPERATOR` Defaults to: `,`	The character/s that separates the context of every status elements. Keep note that, once you declared a value on this parameter, it will automatically add space from both ends to ensure that the content displays properly. If otherwise, the script will do the spacing on its own.

You got some ideas or did I miss something out? Please generate an issue or PR (if you have declared it on your own), and we will talk about it.

For more information on how the script renders the badge based on preferences, please check the badge.py.

Development Parameters

When developing, there are other fields that shouldn't be used in the first place. Though they are helpful if you are planning to contribute or replicate the project.

Parameters	Type	Default	Description
`IS_DRY_RUN`	`bool`	`False`	Runs the usual process but it doesn't commit changes.

The list does seem to contain only one parameter. Worry not, there will be more parameters to be introduced in the future!

Credits

Here contains a list of resources that I have used in any form that contributed to the development of this repository.

Used Libraries and Technologies

argparse — Parser for command-line options, arguments and sub-commands.
ast — Parser for command-line options, arguments and sub-commands.
aiohttp — Asynchronous HTTP client/server framework for asyncio and Python.
asyncio — is a library to write concurrent code using the async/await syntax (Asynchronous I/O).
Badgen.net — Fast badge generating service.
base64 — Base16, Base32, Base64, Base85 Data Encodings.
black — The uncompromising Python code formatter.
Discord.py — An API wrapper for Discord written in Python.
Docker — Empowering App Development for Developers
datetime — Basic date and time types.
discord.py-stubs — Literally Discord.py Stubs for typing library.
enum — Support for enumerations.
flake8 — flake8 is a python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code.
logging — Logging facility for Python.
mypy — Optional static typing for Python 3 and 2 (PEP 484).
urllib3 — Python HTTP library with thread-safe connection pooling, file post support, user friendly, and more.
os — Miscellaneous operating system interfaces.
Poetry — Python dependency management and packaging made easy.
Python — an interpreted high-level general-purpose programming language.
Pythex — FIrst regular expression checker that I have used.
python-dotenv — Get and set values in your .env file in local and production servers. 🎉
Regex101 — One of the second regular expression checkers.
re — Regular expression operations.
sys — System-specific parameters and functions.
time — Time access and conversions.
typing — Support for type hints.
urllib — URL handling modules.
Visual Studio Code — Code editing. Redefined.

Special Thanks

The following were the ones who inspired me and gave me confidence for making this pet project possible.

jacobtomlinson/python-container-action — A template for creating GitHub Actions in Python.
athul/waka-readme — Wakatime Weekly Metrics on your Profile Readme.
https://dev.to/dtinth/caching-docker-builds-in-github-actions-which-approach-is-the-fastest-a-research-18ei
https://github.com/dtinth/github-actions-docker-layer-caching-poc -> https://github.com/sagikazarmark/github-actions-docker-layer-caching-poc

Other Resources

Keep in mind that most of these resources have been used for references and were not used for copy-pasting code! Also, it's worth noting that the links may be unsorted.

Articles or Guides

Questions (Unsorted)

Some of the questions here were snipped. They will redirect you to the answer.

Sites

I would like to thank those who asked and those who answered a particular question (for Questions), and to the repository and articles that describe the problem, which leads me to a certain direction, resulting in solving it.

License

  Copyright 2021 Janrey "CodexLink" Licas

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

You may see the LICENSE file for more information.

About

Bridge your discord's state and activity to a representable badge on your repository / profile to show your discord's current status. Powered by Docker and Python + AsyncIO + discord.py + aiohttp.