Aminskid_bot

A full-stack application that integrates a Telegram bot with Plaid's banking API, allowing users to securely connect their bank accounts and view financial information directly through Telegram.

🌟 Features

Telegram Bot Interface
- Interactive command-based navigation
- User-friendly keyboard buttons
- Real-time account balance viewing
- Transaction history retrieval
- Secure user authentication
Plaid Banking Integration
- Secure bank account linking via Plaid Link
- Multi-account support
- Real-time balance fetching
- Transaction history (last 30 days)
- Webhook support for updates
Security & Privacy
- AES-256-GCM encryption for access tokens
- Environment-based configuration
- Rate limiting protection
- No credential storage
- Bank-level security through Plaid
Robust Backend
- RESTful API with Express.js
- PostgreSQL database with connection pooling
- Comprehensive error handling
- Winston logging system
- Docker support for easy deployment

🎯 How It Works - Telegram as Your GUI

Unlike traditional web apps, this bot uses Telegram as the entire user interface:

No frontend code needed - Telegram handles all UI rendering
Cross-platform - Works on iOS, Android, Web, Desktop automatically
Built-in auth - Telegram manages user identity
Rich UI - Buttons, keyboards, inline menus provided by Telegram
Users interact via chat - Simple commands like /balance or /transactions

The flow: User's Telegram App → Your Bot → Express API → PostgreSQL + Plaid → Bank Data

📘 For complete deployment instructions, see DEPLOYMENT.md

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18.x or higher
PostgreSQL 14.x or higher
npm or yarn package manager
Telegram Bot Token (from @BotFather)
Plaid Account (Sign up at Plaid.com)

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/telegram-plaid-bot.git
cd telegram-plaid-bot

2. Install Dependencies

npm install

3. Configure Environment Variables

Copy the example environment file and configure it:

cp .env.example .env

Edit .env with your credentials:

# Telegram Bot Token (get from @BotFather)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# Plaid Credentials (from Plaid Dashboard)
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret
PLAID_ENV=sandbox  # Use 'sandbox' for testing, 'production' for live

# Database Connection
DATABASE_URL=postgresql://user:password@localhost:5432/telegram_plaid

# Server Configuration
PORT=3000
API_BASE_URL=http://localhost:3000

# Security (IMPORTANT: Change these!)
ENCRYPTION_KEY=your_32_character_encryption_key_here
JWT_SECRET=your_jwt_secret_here

# Logging
LOG_LEVEL=info

Important Security Notes:

ENCRYPTION_KEY must be exactly 32 characters
Never commit .env file to version control
Use strong, random values for encryption keys
In production, use environment variables or secrets management

4. Set Up Database

Option A: Manual Setup

Create the database:

createdb telegram_plaid

Initialize the schema:

npm run init-db

Option B: Docker Setup (Recommended)

docker-compose up -d db

The database will be automatically initialized with the schema.

🏃 Running the Application

Development Mode

npm run dev

This uses nodemon for automatic reloading on file changes.

Production Mode

npm start

Using Docker

Build and run everything with Docker Compose:

docker-compose up -d

Stop the application:

docker-compose down

View logs:

docker-compose logs -f app

💬 Available Bot Commands

Command	Description
`/start`	Welcome message and initialization
`/link`	Connect your bank account via Plaid
`/balance`	View all connected account balances
`/transactions`	View recent transactions (last 30 days)
`/help`	Display help information

Keyboard Shortcuts

The bot also provides interactive buttons:

💳 Link Account - Same as /link
💰 Balance - Same as /balance
📊 Transactions - Same as /transactions
❓ Help - Same as /help

🔌 API Documentation

Endpoints

Create Link Token

POST /api/plaid/create-link-token
Content-Type: application/json

{
  "telegram_id": 123456789
}

Response:
{
  "success": true,
  "link_token": "link-sandbox-xxx",
  "expiration": "2024-01-01T12:00:00Z"
}

Exchange Public Token

POST /api/plaid/exchange-token
Content-Type: application/json

{
  "public_token": "public-sandbox-xxx",
  "telegram_id": 123456789
}

Response:
{
  "success": true,
  "institution_name": "Chase"
}

Get Accounts

GET /api/plaid/accounts/:telegram_id

Response:
{
  "success": true,
  "accounts": [
    {
      "name": "Plaid Checking",
      "balance": 100.00,
      "available": 95.00,
      "type": "depository",
      "subtype": "checking",
      "institution": "Chase"
    }
  ]
}

Get Transactions

GET /api/plaid/transactions/:telegram_id?start_date=2024-01-01&end_date=2024-01-31

Response:
{
  "success": true,
  "transactions": [
    {
      "transaction_id": "xxx",
      "name": "Uber",
      "amount": 12.50,
      "date": "2024-01-15",
      "category": ["Transportation"],
      "pending": false,
      "institution": "Chase"
    }
  ]
}

Webhook Handler

POST /api/webhook/plaid
Content-Type: application/json

{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "xxx"
}

Response:
{
  "received": true
}

Health Check

GET /health

Response:
{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

🧪 Testing in Sandbox

Plaid provides a sandbox environment for testing without real bank connections.

Sandbox Test Credentials

When using Plaid Link in sandbox mode:

Institution: Search for "First Platypus Bank"
Username: user_good
Password: pass_good
MFA: 1234 (if prompted)

Testing the Flow

Start the bot with /start
Use /link to get a link token
In a real implementation, you'd complete Plaid Link flow in a web interface
The bot will guide you through the connection process
Use /balance to view connected accounts
Use /transactions to see transaction history

🗂️ Project Structure

telegram-plaid-bot/
├── src/
│   ├── bot/                      # Telegram bot
│   │   ├── index.js              # Bot initialization
│   │   ├── commands/             # Command handlers
│   │   │   ├── start.js
│   │   │   ├── link.js
│   │   │   ├── balance.js
│   │   │   ├── transactions.js
│   │   │   └── help.js
│   │   └── middleware/           # Bot middleware
│   │       └── auth.js
│   ├── api/                      # Express API
│   │   ├── server.js             # Server setup
│   │   ├── routes/               # Route definitions
│   │   │   ├── plaid.js
│   │   │   └── webhook.js
│   │   └── controllers/          # Request handlers
│   │       ├── plaidController.js
│   │       └── webhookController.js
│   ├── services/                 # Business logic
│   │   ├── plaidService.js       # Plaid API wrapper
│   │   ├── userService.js        # User operations
│   │   └── encryptionService.js  # Token encryption
│   ├── models/                   # Data models
│   │   ├── User.js
│   │   └── PlaidConnection.js
│   ├── database/                 # Database setup
│   │   ├── connection.js         # DB connection pool
│   │   ├── init.sql              # Schema definition
│   │   └── init.js               # Initialization script
│   ├── config/                   # Configuration
│   │   └── index.js
│   ├── utils/                    # Utilities
│   │   ├── logger.js             # Winston logger
│   │   └── errorHandler.js       # Error handling
│   └── index.js                  # Application entry point
├── .env.example                  # Environment template
├── .gitignore
├── package.json
├── Dockerfile
├── docker-compose.yml
├── DEPLOYMENT.md                 # Complete deployment guide
└── README.md

🚀 Deployment

This application can be deployed to various platforms. The Telegram bot serves as your GUI - no frontend deployment needed!

Quick Deploy Options

Heroku (Easiest for beginners)

heroku create my-telegram-bot
heroku addons:create heroku-postgresql:mini
git push heroku main

DigitalOcean/VPS (Best for production)
- Install Node.js, PostgreSQL, PM2
- Clone repo, configure .env
- Start with pm2 start src/index.js
Docker (Recommended)
```
docker-compose up -d
```

Essential Steps for Any Platform

Get Telegram Bot Token: Talk to @BotFather on Telegram
Get Plaid Credentials: Sign up at Plaid.com
Set Environment Variables: Copy .env.example and fill in your credentials
Initialize Database: Run npm run init-db
Start Application: The bot will be your GUI automatically!

📘 For detailed deployment instructions (cloud, VPS, Docker, monitoring), see DEPLOYMENT.md

🔐 Security Best Practices

Implemented Security Measures

Token Encryption
- All Plaid access tokens encrypted with AES-256-GCM
- Unique initialization vectors for each encryption
- Authentication tags for integrity verification
Environment Security
- All secrets in environment variables
- .env excluded from version control
- Validation of required environment variables on startup
API Security
- Helmet.js for HTTP security headers
- CORS configured for controlled access
- Rate limiting (60 requests/minute per IP)
- Input validation on all endpoints
Database Security
- Parameterized queries prevent SQL injection
- Connection pooling with timeouts
- CASCADE deletes for data integrity
Error Handling
- No sensitive data in error messages
- Production mode hides stack traces
- Comprehensive logging without secrets
Production Recommendations
- Use HTTPS for all communications
- Set up SSL/TLS for database connections
- Implement proper secrets management (AWS Secrets Manager, etc.)
- Enable webhook signature verification
- Regular security audits
- Keep dependencies updated

🐛 Troubleshooting

Common Issues

Bot Not Responding

Verify TELEGRAM_BOT_TOKEN is correct
Check bot is running: docker-compose ps or check process
Review logs: docker-compose logs app or tail -f combined.log

Database Connection Errors

Ensure PostgreSQL is running
Verify DATABASE_URL is correct
Check database exists: psql -l
Run database initialization: npm run init-db

Plaid API Errors

Verify PLAID_CLIENT_ID and PLAID_SECRET
Check PLAID_ENV matches your credentials (sandbox/production)
Review Plaid error codes in logs
Ensure test credentials are correct for sandbox

Encryption Errors

ENCRYPTION_KEY must be exactly 32 characters
Don't change key after encrypting tokens (they'll be unreadable)
If needed, generate new key: node -e "console.log(crypto.randomBytes(16).toString('hex'))"

Rate Limiting

Default: 60 requests/minute
Adjust in src/api/server.js if needed
Wait or increase limit for legitimate high-volume use

Logs

Check application logs:

# Combined logs
tail -f combined.log

# Error logs only
tail -f error.log

# Docker logs
docker-compose logs -f app

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style
Add comments for complex logic
Update README for new features
Test thoroughly before submitting
Keep commits focused and descriptive

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Plaid for the banking API
Telegraf for the Telegram bot framework
Express for the web framework
All contributors and supporters

📞 Support

For issues and questions:

Open an issue on GitHub
Check the Plaid API Documentation
Review Telegraf Documentation

⚠️ Disclaimer

This bot handles sensitive financial information. Always:

Use in compliance with local regulations
Implement additional security measures for production
Never store or log sensitive user data
Follow Plaid's terms of service
Obtain proper user consent
Keep all dependencies updated

Happy Banking! 🏦

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github		.github
src		src
.env		.env
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
dotenv		dotenv
package-lock.json		package-lock.json
package.json		package.json
stripe		stripe

Folders and files

Latest commit

History

Repository files navigation

Aminskid_bot

🌟 Features

🎯 How It Works - Telegram as Your GUI

📋 Prerequisites

🚀 Installation

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Set Up Database

Option A: Manual Setup

Option B: Docker Setup (Recommended)

🏃 Running the Application

Development Mode

Production Mode

Using Docker

💬 Available Bot Commands

Keyboard Shortcuts

🔌 API Documentation

Endpoints

Create Link Token

Exchange Public Token

Get Accounts

Get Transactions

Webhook Handler

Health Check

🧪 Testing in Sandbox

Sandbox Test Credentials

Testing the Flow

🗂️ Project Structure

🚀 Deployment

Quick Deploy Options

Essential Steps for Any Platform

🔐 Security Best Practices

Implemented Security Measures

🐛 Troubleshooting

Common Issues

Bot Not Responding

Database Connection Errors

Plaid API Errors

Encryption Errors

Rate Limiting

Logs

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

📞 Support

⚠️ Disclaimer

About

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages