Development Guide

This guide provides information for developers who want to extend or modify the CopperX Payout Bot.

Development Environment Setup

Prerequisites

Node.js (v16 or higher)

npm or pnpm

Redis (local or cloud)

Telegram Bot Token (from BotFather)

CopperX API credentials

Text editor or IDE (VSCode recommended)

Local Development Setup

Clone the repository

Install dependencies

Configure environment variables

Copy .env.example to .env (if available)

Otherwise create a new .env file with the required variables:

BOT_TOKEN=your_telegram_bot_token
BOT_USER=https://t.me/your_bot_username
COPPERX_API_KEY=your_copperx_api_key
REDIS_DATABASE_URL=your_redis_connection_string
SERVER_URL=https://your-webhook-url.com
PORT=3000
NODE_ENV=development
PUSHER_KEY=your_pusher_key
PUSHER_CLUSTER=your_pusher_cluster
COPPERX_API_URL=https://income-api.copperx.io

Set up ngrok for local development

Since Telegram requires a public HTTPS endpoint for webhooks, you'll need ngrok or a similar tool for local development:

Then update your .env file with the ngrok HTTPS URL:

SERVER_URL=https://your-ngrok-url.ngrok.io

Set up the webhook and commands

Project Structure

The project follows a modular structure for maintainability and separation of concerns:

src/
├── app.ts                 # Express application setup
├── server.ts              # Server startup
├── bot/                   # Telegram bot-specific code
│   ├── webhook.ts         # Webhook handler
│   ├── handlers/          # Command handlers
│   ├── messages/          # Message templates
│   ├── operations/        # Command and callback operations
│   └── utils/             # Bot-specific utilities
├── constants/             # Application constants
├── services/              # Business logic services
├── types/                 # TypeScript type definitions
└── utils/                 # Shared utilities
    ├── config/            # Configuration management
    ├── copperxApi/        # CopperX API clients
    ├── database/          # Database utilities
    ├── exceptions/        # Custom exceptions
    ├── logger/            # Logging utilities
    ├── middleware/        # Express middleware
    ├── rate-limit/        # Rate limiting utilities
    ├── session/           # Session management
    └── telegram/          # Telegram API utilities

Key Components

1. Webhook Handler

The webhook handler (src/bot/webhook.ts) is the entry point for all Telegram updates. It:

Receives and validates webhook requests

Extracts chat ID and applies rate limiting

Routes updates to appropriate handlers based on type

Manages error handling and response codes

2. Command System

Commands are processed through:

Command Operations (src/bot/operations/command.operations.ts): Maps command strings to handler functions

Command Handlers (src/bot/handlers/): Implement the logic for each command

Command Enum (src/constants/bot-commands.ts): Defines available commands

To add a new command:

Add your command to CommandsEnum

Create a handler function in the appropriate file under src/bot/handlers/

Add the command to commandOperations in src/bot/operations/command.operations.ts

Add your command to BotCommands to make it visible in the Telegram command menu

Run npm run setup to update the bot commands in Telegram

Example command handler:

3. Callback System

Callbacks are processed through:

Callback Operations (src/bot/operations/callback.operations.ts): Maps callback data to handler functions

Callback Handlers: Often included in the same file as related command handlers

Callback Enum (src/constants/callback.enum.ts): Defines available callbacks

To add a new callback:

Add your callback to CallbackEnum

Create a handler function for the callback

Add the callback to callbackOperations or handle it in handleCallback

Example callback handler:

For parameterized callbacks, add a case in the handleCallback function:

4. Services

Services encapsulate business logic and API interactions:

AuthService: Handles user authentication

WalletService: Manages wallet operations

TransferService: Handles transfer operations

NotificationService: Manages real-time notifications

Services typically follow the singleton pattern:

5. Session Management

Sessions are managed by SessionService using Redis:

User state is tracked using the UserState enum in src/types/session.types.ts.

Testing

Unit Testing

Unit tests can be written using Jest or Mocha. Example test setup:

Manual Testing

For manual testing:

Start the bot in development mode: npm run dev

Expose your localhost with ngrok

Set up the webhook: npm run setup

Test commands in Telegram

Deployment

Railway Deployment

The bot is configured for deployment on Railway:

Connect your GitHub repository to Railway

Configure environment variables in Railway

Railway will use the settings in railway.json for deployment

Custom deployment configurations can be set in railway.json:

{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm run start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Best Practices

Code Style

Follow TypeScript best practices for type safety

Use async/await for asynchronous operations

Structure code in a modular, single-responsibility pattern

Add JSDoc comments for complex functions

Use constants for magic values

Error Handling

Always handle errors properly:

Logging

Use the LoggerService for consistent logging:

Security Considerations

Validate all user input

Use rate limiting to prevent abuse

Store sensitive information in environment variables

Keep dependencies updated

Follow the principle of least privilege

Contributing

When contributing to the project:

Create a feature branch from main

Make your changes following the project's code style

Update documentation as necessary

Add or update tests when possible

Submit a pull request with a clear description of changes

Request review from the project maintainers

Additional Resources

Telegram Bot API Documentation

CopperX API Documentation

TypeScript Documentation

Express.js Documentation

Redis Documentation

development

Development Guide#

Development Environment Setup#

Prerequisites#

Local Development Setup#

Project Structure#

Key Components#

1. Webhook Handler#

2. Command System#

3. Callback System#

4. Services#

5. Session Management#

Testing#

Unit Testing#

Manual Testing#

Deployment#

Railway Deployment#

Best Practices#

Code Style#

Error Handling#

Logging#

Security Considerations#

Contributing#

Additional Resources#