@primocaredentgroup/convex-campaigns-component 0.1.1

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

@@ -0,0 +1,273 @@
+import type { QueryCtx, MutationCtx } from "../../../_generated/server";
+import type { Doc, Id } from "../../../_generated/dataModel";
+
+export type CampaignScope = {
+  scopeType: "HQ" | "CLINIC";
+  scopeClinicIds: Id<"clinics">[];
+};
+
+export type SegmentationRules = {
+  segmentType: "RECALL" | "QUOTE_FOLLOWUP" | "NO_SHOW" | "CUSTOM_IDS";
+  params?: any;
+};
+
+export type CandidatePatient = {
+  patientId: Id<"patients">;
+  clinicId?: Id<"clinics">;
+  email?: string;
+  phone?: string;
+};
+
+const DEFAULT_PAGE_SIZE = 200;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+type AppointmentDoc = Doc<"appointments">;
+
+async function deriveClinicIdFromAppointments(
+  ctx: QueryCtx | MutationCtx,
+  patient: Doc<"patients">,
+  scope: CampaignScope,
+): Promise<Id<"clinics"> | undefined> {
+  const appointments = await ctx.db
+    .query("appointments")
+    .withIndex("by_patient", (q) => q.eq("patientId", patient._id))
+    .collect();
+
+  const withClinic = appointments.find((a) => a.clinicId);
+  if (!withClinic?.clinicId) return undefined;
+  if (scope.scopeType === "HQ") return withClinic.clinicId;
+  if (scope.scopeClinicIds.includes(withClinic.clinicId)) return withClinic.clinicId;
+  return undefined;
+}
+
+function isAppointmentActive(appointment: AppointmentDoc): boolean {
+  return !appointment.deletedAt && !appointment.isSuspended;
+}
+
+function isInScope(
+  scope: CampaignScope,
+  clinicId: Id<"clinics"> | undefined,
+): boolean {
+  if (scope.scopeType === "HQ") return true;
+  if (!clinicId) return false;
+  return scope.scopeClinicIds.includes(clinicId);
+}
+
+async function resolveAppointmentTypeIdsByCodes(
+  ctx: QueryCtx | MutationCtx,
+  codes: string[],
+): Promise<Set<Id<"appointment_types">>> {
+  const ids = new Set<Id<"appointment_types">>();
+  for (const code of codes) {
+    const typeDoc = await ctx.db
+      .query("appointment_types")
+      .withIndex("by_code", (q) => q.eq("code", code))
+      .first();
+    if (typeDoc) ids.add(typeDoc._id);
+  }
+  return ids;
+}
+
+async function queryNoShowCandidates(
+  ctx: QueryCtx | MutationCtx,
+  campaignScope: CampaignScope,
+  params: any,
+  paginationCursor: string | null,
+): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
+  const daysBack = typeof params?.daysBack === "number" ? params.daysBack : 90;
+  const cutoff = Date.now() - daysBack * DAY_MS;
+  const patientPage = await ctx.db
+    .query("patients")
+    .withIndex("by_status", (q) => q.eq("status", "active"))
+    .paginate({ numItems: DEFAULT_PAGE_SIZE, cursor: paginationCursor ?? null });
+
+  const patients: CandidatePatient[] = [];
+  for (const patient of patientPage.page) {
+    const appointments = await ctx.db
+      .query("appointments")
+      .withIndex("by_patient", (q) => q.eq("patientId", patient._id))
+      .collect();
+
+    const hasNoShow = appointments.some(
+      (appointment) =>
+        isAppointmentActive(appointment) &&
+        appointment.status === "no-show" &&
+        appointment.appointmentDate >= cutoff &&
+        isInScope(campaignScope, appointment.clinicId),
+    );
+    if (!hasNoShow) continue;
+
+    const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
+    if (campaignScope.scopeType === "CLINIC" && !clinicId) continue;
+    patients.push({
+      patientId: patient._id,
+      clinicId,
+      email: patient.email,
+      phone: patient.phone,
+    });
+  }
+
+  return {
+    patients,
+    nextCursor: patientPage.isDone ? null : patientPage.continueCursor,
+  };
+}
+
+function hasFutureAppointment(appointments: AppointmentDoc[], now: number): boolean {
+  return appointments.some(
+    (a) =>
+      isAppointmentActive(a) &&
+      a.appointmentDate >= now &&
+      (a.status === "scheduled" || a.status === "confirmed"),
+  );
+}
+
+async function queryRecallOrQuoteFollowupCandidates(
+  ctx: QueryCtx | MutationCtx,
+  campaignScope: CampaignScope,
+  segmentationRules: SegmentationRules,
+  paginationCursor: string | null,
+): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
+  const now = Date.now();
+  const page = await ctx.db
+    .query("patients")
+    .withIndex("by_status", (q) => q.eq("status", "active"))
+    .paginate({ numItems: DEFAULT_PAGE_SIZE, cursor: paginationCursor ?? null });
+
+  const isRecall = segmentationRules.segmentType === "RECALL";
+  const monthsSince = typeof segmentationRules.params?.monthsSince === "number"
+    ? segmentationRules.params.monthsSince
+    : 6;
+  const daysSince = typeof segmentationRules.params?.daysSince === "number"
+    ? segmentationRules.params.daysSince
+    : 14;
+  const cutoffRecall = now - monthsSince * 30 * DAY_MS;
+  const cutoffQuote = now - daysSince * DAY_MS;
+
+  const defaultQuoteCodes = ["consultation", "quote", "preventivo"];
+  const quoteCodes = Array.isArray(segmentationRules.params?.appointmentTypeCodes)
+    ? (segmentationRules.params.appointmentTypeCodes as string[])
+    : defaultQuoteCodes;
+  const recallCodes = Array.isArray(segmentationRules.params?.appointmentTypeCodes)
+    ? (segmentationRules.params.appointmentTypeCodes as string[])
+    : [];
+  const typeCodes = isRecall ? recallCodes : quoteCodes;
+  let typeIds = typeCodes.length
+    ? await resolveAppointmentTypeIdsByCodes(ctx, typeCodes)
+    : new Set<Id<"appointment_types">>();
+  // If requested quote codes are not configured yet, fallback to all completed appointments.
+  if (!isRecall && typeCodes.length > 0 && typeIds.size === 0) {
+    typeIds = new Set<Id<"appointment_types">>();
+  }
+
+  const patients: CandidatePatient[] = [];
+  for (const patient of page.page) {
+    const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
+    if (campaignScope.scopeType === "CLINIC" && !clinicId) continue;
+
+    const appointments = await ctx.db
+      .query("appointments")
+      .withIndex("by_patient", (q) => q.eq("patientId", patient._id))
+      .collect();
+    const activeAppointments = appointments.filter(isAppointmentActive);
+    if (activeAppointments.length === 0) continue;
+    if (hasFutureAppointment(activeAppointments, now)) continue;
+
+    const completed = activeAppointments
+      .filter((a) => a.status === "completed")
+      .filter((a) =>
+        typeIds.size > 0 ? (a.appointmentTypeId ? typeIds.has(a.appointmentTypeId) : false) : true,
+      );
+
+    if (completed.length === 0) continue;
+    const lastCompleted = completed.reduce((acc, curr) =>
+      curr.appointmentDate > acc.appointmentDate ? curr : acc,
+    );
+
+    const qualifies = isRecall
+      ? lastCompleted.appointmentDate <= cutoffRecall
+      : lastCompleted.appointmentDate <= cutoffQuote;
+    if (!qualifies) continue;
+
+    patients.push({
+      patientId: patient._id,
+      clinicId,
+      email: patient.email,
+      phone: patient.phone,
+    });
+  }
+
+  return { patients, nextCursor: page.isDone ? null : page.continueCursor };
+}
+
+export async function queryCandidates(
+  ctx: QueryCtx | MutationCtx,
+  campaignScope: CampaignScope,
+  segmentationRules: SegmentationRules,
+  paginationCursor: string | null,
+): Promise<{ patients: CandidatePatient[]; nextCursor: string | null }> {
+  if (segmentationRules.segmentType === "CUSTOM_IDS") {
+    const patientIds = Array.isArray(segmentationRules.params?.patientIds)
+      ? (segmentationRules.params.patientIds as Id<"patients">[])
+      : [];
+    const offset = paginationCursor ? Number(paginationCursor) : 0;
+    const chunk = patientIds.slice(offset, offset + DEFAULT_PAGE_SIZE);
+
+    const patients: CandidatePatient[] = [];
+    for (const patientId of chunk) {
+      const patient = await ctx.db.get(patientId);
+      if (!patient || patient.status === "archived") continue;
+      const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
+      if (campaignScope.scopeType === "CLINIC" && !clinicId) continue;
+      patients.push({
+        patientId: patient._id,
+        clinicId,
+        email: patient.email,
+        phone: patient.phone,
+      });
+    }
+
+    const next = offset + chunk.length;
+    return { patients, nextCursor: next < patientIds.length ? String(next) : null };
+  }
+
+  if (segmentationRules.segmentType === "NO_SHOW") {
+    return queryNoShowCandidates(
+      ctx,
+      campaignScope,
+      segmentationRules.params,
+      paginationCursor,
+    );
+  }
+
+  if (
+    segmentationRules.segmentType === "RECALL" ||
+    segmentationRules.segmentType === "QUOTE_FOLLOWUP"
+  ) {
+    return queryRecallOrQuoteFollowupCandidates(
+      ctx,
+      campaignScope,
+      segmentationRules,
+      paginationCursor,
+    );
+  }
+
+  const page = await ctx.db
+    .query("patients")
+    .withIndex("by_status", (q) => q.eq("status", "active"))
+    .paginate({ numItems: DEFAULT_PAGE_SIZE, cursor: paginationCursor ?? null });
+
+  const patients: CandidatePatient[] = [];
+  for (const patient of page.page) {
+    const clinicId = await deriveClinicIdFromAppointments(ctx, patient, campaignScope);
+    if (campaignScope.scopeType === "CLINIC" && !clinicId) continue;
+    patients.push({
+      patientId: patient._id,
+      clinicId,
+      email: patient.email,
+      phone: patient.phone,
+    });
+  }
+
+  return { patients, nextCursor: page.isDone ? null : page.continueCursor };
+}

package/convex/components/campaigns/schema.ts

@@ -0,0 +1,154 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+import {
+  campaignStatusValidator,
+  recipientStateValidator,
+  runConfigValidator,
+  scopeTypeValidator,
+  scheduleSpecValidator,
+  segmentationRulesValidator,
+  snapshotStatusValidator,
+  stepTypeValidator,
+} from "./domain/types";
+
+export const campaignsTables = {
+  campaigns: defineTable({
+    name: v.string(),
+    description: v.optional(v.string()),
+    ownerUserId: v.optional(v.id("users")),
+    scopeType: scopeTypeValidator,
+    scopeClinicIds: v.array(v.id("clinics")),
+    priority: v.number(),
+    status: campaignStatusValidator,
+    defaultRunConfig: runConfigValidator,
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  }).index("by_status", ["status"]),
+
+  campaign_steps: defineTable({
+    campaignId: v.id("campaigns"),
+    order: v.number(),
+    type: stepTypeValidator,
+    templateRef: v.optional(v.string()),
+    scheduleSpec: scheduleSpecValidator,
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_campaign", ["campaignId"])
+    .index("by_campaign_order", ["campaignId", "order"]),
+
+  audience_snapshots: defineTable({
+    campaignId: v.id("campaigns"),
+    createdAt: v.number(),
+    createdBy: v.optional(v.id("users")),
+    status: snapshotStatusValidator,
+    segmentationRules: segmentationRulesValidator,
+    runConfig: runConfigValidator,
+    nextCursor: v.optional(v.string()),
+    stats: v.object({
+      totalCandidates: v.number(),
+      eligible: v.number(),
+      suppressedByReason: v.record(v.string(), v.number()),
+      queued: v.number(),
+      sent: v.number(),
+      taskCreated: v.number(),
+      completed: v.number(),
+      converted: v.number(),
+      failed: v.number(),
+    }),
+    updatedAt: v.number(),
+  })
+    .index("by_campaign_createdAt", ["campaignId", "createdAt"])
+    .index("by_status", ["status"]),
+
+  audience_members: defineTable({
+    snapshotId: v.id("audience_snapshots"),
+    campaignId: v.id("campaigns"),
+    patientId: v.id("patients"),
+    clinicId: v.optional(v.id("clinics")),
+    contactRefs: v.object({
+      email: v.optional(v.string()),
+      phone: v.optional(v.string()),
+    }),
+    eligibility: v.object({
+      email: v.boolean(),
+      sms: v.boolean(),
+      phone: v.boolean(),
+      blacklisted: v.boolean(),
+    }),
+    createdAt: v.number(),
+  })
+    .index("by_snapshot", ["snapshotId"])
+    .index("by_snapshot_patient", ["snapshotId", "patientId"]),
+
+  recipient_states: defineTable({
+    campaignId: v.id("campaigns"),
+    snapshotId: v.id("audience_snapshots"),
+    patientId: v.id("patients"),
+    stepId: v.id("campaign_steps"),
+    state: recipientStateValidator,
+    reason: v.optional(v.string()),
+    dueAt: v.optional(v.number()),
+    lastEventAt: v.optional(v.number()),
+    updatedAt: v.number(),
+    createdAt: v.number(),
+  })
+    .index("by_snapshot_step_state", ["snapshotId", "stepId", "state"])
+    .index("by_snapshot_step_state_dueAt", ["snapshotId", "stepId", "state", "dueAt"])
+    .index("by_snapshot_patient_step", ["snapshotId", "patientId", "stepId"]),
+
+  contact_locks: defineTable({
+    patientId: v.id("patients"),
+    lockedByCampaignId: v.id("campaigns"),
+    until: v.number(),
+    reason: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  }).index("by_patient", ["patientId"]),
+
+  event_log: defineTable({
+    campaignId: v.optional(v.id("campaigns")),
+    snapshotId: v.optional(v.id("audience_snapshots")),
+    patientId: v.optional(v.id("patients")),
+    type: v.string(),
+    payload: v.optional(v.any()),
+    idempotencyKey: v.optional(v.string()),
+    createdAt: v.number(),
+  })
+    .index("by_campaign_createdAt", ["campaignId", "createdAt"])
+    .index("by_idempotency_key", ["idempotencyKey"])
+    .index("by_patient_createdAt", ["patientId", "createdAt"]),
+
+  message_jobs: defineTable({
+    channel: v.union(v.literal("EMAIL"), v.literal("SMS")),
+    campaignId: v.id("campaigns"),
+    snapshotId: v.id("audience_snapshots"),
+    patientId: v.id("patients"),
+    stepId: v.id("campaign_steps"),
+    payload: v.any(),
+    status: v.string(),
+    dedupeKey: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_status", ["status"])
+    .index("by_dedupe_key", ["dedupeKey"]),
+
+  call_tasks_outbox: defineTable({
+    patientId: v.id("patients"),
+    clinicId: v.optional(v.id("clinics")),
+    campaignId: v.id("campaigns"),
+    snapshotId: v.id("audience_snapshots"),
+    stepId: v.id("campaign_steps"),
+    dueAt: v.number(),
+    priority: v.number(),
+    script: v.optional(v.string()),
+    attempt: v.number(),
+    status: v.string(),
+    dedupeKey: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_status", ["status"])
+    .index("by_dedupe_key", ["dedupeKey"]),
+};

package/convex.config.ts

@@ -0,0 +1,6 @@
+import { defineComponent } from "convex/server";
+
+// Convex component definition entrypoint for npm distribution.
+const component = defineComponent("campaigns");
+
+export default component;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@primocaredentgroup/convex-campaigns-component",
+  "version": "0.1.1",
+  "description": "Convex Campaigns backend component for PrimoCore",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "convex.config.ts",
+  "files": [
+    "convex.config.ts",
+    "README.md",
+    "convex/**"
+  ],
+  "scripts": {
+    "sync:from-repo": "node ./scripts/sync-from-repo.mjs",
+    "prepack": "npm run sync:from-repo"
+  },
+  "peerDependencies": {
+    "convex": "^1.14.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  }
+}