System-End/nephthys
1
0
Fork 0
mirror of https://github.com/System-End/nephthys.git synced 2026-04-19 16:28:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Support bot for the Hack Club Slack
103 commits 4 branches 0 tags 1.2 MiB
Find a file
MMK21 bed6f313ca
Overhaul deleted message handling (#73) 
* Update DB when unthreaded messages are deleted

* Add required library libatomic1 to Dockerfile (#71)

* Handle quick message deletions

This is a quick and dirty way to handle the bug, but it works.

I also realised that handle_question_deletion() doesn't delete it in #tickets

* Create a system for tracking bot messages attached to tickets

* Ensure resolved message is added to userFacingMsgs

TODO I''ll need to make a function that all the macros can use to send a user-facing message

* Add a reply_to_ticket() helper for updating the DB
while replying to a ticket

* Fix type errors in reply_to_ticket()

* Use reply_to_ticket when resolving tickets

* Fix type errors in message.py

* Create delete_replies_to_ticket()

* Remove unused parameter in delete_replies_to_ticket

* Rename BotMessage.msgTs to BotMessage.ts

* Write a stub delete_and_clean_up_ticket function

* Partially implement delete_and_clean_up_ticket

* Delete "ticket" message in delete_and_clean_up_ticket()

* Use the new ticket methods where appropriate

* Make function name clearer ("delete_bot_replies")

* Log if a question is deleted but not present in DB

* Fix error when normal messages are deleted

* Actually include userFacingMsgs in the query when deleting bot replies

* Add success heartbeat to delete queue

* Document the deletion queue needing workspace admin

* Don't use delete queue in ticket_methods.py

This is because the delete queue requires an admin token, ew

* Fix deleting the backend message on ticket deletion

* Always preserve support threads with >3 bot messages

This is so that if someone runs ?faq, the ticket still counts as being resolved in the DB.

* Debug-log message event data instead of printing

* Use the reply_to_ticket util in macros

---------

Co-authored-by: RandomSearch <101704343+RandomSearch18@users.noreply.github.com>
2025-10-25 07:52:21 +00:00
.github/workflows Configure CodeQL scans using YAML (#65) 2025-10-20 23:03:29 +00:00
.vscode Add a VSCode launch.json (#64) 2025-10-21 09:31:45 +00:00
nephthys Overhaul deleted message handling (#73) 2025-10-25 07:52:21 +00:00
prisma Overhaul deleted message handling (#73) 2025-10-25 07:52:21 +00:00
.env.sample Add SLACK_HELP_CHANNEL to .env.sample 2025-08-11 14:16:15 +01:00
.gitignore Initial commit 2025-05-30 22:49:06 +01:00
.pre-commit-config.yaml Initial commit 2025-05-30 22:49:06 +01:00
.python-version Initial commit 2025-05-30 22:49:06 +01:00
Dockerfile Add required library libatomic1 to Dockerfile (#71) 2025-10-22 22:37:01 +00:00
LICENSE Initial commit 2025-05-30 22:49:06 +01:00
manifest.yml Fix tags (#67) 2025-10-21 14:59:54 +00:00
pyproject.toml leaderboard 2025-07-03 17:26:31 +00:00
README.md Fix tags (#67) 2025-10-21 14:59:54 +00:00
uv.lock leaderboard 2025-07-03 17:26:31 +00:00

README.md

Nephthys

Nephthys is the bot powering #summer-of-making-help and #identity-help in the Hack Club Slack! Below is a guide to set her up for developing and here's a list of some of her features :)

Features

Tags

You can tag tickets in the private tickets channel or with the macro ?tag <tag_name>. This will DM the people who are specialised in responding to those issues and have it show up in their assigned tickets. You can assign yourself to get notified for specific tags on the app home

Macros

Sometimes it’s nice to be able to do things quickly... Here’s where macros come in! Send one of the following messages in an open thread and something will happen

  • ?resolve - the ticket gets closed. Equivalent of hitting i get it now
  • ?identity - redirect to #identity-help
  • ?faq - redirect to the FAQ
  • ?hii - silly message :3
  • ?shipcertqueue - tell them to wait and vote because there's a backlog of ships
  • ?fraud - redirect to fraud dept
  • ?thread - remove the reaction and all Nephthys replies to unclutter duplicates
  • more to come?? feel free to PR your own into hackclub/nephthys or tell me what you want

Stale

Tickets that have been not had a response for more than 3 days will automatically be closed as stale. The last helper to respond in the thread gets credit for closing them

Stale ticket handling is not working at the moment, but more features for dealing with stale tickets are planned.

Leaderboard

At midnight UK time each day, you get to see the stats for the day in the team channel! Helpers can also see more detailed stats at any time on the app home for the bot!

Assigned Tickets

When you send a message in a help thread, that thread is assigned to you and it is up to you to resolve it. You can see a list of threads waiting for you on the app home - just select the Assigned Tickets tab at the top

Prerequisites

  • Python (3.13 or later)
  • uv
  • A Slack workspace where you have permissions to install apps
  • Tunneling tool (for local development)
  • A PostgreSQL database (you can run one in Docker using the command below)
docker run --name hh-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

Setting up the Slack App

  1. Go to https://api.slack.com/apps and click "Create New App".
  2. Choose "From an app manifest" and select your workspace.
  3. Copy and paste the manifest in manifest.yml.
  4. Review and create the app.
  5. In the "Basic Information" section, note down the App Id, Client Id, Client Secret, Signing Secret .
  6. Go to "OAuth & Permissions" and install the app to your workspace. Note down the "Bot User OAuth Token".

Setting up the Project

  1. Clone the repository:

    git clone https://github.com/hackclub/nephthys
cd nephthys

  2. Install dependencies:

    uv sync
source .venv/bin/activate # for bash/zsh
source .venv/bin/activate.fish # for fish
source .venv/bin/activate.csh # for csh
source .venv/bin/activate.ps1 # for powershell

  3. Copy the .env.sample file to .env:

    cp .env.sample .env

  4. Edit the .env file and fill in the values:

Running the Application

  1. Start your tunneling tool and expose the local server. (Not needed in socket mode with SLACK_APP_TOKEN set)

    Note the HTTPS URL you get.

  2. Update your Slack app's request URLs:

    • Go to your Slack app's settings.
    • In "Event Subscriptions" and "Interactivity & Shortcuts", update the request URL to your HTTPS URL followed by /slack/events.
    • In "OAuth & Permissions", update Redirect URLs to your HTTPS URL followed by /slack/oauth_redirect.

  3. MAKE SURE YOU CHANGE THE COMMAND - DO NOT USE THE SAME COMMAND

  4. Install pre-commit hooks:

    uv run pre-commit install

  5. Start your database and update the database schema:

    uv run prisma db push
uv run prisma generate

  6. Start the application:

    nephthys

Your Slack app should now be running and connected to your Slack workspace!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Scripts

The codebase contains some scripts in the nephthys/scripts/ directory to help with development and testing. They are documented below.

Adding Dummy Data

add_dummy_data.py is a script that adds a bunch of dummy (i.e. fake) support ticket records to the database, for stress-testing/performance testing.

Usage: uv run nephthys/scripts/add_dummy_data.py <num_records>

  • Ensure you run it after the nephthys has been run at least once (and once the DB has been initialized)
  • It takes a while to run (adding 20k records takes ~50 seconds on my machine)
  • Don't run this in production, obviously

License

This project is licensed under the MIT License.