110 lines
3.1 KiB
Markdown
110 lines
3.1 KiB
Markdown
# Yaltopia Telegram Bot
|
||
|
||
A feature-rich Telegram bot for property listings built with TypeScript and organized using a feature-first architecture.
|
||
|
||
## Features
|
||
|
||
- 📱 **Phone-based Authentication**: Users share phone number to login/register
|
||
- 🏠 **Property Management**: Browse, view, and add properties
|
||
- 👤 **User Registration**: Complete registration flow with validation
|
||
- 🔐 **Secure Login**: Password-based authentication for existing users
|
||
- 📋 **Property Listings**: View all available properties
|
||
- 🏘️ **My Properties**: Manage user's own property listings
|
||
|
||
## Architecture
|
||
|
||
This project follows a **feature-first approach** for better scalability:
|
||
|
||
```
|
||
src/
|
||
├── shared/ # Shared utilities and services
|
||
│ ├── types/ # Common TypeScript interfaces
|
||
│ └── services/ # Shared services (API, Session)
|
||
├── features/ # Feature modules
|
||
│ ├── auth/ # Authentication feature
|
||
│ └── properties/ # Property management feature
|
||
└── bot/ # Bot orchestration
|
||
```
|
||
|
||
## Setup
|
||
|
||
1. **Install dependencies:**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **Environment setup:**
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Edit `.env` and add your Telegram bot token:
|
||
```
|
||
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
||
API_BASE_URL=http://localhost:3000/api
|
||
```
|
||
|
||
3. **Build the project:**
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
4. **Start the bot:**
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
For development:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
## Bot Flow
|
||
|
||
### 1. Authentication Flow
|
||
- User starts with `/start`
|
||
- Bot requests phone number
|
||
- If phone exists → Login with password
|
||
- If new user → Registration flow (name, email, password, confirm)
|
||
|
||
### 2. Main Menu (After Login)
|
||
- 🏘️ **Browse Properties**: View all available properties
|
||
- 🏠 **My Properties**: View user's own listings
|
||
- ➕ **Add Property**: Create new property listing
|
||
- 👤 **Profile**: View user profile information
|
||
|
||
### 3. Property Creation Flow
|
||
- Title → Description → Type (Rent/Sale) → Price → Area → Rooms → Toilets → Subcity → House Type
|
||
|
||
## API Integration
|
||
|
||
The bot integrates with your existing backend APIs:
|
||
|
||
- `POST /telegram-auth/telegram-register` - User registration
|
||
- `POST /telegram-auth/telegram-login` - User login
|
||
- `GET /telegram-auth/phone/{phone}/check` - Check phone existence
|
||
- `GET /telegram-auth/validate-email/{email}` - Email validation
|
||
- `GET /listings` - Get all properties
|
||
- `POST /listings` - Create new property
|
||
|
||
## Development
|
||
|
||
### Scripts
|
||
- `npm run build` - Compile TypeScript
|
||
- `npm run dev` - Run in development mode with ts-node
|
||
- `npm run watch` - Watch mode for TypeScript compilation
|
||
- `npm start` - Run compiled JavaScript
|
||
|
||
### Adding New Features
|
||
|
||
1. Create feature directory in `src/features/`
|
||
2. Add service class for API interactions
|
||
3. Add handler class for bot interactions
|
||
4. Integrate in main bot class (`src/bot/bot.ts`)
|
||
|
||
## Getting Your Bot Token
|
||
|
||
1. Message [@BotFather](https://t.me/botfather) on Telegram
|
||
2. Use `/newbot` command
|
||
3. Follow the setup process
|
||
4. Copy the token to your `.env` file |