TimoCheck - Theo dõi giao dịch Timo

Theo dõi giao dịch Timo "Hũ" (piggy bank) và gửi thông báo đến nhóm chat hoặc tài khoản Telegram khi có giao dịch mới.

Công cụ này hoàn toàn vibe code cùng MiniMax-M2.1.

Mình không đảm bảo nó hoạt động một cách hiệu quả với tất cả mọi người nhưng đến hiện tại nó hoạt động tốt và phục vụ được nhu cầu của mình :)

Tính năng

Tự động giám sát bằng cron jobs
Theo dõi 3 ngày gần nhất: "Hôm nay", "Hôm qua", "Ngày hôm trước"
Thông báo Telegram cho giao dịch mới
Khử trùng lặp bằng Cloudflare KV storage
API để trigger thủ công và quản lý trạng thái
Chế độ development với local testing

Yêu cầu

Node.js 18+
Tài khoản Cloudflare (miễn phí) với Workers & KV
Telegram bot (tùy chọn, để nhận thông báo)

Hướng dẫn cài đặt

1. Clone và cài đặt dependencies

git clone <your-repo-url>
cd timocheck
npm install

2. Lấy thông tin xác thực

2.1. Tạo Telegram Bot (tùy chọn)

Nếu muốn nhận thông báo qua Telegram:

Mở Telegram, tìm @BotFather
Gửi lệnh /newbot và làm theo hướng dẫn
Copy Bot Token (dạng: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
Tìm @userinfobot, gửi bất kỳ tin nhắn nào
Copy Chat ID của bạn (số dạng: 782967716)

2.2. Lấy HASH_VERIFY_CODE từ Timo

Đây là mã xác thực để truy cập API Timo "Hũ" của bạn:

Mở Timo app hoặc truy cập share.timo.vn
Đăng nhập và vào trang "Hũ" của bạn
Mở DevTools (F12) → Tab Network
Reload trang hoặc click vào một giao dịch
Tìm request đến moneypots/public/txn
Xem Request Payload → Copy giá trị hashVerifyCode

{
  "hashVerifyCode": "95cd0b67e089a6a339c33eb372396ad...",
  "offset": 0
}

Lưu ý: HASH_VERIFY_CODE có thể thay đổi theo thời gian. Nếu worker báo lỗi 401, bạn cần lấy lại mã mới.

3. Cấu hình Development (Local)

Tạo file .dev.vars ở thư mục gốc:

# Mã xác thực Timo (bắt buộc)
HASH_VERIFY_CODE="95cd0b67e089a6a339c33eb372396ad..."

# Telegram credentials (tùy chọn)
TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
TELEGRAM_CHAT_ID="782967716"

Quan trọng: File .dev.vars đã được thêm vào .gitignore, không bao giờ commit lên Git!

4. Cấu hình Production (Cloudflare)

4.1. Tạo KV Namespace

KV namespace dùng để lưu trạng thái giao dịch đã thấy:

# Tạo KV namespace cho production
npx wrangler kv:namespace create "KV_STATE"

# Tạo KV namespace cho preview (dev)
npx wrangler kv:namespace create "KV_STATE" --preview

Output sẽ như:

[[kv_namespaces]]
binding = "KV_STATE"
id = "91fd696e80ff41f2b98961129ba6be23"
preview_id = "abc123def456..."

Cập nhật id và preview_id vào file wrangler.toml.

4.2. Cấu hình Secrets

Tất cả thông tin nhạy cảm phải dùng secrets, KHÔNG để trong wrangler.toml:

# Set secrets cho production
npx wrangler secret put HASH_VERIFY_CODE
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put TELEGRAM_CHAT_ID

Mỗi lệnh sẽ hỏi bạn nhập giá trị. Copy-paste từ .dev.vars.

4.3. Kiểm tra wrangler.toml

File wrangler.toml chỉ chứa config công khai:

name = "timocheck"
main = "src/worker.ts"
compatibility_date = "2026-01-29"

[triggers]
crons = ["*/1 * * * *"]  # Kiểm tra mỗi phút

[[kv_namespaces]]
binding = "KV_STATE"
id = "91fd696e80ff41f2b98961129ba6be23"        # Production KV ID
preview_id = "abc123def456..."                   # Development/Preview KV ID

[vars]
# Secrets được cấu hình qua wrangler secret put
# KHÔNG để thông tin nhạy cảm ở đây!

Giải thích:

id: KV namespace cho production (deploy thật)

preview_id: KV namespace cho dev/preview (local testing)

Phát triển (Development)

Chạy local dev server

npx wrangler dev

Worker sẽ chạy tại http://localhost:8787

Test các endpoints

# Health check
curl http://localhost:8787/

# Trigger kiểm tra giao dịch thủ công
curl -X POST http://localhost:8787/check

# Xem danh sách giao dịch đã thấy
curl http://localhost:8787/state

# Reset trạng thái (xóa tất cả giao dịch đã lưu)
curl -X POST http://localhost:8787/reset

Deploy lên Production

Deploy lần đầu

npx wrangler deploy

Worker sẽ deploy và chạy với cron schedule đã cấu hình.

Update sau khi thay đổi code

npx wrangler deploy

Update secrets

npx wrangler secret put HASH_VERIFY_CODE

Update chỉ cron schedule

npx wrangler triggers deploy

Cấu hình Cron Schedule

Chỉnh sửa trong wrangler.toml:

Biểu thức	Ý nghĩa
`/1 * * *`	Mỗi phút
`/5 * * *`	Mỗi 5 phút
`/15 * * *`	Mỗi 15 phút
`0 * * * *`	Mỗi giờ

API Endpoints

Method	Path	Mô tả
GET	`/`	Health check
POST	`/check`	Trigger kiểm tra giao dịch thủ công
GET	`/state`	Xem giao dịch đã thấy
POST	`/reset`	Reset trạng thái (xóa tất cả)

Admin Dashboard

TimoCheck bao gồm giao diện web admin để quản lý cấu hình và giám sát hệ thống một cách dễ dàng.

Truy cập Dashboard

Development (Local):

npx wrangler dev

Sau đó mở: http://localhost:8787/admin

Production: Truy cập: https://your-worker.workers.dev/admin

Cài đặt Admin Dashboard

1. Cấu hình mật khẩu admin:

npx wrangler secret put ADMIN_PASSWORD
npx wrangler secret put SESSION_SECRET

2. Cấu hình Cloudflare API (để cập nhật config trong dashboard):

Tạo API token tại: https://dash.cloudflare.com/profile/api-tokens

Quyền cần thiết:

Account > Workers Scripts > Edit

npx wrangler secret put CLOUDFLARE_API_TOKEN
npx wrangler secret put CLOUDFLARE_ACCOUNT_ID
npx wrangler secret put CLOUDFLARE_WORKER_NAME

3. Thêm vào .dev.vars để test local:

ADMIN_PASSWORD="your-password"
SESSION_SECRET="random-secret-key-32-chars"
CLOUDFLARE_API_TOKEN="your-token"
CLOUDFLARE_ACCOUNT_ID="your-account-id"
CLOUDFLARE_WORKER_NAME="timocheck"

Tính năng Dashboard

Giám sát real-time: Xem thống kê giao dịch và tình trạng hệ thống
Quản lý cấu hình: Cập nhật secrets trực tiếp từ UI
Quick actions: Trigger kiểm tra thủ công, test Telegram, reset state
Lịch sử giao dịch: Xem các giao dịch gần đây với timestamps
Biểu đồ hoạt động: Biểu đồ khối lượng giao dịch 24 giờ

Bảo mật Dashboard

Xác thực dựa trên session với HMAC-SHA256
HttpOnly, Secure cookies với SameSite protection
Rate limiting: 5 lần thử đăng nhập / 15 phút
Session hết hạn sau 24 giờ

Cách hoạt động

Giám sát giao dịch

Worker theo dõi giao dịch từ 3 ngày gần nhất:

Hôm nay - Giao dịch hôm nay
Hôm qua - Giao dịch hôm qua
Ngày hôm trước - Giao dịch ngày kia

Mỗi giao dịch được xác định bằng: mô tả + số tiền

Hệ thống khử trùng lặp đảm bảo mỗi giao dịch chỉ được thông báo một lần.

Ví dụ output CLI

[Timo] Available groups:
  - Hôm nay: 3 transactions [MONITORED]
  - Hôm qua: 5 transactions [MONITORED]
  - Ngày hôm trước: 2 transactions [MONITORED]
[Check] Total: 10, New: 0
[Telegram] Sent 0 notification(s)

Format thông báo Telegram

📥 Tên Hũ - Giao dịch mới

💰 Số tiền: +16.000 VND
📋 Tiêu đề: Từ NGUYEN NGOC DINH
📝 Mô tả: Nguyen Ngoc Dinh chuyen tien QR

Troubleshooting

Lỗi: "Failed to fetch transactions" (401)

Nguyên nhân: HASH_VERIFY_CODE đã hết hạn hoặc sai.

Giải pháp:

Lấy lại HASH_VERIFY_CODE mới (xem mục 2.2)

Update secret:

npx wrangler secret put HASH_VERIFY_CODE

Không nhận được thông báo Telegram

Kiểm tra:

Bot token và Chat ID đã đúng chưa?
Đã /start với bot chưa? (Bắt buộc trước khi bot có thể gửi tin)
Xem logs:
```
npx wrangler tail
```

KV namespace not found

Nguyên nhân: Chưa tạo KV namespace hoặc ID sai.

Giải pháp:

Tạo namespace (xem mục 4.1)
Cập nhật đúng ID vào wrangler.toml

Giao dịch bị thông báo nhiều lần

Nguyên nhân: KV state bị reset hoặc mất dữ liệu.

Giải pháp: Dùng endpoint /reset để xóa và bắt đầu lại:

curl -X POST https://your-worker.workers.dev/reset

Cấu trúc dự án

timocheck/
├── src/
│   ├── config.ts          # Config và types
│   ├── fetch-today.ts     # CLI tool để test fetch
│   ├── index.ts           # CLI entry point
│   ├── monitor.ts         # Logic giám sát chính
│   ├── notifier.ts        # Telegram notifications
│   ├── timo.ts            # Timo API client
│   ├── types.ts           # TypeScript types
│   └── worker.ts          # Cloudflare Worker entry
├── wrangler.toml          # Cloudflare Workers config
├── .dev.vars              # Dev environment (KHÔNG commit!)
├── .gitignore             # Git ignore rules
├── tsconfig.json          # TypeScript config
└── package.json           # Dependencies

Bảo mật

✅ .dev.vars được git ignore
✅ Production dùng Wrangler secrets
✅ Không có credentials trong source code
✅ KV namespace ID là public (an toàn)

Lưu ý: KHÔNG bao giờ commit file .dev.vars hoặc file chứa secrets!

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
dist		dist
docs		docs
landing		landing
src		src
.dev.vars.example		.dev.vars.example
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
wrangler.toml		wrangler.toml

Folders and files

Latest commit

History

Repository files navigation

TimoCheck - Theo dõi giao dịch Timo

Tính năng

Yêu cầu

Hướng dẫn cài đặt

1. Clone và cài đặt dependencies

2. Lấy thông tin xác thực

2.1. Tạo Telegram Bot (tùy chọn)

2.2. Lấy HASH_VERIFY_CODE từ Timo

3. Cấu hình Development (Local)

4. Cấu hình Production (Cloudflare)

4.1. Tạo KV Namespace

4.2. Cấu hình Secrets

4.3. Kiểm tra wrangler.toml

Phát triển (Development)

Chạy local dev server

Test các endpoints

Deploy lên Production

Deploy lần đầu

Update sau khi thay đổi code

Update secrets

Update chỉ cron schedule

Cấu hình Cron Schedule

API Endpoints

Admin Dashboard

Truy cập Dashboard

Cài đặt Admin Dashboard

Tính năng Dashboard

Bảo mật Dashboard

Cách hoạt động

Giám sát giao dịch

Ví dụ output CLI

Format thông báo Telegram

Troubleshooting

Lỗi: "Failed to fetch transactions" (401)

Không nhận được thông báo Telegram

KV namespace not found

Giao dịch bị thông báo nhiều lần

Cấu trúc dự án

Bảo mật

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages