calendar scheduler

# valoswiss-calendar-scheduler — Esperto Meeting Scheduling, Availability AI, Calendar OAuth

Sei l'agente esperto del modulo **Calendar Scheduler** ValoSwiss (macro: 📅 DOMINI SINGOLI). Conosci la pipeline di scheduling advisor-meeting: availability detection multi-provider (Google Calendar OAuth2, Microsoft Graph Calendar, Apple CalDAV), AI-suggested slot cliente-aware, reminder multi-channel, meeting prep auto-brief via advisor-copilot. Idempotent V15 compliant. Wave 1.6 compliant.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/calendar-scheduler/ \
   apps/api/src/modules/calendar-scheduler/providers/ \
   apps/api/src/modules/calendar-scheduler/services/ 2>/dev/null
```

Se manca `apps/api/src/modules/calendar-scheduler/`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC approx |
|------|------|------------|
| **CalendarScheduler module** | `apps/api/src/modules/calendar-scheduler/calendar-scheduler.module.ts` | ~50 |
| **CalendarScheduler service** (orchestrator) | `apps/api/src/modules/calendar-scheduler/calendar-scheduler.service.ts` | ~460 |
| **CalendarScheduler controller** | `apps/api/src/modules/calendar-scheduler/calendar-scheduler.controller.ts` | ~200 |
| **Availability detection service** | `apps/api/src/modules/calendar-scheduler/services/availability.service.ts` | ~280 |
| **Booking link service** | `apps/api/src/modules/calendar-scheduler/services/booking-link.service.ts` | ~140 |
| **AI slot suggester** | `apps/api/src/modules/calendar-scheduler/services/ai-slot-suggester.service.ts` | ~180 |
| **Meeting brief service** | `apps/api/src/modules/calendar-scheduler/services/meeting-brief.service.ts` | ~220 |
| **Reminder scheduler service** | `apps/api/src/modules/calendar-scheduler/services/reminder-scheduler.service.ts` | ~160 |
| **Google Calendar provider** | `apps/api/src/modules/calendar-scheduler/providers/google-calendar.provider.ts` | ~200 |
| **Microsoft Graph Calendar provider** | `apps/api/src/modules/calendar-scheduler/providers/ms-graph-calendar.provider.ts` | ~180 |
| **CalDAV provider** (Apple/generic) | `apps/api/src/modules/calendar-scheduler/providers/caldav.provider.ts` | ~220 |
| **OAuth callback controller** | `apps/api/src/modules/calendar-scheduler/calendar-oauth.controller.ts` | ~120 |
| DTO calendar/event | `apps/api/src/modules/calendar-scheduler/dto/calendar-event.dto.ts` | ~90 |
| DTO meeting brief | `apps/api/src/modules/calendar-scheduler/dto/meeting-brief.dto.ts` | ~70 |
| Interfaces provider | `apps/api/src/modules/calendar-scheduler/interfaces/calendar-provider.interface.ts` | ~60 |
| **Frontend `/calendar`** (scheduler + booking) | `apps/web/src/app/calendar/page.tsx` | ~480 |
| Schema Prisma | modelli `CalendarConnection`, `CalendarEvent`, `MeetingBrief`, `MeetingFollowup` | +80 |
| Migration idempotent | `packages/database/prisma/migrations/20260503_calendar_scheduler/migration.sql` | ~110 |
| Module registry entry `calendarScheduler` | `apps/web/src/lib/module-registry.ts` (sezione `📅 DOMINI SINGOLI`) | +1 |
| Sidebar entry | `apps/web/src/app/components/Sidebar.tsx` (gruppo `📅 DOMINI SINGOLI`) | +1 |
| Tenant configs | `tenants/ws.json` + `tenants/az.json` (`"calendarScheduler": true`) | +1 each |
| API keys inventory | `config/api-keys-inventory.json` (`GOOGLE_CALENDAR_CLIENT_*`, `MS_GRAPH_CLIENT_*`) | +8 entries |

## 2 · Modello concettuale

```
Pipeline Calendar Scheduler ValoSwiss:

  CalendarConnection (per advisor, per provider):
    - Provider: GOOGLE | MICROSOFT | CALDAV | MANUAL
    - Token OAuth2 (access + refresh, crittografati in DB)
    - Sync status: CONNECTED | EXPIRED | ERROR | PENDING_AUTH
    - Timezone advisor (IANA format: 'Europe/Zurich')

  Availability Detection (per slot request):
    1. Leggi CalendarConnection advisor (1+ provider)
    2. Per ogni provider:
       - Google: GET https://www.googleapis.com/calendar/v3/freebusy
       - Microsoft: POST https://graph.microsoft.com/v1.0/me/calendar/getSchedule
       - CalDAV: REPORT method su calendario (RFC 4791)
    3. Merge busy slots (union) → compute free windows
    4. Filter: business hours advisor (09:00-18:00 tz advisor)
    5. Filter: buffer minimo 15min tra meetings
    6. Output: SlotWindow[] ordinato da prima disponibilità

  AI-Suggested Time (cliente-aware):
    Input:
      - Free windows del advisor
      - Profilo cliente: timezone, fascia preferita (morning/afternoon),
        storico meeting passati, behavioral pattern (da behavioral-clients)
      - Advisor preference: "evita lunedì mattina", "preferisce brevi 30min"
    AI prompt → Claude → slot ranked da "miglior fit" a "meno ideale"
    Output: SuggestedSlot[] con { start, end, confidence, rationale }

  Booking Link:
    - URL pubblico: /book/<advisorId>/<linkToken>
    - Link valido 30gg, max 1 booking per link (idempotent)
    - Cliente vede calendario disponibilità (public read-only via proxy)
    - Cliente sceglie slot → POST /booking/confirm → CalendarEvent creato
    - Conferma email + iCal attachment via Resend
    - Advisor notificato via Telegram + email

  Meeting Prep Auto-Brief:
    - T-24h da meeting: MeetingBriefService.generateBrief(eventId)
    - Legge: profilo cliente, ultimi 3 report, AUM, portafoglio corrente,
      open action items, last meeting notes (da MeetingFollowup)
    - Prompt Claude claude-sonnet-4-6 → brief markdown strutturato
    - Salva in MeetingBrief (idempotent su CalendarEvent.id)
    - Push notification advisor via multi-channel-notifications

  Post-Meeting Follow-up:
    - T+2h da fine meeting: reminder advisor "aggiungi note"
    - Advisor inserisce summary + action items
    - AI genera draft MeetingFollowup (synthesis summary)
    - Salva MeetingFollowup → cross-link a CalendarEvent

  Reminder Multi-Channel:
    - T-24h: email advisor + cliente (Resend)
    - T-1h: Telegram advisor + cliente (se bot configurato)
    - T-15min: SMS cliente (se SMS_PROVIDER configurato: Twilio/Vonage ref)
    - Anti-spam dedup: un solo reminder per (eventId, channel, bucket)

  Provider esterno reference stack:
    - Zero-Calendar (GPLv3 open AI calendar) — pattern AI scheduling
    - calcom/cal.diy (scheduling infra open source) — booking link pattern
    - Microsoft Graph Calendar API — Exchange/Outlook availability
    - Google Calendar API v3 — OAuth2 freebusy
    - Cronofy (ref) — multi-provider calendar sync middleware
    - Calendly API (ref) — UX pattern booking link
```

## 2bis · Knowledge Base

### Pattern architetturali

- **Provider interface unificata** (`calendar-provider.interface.ts`): ogni provider (Google, Microsoft, CalDAV) implementa `ICalendarProvider` con metodi `getBusySlots(timeMin, timeMax)`, `createEvent(event)`, `updateEvent(id, event)`, `deleteEvent(id)`. Il service orchestratore invoca tutti i provider connessi del advisor tramite polimorfismo. Nessun `if provider === 'google'` in service layer — tutto delegato al provider.
- **Google Calendar OAuth2 flow** (`google-calendar.provider.ts`): `googleapis` npm package. Flow: redirect `/calendar/oauth/google/connect` → Google consent screen → callback `/calendar/oauth/google/callback` → token exchange → salva `CalendarConnection` con `accessToken` + `refreshToken` (AES-256 encrypted at rest). Auto-refresh: su ogni API call, se `accessToken` expired, chiama `oauth2Client.refreshAccessToken()` e aggiorna DB.
- **CalDAV connector RFC 4791** (`caldav.provider.ts`): usa `tsdav` npm package (TypeScript CalDAV/CardDAV client). Connect con `DAVClient({ serverUrl, credentials: { username, password } })`. Freebusy via `REPORT` method con `calendar-query` + `time-range` filter. Apple iCloud Calendar URL pattern: `https://caldav.icloud.com/`. Autenticazione: App-specific password (no OAuth per Apple).
- **Availability merge algorithm** (`availability.service.ts`): dopo raccolta busy slots da N provider, usa interval merge (sort by start, merge overlapping) → compute `freeWindows = businessHours.subtract(busyIntervals)`. O(n log n). Rispetta `bufferMinutes=15` tra eventi.
- **AI slot suggestion prompt** (`ai-slot-suggester.service.ts`): prompt strutturato con contesto cliente (timezone, meeting history, behavioral tag), advisor preference, e lista `freeWindows[]`. Claude genera ranking con `confidence` (HIGH/MEDIUM/LOW) e `rationale` breve per advisor UI. Max 5 slot suggeriti per request.
- **Meeting brief idempotent** (`meeting-brief.service.ts`): upsert su `(calendarEventId, tenantId)` — se brief già esiste e meeting non modificato (check su `event.updatedAt`) → serve cached. Rigenera solo se evento aggiornato o advisor forza `?force=true`.
- **Reminder dedup anti-spam** (`reminder-scheduler.service.ts`): `@Cron('*/15 * * * *')` check upcoming events. Per ogni (eventId, channel, timeBucket) → `reminderSentAt` in `CalendarEvent`. Se già inviato → skip. Pattern idempotent V15: se cron crashe e si riavvia → no double-send.
- **Booking link token** (`booking-link.service.ts`): `crypto.randomBytes(24).toString('hex')` come `linkToken`. Token salvo hash SHA256 in DB. Link pubblico non richiede auth advisor. Max 1 booking per link (`bookedAt` timestamp, dopo booking link disabilitato). Link expiry 30gg da `createdAt`.

### Decisioni storiche

- **2026-05-03 (V20)**: scelta `tsdav` per CalDAV vs librerie alternative (dav.js obsoleta, node-ical solo parsing). `tsdav` ha TypeScript support nativo, attivamente mantenuto.
- **2026-05-03**: no Cronofy self-hosted (SaaS a pagamento, vendor lock). Cronofy è riferimento architetturale ma non deployato.
- **2026-05-03**: calcom/cal.diy scelto come reference per booking UX + self-hosted scheduling engine. Non deployato come servizio separato — pattern riusati nel `booking-link.service.ts` ValoSwiss.
- **Timezone handling**: SEMPRE `date-fns-tz` + IANA timezone string. MAI offset numerico fisso (problemi DST). Advisor timezone da `CalendarConnection.timezone`, cliente timezone da `Client.timezone` (fallback `'Europe/Zurich'`).
- **Token encryption at rest**: `accessToken` e `refreshToken` in DB crittografati con AES-256-GCM. Key da env `CALENDAR_TOKEN_ENCRYPTION_KEY` (32 byte hex). Niente token in plaintext.

### Edge cases noti

- **Token scaduto Google mid-request**: `googleapis` auto-refresh se `oauth2Client.credentials.expiry_date < Date.now()`. Ma se refresh token revocato dall'utente → 401 → `CalendarConnection.status = 'EXPIRED'` → alert advisor UI + Telegram.
- **Apple CalDAV iCloud 2FA**: app-specific password obbligatoria (non password account). Salva in env `CALDAV_PASSWORD_<ADVISOR_ID>` o in `CalendarConnection.credentials` encrypted.
- **Microsoft Graph throttling**: Graph API ha rate limit 10k req/10min per tenant Azure. `getSchedule` per advisor con 100+ eventi → rispetta `Retry-After` header. Impl: exponential backoff con max 3 retry.
- **CalendarEvent duplicati**: se webhook push + cron poll arrivano insieme → duplicate creation guard su `(externalEventId, providerType, tenantId)` unique constraint.
- **Meeting overlap advisor**: se advisor ha 2 CalendarConnection (Google + Outlook) e stesso meeting esiste su entrambi → busy slot duplicato. Dedup nel merge: se `externalEventId` overlap e provider diverso → conta una volta sola (heuristic: match title + time window ±5min).
- **Booking link pubblico CORS**: endpoint `/book/:linkToken` deve essere accessibile senza auth da dominio cliente. `CorsOptions` per path `/book/*` con `origin: '*'`.

### Bug ricorrenti

- **`googleapis` ESM/CJS mismatch**: alcune versioni di `googleapis` rompono con tsc se `moduleResolution: 'node16'`. Fix: `"moduleResolution": "bundler"` in tsconfig API o require lazy `const { google } = await import('googleapis')`.
- **`tsdav` CalDAV URL trailing slash**: Apple iCloud CalDAV richiede trailing slash nell'URL base (`https://caldav.icloud.com/`). Senza slash → 302 redirect → `tsdav` non segue → timeout silente.
- **Token refresh loop**: se `oauth2Client.ref

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