Imported from kdv1995/telegram-bot (AGENTS.md). Install upstream with npx skills add kdv1995/telegram-bot. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Source code lives in src/ (NestJS modules, controllers, services).
  • Example: src/app.module.ts, src/app.controller.ts, src/app.service.ts.
• Unit tests colocate with source as *.spec.ts (see src/app.controller.spec.ts).
• End-to-end tests live in test/ as *.e2e-spec.ts (see test/app.e2e-spec.ts).
• Build output goes to dist/ (generated). Config: tsconfig*.json, nest-cli.json.

Build, Test, and Development Commands

• npm run start — start the app.
• npm run start:dev — start with watch/reload for local dev.
• npm run start:prod — run compiled app from dist/.
• npm run build — compile TypeScript to dist/.
• npm run test — run unit tests (Jest).
• npm run test:e2e — run E2E tests (Supertest + Jest).
• npm run test:cov — generate coverage report in coverage/.
• npm run lint — ESLint with autofix.
• npm run format — Prettier format src/ and test/.

Coding Style & Naming Conventions

• Language: TypeScript (ES2023 target). Use NestJS patterns.
• Formatting: Prettier (.prettierrc: singleQuote, trailingComma=all).
• Linting: ESLint + typescript-eslint + prettier integration. Fix warnings before PR.
• File names: feature.controller.ts, feature.service.ts, feature.module.ts (kebab/dot style).
• Classes/Enums: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE_CASE.

Testing Guidelines

• Framework: Jest (ts-jest).
• Unit tests: colocated *.spec.ts; E2E: test/*.e2e-spec.ts using supertest.
• Aim for meaningful coverage (target ≥80%). Add tests for new behavior and bug fixes.
• Run npm run test and npm run test:e2e locally; ensure they pass.

Commit & Pull Request Guidelines

• Use clear commits; Conventional Commits encouraged: feat:, fix:, chore:, refactor:, test:.
• PRs must include: concise description, rationale, testing notes/commands, and linked issues.
• Keep changes focused; update or add tests and docs when behavior changes.

Security & Configuration Tips

• Do not commit secrets. Use environment variables (e.g., PORT) via a local .env ignored by Git.
• Validate inputs at controller/service boundaries. Handle async errors; avoid unhandled promise rejections.

Telegram Bot Integration (node-telegram-bot-api)

• Library: node-telegram-bot-api. Bot is initialized in TelegramService.
• Env vars: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_URL, optional TELEGRAM_WEBHOOK_SECRET, TELEGRAM_USE_POLLING.
• Webhook (default in prod): POST /telegram/webhook with 1MB JSON limit (see src/main.ts). If TELEGRAM_WEBHOOK_SECRET is set, header x-telegram-bot-api-secret-token is required. Use POST /telegram/set-webhook to register with Telegram.
• Polling (dev fallback): If TELEGRAM_USE_POLLING=true or TELEGRAM_WEBHOOK_URL is unset and NODE_ENV != production, the bot starts long polling automatically.
• Defaults: /start welcomes; any non-command text is echoed.

Health Endpoints

• Liveness: GET /health → { ok, telegramConfigured, timestamp } (always 200).
• Readiness: GET /health/ready → 200 only when Telegram is configured, else 503.
• Metrics: GET /health/metrics → JSON with process/OS stats for diagnostics.

Env Loading

• .env support is enabled via @nestjs/config (global). Variables from .env are available as process.env.* after app bootstrap.
• Example:
  • Copy .env.example to .env and set values.
  • npm run start:dev then reads PORT, TELEGRAM_* automatically.