@primocaredentgroup/convex-campaigns-component 0.3.3 → 0.3.5

package/convex/campaigns.ts

@@ -2,6 +2,7 @@ export {
   listCampaigns,
   getCampaign,
   getSnapshot,
+  getSnapshotMemberSample,
   getCampaignReport,
 } from "./components/campaigns/functions/queries";
 

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

@@ -83,6 +83,15 @@ export const suppressionReasonValidator = v.union(
   v.literal("LOWER_PRIORITY"),
 );
 
+/**
+ * params esistenti: monthsSince, daysSince, daysBack, appointmentTypeCodes, patientIds
+ * params opzionali anagrafici:
+ *   genders?: ("M" | "F" | "O")[]
+ *   minAge?: number   -- età minima (anni compiuti, da birthDate)
+ *   maxAge?: number   -- età massima (anni compiuti)
+ *   residenceCityIds?: string[]
+ *   birthCityIds?: string[]
+ */
 export const segmentationRulesValidator = v.object({
   segmentType: segmentTypeValidator,
   params: v.optional(v.any()),

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

@@ -157,26 +157,40 @@ export const previewAudience = mutation({
   args: {
     campaignId: v.id("campaigns"),
     segmentationRules: segmentationRulesValidator,
+    sampleSize: v.optional(v.number()),
   },
   handler: async (ctx, args) => {
     await assertAuthorized(ctx, ["Admin", "Marketing"]);
     const campaign = await ctx.db.get(args.campaignId);
     if (!campaign) throw new Error("Campaign not found");
 
+    const sampleSize = Math.min(Math.max(1, args.sampleSize ?? 10), 50);
+    const sample: Array<{
+      patientId: string;
+      firstName?: string;
+      lastName?: string;
+      birthDate?: string;
+      gender?: string;
+      residenceCityName?: string;
+      email?: string;
+      phone?: string;
+    }> = [];
+
     let cursor: string | null = null;
     let total = 0;
     let withEmail = 0;
     let withPhone = 0;
     let blacklisted = 0;
-    const maxPages = 5;
+    const maxPages = 3;
     let pages = 0;
 
-    while (pages < maxPages) {
+    while (pages < maxPages && sample.length < sampleSize) {
       const page = await patientDataPort.queryCandidates(
         ctx,
         { scopeType: campaign.scopeType, scopeClinicIds: campaign.scopeClinicIds },
         args.segmentationRules as any,
         cursor,
+        { includeAnagrafica: true },
       );
       for (const p of page.patients) {
         total += 1;
@@ -184,6 +198,19 @@ export const previewAudience = mutation({
         if (p.email && consent.email) withEmail += 1;
         if (p.phone && consent.phone) withPhone += 1;
         if (consent.blacklisted) blacklisted += 1;
+
+        if (sample.length < sampleSize) {
+          sample.push({
+            patientId: p.patientId,
+            firstName: p.firstName,
+            lastName: p.lastName,
+            birthDate: p.birthDate,
+            gender: p.gender,
+            residenceCityName: p.residenceCityName,
+            email: p.email,
+            phone: p.phone,
+          });
+        }
       }
       cursor = page.nextCursor;
       pages += 1;
@@ -195,6 +222,7 @@ export const previewAudience = mutation({
       warnings: cursor
         ? ["Preview limited to first pages for performance. Build snapshot for full results."]
         : [],
+      sample,
     };
   },
 });

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

@@ -150,6 +150,74 @@ export const getSnapshot = query({
   },
 });
 
+export const getSnapshotMemberSample = query({
+  args: {
+    snapshotId: v.id("audience_snapshots"),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    try {
+      await assertAuthorized(ctx, ["Admin", "Marketing"]);
+      const limit = Math.min(Math.max(1, args.limit ?? 10), 100);
+
+      let members: any[];
+      try {
+        members = (await ctx.db
+          .query("audience_members")
+          .withIndex("by_snapshot", (q: any) => q.eq("snapshotId", args.snapshotId))
+          .collect()).slice(0, limit);
+      } catch {
+        members = (await ctx.db
+          .query("audience_members")
+          .filter((q: any) => q.eq(q.field("snapshotId"), args.snapshotId))
+          .collect()).slice(0, limit);
+      }
+
+      const sample: Array<{
+        patientId: string;
+        firstName?: string;
+        lastName?: string;
+        birthDate?: string;
+        gender?: string;
+        residenceCityName?: string;
+        email?: string;
+        phone?: string;
+      }> = [];
+
+      for (const m of members) {
+        const patient = await ctx.db.get(m.patientId);
+        if (!patient) continue;
+        const p = patient as any;
+        let residenceCityName: string | undefined;
+        if (p.residenceCityId) {
+          try {
+            const city = await ctx.db.get(p.residenceCityId);
+            residenceCityName = (city as any)?.name;
+          } catch {
+            // Host may not have cities table
+          }
+        }
+        sample.push({
+          patientId: m.patientId,
+          firstName: p.firstName,
+          lastName: p.lastName,
+          birthDate: p.birthDate,
+          gender: p.gender,
+          residenceCityName,
+          email: m.contactRefs?.email ?? p.email,
+          phone: m.contactRefs?.phone ?? p.phone ?? p.mobilePhone,
+        });
+      }
+
+      return { sample };
+    } catch (error) {
+      if (!isRecoverableQueryError(error)) throw error;
+      console.error("[campaigns.getSnapshotMemberSample] recoverable error:", error);
+      return { sample: [] };
+    }
+  },
+});
+
 export const getCampaignReport = query({
   args: {
     campaignId: v.id("campaigns"),

package/convex/components/campaigns/ports/patientData.ts

@@ -16,6 +16,11 @@ export type CandidatePatient = {
   clinicId?: Id<"clinics">;
   email?: string;
   phone?: string;
+  firstName?: string;
+  lastName?: string;
+  birthDate?: string;
+  gender?: string;
+  residenceCityName?: string;
 };
 
 const DEFAULT_PAGE_SIZE = 200;
@@ -23,6 +28,98 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 
 type AppointmentDoc = Doc<"appointments">;
 
+/** Calcola età in anni da birthDate (formato "YYYY-MM-DD" o simile) */
+function ageFromBirthDate(birthDate: string | undefined): number | null {
+  if (!birthDate) return null;
+  const parts = birthDate.split("-").map(Number);
+  if (parts.length < 2) return null;
+  const [y, m = 1, d = 1] = parts;
+  const birth = new Date(y, m - 1, d).getTime();
+  const now = Date.now();
+  return Math.floor((now - birth) / (365.25 * DAY_MS));
+}
+
+/**
+ * Verifica se il paziente passa i filtri demografici (genere, età, città).
+ * Se un filtro è assente, non viene applicato.
+ */
+export function matchesDemographicFilters(
+  patient: { gender?: string; birthDate?: string; residenceCityId?: any; birthCityId?: any },
+  params: any,
+): boolean {
+  if (!params) return true;
+
+  const genders = Array.isArray(params.genders) ? params.genders as string[] : [];
+  if (genders.length > 0 && patient.gender) {
+    if (!genders.includes(patient.gender)) return false;
+  }
+
+  const minAge = typeof params.minAge === "number" ? params.minAge : undefined;
+  const maxAge = typeof params.maxAge === "number" ? params.maxAge : undefined;
+  if (minAge != null || maxAge != null) {
+    const age = ageFromBirthDate(patient.birthDate);
+    if (age === null) return false;
+    if (minAge != null && age < minAge) return false;
+    if (maxAge != null && age > maxAge) return false;
+  }
+
+  const residenceCityIds = Array.isArray(params.residenceCityIds)
+    ? params.residenceCityIds.map(String)
+    : [];
+  if (residenceCityIds.length > 0 && patient.residenceCityId) {
+    if (!residenceCityIds.includes(String(patient.residenceCityId))) return false;
+  }
+
+  const birthCityIds = Array.isArray(params.birthCityIds) ? params.birthCityIds.map(String) : [];
+  if (birthCityIds.length > 0 && patient.birthCityId) {
+    if (!birthCityIds.includes(String(patient.birthCityId))) return false;
+  }
+
+  return true;
+}
+
+async function resolveResidenceCityName(
+  ctx: QueryCtx | MutationCtx,
+  residenceCityId: any,
+): Promise<string | undefined> {
+  if (!residenceCityId) return undefined;
+  try {
+    const city = await ctx.db.get(residenceCityId);
+    return (city as any)?.name;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildCandidatePatient(
+  patient: any,
+  clinicId: Id<"clinics"> | undefined,
+  residenceCityName?: string,
+): CandidatePatient {
+  return {
+    patientId: patient._id,
+    clinicId,
+    email: patient.email,
+    phone: patient.phone ?? patient.mobilePhone,
+    firstName: patient.firstName,
+    lastName: patient.lastName,
+    birthDate: patient.birthDate,
+    gender: patient.gender,
+    residenceCityName,
+  };
+}
+
+async function buildCandidateWithAnagrafica(
+  ctx: QueryCtx | MutationCtx,
+  patient: any,
+  clinicId: Id<"clinics"> | undefined,
+): Promise<CandidatePatient> {
+  const residenceCityName = patient.residenceCityId
+    ? await resolveResidenceCityName(ctx, patient.residenceCityId)
+    : undefined;
+  return buildCandidatePatient(patient, clinicId, residenceCityName);
+}
+
 async function deriveClinicIdFromAppointments(
   ctx: QueryCtx | MutationCtx,
   patient: Doc<"patients">,
@@ -73,6 +170,7 @@ async function queryNoShowCandidates(
   campaignScope: CampaignScope,
   params: any,
   paginationCursor: string | null,
+  options?: { includeAnagrafica?: boolean },
 ): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
   const daysBack = typeof params?.daysBack === "number" ? params.daysBack : 90;
   const cutoff = Date.now() - daysBack * DAY_MS;
@@ -96,15 +194,15 @@ async function queryNoShowCandidates(
         isInScope(campaignScope, appointment.clinicId),
     );
     if (!hasNoShow) continue;
+    if (!matchesDemographicFilters(patient as any, params)) continue;
 
     const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
     if (campaignScope.scopeType !== "HQ" && !clinicId) continue;
-    patients.push({
-      patientId: patient._id,
-      clinicId,
-      email: patient.email,
-      phone: patient.phone,
-    });
+    patients.push(
+      options?.includeAnagrafica
+        ? await buildCandidateWithAnagrafica(ctx, patient as any, clinicId)
+        : buildCandidatePatient(patient as any, clinicId),
+    );
   }
 
   return {
@@ -127,6 +225,7 @@ async function queryRecallOrQuoteFollowupCandidates(
   campaignScope: CampaignScope,
   segmentationRules: SegmentationRules,
   paginationCursor: string | null,
+  options?: { includeAnagrafica?: boolean },
 ): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
   const now = Date.now();
   const page = await ctx.db
@@ -188,13 +287,13 @@ async function queryRecallOrQuoteFollowupCandidates(
       ? lastCompleted.appointmentDate <= cutoffRecall
       : lastCompleted.appointmentDate <= cutoffQuote;
     if (!qualifies) continue;
+    if (!matchesDemographicFilters(patient as any, segmentationRules.params)) continue;
 
-    patients.push({
-      patientId: patient._id,
-      clinicId,
-      email: patient.email,
-      phone: patient.phone,
-    });
+    patients.push(
+      options?.includeAnagrafica
+        ? await buildCandidateWithAnagrafica(ctx, patient as any, clinicId)
+        : buildCandidatePatient(patient as any, clinicId),
+    );
   }
 
   return { patients, nextCursor: page.isDone ? null : page.continueCursor };
@@ -205,6 +304,7 @@ export async function queryCandidates(
   campaignScope: CampaignScope,
   segmentationRules: SegmentationRules,
   paginationCursor: string | null,
+  options?: { includeAnagrafica?: boolean },
 ): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
   if (segmentationRules.segmentType === "CUSTOM_IDS") {
     const patientIds = Array.isArray(segmentationRules.params?.patientIds)
@@ -217,14 +317,14 @@ export async function queryCandidates(
     for (const patientId of chunk) {
       const patient = await ctx.db.get(patientId);
       if (!patient || patient.status === "archived") continue;
+      if (!matchesDemographicFilters(patient as any, segmentationRules.params)) continue;
       const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
       if (campaignScope.scopeType !== "HQ" && !clinicId) continue;
-      patients.push({
-        patientId: patient._id,
-        clinicId,
-        email: patient.email,
-        phone: patient.phone,
-      });
+      patients.push(
+        options?.includeAnagrafica
+          ? await buildCandidateWithAnagrafica(ctx, patient as any, clinicId)
+          : buildCandidatePatient(patient as any, clinicId),
+      );
     }
 
     const next = offset + chunk.length;
@@ -237,6 +337,7 @@ export async function queryCandidates(
       campaignScope,
       segmentationRules.params,
       paginationCursor,
+      options,
     );
   }
 
@@ -249,6 +350,7 @@ export async function queryCandidates(
       campaignScope,
       segmentationRules,
       paginationCursor,
+      options,
     );
   }
 
@@ -259,14 +361,14 @@ export async function queryCandidates(
 
   const patients: CandidatePatient[] = [];
   for (const patient of page.page) {
+    if (!matchesDemographicFilters(patient as any, segmentationRules.params)) continue;
     const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
     if (campaignScope.scopeType !== "HQ" && !clinicId) continue;
-    patients.push({
-      patientId: patient._id,
-      clinicId,
-      email: patient.email,
-      phone: patient.phone,
-    });
+    patients.push(
+      options?.includeAnagrafica
+        ? await buildCandidateWithAnagrafica(ctx, patient as any, clinicId)
+        : buildCandidatePatient(patient as any, clinicId),
+    );
   }
 
   return { patients, nextCursor: page.isDone ? null : page.continueCursor };

package/convex/playground.ts

@@ -11,6 +11,9 @@ import { components } from "./_generated/api";
 
 const c = components as {
   campaigns?: {
+    campaignsQueries?: {
+      getSnapshotMemberSample: (args: { snapshotId: string; limit?: number }) => Promise<unknown>;
+    };
     campaignsPlayground?: {
       listCampaignsV2: (args: { orgId: string; status?: "draft" | "ready" | "archived" }) => Promise<unknown>;
       getPlaygroundBootstrap: (args: { orgId: string }) => Promise<unknown>;
@@ -79,6 +82,19 @@ export const getAudiencePage = query({
   },
 });
 
+export const getSnapshotMemberSample = query({
+  args: {
+    snapshotId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsQueries!.getSnapshotMemberSample, {
+      snapshotId: args.snapshotId,
+      limit: args.limit,
+    });
+  },
+});
+
 export const getPatientCampaignMemberships = query({
   args: { orgId: v.string(), patientId: v.string() },
   handler: async (ctx, args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primocaredentgroup/convex-campaigns-component",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Convex Campaigns backend component for PrimoCore",
   "license": "UNLICENSED",
   "type": "module",
@@ -9,20 +9,23 @@
     "convex.config.ts",
     "README.md",
     "CHANGELOG.md",
-    "convex/**",
-    "scripts/**"
+    "convex/**"
   ],
   "scripts": {
     "sync:from-repo": "node ./scripts/sync-from-repo.mjs",
     "prepack": "npm run sync:from-repo",
     "test": "tsx --test tests/**/*.test.ts",
-    "smoke": "node scripts/smoke-test.mjs"
+    "smoke": "node scripts/smoke-test.mjs",
+    "version:patch": "npm version patch --no-git-tag-version",
+    "publish:component": "npm run version:patch && npm publish"
   },
   "peerDependencies": {
     "convex": "^1.14.0"
   },
   "peerDependenciesMeta": {
-    "convex": { "optional": true }
+    "convex": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "convex": "^1.14.0",

package/scripts/smoke-test.mjs

@@ -1,171 +0,0 @@
-#!/usr/bin/env node
-/**
- * Smoke test per componente campaigns.
- * Chiama le API pubbliche in sequenza per verificare funzionamento end-to-end.
- *
- * L'URL Convex viene letto da (in ordine):
- * 1. CONVEX_URL o VITE_CONVEX_URL (env)
- * 2. .env.local (nella cwd o nelle cartelle parent)
- *
- * Uso:
- *   cd /path/alla/repo/convex-campaigns-component  # o repo con convex dev
- *   npm run smoke
- *
- *   # oppure con URL esplicito:
- *   CONVEX_URL=https://tuo-deployment.convex.cloud npm run smoke
- */
-import { ConvexHttpClient } from "convex/browser";
-import { readFileSync, existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-function loadEnvLocal() {
-  const dirs = [
-    process.cwd(),
-    resolve(process.cwd(), ".."),
-    resolve(process.cwd(), "../.."),
-    resolve(dirname(fileURLToPath(import.meta.url)), ".."),
-  ];
-  for (const dir of dirs) {
-    const p = resolve(dir, ".env.local");
-    if (existsSync(p)) {
-      try {
-        const content = readFileSync(p, "utf8");
-        for (const line of content.split("\n")) {
-          const m = line.match(/^(?:CONVEX_URL|VITE_CONVEX_URL)=(.+)$/);
-          if (m) return m[1].trim().replace(/^["']|["']$/g, "");
-        }
-      } catch {}
-    }
-  }
-  return null;
-}
-
-const CONVEX_URL =
-  process.env.CONVEX_URL ?? process.env.VITE_CONVEX_URL ?? loadEnvLocal();
-const ORG_ID = process.env.SMOKE_ORG_ID ?? "demo-org";
-const CLINIC_IDS = (process.env.SMOKE_CLINIC_IDS ?? "clinic-a,clinic-b")
-  .split(",")
-  .map((s) => s.trim());
-
-if (!CONVEX_URL) {
-  console.error(`
-ERRORE: URL Convex non trovato.
-
-Opzioni:
-1. Esegui da una cartella con .env.local (creato da "npx convex dev")
-2. Imposta CONVEX_URL:
-   CONVEX_URL=https://tuo-deployment.convex.cloud npm run smoke
-3. L'URL si trova nel dashboard Convex o in .env.local dopo convex dev
-`);
-  process.exit(1);
-}
-
-const client = new ConvexHttpClient(CONVEX_URL);
-
-async function run(name, fn) {
-  try {
-    const result = await fn();
-    console.log(`✓ ${name}`);
-    return result;
-  } catch (err) {
-    console.error(`✗ ${name}:`, err.message);
-    throw err;
-  }
-}
-
-async function main() {
-  console.log("Smoke test campaigns component...");
-  console.log("CONVEX_URL:", CONVEX_URL);
-  console.log("ORG_ID:", ORG_ID);
-
-  let campaignId;
-  let versionId;
-
-  if (process.env.SMOKE_SKIP_SEED !== "1") {
-    const seedResult = await run("seedDemoData", () =>
-      client.mutation("campaigns:seedDemoData", {
-        orgId: ORG_ID,
-        clinicIds: CLINIC_IDS,
-        nPatients: 50,
-      }),
-    );
-    console.log("  inserted:", seedResult?.insertedPatients);
-  }
-
-  const createResult = await run("upsertCampaign", () =>
-    client.mutation("campaigns:upsertCampaign", {
-      orgId: ORG_ID,
-      name: "Smoke Test Campaign",
-      clinicIds: CLINIC_IDS,
-      rules: {
-        op: "AND",
-        rules: [{ fieldKey: "patient.hasCallConsent", operator: "is", value: true }],
-      },
-      status: "draft",
-    }),
-  );
-  campaignId = createResult?.id;
-
-  await run("setCampaignLifecycleStatus ready", () =>
-    client.mutation("campaigns:setCampaignLifecycleStatus", {
-      campaignId,
-      status: "ready",
-    }),
-  );
-
-  const publishResult = await run("publishCampaignVersion", () =>
-    client.mutation("campaigns:publishCampaignVersion", {
-      campaignId,
-      label: "Smoke test",
-    }),
-  );
-  versionId = publishResult?.versionId;
-  console.log("  version:", publishResult?.version, "inserted:", publishResult?.inserted);
-
-  const active = await run("listActiveCampaignsForOrg", () =>
-    client.query("campaigns:listActiveCampaignsForOrg", {
-      orgId: ORG_ID,
-      clinicId: CLINIC_IDS[0],
-    }),
-  );
-  console.log("  campaigns:", active?.length);
-
-  const audience = await run("getAudiencePage", () =>
-    client.query("campaigns:getAudiencePage", {
-      versionId,
-      limit: 5,
-    }),
-  );
-  console.log("  page length:", audience?.page?.length);
-
-  const samplePatient = audience?.page?.[0]?.patientId;
-  if (samplePatient) {
-    await run("recordContactAttempt", () =>
-      client.mutation("campaigns:recordContactAttempt", {
-        orgId: ORG_ID,
-        clinicId: audience.page[0].clinicId,
-        patientId: samplePatient,
-        campaignId,
-        versionId,
-        channel: "call",
-        outcome: "answered",
-      }),
-    );
-  }
-
-  const memberships = await run("getPatientCampaignMemberships", () =>
-    client.query("campaigns:getPatientCampaignMemberships", {
-      orgId: ORG_ID,
-      patientId: samplePatient ?? "demo-smoke-org-clinic-a-1",
-    }),
-  );
-  console.log("  memberships:", memberships?.length);
-
-  console.log("\nSmoke test completato.");
-}
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});

package/scripts/sync-from-repo.mjs

@@ -1,42 +0,0 @@
-import { access, cp, mkdir, rm } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const packageRoot = path.resolve(__dirname, "..");
-const repoRoot = path.resolve(packageRoot, "..", "..");
-
-const sourceComponentDir = path.join(repoRoot, "convex", "components", "campaigns");
-const targetComponentDir = path.join(
-  packageRoot,
-  "convex",
-  "components",
-  "campaigns",
-);
-
-const sourcePublicApi = path.join(repoRoot, "convex", "campaigns.ts");
-const targetPublicApi = path.join(packageRoot, "convex", "campaigns.ts");
-
-async function main() {
-  const sourceExists = await access(sourceComponentDir).then(
-    () => true,
-    () => false,
-  );
-  if (!sourceExists) {
-    console.log("No external monorepo source found, keeping local component files.");
-    return;
-  }
-
-  await rm(targetComponentDir, { recursive: true, force: true });
-  await mkdir(path.dirname(targetComponentDir), { recursive: true });
-  await cp(sourceComponentDir, targetComponentDir, { recursive: true });
-  await cp(sourcePublicApi, targetPublicApi);
-  console.log("Synced campaigns component from repo into npm package.");
-}
-
-main().catch((error) => {
-  console.error("Failed to sync component files:", error);
-  process.exit(1);
-});