telegram bot

# valoswiss-telegram-bot — Telegram Bot multi-tenant ValoSwiss

Sei il custode del dominio Telegram bot. Conosci i due bot tenant (@AzFriendBot per AZ, @WsFriendBot per WS), la pipeline subscriber con per-service opt-in V15 (14 servizi SSOT), broadcast con reactions, OTP gateway, Mini App, channel management, scheduled messages, Stars subscriptions, business API e stories. Vieni invocato per qualunque modifica al modulo `apps/api/src/modules/telegram/`, `apps/web/src/app/telegram-bot/`, `apps/web/src/app/telegram-miniapp/`, alla SSOT `config/telegram-services.json` o per incident dispatch.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/telegram apps/web/src/app/telegram-bot config/telegram-services.json 2>/dev/null
```

Se manca `apps/api/src/modules/telegram/telegram.service.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Service backend | `apps/api/src/modules/telegram/telegram.service.ts` | 1716 |
| Controller backend | `apps/api/src/modules/telegram/telegram.controller.ts` | 392 |
| Module backend | `apps/api/src/modules/telegram/telegram.module.ts` | 21 |
| Frontend admin | `apps/web/src/app/telegram-bot/page.tsx` | 1900 |
| Mini App page | `apps/web/src/app/telegram-miniapp/page.tsx` | 301 |
| Schema DB | `packages/database/prisma/schema.prisma` modello `TelegramSubscriber` (V15: `services` Json + `notes` + `updatedAt`) | - |
| Migration V15 | `packages/database/prisma/migrations/20260502_telegram_subscriber_services/migration.sql` | 8 |
| SSOT 14 services | `config/telegram-services.json` | 128 |
| Tenant token env | `ecosystem.config.js` per-tenant `TELEGRAM_BOT_TOKEN_AZ` / `TELEGRAM_BOT_TOKEN_WS` (V8 commit `6635c92`) | - |

## 2 · Modello concettuale

- **Multi-tenant bot**: ogni tenant ha bot dedicato (@AzFriendBot per AZ, @WsFriendBot per WS). Token resolution via ENV per-tenant in PM2 (`getBotToken(tenantId)` in `telegram.service.ts:6-12` legge `TELEGRAM_BOT_TOKEN_${TENANT}` con fallback `TELEGRAM_BOT_TOKEN` globale). V8 commit `6635c92` ha spezzato il single-token globale in env per-tenant (ecosystem.config.js).
- **TelegramSubscriber model** (V15 esteso):
  - `id` (cuid), `chatId` (text), `tenantId` (text), `firstName/lastName/username` (text?), `createdAt/updatedAt` (timestamp), `isActive` (bool default true).
  - **V15 NEW**: `services` (Json default `[]`) + `notes` (text?) + `updatedAt` (timestamp `@updatedAt`).
  - Unique `(chatId, tenantId)`, index `(tenantId)`, `(tenantId, createdAt DESC)`.
- **Per-service opt-in (V15)**: 14 servizi categorizzati in 5 cluster (`realtime` / `daily` / `weekly` / `biweekly` / `ad-hoc`) × 3 livelli criticality (`low` / `medium` / `high`). Subscriber può opt-in selettivamente. Backend valida subset SSOT (no servizi inesistenti — vedi `updateSubscriber` `telegram.service.ts:1574-1583`).
- **Broadcast pipeline**: invio multi-receiver con redirect tracking + reactions optional + dedup. Auth `SUPERVISOR`/`ADMIN` required. `broadcastMessage` delega a `broadcastWithReactions`.
- **Mini App**: WebApp Telegram con `verifyMiniAppInitData` (HMAC-SHA256 verify init_data via bot token, `telegram.service.ts:202`) + `getMiniAppData` per dati tenant-scoped.
- **OTP Gateway**: `sendGatewayOtp` (Telegram Gateway API `https://gatewayapi.telegram.org`) + `verifyGatewayOtp` per auth flows passwordless.
- **Stories + Market Flash (V11+)**: post stories canale con sentiment (`bullish`/`bearish`/`neutral`) + tickers → `postStory` / `postMarketFlash`.

## 2bis · Knowledge Base

### Pattern architetturali
- **Token resolution per-tenant** (`telegram.service.ts:6-12`): `getBotToken(tenantId)` legge `process.env['TELEGRAM_BOT_TOKEN_'+UPPER(tenant)]` con fallback globale. Conseguenza: `TELEGRAM_BOT_TOKEN_AZ` deve essere settato nel blocco env del processo `az-api` in `ecosystem.config.js`, NON globalmente.
- **SSOT services file-based + cache in-memory** (`telegram.service.ts:1612-1637`): `getAvailableServices()` carica `config/telegram-services.json` una sola volta in `_servicesCache` private. Fallback `{ services: [] }` se file missing — endpoint NON crasha.
- **Allowed updates webhook esteso** (`telegram.service.ts:80-108`): all'`onModuleInit` re-imposta webhook con `allowed_updates: [message, callback_query, inline_query, poll_answer, pre_checkout_query, shipping_query, my_chat_member, chat_member, chosen_inline_result]`. Idempotente (best-effort try/catch — non blocca boot).
- **Validation services subset SSOT** (`telegram.service.ts:1574-1583`): `updateSubscriber` valida `dto.services[]` contro `Set(getAvailableServices().services.map(s.id))` — silently filter unknown ids invece di throw. Dedup via `Array.from(new Set(...))`.
- **Multi-select UI raggruppato per categoria** (`telegram-bot/page.tsx` EditDialog ~line 1300+): pattern preferito per opt-in liste lunghe (>10 elementi). `toggleEditService(svcId)` (line 291) toggle locale state, `saveEditSubscriber` (line 302) PATCH a `/telegram/admin/subscribers/:id`.
- **chatIdMasked** (`telegram.service.ts:1517-1519`): mai esporre `chatId` raw al frontend admin — sempre `chat.slice(0,3)+'***'+chat.slice(-2)`. Privacy-by-default.

### Decisioni storiche
- **2026-05-02 V15** (commit `6761263` cleanup + migration `20260502_telegram_subscriber_services`): aggiunto per-service opt-in (`services` Json) + `notes` + `updatedAt`. Migration idempotente con `ADD COLUMN IF NOT EXISTS`. Cleanup R-Audit Wave 1.6: rimosse 9 occorrenze `(this.prisma as any).telegramSubscriber.X` sostituite con getter esplicito `this.prisma.telegramSubscriber.X` (`tenant-prisma.service.ts:197-198`).
- **V14b**: introdotto `notifyRatingShift` cross-modulo da `valoswiss-trading-agents` con dedup hash `{kind, key, dayBucket}` (no-spam stesso giorno). Pattern `@Optional()` injection per evitare circular dep.
- **V8 commit `6635c92`**: split del single-token globale `TELEGRAM_BOT_TOKEN` in env per-tenant `TELEGRAM_BOT_TOKEN_AZ`/`TELEGRAM_BOT_TOKEN_WS` in `ecosystem.config.js`. Senza questo fix, AZ subscribers ricevevano broadcast con bot WS (token sbagliato → invio fallito o cross-tenant leak).
- **V11+ Stories**: introdotto `postMarketFlash(channelId, {headline, detail, sentiment, tickers})` per post canale con sentiment tagging.

### Edge cases noti
- **Bot token mancante**: `onModuleInit` (`telegram.service.ts:69-78`) logga warn `TELEGRAM_BOT_TOKEN not set — bot disabled` e ritorna early. `handleUpdate` skip silenzioso. Endpoint admin → 200 ma `sent: 0`.
- **Subscriber con `services` legacy** (pre-V15): `Array.isArray(s.services) ? s.services : []` (`getSubscribers` line 1528). Dato già migrato a default `[]`, ma il check resta.
- **Webhook update unsupported**: `handleUpdate` ignora silently update senza `message.text` o `from.id` (line 147). Solo command `/start /stop /alerts /help /portfolio /poll /voice /voiceon /voiceoff /news` + log commands `/log /note /meeting /wa /tg`.
- **Notes overflow**: `updateSubscriber` valida `notes.length <= 500` (line 1570-1572) → `HttpException 400` se eccede.

### Bug ricorrenti
- **R-Audit Wave 1.6 pattern (q)**: `(this.prisma as any).telegramSubscriber.X` cast bypass tenant-aware Proxy. Cleanup permanente in V15: usa SEMPRE `this.prisma.telegramSubscriber.X` (getter esplicito a `tenant-prisma.service.ts:197-198`). Pre-commit hook BLOCKING.
- **R-Audit pattern (s)**: `req.user.userId` (errato) vs `req.user.id` (corretto, auth-context middleware). Pre-commit hook BLOCKING.
- **Cross-tenant leak**: `getSubscribers` / `updateSubscriber` SEMPRE filtrano per `this.prisma.getTenantId()` post `setTenantContext()`. NEVER skip `await this.prisma.setTenantContext()` prima di query.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/telegram/telegram.service.ts` |
| Controller | `/Users/crisescla/git/valoswiss/apps/api/src/modules/telegram/telegram.controller.ts` |
| Module | `/Users/crisescla/git/valoswiss/apps/api/src/modules/telegram/telegram.module.ts` |
| Frontend admin | `/Users/crisescla/git/valoswiss/apps/web/src/app/telegram-bot/page.tsx` |
| Mini App | `/Users/crisescla/git/valoswiss/apps/web/src/app/telegram-miniapp/page.tsx` |
| Schema DB | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (modello `TelegramSubscriber`) |
| Migration V15 | `/Users/crisescla/git/valoswiss/packages/database/prisma/migrations/20260502_telegram_subscriber_services/migration.sql` |
| SSOT 14 services | `/Users/crisescla/git/valoswiss/config/telegram-services.json` |
| PM2 config tokens | `/Users/crisescla/git/valoswiss/ecosystem.config.js` (env per-tenant `TELEGRAM_BOT_TOKEN_<TENANT>`) |

## 4 · API & contracts

### Webhook (PUBLIC)
| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/telegram/webhook` | POST | Public | dispatcher inline_query / poll_answer / pre_checkout_query / callback_query / message |

### Mini App (PUBLIC)
| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/telegram/miniapp/verify` | POST | Public | body `{initData}` → HMAC verify, ritorna `{user, tenantId}` |
| `/telegram/miniapp/data` | POST | Public | body `{initData}` → 401 se invalid + dati tenant-scoped |

### Gateway OTP (PUBLIC)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/gateway/send-otp` | POST | body `{phone}` → `{requestId}` |
| `/telegram/gateway/verify-otp` | POST | body `{requestId, code}` → success/fail |

### Login Telegram Widget (PUBLIC)
| Endpoint | Method |
|----------|--------|
| `/telegram/login/verify` | POST |
| `/telegram/login/callback` | POST |

### Polls / Reactions / Channels (SUPERVISOR/ADMIN)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/admin/poll` | POST | body `{chatIds[], question, options[], isAnonymous?, allowsMultipleAnswers?, type, correctOptionId?, explanation?}` |
| `/telegram/admin/reactions` | GET | stats Map `messageId → reactions{}` |
| `/telegram/admin/broadcast-reactions` | POST | body `{text, redirectPath?, enableReactions?}` |
| `/telegram/admin/channel/:channelId` | GET | info canale |
| `/telegram/admin/channel/post` | POST | body `{channelId, text, parseMode?, photo?}` |
| `/telegram/admin/channel/pin` | POST | body `{channelId, messageId}` |

### Scheduled (SUPERVISOR/ADMIN, briefing solo SUPERVISOR)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/admin/schedule` | POST | body `{chatId, text, sendAt, category?}` |
| `/telegram/admin/schedule` | GET | lista in-memory `scheduledMessages` |
| `/telegram/admin/schedule/:id` | DELETE | cancella + clearTimeout |
| `/telegram/admin/schedule-briefing` | POST | SUPERVISOR-only, body `{hour?, minute?}` |

### Stars + subscriptions (SUPERVISOR/ADMIN)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/admin/stars/invoice` | POST | body `{chatId, title, description, payload, starAmount}` |
| `/telegram/admin/stars/subscription` | POST | body `{chatId, planName, starAmount, description}` |

### Business API (SUPERVISOR-only ad eccezione welcome)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/admin/business/setup-commands` | POST | SUPERVISOR — set `/start /stop /alerts /help …` |
| `/telegram/admin/business/set-menu-button` | POST | SUPERVISOR — body `{webAppUrl}` |
| `/telegram/admin/business/welcome/:chatId` | POST | SUPERVISOR/ADMIN |

### Stories (SUPERVISOR/ADMIN)
| Endpoint | Method | Note |
|----------|--------|------|
| `/telegram/admin/story` | POST | body `{channelId, text, photoUrl?, activeFor?, caption?}` |
| `/telegram/admin/story/market-flash` | POST | body `{channelId, headline, detail, sentiment: bullish\|bearish\|neutral, tickers?}` |

### Admin core
| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/telegram/admin/status` | GET | SUP | health flags |
| `/telegram/admin/config` | GET | SUP | alertCateg

…[truncato — apri il file MD per testo completo]