@primocaredentgroup/convex-campaigns-component 0.3.3 → 0.3.4

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.4",
   "description": "Convex Campaigns backend component for PrimoCore",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,7 +16,9 @@
     "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"