# Telegram User Account Gateway

A production-grade REST API + Webhook gateway for managing Telegram user accounts via TDLib (not Bot API). Supports multi-tenant, multi-account management with independent proxies, message queue, rate limiting, and audit logging.

## Architecture

- **Runtime**: Node.js 20+ with TypeScript
- **Framework**: NestJS 11.x
- **Database**: PostgreSQL 16 (TypeORM)
- **Cache/Queue**: Redis 7 + BullMQ
- **TDLib**: tdjson via worker_threads
- **Auth**: JWT (Bearer tokens)
- **API Docs**: Swagger at `/api/docs`

## Quick Start

```bash
# Copy environment config
cp .env.example .env

# Start infrastructure
docker-compose -f docker/docker-compose.yml up -d postgres redis

# Install dependencies
npm install

# Run migrations
npm run migration:run

# Start development server
npm run start:dev
```

## Docker Compose

```bash
# Start all services
docker compose --env-file .env -f docker/docker-compose.yml up -d --build
```

See [DEPLOYMENT.md](./DEPLOYMENT.md) for production setup, readiness checks,
persistent data, and Windows WSL requirements.

When used by 灵犀跨境, also read the repository-level
[integration guide](../docs/TELEGRAM-GATEWAY.md).

## API Endpoints

### Admin
- `GET /api/admin/health` - Health check (public)
- `GET /api/admin/metrics` - Application metrics
- `GET /api/admin/status` - TDLib client status

### Auth
- `POST /api/auth/register` - Register user (public)
- `POST /api/auth/login` - Login (public)

### Tenants
- `POST /api/tenants` - Create tenant
- `GET /api/tenants` - List tenants
- `GET /api/tenants/:id` - Get tenant
- `PUT /api/tenants/:id` - Update tenant
- `DELETE /api/tenants/:id` - Delete tenant

### TG Accounts
- `POST /api/tg-accounts` - Create Telegram account
- `GET /api/tg-accounts` - List accounts
- `GET /api/tg-accounts/:id` - Get account
- `DELETE /api/tg-accounts/:id` - Remove account

### TG Account Authorization
- `POST /api/tg-accounts/:id/auth/phone` - Set phone number
- `POST /api/tg-accounts/:id/auth/code` - Submit verification code
- `POST /api/tg-accounts/:id/auth/password` - Submit 2FA password
- `POST /api/tg-accounts/:id/auth/logout` - Logout

### Chats & Messages
- `GET /api/tg-accounts/:id/chats` - List chats
- `GET /api/tg-accounts/:id/chats/:chatId/history` - Chat history
- `POST /api/tg-accounts/:id/messages/send` - Send message (queued)
- `POST /api/tg-accounts/:id/messages/send-direct` - Send message (direct)
- `POST /api/tg-accounts/:id/messages/pin` - Pin a message
- `POST /api/tg-accounts/:id/messages/unpin` - Unpin a message
- `POST /api/tg-accounts/:id/messages/action` - Send typing/chat action
- `GET /api/tg-accounts/:id/messages/:chatId/:messageId/link` - Get message link

### Contacts, Sessions & Groups
- `GET /api/tg-accounts/:id/contacts/search?q=...` - Search by phone, username, or general query
- `GET /api/tg-accounts/:id/dialogs/sessions` - List active Telegram sessions
- `POST /api/tg-accounts/:id/dialogs/sessions/:sessionId/terminate` - Terminate session
- `POST /api/tg-accounts/:id/dialogs/users/:userId/block` - Block user
- `POST /api/tg-accounts/:id/dialogs/users/:userId/unblock` - Unblock user
- `POST /api/tg-accounts/:id/groups/join-by-invite-link` - Join via invite link
- `PUT /api/tg-accounts/:id/groups/:chatId/title` - Change group title
- `PUT /api/tg-accounts/:id/groups/:chatId/photo` - Change/remove group photo

### Webhooks
- `POST /api/tg-accounts/:id/webhooks` - Create webhook
- `GET /api/tg-accounts/:id/webhooks` - List webhooks

### Operations
- `GET /api/admin/audit-logs` - Query tenant-scoped audit logs
- `GET /api/admin/audit-logs/accounts/:accountId` - Query account audit logs
- `GET /api/admin/rate-limits/:accountId` - Get account rate-limit statistics

## Environment Variables

See `.env.example` for all available configuration options.

## License

MIT