{"id":44545457,"url":"https://github.com/jhonnymoreira/financial-bot","last_synced_at":"2026-02-13T19:15:38.742Z","repository":{"id":334337236,"uuid":"1127991952","full_name":"jhonnymoreira/financial-bot","owner":"jhonnymoreira","description":" A Telegram bot integration to tidy up your finances.","archived":false,"fork":false,"pushed_at":"2026-02-02T15:40:25.000Z","size":492,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T04:36:33.187Z","etag":null,"topics":["bot","finances","personal-finances","telegram"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"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/jhonnymoreira.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2026-01-05T01:14:24.000Z","updated_at":"2026-02-02T15:42:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jhonnymoreira/financial-bot","commit_stats":null,"previous_names":["jhonnymoreira/financial-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jhonnymoreira/financial-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhonnymoreira%2Ffinancial-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhonnymoreira%2Ffinancial-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhonnymoreira%2Ffinancial-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhonnymoreira%2Ffinancial-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhonnymoreira","download_url":"https://codeload.github.com/jhonnymoreira/financial-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhonnymoreira%2Ffinancial-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29414731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T06:24:03.484Z","status":"ssl_error","status_checked_at":"2026-02-13T06:23:12.830Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["bot","finances","personal-finances","telegram"],"created_at":"2026-02-13T19:15:37.912Z","updated_at":"2026-02-13T19:15:38.733Z","avatar_url":"https://github.com/jhonnymoreira.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Financial Bot\n\nA Telegram bot integration to tidy up your finances.\n\nParses natural language expense messages using Claude AI and automatically registers them into a Google Sheets spreadsheet.\n\n**Note**: Bot status messages are currently in pt-BR. Support for other locales is planned.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Prerequisites](#prerequisites)\n  - [Anthropic API Key](#anthropic-api-key)\n  - [Google Sheets Setup](#google-sheets-setup)\n  - [Cloudflare Setup](#cloudflare-setup)\n    - [Configure wrangler.jsonc](#configure-wranglerjsonc)\n    - [Secrets Store](#secrets-store)\n    - [Wrangler Secrets](#wrangler-secrets)\n    - [Deploy](#deploy)\n  - [Telegram Setup](#telegram-setup)\n    - [Creating the Bot](#creating-the-bot)\n    - [Registering the Webhook](#registering-the-webhook)\n    - [Getting User and Chat IDs](#getting-user-and-chat-ids)\n- [Usage](#usage)\n  - [Examples](#examples)\n  - [Payment Methods](#payment-methods)\n  - [Temporal References](#temporal-references)\n  - [Categories](#categories)\n- [Monitoring](#monitoring)\n- [Local Development](#local-development)\n  - [Setup](#setup)\n- [Available Scripts](#available-scripts)\n- [TODO](#todo)\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone git@github.com:jhonnymoreira/financial-bot.git\ncd financial-bot\n```\n\n2. Enable corepack and install dependencies:\n\n```bash\ncorepack enable\npnpm install\n```\n\n3. Authenticate with Cloudflare:\n\n```bash\npnpm exec wrangler login\n```\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) v24.13.0 (use [nvm](https://github.com/nvm-sh/nvm) with the `.nvmrc` file)\n- [pnpm](https://pnpm.io/) v10.28.1 via [corepack](https://nodejs.org/api/corepack.html)\n- [Cloudflare account](https://dash.cloudflare.com/sign-up)\n- [Anthropic account](https://platform.claude.com/)\n- [Google account](https://accounts.google.com/)\n- [Telegram account](https://telegram.org/)\n\n### Anthropic API Key\n\n1. Go to [Claude Platform](https://platform.claude.com/)\n2. Sign up or log in\n3. Navigate to **API Keys**\n4. Click **Create Key** and give it a name\n5. Copy the key — you'll need it for the [Secrets Store](#secrets-store)\n\n### Google Sheets Setup\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Enable the **Google Sheets API**\n4. Go to **IAM \u0026 Admin** \u003e **Service Accounts** and create a new service account\n5. Create a JSON key for the service account and save it — this is your `GOOGLE_SERVICE_ACCOUNT_CREDENTIALS`\n6. Create a Google Sheet with the following columns (in order):\n\n| occurredAt | amount | description | category | paymentMethod | paymentIdentifier | currency | messageId | registeredAt |\n|------------|--------|-------------|----------|---------------|-------------------|----------|-----------|--------------|\n\n7. Share the spreadsheet with the service account email (found in the JSON key as `client_email`) with **Editor** permissions\n8. Copy the spreadsheet ID from the URL: `https://docs.google.com/spreadsheets/d/\u003cSPREADSHEET_ID\u003e/edit`\n\n### Cloudflare Setup\n\n#### Configure wrangler.jsonc\n\nUpdate the `name` field in `wrangler.jsonc` to your project identifier:\n\n```jsonc\n{\n  \"name\": \"\u003cyour-project-name\u003e\",\n  // ...\n}\n```\n\nThis name is used as a prefix for your secrets in the secrets store.\n\n#### Secrets Store\n\nCreate a secrets store:\n\n```bash\npnpm exec wrangler secrets-store create \u003cyour-project-name\u003e-secrets --remote\n```\n\nSave the returned store ID. Add secrets to the store:\n\n```bash\npnpm exec wrangler secrets-store secret put \u003cstore-id\u003e \u003cyour-project-name\u003e_anthropic_api_key --remote\npnpm exec wrangler secrets-store secret put \u003cstore-id\u003e \u003cyour-project-name\u003e_telegram_bot_token --remote\npnpm exec wrangler secrets-store secret put \u003cstore-id\u003e \u003cyour-project-name\u003e_telegram_webhook_secret_token --remote\n```\n\nTo generate a webhook secret token:\n\n```bash\nopenssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32\n```\n\nSave this value — you'll need it for both the secrets store and Telegram webhook registration.\n\nUpdate `wrangler.jsonc` with your store ID and secret names:\n\n```jsonc\n{\n  \"secrets_store_secrets\": [\n    {\n      \"binding\": \"ANTHROPIC_API_KEY\",\n      \"store_id\": \"\u003cyour-store-id\u003e\",\n      \"secret_name\": \"\u003cyour-project-name\u003e_anthropic_api_key\"\n    },\n    {\n      \"binding\": \"TELEGRAM_BOT_TOKEN\",\n      \"store_id\": \"\u003cyour-store-id\u003e\",\n      \"secret_name\": \"\u003cyour-project-name\u003e_telegram_bot_token\"\n    },\n    {\n      \"binding\": \"TELEGRAM_WEBHOOK_SECRET_TOKEN\",\n      \"store_id\": \"\u003cyour-store-id\u003e\",\n      \"secret_name\": \"\u003cyour-project-name\u003e_telegram_webhook_secret_token\"\n    }\n  ]\n}\n```\n\n#### Wrangler Secrets\n\nSet the remaining secrets via `wrangler secret put`:\n\n```bash\npnpm exec wrangler secret put ALLOWED_USER_IDS\n# Enter: [\u003cuser-id-1\u003e, \u003cuser-id-2\u003e]\n\npnpm exec wrangler secret put ALLOWED_CHAT_IDS\n# Enter: [\u003cchat-id-1\u003e, \u003cchat-id-2\u003e]\n\npnpm exec wrangler secret put GOOGLE_SERVICE_ACCOUNT_CREDENTIALS\n# Enter: \u003cservice-account-json\u003e\n\npnpm exec wrangler secret put SPREADSHEET_ID\n# Enter: \u003cspreadsheet-id\u003e\n\npnpm exec wrangler secret put SPREADSHEET_BACKLOG_SHEET_NAME\n# Enter: \u003csheet-name\u003e\n```\n\n#### Deploy\n\n1. Generate Cloudflare bindings types:\n\n```bash\npnpm cf:typegen\n```\n\n2. Deploy:\n\n```bash\npnpm cf:deploy\n```\n\nNote the worker URL from the output (e.g., `https://\u003cyour-project-name\u003e.\u003caccount\u003e.workers.dev`).\n\n### Telegram Setup\n\n#### Creating the Bot\n\n1. Open Telegram and search for [@BotFather](https://t.me/BotFather)\n2. Send `/newbot` and follow the prompts to name your bot\n3. Save the bot token — add it to `\u003cyour-project-name\u003e_telegram_bot_token` (see [Secrets Store](#secrets-store) section for reference)\n4. Send `/setprivacy`, select your bot, then choose `Disable` to allow the bot to read group messages\n\n#### Registering the Webhook\n\nAfter deploying, register the webhook with Telegram:\n\n```bash\ncurl -X POST \"https://api.telegram.org/bot\u003cTELEGRAM_BOT_TOKEN\u003e/setWebhook\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://\u003cyour-worker-url\u003e/webhook\",\n    \"secret_token\": \"\u003cTELEGRAM_WEBHOOK_SECRET_TOKEN\u003e\"\n  }'\n```\n\n#### Getting User and Chat IDs\n\nSend `/start` to your bot — it will respond with your user ID and chat ID.\n\nFor group chats, add the bot to the group and send `/start` there to get the group's chat ID (groups have negative IDs).\n\n## Usage\n\nAdd the bot to a group or send a direct message, then send expense messages following this format:\n\n**Note**: The bot currently supports single messages only. Multi-message support is planned for the future.\n\n```\n{amount} {description} {temporal_ref} {payment_method} {payment_identifier} [categories]\n```\n\n### Examples\n\n```\n99 Pizzaria maneira hoje débito identificador-do-banco\n32.50 Besteirinhas no mercado 21/12/2025 pix identificador-do-banco\n150 Cinema com a família ontem crédito identificador-do-banco entertainment,food\n```\n\n### Payment Methods\n\n`débito` (debit), `crédito` (credit), `pix`, `boleto`\n\n### Temporal References\n\nThe bot understands temporal references in pt-BR and calculates the `occurredAt` date accordingly. These references are stripped from the final description:\n\n`hoje`, `ontem`, `anteontem`, `[N] dia(s) atrás`, `semana passada`, `mês passado`, `ano passado`, `segunda`, `terça`, `quarta`, `quinta`, `sexta`, `sábado`, `domingo`\n\nYou can also use explicit dates like `21/12/2025`.\n\n### Categories\n\nYou can pass one or more categories as the last argument, separated by comma. If not provided, the bot infers from the description.\n\n`appliances`, `candomble`, `car`, `credit-allowance`, `education`, `entertainment`, `food`, `gifts`, `health`, `market`, `monthly-expenses`, `pets`, `self-care`, `subscriptions`, `subscriptions-1-month`, `subscriptions-3-months`, `subscriptions-6-months`, `subscriptions-1-year`, `taxes`, `transport`, `work`\n\n## Monitoring\n\nMonitor real-time logs from your deployed worker:\n\n```bash\npnpm exec wrangler tail\n```\n\n## Local Development\n\nThis project is webhook-based and designed to run on Cloudflare Workers. Local development requires tunneling your connection (e.g., [ngrok](https://ngrok.com/), [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)).\n\n**Note**: If the tunnel URL changes, you must re-register the webhook with Telegram.\n\n### Setup\n\nCreate a `.dev.vars` file with all required variables:\n\n```bash\nALLOWED_USER_IDS=\"[\u003cuser-id-1\u003e, \u003cuser-id-2\u003e]\"\nALLOWED_CHAT_IDS=\"[\u003cchat-id-1\u003e, \u003cchat-id-2\u003e]\"\nGOOGLE_SERVICE_ACCOUNT_CREDENTIALS=\u003cservice-account-json\u003e\nSPREADSHEET_ID=\"\u003cspreadsheet-id\u003e\"\nSPREADSHEET_BACKLOG_SHEET_NAME=\"\u003csheet-name\u003e\"\nANTHROPIC_API_KEY=\u003cyour-anthropic-api-key\u003e\nTELEGRAM_BOT_TOKEN=\u003cyour-telegram-bot-token\u003e\nTELEGRAM_WEBHOOK_SECRET_TOKEN=\u003cyour-webhook-secret-token\u003e\n```\n\nStart the development server:\n\n```bash\npnpm cf:dev\n```\n\nTunnel your connection and register the webhook with the tunnel URL.\n\n## Available Scripts\n\n| Script | Description |\n|--------|-------------|\n| `pnpm cf:dev` | Start local development server |\n| `pnpm cf:deploy` | Deploy to Cloudflare Workers (minified) |\n| `pnpm cf:typegen` | Generate TypeScript types for Cloudflare bindings |\n| `pnpm code:lint` | Run Biome linter |\n| `pnpm code:lint:fix` | Run Biome linter with auto-fix |\n| `pnpm code:prettify` | Format code with Biome |\n| `pnpm code:typecheck` | Run TypeScript type checking |\n| `pnpm test` | Run test suite |\n| `pnpm test:coverage` | Run tests with coverage report |\n| `pnpm test:watch` | Run tests in watch mode |\n\n## TODO\n\n- [ ] Add changesets\n- [ ] Add commit hooks to integrate `pnpm code:lint`, `pnpm code:typecheck`, and `pnpm test`\n- [ ] Add GitHub Actions integration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhonnymoreira%2Ffinancial-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhonnymoreira%2Ffinancial-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhonnymoreira%2Ffinancial-bot/lists"}