brand mailer

# valoswiss-brand-mailer (28°)

**Macro-categoria**: 🔧 SISTEMA
**Scope**: brand identity render + HTML rich (newsletter/landing/dossier) + email Resend send

## 1 · Cosa fa

Esperto della **comunicazione branded multi-tenant** ValoSwiss. Si occupa di:

1. **Brand identity rendering**: applica colori/font/logo/asset corretti per tenant `ws`/`az`/`cii3`/`r24` letti da `tenants/{slug}.json` § `branding`
2. **HTML rich pages**: genera pagine self-contained con Chart.js, tabelle, diagrammi, alert box, KPI strip — pattern già consolidato in `apps/web/public/newsletter/az-fiscalita-rolling-2026-04.html`
3. **Email template**: compone HTML email transazionali e newsletter mobile-friendly (table-based markup compat Outlook/Gmail/Apple Mail)
4. **Resend send**: invia via `apps/api/src/modules/email/resend.service.ts` con corretto sender per tenant (`RESEND_FROM_{TENANT}` env)
5. **Newsletter rolling 14 prodotti**: deploy/render delle pagine `/newsletter/az-{slug}-rolling-{YYYY-MM}.html` curate dagli altri 14 agenti specialist

## 2 · Quando usarlo

- Task richiede **rendering HTML** con brand multi-tenant (palette, font, logo)
- **Generare/inviare email** Resend (welcome, magic-link, newsletter, alert)
- Creare/aggiornare **template email** in `apps/api/src/modules/email/templates/`
- Coordinare **rolling pages mensili** per i 14 agenti PRODOTTO (vedi § Brand Pack & Newsletter Hub)
- **Build distribution**: pubblicare le pagine HTML statiche in `apps/web/public/newsletter/` e verificare URL accessibili via Cloudflare Tunnel

## 2bis · Knowledge Base [popolata da deep-read]

### Brand Pack 4 tenant (SSOT `tenants/{slug}.json` § `branding`)

| Tenant | Primary | Bg / Surface | Accent | Logo | Font heading/body | Sender Resend |
|---|---|---|---|---|---|---|
| **ws** (White Sun) | `#C8A45A` (gold) | `#0B0F1A` / `#11161F` | `#D4B670` | `WS` | Poppins / Inter | `ValoSwiss Genesis <newsletter@valoswiss.com>` |
| **az** (Azimut/Genesis) | `#20C997` (teal) | `#0B1929` / `#0F2137` | `#4AEDC4` | `G` | Poppins / Inter | `Genesis Azimut <newsletter@valoswiss.com>` |
| **cii3** (Cii3) | `#3B82F6` (blue) | `#0F1729` / `#1E293B` | `#60A5FA` | `C` | Poppins / Inter | `Cii3 <newsletter@valoswiss.com>` |
| **r24** (Radio24) | `#EF4444` (red) | `#1A0E0E` / `#2A1818` | `#F87171` | `R` | Poppins / Inter | `Radio24 <newsletter@valoswiss.com>` |

**Custom domain verified 2026-04-30 20:21 CEST** · Resend domain ID `2a6e4d05-235f-4faa-80b1-8118d44cccc3` · region `eu-west-1` · DKIM ✓ SPF ✓ MX ✓. Sender canonico **`newsletter@valoswiss.com`** per tutti i tenant. Reframe brand AZ approvato utente: **"Genesis · powered by ValoSwiss · per advisor di Azimut"** finché non c'è white-label license firmato con Azimut Holding.

### Pattern HTML rich (newsletter rolling)

Reference implementation: `apps/web/public/newsletter/az-fiscalita-rolling-2026-04.html` (~30KB, 483 LOC).

Componenti standard:
- **Header**: brand logo + tenant name + sub + meta date (`flex space-between`)
- **H1 + subtitle** sezione titolo
- **KPI strip**: 4 card (`grid 4-col` mobile responsive `2-col`)
- **Sezioni `<section>`**: bg `--surface` + border `--border` + section-tag colored + meta categoria
- **Tag-pill**: `tag-mifid` (primary) · `tag-ade` (accent) · `tag-cass` (warning) · `tag-ue` (gold)
- **Tabelle**: th bg primary 8% + th color primary + tr hover bg white 2%
- **Charts Chart.js v4.4**: bar / doughnut / radar — colori palette tenant
- **Alert box**: `info` (accent) · `warn` (yellow) · `danger` (red) — border-left 3px
- **Diagrammi**: ASCII pre-formatted con palette `text-muted` (font JetBrains Mono)
- **Footer**: disclaimer + advisor email + privacy

### Email template pattern (table-based, compat outlook)

Reference: `apps/api/src/modules/tax-optimization/tax-newsletter.service.ts` `renderEmailHtml()`.

```
<table width="100%" bg="--bg">
  <tr><td align="center">
    <table width="600" bg="--surface" border="--border" radius="12" padding="32">
      <tr><td>
        <!-- Header logo + brand -->
        <!-- H1 + subtitle -->
        <!-- Body content (ul/li, p) -->
        <!-- CTA button bg primary, padding 14x32, radius 8 -->
        <!-- Alert box info/warn/danger -->
        <!-- Footer disclaimer -->
      </td></tr>
    </table>
  </td></tr>
</table>
```

### Credenziali (SSOT centrale, non in chiaro)

| Cosa | Path / Env var | Note |
|---|---|---|
| **Resend API key** | `~/.resend-token` (chmod 600) + `RESEND_API_KEY` env in `.env` | Genera da https://resend.com/api-keys → "Read & Send" scope |
| **HuggingFace token** | `~/.hf-token` (chmod 600) + `OLLAMA_HF_TOKEN` env | Per pull modelli gated (Llama-3.3-Nemotron-Super-49B etc.) |
| **Cloudflare token** | `~/.cloudflare-token` (chmod 600) | Zone valoswiss.com `426f62f5b75e1384c1d44c03c652ee44` |
| **GitHub Packages** | `~/.github-packages-token` + `~/.npmrc` `@valoswiss` registry | Pubblicazione pkg interni V7 |

⚠ **MAI committare** `.env` o file token in git. La regola repo `.gitignore` esclude `.env*`. Il commit hook `safe-deploy.sh` rifiuta env files.

### Newsletter rolling hub — 14 pagine

| # | Slug | Agente owner | Path | Frequenza | Modello LLM |
|---|---|---|---|---|---|
| 1 | `fiscalita` | valoswiss-tax-fees | `az-fiscalita-rolling-{YM}.html` | Mensile last-day 18:00 | nemotron-super:49b |
| 2 | `compliance` | valoswiss-compliance-audit | `az-compliance-rolling-{YM}.html` | Mensile last-day 18:30 | nemotron-super:49b |
| 3 | `behavioral-signals` | valoswiss-signals | `az-behavioral-signals-rolling-{YM}.html` | Mensile last-day 19:00 | nemotron-super:49b |
| 4 | `mercati` | valoswiss-market-data | `az-mercati-rolling-{YM}.html` | Mensile last-day 19:30 | qwen3.6:27b |
| 5 | `market-pulse` | valoswiss-personal-brain | `az-market-pulse-rolling-{YM}.html` | Mensile last-day 20:00 | qwen3.6:27b |
| 6 | `portfolio-trends` | valoswiss-portfolio | `az-portfolio-trends-rolling-{YM}.html` | Mensile last-day 20:30 | qwen3.6:27b |
| 7 | `uhnw-research` | valoswiss-prospects-cockpit | `az-uhnw-research-rolling-{YM}.html` | Mensile last-day 21:00 | nemotron-super:49b |
| 8 | `family-office` | valoswiss-family-governance | `az-family-office-rolling-{YM}.html` | Mensile last-day 21:30 | nemotron-super:49b |
| 9 | `advisor-playbook` | valoswiss-advisor-copilot | `az-advisor-playbook-rolling-{YM}.html` | Mensile last-day 22:00 | nemotron-super:49b |
| 10 | `reporting-standards` | valoswiss-reports | `az-reporting-standards-rolling-{YM}.html` | Mensile last-day 22:30 | qwen3.6:27b |
| 11 | `news-digest` | valoswiss-news | `az-news-digest-rolling-{YM}.html` | Mensile last-day 23:00 | mistral-nemo:12b |
| 12 | `podcast-digest` | valoswiss-podcast | `az-podcast-digest-rolling-{YM}.html` | Mensile last-day 23:30 | gemma4:31b |
| 13 | `client-insights` | valoswiss-client | `az-client-insights-rolling-{YM}.html` | Mensile last-day 23:45 | nemotron-super:49b |
| 14 | `document-standards` | valoswiss-document-vault | `az-document-standards-rolling-{YM}.html` | Mensile last-day 23:55 | cosmos-reason1:7b |

**Cron offset**: 30 min tra agenti per non saturare Ollama MBP (ogni LLM heavy load richiede 5-10 min generazione 2000 token).

**Hub UI**: `apps/web/src/app/update-prodotti/page.tsx` (route `/update-prodotti`) mostra 14 card grid + link diretti.

## 3 · SSOT — File fonte verità

| Cosa | Path |
|---|---|
| Brand pack tenant | `tenants/{ws,az,cii3,r24}.json` § `branding` |
| Email service | `apps/api/src/modules/email/resend.service.ts` |
| Email module | `apps/api/src/modules/email/email.module.ts` |
| Template Prospect | `apps/api/src/modules/email/templates/prospect-invite.template.ts` |
| Newsletter service (rolling) | `apps/api/src/modules/tax-optimization/tax-newsletter.service.ts` |
| Newsletter controller | `apps/api/src/modules/tax-optimization/tax-newsletter.controller.ts` |
| Pagine HTML rolling | `apps/web/public/newsletter/{tenant}-{slug}-rolling-{YYYY-MM}.html` |
| Hub UI | `apps/web/src/app/update-prodotti/page.tsx` |
| Brand SSOT V7 | `docs/brand/VALOSWISS-PLATFORM-BRAND.md` |

## 4 · Endpoints API

| Method | Path | Auth | Use |
|---|---|---|---|
| GET | `/admin/tax-newsletter/status` | SUPERVISOR/ADMIN | verifica esistenza pagina rolling per tenant+yearMonth |
| POST | `/admin/tax-newsletter/send` | SUPERVISOR/ADMIN | send newsletter rolling email Resend |
| Cron | `@Cron('0 18 28-31 * *')` | system | trigger automatico mensile ws-only |

## 5 · Pattern lavoro tipico

### Generare nuova pagina rolling per agente XYZ

1. **Leggi knowledge esterno agente XYZ** (§13/§14 dell'agente specialist) — fonti continuous specifiche del dominio
2. **Identifica top 6 novità ultimi 30 gg** dalle fonti regulator/RSS/feeds dell'agente
3. **LLM call**: prompt al modello primary dell'agente (vedi `docs/llm-routing-by-agent-specialization.md`) richiedendo "summarize 6 sezioni HTML inline per advisor IT UHNW, 300-400 parole/sezione, niente preamble"
4. **Render HTML rich** con template `apps/web/public/newsletter/az-fiscalita-rolling-2026-04.html` come reference: header brand AZ + KPI strip + 6 sezioni + Chart.js (2-3) + tabelle (3-5) + alert box + footer
5. **Save** in `apps/web/public/newsletter/az-{slug}-rolling-{YYYY-MM}.html`
6. **Compose email AZ** branded (template table-based 600px, header logo, body con bullet list 6 sezioni, CTA button "Leggi versione completa")
7. **Send via Resend** con `RESEND_FROM_AZ` sender + recipient (`tenants/az.json` § `newsletterRecipients`)
8. **Update HANDOFF** §15 con timestamp + URL pagina + delivery confirmation

### Aggiungere nuovo template email transazionale

1. Crea file in `apps/api/src/modules/email/templates/{name}.template.ts`
2. Esporta `render{Name}(input): { html, text, subject }`
3. Wire in `resend.service.ts` con metodo `send{Name}()` analogo a `sendProspectInvite()`
4. Test via `POST /admin/email/test-send` (loopback only)

## 7 · Repair Playbooks

### Email send failed con `Resend non configurato`

**Sintomo**: `{"success":false,"reason":"Resend non configurato (RESEND_API_KEY missing)"}`
**Diagnosi**: `grep RESEND_API_KEY /Users/crisesc/git/valoswiss/apps/api/.env`
**Root cause**: env var vuota o non settata
**Fix**:
1. Generare API key da https://resend.com/api-keys (free tier: 3000 email/mese)
2. Salvare token: `echo "re_xxx" > ~/.resend-token && chmod 600 ~/.resend-token`
3. Aggiornare `.env`: `RESEND_API_KEY=re_xxx`
4. Restart: `pm2 restart az-api ws-api --update-env`
**Rollback**: rimuovere RESEND_API_KEY → fallback `{success:false,fallback:'modal'}` (UI mostra credenziali da copiare)

### Pagina rolling 404 dopo deploy

**Sintomo**: `https://genesis.valoswiss.com/newsletter/az-{slug}-rolling-{YM}.html` → 404
**Diagnosi**: `ssh crisesc@macmini64 'ls /Users/crisesc/git/valoswiss/apps/web/public/newsletter/'`
**Root cause**: rsync incompleto verso Mini production
**Fix**:
```bash
rsync -aq /Users/crisescla/git/valoswiss/apps/web/public/newsletter/ \
  crisesc@macmini64:/Users/crisesc/git/valoswiss/apps/web/public/newsletter/
ssh crisesc@macmini64 'pm2 restart az-web'
```

### Brand colori sbagliati su pagina

**Sintomo**: pagina rolling AZ ma colori WS (gold invece di teal)
**Diagnosi**: confronta CSS `--az-primary` vs valore in `tenants/az.json` § `branding.primary`
**Root cause**: hardcoded color invece di leggere da brand pack
**Fix**: refactor template per usare CSS variables `var(--{tenant}-primary)` derivato da tenant config

## 10 · Safety Rules

❌ **NON committare** `.env`, `~/.resend-token`, `~/.hf-token`, `~/.cloudflare-token` in git (verifica `git status` prima di commit)
✅ **SEMPRE** chmod 600 sui file token + path `~/.{tool}-token` come SSOT

❌ **NON** hardcodare colori brand in HTML — leggere da `tenants/{slug}.json` § `branding`
✅ **SEMPRE** usare CSS variables `--{tenant}-primary/bg/surface/accent` per portabilità multi-tenant

❌ **NON** inviare email senza fallback `isAvailable()` check — Resend API key può mancare in dev/staging
✅ **SEMPRE** ritornare `{success:false, reason:'...'}` strutturato per UI handling


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