Integrazione del widget

Il widget embeddabile è un servizio separato (packages/widget, porta 3211) che espone una chat AI sul tuo sito. Architettura: Express + Preact IIFE in iframe sandboxed, proxy SSE trasparente verso il server, sessioni anonime, lead capture, branding per-sito.

Il widget è una feature Enterprise (license widget_enabled); Community ha 1 widget

di default ma la creazione richiede il flag attivo.

Come embeddare (quick start)

1. Crea il widget (admin UI → Settings → Widgets, o API):

POST /api/widgets
Authorization: Bearer <admin JWT>
{ "name": "Sito Azienda", "allowedOrigins": ["https://www.azienda.it"],
  "workspaceIds": ["<uuid>"], "primaryColor": "#4c6ef5", "botName": "Assistente" }

Risposta: { widget } con widget.id.

1. Whitelist knowledge base - PUT /api/widgets/:id/workspaces con gli UUID dei workspace il cui RAG sarà accessibile al widget (tabella WidgetWorkspace, PK composita [widgetId, workspaceId]).

1. Inserisci lo snippet nella pagina host:

<div id="simmetric-widget" data-widget-id="<widget.id>" data-position="bottom-right"></div>
<script
  src="https://widget.tuodominio.it/widget/<widget.id>.js"
  integrity="sha384-<HASH>"
  crossorigin="anonymous"
  async
></script>

Sicurezza: se servi il loader da un CDN di terze parti, genera l'hash SHA-384 del

bundle e aggiungi integrity + crossorigin="anonymous" (Subresource Integrity). Se

il loader è same-origin con il tuo widget service, SRI è opzionale ma consigliato per

difendere da compromissione del CDN/asset.

Il loader (packages/widget/src/routes/loader.ts) legge gli attributi data-*, crea un <iframe sandbox="allow-scripts allow-forms"> (no allow-same-origin, no allow-top-navigation), carica /widget/<id> (HTML) che monta il bundle Preact /widget/app.js.

Configurazione branding & trigger

Campi del modello Widget (validati da widget.schema.ts in shared):

Query param URL (?primaryColor=...&position=...&locale=...) override runtime. Campi aggiuntivi v0.22: rateLimitPerMinute / sessionLimitPerDay (override per-widget dei limiti globali; null = default globale) e responseProviderId/responseModel.

Response model pin (v0.22): la configurazione admin di ogni widget può selezionare il provider + modello LLM che serve le risposte di quel widget (responseProviderId, UUID provider; responseModel, nome modello). Il pin è risolto server-side dalla riga widget del DB ad ogni richiesta chat (mai fornito dal client - proxy e UI visitatore non toccati), ha priorità sul default del workspace, e i widget senza pin mantengono la catena di risoluzione workspace/globale esistente. Le chat widget registrano il modello effettivo che le ha servite.

Trigger (widget/hooks/useTriggers.ts): ascolta postMessage dal loader - simmetric:urlChange (check autoOpenUrlPatterns via matchUrlPattern/globToRegex: **, *, ?, {a,b}), simmetric:exitIntent (open con cooldown). Exit intent rilevato lato loader via mouseleave con e.clientY <= 10. Il autoOpenDelay è in secondi (1–300, null = disabilitato); exitIntentCooldownMs 60000–86400000 ms.

Autenticazione & API key

• Widget ↔ Server: header X-Api-Key: <WIDGET_API_KEY> verso /api/internal/widget/*. La key deve matchare tra packages/widget/.env e packages/server/.env.
• Visitatore ↔ Widget service: header x-session-token (sessione anonima, non JWT).
• CORS dinamico (widgetCors.ts): header CORS per-origin basati su allowedOrigins. Fail-closed su DB error (no header = browser blocca).

Sessioni anonime

POST /api/sessions (widget) → server crea WidgetSession: token 256-bit hex (crypto.randomBytes(32)), 24h expiry, IP logged. sessionMiddleware valida il token ad ogni richiesta chat e attacca req.widgetSession + req.widgetConfig. La sessione è persistita nella sessionStorage dell'host via handshake postMessage col loader (simmetric:storage-*) e riusata ai reload; a scadenza → 401 → il Preact mostra "Session expired" e al refresh della pagina il widget ricrea la sessione.

Chat flow (SSE proxy)

Visitatore → POST /api/chat/:widgetId/stream  (x-session-token, body {message, chatId?})
→ widgetDailyMessageLimiter (per widget+IP, 5/24h prod, override sessionLimitPerDay)
→ widgetChatLimiter (per widgetId, 30/min prod, override rateLimitPerMinute)
→ sessionMiddleware valida sessione
→ check hourlyRemaining (DB-tracked, 20/h) → 429 se esaurito
→ increment messageCount (fire-and-forget)
→ pre-search RAG: POST /api/internal/widget/search {query, widgetId}
   server risolve workspaceIds dalla whitelist WidgetWorkspace (IDOR prevention)
→ proxy a SERVER_URL/api/internal/widget/chat/stream
   headers: X-Api-Key, X-Widget-Id, X-Widget-Session-Id, X-Accel-Buffering: no
→ relay byte SSE verbatim (responseType: "stream", filtra event: thinking)
→ Preact useWidgetChat parse: token | citations | done | error

Il proxy è trasparente: non parse/filtra/trasforma gli eventi SSE. Se la pre-search RAG fallisce, emette status: rag-degraded ma la chat continua senza contesto.

Lead capture

POST /api/lead/:widgetId (widget, sessionMiddleware):

• Check config.leadCaptureEnabled (403 se off).
• Body widgetLeadSubmitSchema: email (req), name (opt), transcript[] (role/content/timestamp).
• submitLead(widgetId, email, name, transcript, session.id) - passa session.id (UUID FK).
• Limiter 3 leads/hour per IP.
• Admin recupera: GET /api/widgets/:id/leads, export CSV GET /api/widgets/:id/leads/export (con filtro date + selezione colonne; dalla v0.22 sempre disponibile - il flag commodity lead_export è stato rimosso).

Rate limit (doppio layer)

Sicurezza

• iframe sandbox allow-scripts allow-forms (no same-origin, no top-navigation).
• helmet rilassato per embedding (no CSP, no frameguard, no COOP/COEP/CORP).
• Messaggi renderizzati via markdown-it + dompurify (anti-XSS).
• DLP server-side: i match DLP di ogni run viaggiano nell'SSE done (dlp_matches, solo con DLP attivo e nessun ruolo bypass); il consenso PII del visitatore è gestito dal PIIWarningPrompt (gate pre-chat, testi piiConsent per locale).
• No cookie, no localStorage dal sandboxed iframe (storage via handshake postMessage col loader, batching su done/error/unmount).
• Loader usa getAttribute() (no innerHTML) + encodeURIComponent; i messaggi simmetric:* in ingresso sono validati con il guard event.source === iframeEl.contentWindow.
• La cache-bust endpoint (POST /api/config/:widgetId/cache-bust) confronta X-Api-Key in tempo costante (crypto.timingSafeEqual con length guard, fail-closed se unset).

Pin modello & prompt per-widget (F-WIDGET-1-class)

Il widget può pinnare il proprio modello: la riga Widget porta responseProviderId + responseModel (stringa max 200, nullable). Solo server-side: la proxy widget rimuove qualunque providerId/model che il client invia nel body (tamper pin, routes/internalWidget.ts:287-306); la pin arriva come 6° arg dal DB row (:336-352). Colonne non impostate (null) → la risoluzione cade sulla catena esistente workspace default → global default → ENV.

Prompt di sistema per-widget: amministrabile, max 4000 caratteri, risolto dal DB; blank/null → passa per resolveWidgetSystemPrompt al grounding floor module-privato (un widget senza pin né prompt resta comunque grounded); la direttiva lingua-risposta viene composta downstream dall'orchestrator col locale del visitatore. Write contract: la null ripulisce la pin.

MCP (indiretto)

Il widget non gestisce MCP: installa/unpin avviene nel server admin. I workspace linked possono avere MCP tool installati → l'agente li usa durante la chat widget automaticamente (zero codice widget). mcpSources nel SSE done indica quali MCP hanno contribuito.

Estendere

• Nuovo componente → packages/widget/src/widget/components/ (Preact + Tailwind, no shadcn/ui).
• Nuovo trigger → estendi useTriggers.ts + campo Widget + route internalWidget.ts.
• Nuovo rate limit → src/middleware/rateLimit.ts + mount in index.ts.
• CSS themable → namespace --widget-* in src/widget/index.css; statiche con Tailwind utility.

File chiave

Cross-link

• Endpoint widget: 04 - API Reference
• Internals RAG/agent: 05 - Feature Guide