{"id":49575061,"url":"https://github.com/rollecode/ynab-bot","last_synced_at":"2026-05-03T16:10:45.786Z","repository":{"id":305934171,"uuid":"1024442689","full_name":"rollecode/ynab-bot","owner":"rollecode","description":"YNAB to Matrix bot","archived":false,"fork":false,"pushed_at":"2025-08-31T14:38:23.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-02T13:33:35.322Z","etag":null,"topics":["matrix","ynab","ynab-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rollecode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-22T17:49:56.000Z","updated_at":"2025-08-31T14:38:26.000Z","dependencies_parsed_at":"2025-07-22T19:40:13.270Z","dependency_job_id":null,"html_url":"https://github.com/rollecode/ynab-bot","commit_stats":null,"previous_names":["ronilaukkarinen/ynab-bot","rollecode/ynab-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rollecode/ynab-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollecode%2Fynab-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollecode%2Fynab-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollecode%2Fynab-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollecode%2Fynab-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rollecode","download_url":"https://codeload.github.com/rollecode/ynab-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rollecode%2Fynab-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32575383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["matrix","ynab","ynab-api"],"created_at":"2026-05-03T16:10:44.920Z","updated_at":"2026-05-03T16:10:45.780Z","avatar_url":"https://github.com/rollecode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YNAB Matrix Bot\n\n### A Matrix bot that monitors your YNAB (You Need A Budget) transactions and sends real-time notifications to a Matrix room, including budget progress for each category.\n\n\u003cimg width=\"80\" height=\"28\" alt=\"YNAB\" src=\"https://github.com/user-attachments/assets/c7300ced-3496-4604-ad5d-22cd60f73276\" /\u003e ![Version](https://img.shields.io/badge/version-1.0.2-blue?style=for-the-badge) [![javascript](https://img.shields.io/badge/javascript-%23F7DF1E.svg?style=for-the-badge\u0026logo=javascript\u0026logoColor=black)](#) [![node.js](https://img.shields.io/badge/node.js-%23339933.svg?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)](#)\n\n## Features\n\n⚡ **Near-instant notifications** for new YNAB transactions (10-second monitoring)\u003cbr\u003e\n📊 **Budget progress tracking** with visual progress bars\u003cbr\u003e\n💰 **Income and expense categorization**\u003cbr\u003e\n💬 **Matrix room messaging** with rich formatting\u003cbr\u003e\n🔄 **Smart monitoring** that only checks when needed\u003cbr\u003e\n🛡️ **Secure credential management**\n\n## Prerequisites\n\nBefore setting up the bot, you'll need:\n\n1. **YNAB Account** with API access\n2. **Matrix Account** (homeserver and bot user)\n3. **Node.js** (v22 via nvm)\n4. **Linux server** for deployment\n\n## Installation\n\n### 1. Install Node.js via nvm\n\nFirst, install [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm) if you don't have it already.\n\n```bash\n# Install and use the correct Node.js version\nnvm install\nnvm use\n\n# Verify installation\nnode --version\n```\n\n### 2. Clone and Setup the Bot\n\n```bash\n# Clone the repository\ngit clone https://github.com/ronilaukkarinen/ynab-bot\ncd ynab-bot\n\n# Install dependencies\nnpm install\n\n# Run the interactive setup\nnpm run setup\n```\n\n## Usage\n\n### Running the Bot\n\nThe bot monitors YNAB for new manually added transactions and sends instant notifications to Matrix:\n\n```bash\n# Start the bot\nnpm start\n\n# Start in development mode with detailed logging\nnpm run dev\n\n# Test the connection\nnpm start -- --test\n```\n\nThe bot will:\n1. Monitor your YNAB budget every 10 seconds for new transactions\n2. Send clean, formatted notifications to your Matrix room\n3. Include budget progress and category information\n4. Only notify about truly new transactions (no spam)\n\n### Bot Commands\n\n```bash\n# Test connectivity\nnpm start -- --test\n\n# Show help\nnpm start -- --help\n```\n\n### Message examples\n\n**Single transaction:**\n```\n**12.50 €** meno, Saaja: *Starbucks*. Kulu: *Morning coffee*.\n\n**Budjetin kategoria:** Food \u0026 Dining (Everyday Expenses)\n└ Budjetti: 200.00 € - Käytetty: 156.50 € (78%)\n└ ████████░░ Jäljellä: 43.50 €\n```\n\n**Multiple transactions:**\n```\n**2 uutta tapahtumaa**\n\n**12.50 €** meno, Saaja: *Starbucks*. Kulu: *Morning coffee*.\n\n**Budjetin kategoria:** Food \u0026 Dining (Everyday Expenses)\n└ Budjetti: 200.00 € - Käytetty: 156.50 € (78%)\n└ ████████░░ Jäljellä: 43.50 €\n\n**25.00 €** meno, Saaja: *Grocery Store*.\n\n**Budjetin kategoria:** Groceries (Everyday Expenses)\n└ Budjetti: 300.00 € - Käytetty: 275.00 € (92%)\n└ █████████░ Jäljellä: 25.00 €\n```\n\n## Configuration\n\nThe bot uses environment variables for configuration. Run `npm run setup` to configure these interactively, or set them manually:\n\n### Required Environment Variables\n\n```bash\n# YNAB Configuration\nYNAB_ACCESS_TOKEN=your_ynab_token_here\n\n# Matrix Configuration  \nMATRIX_HOMESERVER=https://your.homeserver.com\nMATRIX_USER_ID=@bot:your.homeserver.com\nMATRIX_ACCESS_TOKEN=your_matrix_token_here\nMATRIX_ROOM_ID=!roomid:your.homeserver.com\n\n# Bot Configuration\nCURRENCY=EUR\nTIMEZONE=Europe/Helsinki\n```\n\n### Optional Environment Variables\n\n```bash\n# Budget ID (leave empty for default budget)\nYNAB_BUDGET_ID=your_budget_id_here\n\n# Customizable text (Finnish by default)\nTEXT_INCOME=Tulo\nTEXT_EXPENSE=Meno\nTEXT_PAYEE=Saaja\nTEXT_MEMO=Muistiinpano\nTEXT_BUDGET=Budjetti\nTEXT_SPENT=Käytetty\nTEXT_REMAINING=Jäljellä\nTEXT_NEW_TRANSACTIONS=uutta tapahtumaa\nTEXT_NO_BUDGET=Ei budjettia tälle kategorialle\n\n# Month names (Finnish by default)\nMONTH_1=tammi\nMONTH_2=helmi\n# ... etc\n```\n\n## Deployment\n\n### Running as a systemd Service\n\n1. Create a systemd service file:\n\n```bash\nsudo nano /etc/systemd/system/ynab-bot.service\n```\n\n2. Add the following content:\n\n```ini\n[Unit]\nDescription=YNAB Matrix Bot\nAfter=network.target\n\n[Service]\nType=simple\nUser=your-username\nWorkingDirectory=/path/to/ynab-bot\nExecStart=/home/your-username/.nvm/versions/node/v22.16.0/bin/node src/index.js\nRestart=always\nRestartSec=10\nEnvironment=NODE_ENV=production\n\n[Install]\nWantedBy=multi-user.target\n```\n\n3. Enable and start the service:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable ynab-bot\nsudo systemctl start ynab-bot\n\n# Check status\nsudo systemctl status ynab-bot\n\n# View logs\njournalctl -u ynab-bot -f\n```\n\n### Updating the Bot\n\n```bash\ncd ynab-bot\ngit pull origin main\nnpm install\nsudo systemctl restart ynab-bot\n```\n\n## Getting API Tokens\n\n### YNAB API Token\n\n1. Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer)\n2. Click \"New Token\"\n3. Copy the generated token\n\n### Matrix Access Token\n\n#### Method 1: Using Element (Recommended)\n\n1. Open Element in your browser\n2. Go to Settings → Help \u0026 About\n3. Scroll down to \"Advanced\" section\n4. Click \"Access Token\" and copy it\n\n#### Method 2: Using curl\n\n```bash\ncurl -XPOST -d '{\"type\":\"m.login.password\", \"user\":\"your_username\", \"password\":\"your_password\"}' \"https://your.homeserver.com/_matrix/client/r0/login\"\n```\n\n### Getting Room ID\n\n1. In Element, go to the room\n2. Click room settings (gear icon)\n3. Go to \"Advanced\" tab\n4. Copy the \"Internal room ID\"\n\n## Troubleshooting\n\n### Common Issues\n\n**Bot not sending notifications:**\n- Check that YNAB token is valid\n- Verify Matrix credentials\n- Ensure the bot user has joined the target room\n- Check logs for error messages\n\n**\"This room is configured to use encryption\" error:**\n- The bot automatically handles this - messages should still be sent\n- Consider using an unencrypted room for bot notifications\n\n**Connection timeouts:**\n- Check your internet connection\n- Verify homeserver URL is correct\n- Try restarting the bot\n\n### Logs\n\nView detailed logs:\n```bash\n# If running with npm\nnpm run dev\n\n# If running as systemd service\njournalctl -u ynab-bot -f\n\n# Check recent logs\njournalctl -u ynab-bot --since \"10 minutes ago\"\n```\n\n## Development\n\n### Running in Development Mode\n\n```bash\n# Install dependencies\nnpm install\n\n# Run with detailed logging\nnpm run dev\n\n# Run tests\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frollecode%2Fynab-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frollecode%2Fynab-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frollecode%2Fynab-bot/lists"}