whatsapp-spend-tracker

KO | EN

gitlite — search

#vue #windows #llm #privacy #ai-agents #golang #agent #data-science #codex #ui

whatsapp-spend-tracker

(★ 9)

An agent that helps you manage daily expenses through whatsapp with Kapso and Chat SDK

File Explorer

ZIP Download

- - ci.yml
- demo.gif
- bot.ts
- env.ts
- format.ts
- handler.ts
- index.ts
- media.ts
- parser.ts
- store.ts
- time.ts
- types.ts
- user.ts
- fakes.ts
- handler.test.ts
- parser.test.ts
- store.test.ts
- webhook.test.ts
.env.example
.gitignore
biome.json
LICENSE
package-lock.json
package.json
README.md
tsconfig.build.json
tsconfig.json
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A tiny open-source WhatsApp expense tracker that showcases the Kapso Chat SDK adapter.

Send a WhatsApp message like `Spent 3k CLP on a Diet Coke`, a voice note, or a receipt photo. The bot parses the expense with AI, stores it in Upstash Redis, and replies with what it saved plus your daily total.

This repo is intentionally small so teams can fork it and turn it into their own WhatsApp AI app.

## Demo

![Kapso Spend Tracker demo](https://raw.githubusercontent.com/gokapso/whatsapp-spend-tracker/master/docs/demo.gif)

## What It Shows

- Receiving Kapso WhatsApp webhooks through `@kapso/chat-adapter`
- Replying with Chat SDK `thread.post()`
- Reading text, voice, and image attachments from Chat SDK messages
- Parsing expenses with the AI SDK and OpenAI
- Storing user expense state in Upstash Redis

## Stack

- Runtime: Node.js 20.19+
- API: Hono
- WhatsApp: Chat SDK + Kapso adapter
- AI: AI SDK + OpenAI
- Storage: Upstash Redis
- Tests: Vitest
- Formatting/linting: Biome

## Setup

```bash
npm install
cp .env.example .env
```

Fill in:

```bash
KAPSO_API_KEY=
KAPSO_PHONE_NUMBER_ID=
KAPSO_WEBHOOK_SECRET=
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
OPENAI_API_KEY=
USER_ID_SALT=
```

The app loads `.env` automatically in both `npm run dev` and `npm start`.

Generate `USER_ID_SALT` with:

```bash
openssl rand -hex 32
```

Optional defaults:

```bash
DEFAULT_CURRENCY=CLP
DEFAULT_TIMEZONE=America/Santiago
OPENAI_EXPENSE_MODEL=gpt-4o-mini
KAPSO_BOT_USERNAME=spend-tracker
```

## Run Locally

```bash
npm run dev
```

Expose the local server with a tunnel:

```bash
npx localtunnel --port 3000
```

Configure your Kapso webhook:

- Endpoint: `https://your-public-url/webhooks/kapso`
- Secret: same value as `KAPSO_WEBHOOK_SECRET`
- Event: `whatsapp.message.received`

Health check:

```bash
curl http://localhost:3000/health
```

## WhatsApp Commands

- `Spent 3k CLP on a Diet Coke`
- Send a voice note saying what you spent
- Send a receipt photo
- `today`
- `week`
- `undo`
- `help`

The bot auto-saves valid expenses. If the amount or description is unclear, it asks a short clarification and does not save.

## Redis Keys

- `expense:{expenseId}` stores the expense JSON
- `user:{userId}:expenses` indexes expense ids by purchase timestamp
- `user:{userId}:last-expense` stores the latest saved id for `undo`
- `dedupe:{messageId}` prevents duplicate webhook processing

User ids are derived from WhatsApp ids with HMAC and `USER_ID_SALT`, so raw phone numbers are not used as Redis keys.

## Develop

```bash
npm run lint
npm run typecheck
npm test
```

## Fork Ideas

- Add categories and monthly budgets
- Add Slack, Telegram, or web chat adapters
- Export CSV files
- Send weekly summaries
- Add a small dashboard
- Encrypt stored expense content for production privacy requirements

## License

MIT

whatsapp-spend-tracker

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

whatsapp-spend-tracker

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README