@primocaredentgroup/convex-campaigns-component 0.1.3 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.3.0
+
+- **Public API stabilized** per PrimoUpCore e componente Richiami:
+  - `listActiveCampaignsForOrg` – campagne active con latest version
+  - `getLatestPublishedVersion` – versione più recente
+  - `getPatientCampaignMemberships` – membership lookup (index `by_org_patient`)
+  - `getAudiencePage` – paginazione deterministica (`by_version_createdAt`)
+  - `recordContactAttempt` – contatti con orgId
+  - `getFieldRegistry` – field registry pubblico
+- **Demo datasource toggle**: `CAMPAIGNS_USE_DEMO_DATASOURCE` (default: true dev, false prod)
+- **Indici**: `contactLog.by_org_patient_time`, `audienceMembers.by_version_createdAt`, `by_version_clinic_createdAt`
+- **Hardening**: lifecycle transitions (`canTransitionCampaignStatus`), priority >= 1, clinicId normalization
+- **Packaging**: `campaignsPublic` export, tipi `CampaignCallPolicy`, `RuleGroup` esportati
+
+## 0.2.0
+
+- Added campaigns v2 backend engine with:
+  - rule DSL (`AND/OR` + atomic conditions) validated with `zod`
+  - field registry query (`getFieldRegistry`) and typed resolvers
+  - preview audience (`previewCampaignAudience`) with by-clinic breakdown + sample
+  - immutable campaign versions (`publishCampaignVersion`) and paginated audience (`getAudiencePage`)
+  - contact logging (`recordContactAttempt`)
+  - governance APIs (`upsertCampaign`, `setCampaignLifecycleStatus`, `listCampaignsV2`, `listCampaignVersions`)
+- Added demo data model and seed mutation (`seedDemoData`) for standalone testing.
+- Added data source adapter with demo/core fallback behavior.
+- Extended schema with new tables:
+  - `campaignVersions`, `audienceMembers`, `contactLog`
+  - `demoPatients`, `demoAppointments`, `demoEstimates`, `demoTreatmentPlans`
+- Added org-based indexes on `campaigns` (`by_org`, `by_org_status`, `by_org_priority`).
+- Added example React playground under `examples/campaigns-playground`.
+- Added automated tests for auth/index fallback and schema/input compatibility.
+
+## 0.1.3
+
+- Fixed robust identity mapping in auth:
+  - `subject -> by_auth0` with fallback if index unavailable
+  - `email -> by_email` with fallback if index unavailable
+  - final fallback `collect + find` for host compatibility
+- Improved authorization errors with structured, explicit codes:
+  - `CAMPAIGNS_UNAUTHORIZED`
+  - `CAMPAIGNS_AUTH_USER_NOT_MAPPED`
+  - `CAMPAIGNS_AUTH_NO_ACTIVE_ROLES`
+  - `CAMPAIGNS_FORBIDDEN`
+- Hardened public queries (`listCampaigns`, `getCampaign`, `getSnapshot`, `getCampaignReport`)
+  to return safe fallbacks on recoverable auth/index errors instead of crashing host UI.
+- Added safe index fallbacks for key campaigns lookups, including `campaign_steps.by_campaign`.
+- Added clinic scope compatibility:
+  - `scopeClinicIds` now accepts both `v.id("clinics")` and plain strings
+  - internal normalization/comparison is string-safe cross-host.
+- Added minimal automated tests for permissions fallback behavior.

package/README.md

@@ -40,7 +40,7 @@ Poi nel `convex.config.ts` dell'host installa il componente:
 
 ```ts
 import { defineApp } from "convex/server";
-import campaignsComponent from "@primocaredentgroup/convex-campaigns-component/convex.config";
+import { campaignsComponent } from "@primocaredentgroup/convex-campaigns-component/convex.config";
 
 const app = defineApp();
 app.use(campaignsComponent, { name: "campaigns" });
@@ -54,8 +54,120 @@ Infine esegui:
 npx convex dev
 ```
 
+## Sviluppo standalone (npx convex dev)
+
+Il componente ha il suo backend e può essere sviluppato in isolamento:
+
+```bash
+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`):
+
+```bash
+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:
+
+```bash
+CONVEX_URL=https://tuo-deployment.convex.cloud npm run smoke
+```
+
+Variabili: `SMOKE_ORG_ID`, `SMOKE_CLINIC_IDS`, `SMOKE_SKIP_SEED=1` per saltare seed.

package/convex/_generated/api.ts

@@ -2,3 +2,4 @@ import { componentsGeneric } from "convex/server";
 
 export const internal = componentsGeneric() as any;
 export const api = {} as any;
+export const components = componentsGeneric();

package/convex/campaigns.ts

@@ -20,3 +20,28 @@ export {
   ingestDeliveryStatus,
   runTick,
 } from "./components/campaigns/functions/actions";
+
+/** Public API stabile per PrimoUpCore e componente Richiami */
+export {
+  listActiveCampaignsForOrg,
+  getLatestPublishedVersion,
+  getPatientCampaignMemberships,
+  getAudiencePage,
+  recordContactAttempt,
+  getFieldRegistry,
+} from "./components/campaigns/functions/public";
+
+/** Playground/dev API (test, examples) */
+export {
+  getPlaygroundBootstrap,
+  seedDemoData,
+  upsertCampaign,
+  setCampaignLifecycleStatus,
+  listCampaignsV2,
+  getCampaignV2,
+  listCampaignVersions,
+  previewCampaignAudience,
+  publishCampaignVersion,
+  updateCampaignCallPolicy,
+  getCampaignCallPolicy,
+} from "./components/campaigns/functions/playground";

package/convex/components/campaigns/domain/stateMachine.ts

@@ -1,5 +1,21 @@
 import type { RecipientState } from "./types";
 
+export type CampaignLifecycleStatus = "draft" | "ready" | "archived";
+
+const CAMPAIGN_ALLOWED_TRANSITIONS: Record<CampaignLifecycleStatus, CampaignLifecycleStatus[]> = {
+  draft: ["ready", "archived"],
+  ready: ["draft", "archived"],
+  archived: ["draft"],
+};
+
+export function canTransitionCampaignStatus(
+  from: CampaignLifecycleStatus,
+  to: CampaignLifecycleStatus,
+): boolean {
+  if (from === to) return true;
+  return CAMPAIGN_ALLOWED_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
 const ALLOWED_TRANSITIONS: Record<RecipientState, RecipientState[]> = {
   ELIGIBLE: ["SUPPRESSED", "QUEUED", "CONVERTED"],
   SUPPRESSED: ["QUEUED", "CONVERTED"],

package/convex/components/campaigns/domain/types.ts

@@ -1,7 +1,16 @@
 import { v } from "convex/values";
 
 export const CAMPAIGN_SCOPE_TYPES = ["HQ", "CLINIC"] as const;
-export const CAMPAIGN_STATUSES = ["DRAFT", "RUNNING", "PAUSED", "COMPLETED", "ARCHIVED"] as const;
+export const CAMPAIGN_STATUSES = [
+  "DRAFT",
+  "RUNNING",
+  "PAUSED",
+  "COMPLETED",
+  "ARCHIVED",
+  "draft",
+  "ready",
+  "archived",
+] as const;
 export const STEP_TYPES = ["EMAIL", "SMS", "CALL_CLINIC", "CALL_CENTER"] as const;
 export const SNAPSHOT_STATUSES = ["BUILDING", "READY", "FAILED"] as const;
 export const SEGMENT_TYPES = ["RECALL", "QUOTE_FOLLOWUP", "NO_SHOW", "CUSTOM_IDS"] as const;
@@ -32,6 +41,9 @@ export const campaignStatusValidator = v.union(
   v.literal("PAUSED"),
   v.literal("COMPLETED"),
   v.literal("ARCHIVED"),
+  v.literal("draft"),
+  v.literal("ready"),
+  v.literal("archived"),
 );
 export const stepTypeValidator = v.union(
   v.literal("EMAIL"),
@@ -107,3 +119,44 @@ export const DEFAULT_RUN_CONFIG = {
   capMaxContacts: 1,
   lockDays: 7,
 };
+
+// --- Call Policy (marketing) ---
+export const OUTCOME_CATEGORIES = ["success", "retry", "fail", "optout"] as const;
+export type OutcomeCategory = (typeof OUTCOME_CATEGORIES)[number];
+
+export const outcomeCategoryValidator = v.union(
+  v.literal("success"),
+  v.literal("retry"),
+  v.literal("fail"),
+  v.literal("optout"),
+);
+
+export const campaignOutcomeValidator = v.object({
+  id: v.string(),
+  label: v.string(),
+  category: outcomeCategoryValidator,
+  isActive: v.boolean(),
+});
+
+export const callPolicyValidator = v.object({
+  dailyQuotaByClinic: v.optional(v.record(v.string(), v.number())),
+  maxAttempts: v.number(),
+  retryDelaysDays: v.array(v.number()),
+  outcomes: v.array(campaignOutcomeValidator),
+});
+
+export const DEFAULT_CALL_POLICY_OUTCOMES = [
+  { id: "success_appointment", label: "Appuntamento fissato", category: "success" as const, isActive: true },
+  { id: "retry_call_later", label: "Richiamare più tardi", category: "retry" as const, isActive: true },
+  { id: "no_answer", label: "Nessuna risposta", category: "retry" as const, isActive: true },
+  { id: "wrong_number", label: "Numero errato", category: "fail" as const, isActive: true },
+  { id: "not_interested", label: "Non interessato", category: "fail" as const, isActive: true },
+  { id: "opt_out", label: "Opt-out", category: "optout" as const, isActive: true },
+];
+
+export const DEFAULT_CALL_POLICY = {
+  dailyQuotaByClinic: {} as Record<string, number>,
+  maxAttempts: 3,
+  retryDelaysDays: [1, 3, 7],
+  outcomes: DEFAULT_CALL_POLICY_OUTCOMES,
+};

package/convex/components/campaigns/functions/authzInternal.ts

@@ -6,6 +6,43 @@ function normalizeRole(role: string | undefined): string | null {
   return value.length > 0 ? value : null;
 }
 
+function isIndexError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Index") && message.includes("not found");
+}
+
+async function queryUserByAuth0WithFallback(ctx: any, subject: string) {
+  try {
+    const byAuth0 = await ctx.db
+      .query("users")
+      .withIndex("by_auth0", (q: any) => q.eq("auth0Id", subject))
+      .first();
+    if (byAuth0?.isActive) return byAuth0;
+  } catch (error) {
+    // Fallback for hosts where users.by_auth0 is unavailable.
+    if (!isIndexError(error)) throw error;
+  }
+
+  const users = await ctx.db.query("users").collect();
+  return users.find((user: any) => user?.isActive && user?.auth0Id === subject) ?? null;
+}
+
+async function queryUserByEmailWithFallback(ctx: any, email: string) {
+  try {
+    const byEmail = await ctx.db
+      .query("users")
+      .withIndex("by_email", (q: any) => q.eq("email", email))
+      .first();
+    if (byEmail?.isActive) return byEmail;
+  } catch (error) {
+    // Fallback for hosts where users.by_email is unavailable.
+    if (!isIndexError(error)) throw error;
+  }
+
+  const users = await ctx.db.query("users").collect();
+  return users.find((user: any) => user?.isActive && user?.email === email) ?? null;
+}
+
 export const resolveRolesForIdentity = internalQuery({
   args: {
     subject: v.optional(v.string()),
@@ -15,22 +52,11 @@ export const resolveRolesForIdentity = internalQuery({
     let user = null;
 
     if (args.subject) {
-      try {
-        // Fallback for hosts where users.by_auth0 is unavailable.
-        user = await ctx.db
-          .query("users")
-          .withIndex("by_auth0", (q) => q.eq("auth0Id", args.subject))
-          .first();
-      } catch {
-        // Ignore index-resolution errors and continue with by_email fallback.
-      }
+      user = await queryUserByAuth0WithFallback(ctx, args.subject);
     }
 
     if (!user && args.email) {
-      user = await ctx.db
-        .query("users")
-        .withIndex("by_email", (q) => q.eq("email", args.email!))
-        .first();
+      user = await queryUserByEmailWithFallback(ctx, args.email);
     }
 
     if (!user || !user.isActive) {

package/convex/components/campaigns/functions/internal.ts

@@ -18,6 +18,66 @@ function resolveRunConfig(input?: Doc<"audience_snapshots">["runConfig"]) {
   };
 }
 
+async function safeCollectCampaignSteps(ctx: any, campaignId: Id<"campaigns">) {
+  try {
+    return await ctx.db
+      .query("campaign_steps")
+      .withIndex("by_campaign", (q: any) => q.eq("campaignId", campaignId))
+      .collect();
+  } catch {
+    return await ctx.db
+      .query("campaign_steps")
+      .filter((q: any) => q.eq(q.field("campaignId"), campaignId))
+      .collect();
+  }
+}
+
+async function safeCollectSnapshotsByCampaign(ctx: any, campaignId: Id<"campaigns">) {
+  try {
+    return await ctx.db
+      .query("audience_snapshots")
+      .withIndex("by_campaign_createdAt", (q: any) => q.eq("campaignId", campaignId))
+      .collect();
+  } catch {
+    return await ctx.db
+      .query("audience_snapshots")
+      .filter((q: any) => q.eq(q.field("campaignId"), campaignId))
+      .collect();
+  }
+}
+
+async function safeFirstSnapshotByStatus(ctx: any, status: "BUILDING" | "READY" | "FAILED") {
+  try {
+    return await ctx.db
+      .query("audience_snapshots")
+      .withIndex("by_status", (q: any) => q.eq("status", status))
+      .first();
+  } catch {
+    const docs = await ctx.db
+      .query("audience_snapshots")
+      .filter((q: any) => q.eq(q.field("status"), status))
+      .collect();
+    return docs[0] ?? null;
+  }
+}
+
+async function safeCollectCampaignsByStatus(
+  ctx: any,
+  status: "DRAFT" | "RUNNING" | "PAUSED" | "COMPLETED" | "ARCHIVED",
+) {
+  try {
+    return await ctx.db
+      .query("campaigns")
+      .withIndex("by_status", (q: any) => q.eq("status", status))
+      .collect();
+  } catch {
+    return await ctx.db
+      .query("campaigns")
+      .filter((q: any) => q.eq(q.field("status"), status))
+      .collect();
+  }
+}
+
 function computeDueAt(
   schedule: Doc<"campaign_steps">["scheduleSpec"],
   baseline: number,
@@ -144,10 +204,7 @@ async function buildSnapshotChunkCore(
     return { done: true, nextCursor: null as string | null };
   }
 
-  const steps = await ctx.db
-    .query("campaign_steps")
-    .withIndex("by_campaign", (q: any) => q.eq("campaignId", campaign._id))
-    .collect();
+  const steps = await safeCollectCampaignSteps(ctx, campaign._id);
   const orderedSteps = [...steps].sort((a, b) => a.order - b.order);
   if (orderedSteps.length === 0) {
     await ctx.db.patch(snapshotId, { status: "FAILED", updatedAt: Date.now() });
@@ -469,33 +526,21 @@ export const _runTickInternal = internalMutation({
   handler: async (ctx) => {
     await assertAuthorized(ctx, ["Admin", "Marketing", "System"]);
 
-    const buildingSnapshot = await ctx.db
-      .query("audience_snapshots")
-      .withIndex("by_status", (q) => q.eq("status", "BUILDING"))
-      .first();
+    const buildingSnapshot = await safeFirstSnapshotByStatus(ctx, "BUILDING");
     if (buildingSnapshot) {
       await buildSnapshotChunkCore(ctx as any, buildingSnapshot._id);
     }
 
-    const runningCampaigns = await ctx.db
-      .query("campaigns")
-      .withIndex("by_status", (q) => q.eq("status", "RUNNING"))
-      .collect();
+    const runningCampaigns = await safeCollectCampaignsByStatus(ctx, "RUNNING");
 
     for (const campaign of runningCampaigns.slice(0, 10)) {
-      const snapshots = await ctx.db
-        .query("audience_snapshots")
-        .withIndex("by_campaign_createdAt", (q) => q.eq("campaignId", campaign._id))
-        .collect();
+      const snapshots = await safeCollectSnapshotsByCampaign(ctx, campaign._id);
       const latestReady = snapshots
-        .filter((s) => s.status === "READY")
-        .sort((a, b) => b.createdAt - a.createdAt)[0];
+        .filter((s: any) => s.status === "READY")
+        .sort((a: any, b: any) => b.createdAt - a.createdAt)[0];
       if (!latestReady) continue;
 
-      const steps = await ctx.db
-        .query("campaign_steps")
-        .withIndex("by_campaign", (q) => q.eq("campaignId", campaign._id))
-        .collect();
+      const steps = await safeCollectCampaignSteps(ctx, campaign._id);
       const ordered = [...steps].sort((a, b) => a.order - b.order);
 
       for (const step of ordered.slice(0, 5)) {

package/convex/components/campaigns/functions/mutations.ts

@@ -12,6 +12,8 @@ import {
 import * as consentPort from "../ports/consent";
 import * as patientDataPort from "../ports/patientData";
 
+const clinicScopeIdValidator = v.union(v.id("clinics"), v.string());
+
 function withDefaultRunConfig(input?: {
   capWindowDays?: number;
   capMaxContacts?: number;
@@ -26,6 +28,12 @@ function withDefaultRunConfig(input?: {
   };
 }
 
+function normalizeScopeClinicIds(
+  scopeClinicIds: string[],
+): string[] {
+  return [...new Set(scopeClinicIds.map((id) => String(id).trim()).filter(Boolean))];
+}
+
 export const createCampaign = mutation({
   args: {
     input: v.object({
@@ -33,7 +41,7 @@ export const createCampaign = mutation({
       description: v.optional(v.string()),
       ownerUserId: v.optional(v.id("users")),
       scopeType: v.union(v.literal("HQ"), v.literal("CLINIC")),
-      scopeClinicIds: v.array(v.id("clinics")),
+      scopeClinicIds: v.array(clinicScopeIdValidator),
       priority: v.number(),
       defaultRunConfig: v.optional(runConfigValidator),
     }),
@@ -43,6 +51,7 @@ export const createCampaign = mutation({
     const now = Date.now();
     return ctx.db.insert("campaigns", {
       ...args.input,
+      scopeClinicIds: normalizeScopeClinicIds(args.input.scopeClinicIds as string[]),
       defaultRunConfig: withDefaultRunConfig(args.input.defaultRunConfig),
       status: "DRAFT",
       createdAt: now,
@@ -59,7 +68,7 @@ export const updateCampaign = mutation({
       description: v.optional(v.string()),
       ownerUserId: v.optional(v.id("users")),
       scopeType: v.optional(v.union(v.literal("HQ"), v.literal("CLINIC"))),
-      scopeClinicIds: v.optional(v.array(v.id("clinics"))),
+      scopeClinicIds: v.optional(v.array(clinicScopeIdValidator)),
       priority: v.optional(v.number()),
       defaultRunConfig: v.optional(runConfigValidator),
     }),
@@ -70,6 +79,9 @@ export const updateCampaign = mutation({
     if (!campaign) throw new Error("Campaign not found");
     await ctx.db.patch(args.campaignId, {
       ...args.patch,
+      scopeClinicIds: args.patch.scopeClinicIds
+        ? normalizeScopeClinicIds(args.patch.scopeClinicIds as string[])
+        : campaign.scopeClinicIds,
       defaultRunConfig: args.patch.defaultRunConfig
         ? withDefaultRunConfig(args.patch.defaultRunConfig)
         : campaign.defaultRunConfig,