PrimoCore Convex Campaigns Component

Pacchetto npm per distribuire il componente Convex campaigns di PrimoCore.

Contenuto

• convex.config.ts: definizione componente Convex.
• convex/components/campaigns/*: funzioni, schema, ports, domain.
• convex/campaigns.ts: API pubblica stabile (campaigns.*).

Build del pacchetto

Dal root del monorepo:

cd packages/convex-campaigns-component
npm run sync:from-repo
npm pack

npm pack esegue anche prepack, quindi sincronizza automaticamente i file dal repo.

Pubblicazione su npmjs

cd packages/convex-campaigns-component
npm login
npm publish

Installazione su host PrimoCore

Nel repo host:

npm install @primocaredentgroup/convex-campaigns-component

Poi nel convex.config.ts dell'host installa il componente:

import { defineApp } from "convex/server";
import { campaignsComponent } from "@primocaredentgroup/convex-campaigns-component/convex.config";

const app = defineApp();
app.use(campaignsComponent, { name: "campaigns" });

export default app;

Infine esegui:

npx convex dev

Sviluppo standalone (npx convex dev)

Il componente ha il suo backend e può essere sviluppato in isolamento:

cd /path/to/campagne   # root del package (dove c'è package.json)
npx convex dev

La convex.config.ts esporta un'app che monta il componente, così convex dev funziona dalla root del package.

Note

• Il componente espone logica backend Campaigns (no UI).
• L'autorizzazione è server-side (assertAuthorized) e va collegata al provider auth del deployment host in produzione.
• La port Consent resta stub fino a disponibilità del componente consensi ufficiale.

Compatibilità host e prerequisiti schema

• Il componente definisce e usa indici Convex per le proprie tabelle (campaign_steps.by_campaign, campaign_steps.by_campaign_order, ecc.).
• In caso di mismatch temporaneo tra codice e indici dopo deploy, le query principali usano fallback safe per evitare crash UI.
• Per le tabelle host (users) il componente prova prima lookup indicizzato (by_auth0, by_email) e, se l'indice non è disponibile, applica fallback collect + find.

Compatibilità clinic IDs

• scopeClinicIds accetta sia:
  • Convex IDs (v.id("clinics"))
  • stringhe clinicId
• Strategia adottata: accettazione stringhe + normalizzazione interna (String(id)), per compatibilità cross-host senza patch nel node_modules host.

Comportamento auth fallback

• Mapping identity robusto:
  • prova subject -> users.by_auth0
  • fallback email -> users.by_email
  • fallback finale collect + find se indici host non disponibili
• Role matching case-insensitive (admin, Admin, ADMIN equivalenti).
• Se identity esiste ma utente/ruoli non mappati:
  • default: errore controllato (CAMPAIGNS_AUTH_*)
  • opzionale dev-safe: impostare CAMPAIGNS_AUTH_MISSING_USER_MODE=allow

Embedding in PrimoUpCore

API pubbliche host-facing (production-ready)

Usare campaignsPublic o le funzioni esportate direttamente:

• listActiveCampaignsForOrg – campagne ready per org, opzionale filter per clinicId
• getLatestPublishedVersion – versione più recente pubblicata di una campagna
• getPatientCampaignMemberships – memberships di un paziente, ordinate per priority
• getAudiencePage – audience paginata (ordine deterministico)
• recordContactAttempt – registra esito contatto
• getFieldRegistry – registry campi per UI builder

Variabili d'ambiente

| Variabile | Valore | Default | Descrizione | |-----------|--------|---------|-------------| | CAMPAIGNS_USE_DEMO_DATASOURCE | "true" | "false" | true in dev, false in prod | Se false, usa solo core datasource (tabella patients). In prod impostare false per evitare uso di dati demo. |

Normalizzazione clinicId

Tutte le API pubbliche normalizzano clinicId al boundary: String(id) per compatibilità con Convex IDs e stringhe.

Checklist installazione in PrimoUpCore

1. npm pack / publish – npm pack dal repo o npm publish su registry
2. install su PrimoUpCore – npm install @primocaredentgroup/convex-campaigns-component
3. set env vars – CAMPAIGNS_USE_DEMO_DATASOURCE=false in produzione
4. chiamare listActiveCampaignsForOrg – verifica integrazione da host
5. verificare demo datasource disabilitato – in prod non deve usare tabelle demo

API v2 (rule engine + snapshot versionati)

API playground/dev (test, examples):

• campaigns:seedDemoData
• campaigns:upsertCampaign
• campaigns:setCampaignLifecycleStatus
• campaigns:listCampaignsV2
• campaigns:getCampaignV2
• campaigns:listCampaignVersions
• campaigns:previewCampaignAudience
• campaigns:publishCampaignVersion
• campaigns:updateCampaignCallPolicy
• campaigns:getCampaignCallPolicy

API pubbliche (vedi sopra): listActiveCampaignsForOrg, getLatestPublishedVersion, getPatientCampaignMemberships, getAudiencePage, recordContactAttempt, getFieldRegistry.

Il motore regole usa DSL JSON (AND/OR + condizioni atomiche) validata con zod.

Playground React

Esempio frontend standalone disponibile in:

• examples/campaigns-playground

Vedi guida completa:

• examples/campaigns-playground/README.md

Smoke test

Script per verificare le API in sequenza. Esegui dalla root del componente (dove si trova package.json):

cd /path/to/campagne   # repo del componente campaigns
npm run smoke

L'URL Convex viene letto da .env.local (creato da npx convex dev) o da variabili d'ambiente:

CONVEX_URL=https://tuo-deployment.convex.cloud npm run smoke

Variabili: SMOKE_ORG_ID, SMOKE_CLINIC_IDS, SMOKE_SKIP_SEED=1 per saltare seed.