A Discord bot to keep track of who owes who money.
This bot keeps track of your financial exchanges with a roommate or friend, storing data securely in a Google Sheets file. It allows for easy submission of new entries and quick balance checks, all within your Discord server.
This bot was created to simplify expense tracking for two individuals, removing the need to manually update a shared spreadsheet.
The bot doesn't require commands to add entries. Instead, it uses regular Discord messages with a flexible syntax that is very forgiving and can make a lot of assumptions on your behalf. This is especially useful when you're outside and want to add an entry immediately after making a purchase, so you don't forget to do it later.
The short message syntax also works well for quickly adding entries using your phone's voice dictation.
Messages are parsed using regular expressions and consist of four parts:
Amount
- The first occurrence of a decimal or whole number is assumed to be the amountDescription
- Text that excludes the name, amount, and category will be used as the description
Name
- The name of the person who made the purchase- The name / nickname of the other person can be used to indicate that the amount is owed to them
- If no name is found, the name of the user who submitted the message will be used
Category
- Text that matches one of the configured categories / category keywords will be used as the category- If no category is found, the default category will be used
John spent $12.48 for Netflix in subscriptions
Assuming Netflix is a keyword for the subscriptions category, the example above can be shortened to:
12.48 Netflix
/balance
- Shows the current balance of the user
/pay
- Add an entry to pay off any outstanding balances
This bot requires self-hosting.
Hosting on a service such as Railway or Render is recommended. Make sure to set the environment variables in the hosting service.
- Clone the repository
- Create a
.env
file in the root directory with the content found in .env.example- Only variables starting with
GOOGLE
andDISCORD
are required, the rest are optional
- Only variables starting with
A service account is required to access the Google Sheets API. Follow the instructions here to create a service account and download the JSON file.
Make sure not to commit this file to source control.
From the JSON file, Add client_email
as the value for GOOGLE_SERVICE_ACCOUNT_CLIENT_EMAIL
, and private_key
for GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY
to your .env
file.
- Create a copy of the spreadsheet from here
- Share the spreadsheet with the
client_email
value, make sure to give it Edit permissions - Populate the cells found in the
Configuration
worksheet. - Copy the
Spreadsheet ID
from the URL of the spreadsheet and add it toGOOGLE_SHEETS_SPREADSHEET_ID
in your.env
file
The spreadsheet ID can be found in the URL of the spreadsheet:
https://docs.google.com/spreadsheets/d/<SPREADSHEET ID>/edit#gid=0
- Run
npm install
- Run
npm run dev
- Run
npm build
, followed bynpm start
- Run
npm test
to run the test suite
-
Create a new Discord application and bot here
-
Copy the bot token and add it to
DISCORD_TOKEN
in your.env
file -
Under
Bot
, enableSERVER MEMBERS INTENT
andMESSAGE CONTENT INTENT
-
Under
OAuth2
, select the client ID and add it toDISCORD_CLIENT_ID
in your.env
file -
Finally, head to
Installation
. SetInstall link
toDiscord provided link
and use it to invite the bot to your server -
Create a text channel strictly for the bot to post messages in. This is where the bot will post balance updates and other messages. Restrict permissions to only allow the bot to send messages in this channel.