@primocaredentgroup/convex-campaigns-component 0.1.1

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

@@ -0,0 +1,508 @@
+import { v } from "convex/values";
+import { internalMutation } from "../../../_generated/server";
+import type { Id, Doc } from "../../../_generated/dataModel";
+import { assertAuthorized } from "../permissions";
+import { canTransitionRecipientState } from "../domain/stateMachine";
+import { DEFAULT_RUN_CONFIG, type SuppressionReason } from "../domain/types";
+import * as consentPort from "../ports/consent";
+import * as patientDataPort from "../ports/patientData";
+import * as messagingPort from "../ports/messaging";
+import * as callCenterPort from "../ports/callCenter";
+
+function resolveRunConfig(input?: Doc<"audience_snapshots">["runConfig"]) {
+  return {
+    capWindowDays: input?.capWindowDays ?? DEFAULT_RUN_CONFIG.capWindowDays,
+    capMaxContacts: input?.capMaxContacts ?? DEFAULT_RUN_CONFIG.capMaxContacts,
+    lockDays: input?.lockDays ?? DEFAULT_RUN_CONFIG.lockDays,
+    quietHours: input?.quietHours,
+  };
+}
+
+function computeDueAt(
+  schedule: Doc<"campaign_steps">["scheduleSpec"],
+  baseline: number,
+  now: number,
+): number {
+  if (schedule.mode === "AT" && schedule.at) return schedule.at;
+  if (schedule.mode === "DELAY") {
+    return baseline + (schedule.delayMinutes ?? 0) * 60_000;
+  }
+  return now;
+}
+
+async function upsertRecipientState(
+  ctx: any,
+  input: {
+    snapshotId: Id<"audience_snapshots">;
+    campaignId: Id<"campaigns">;
+    patientId: Id<"patients">;
+    stepId: Id<"campaign_steps">;
+    state: Doc<"recipient_states">["state"];
+    reason?: string;
+    dueAt?: number;
+  },
+) {
+  const now = Date.now();
+  const existing = await ctx.db
+    .query("recipient_states")
+    .withIndex("by_snapshot_patient_step", (q: any) =>
+      q
+        .eq("snapshotId", input.snapshotId)
+        .eq("patientId", input.patientId)
+        .eq("stepId", input.stepId),
+    )
+    .first();
+
+  if (!existing) {
+    await ctx.db.insert("recipient_states", {
+      ...input,
+      createdAt: now,
+      updatedAt: now,
+      lastEventAt: now,
+    });
+    return;
+  }
+
+  if (!canTransitionRecipientState(existing.state as any, input.state as any)) {
+    return;
+  }
+
+  if (
+    existing.state !== input.state ||
+    existing.reason !== input.reason ||
+    existing.dueAt !== input.dueAt
+  ) {
+    await ctx.db.patch(existing._id, {
+      state: input.state,
+      reason: input.reason,
+      dueAt: input.dueAt,
+      updatedAt: now,
+      lastEventAt: now,
+    });
+  }
+}
+
+async function countRecentContacts(
+  ctx: any,
+  patientId: Id<"patients">,
+  windowStart: number,
+) {
+  const events = await ctx.db
+    .query("event_log")
+    .withIndex("by_patient_createdAt", (q: any) =>
+      q.eq("patientId", patientId).gte("createdAt", windowStart),
+    )
+    .collect();
+
+  return events.filter(
+    (e: any) =>
+      e.type === "message_sent" ||
+      e.type === "message_queued" ||
+      e.type === "call_task_created",
+  ).length;
+}
+
+async function resolveSuppressionReason(input: {
+  lockedByOther: boolean;
+  capExceeded: boolean;
+  consent: Awaited<ReturnType<typeof consentPort.getConsent>>;
+  stepType: Doc<"campaign_steps">["type"];
+  hasEmail: boolean;
+  hasPhone: boolean;
+}): Promise<SuppressionReason | null> {
+  if (input.lockedByOther) return "LOCKED";
+  if (input.capExceeded) return "CAP";
+  if (input.consent.blacklisted) return "BLACKLIST";
+
+  if (input.stepType === "EMAIL") {
+    if (!input.consent.email) return "NO_CONSENT";
+    if (!input.hasEmail) return "INVALID_CONTACT";
+  }
+  if (input.stepType === "SMS") {
+    if (!input.consent.sms) return "NO_CONSENT";
+    if (!input.hasPhone) return "INVALID_CONTACT";
+  }
+  if (input.stepType === "CALL_CENTER" || input.stepType === "CALL_CLINIC") {
+    if (!input.consent.phone) return "NO_CONSENT";
+    if (!input.hasPhone) return "INVALID_CONTACT";
+  }
+
+  return null;
+}
+
+async function buildSnapshotChunkCore(
+  ctx: any,
+  snapshotId: Id<"audience_snapshots">,
+  forcedCursor?: string,
+) {
+  const snapshot = await ctx.db.get(snapshotId);
+  if (!snapshot || snapshot.status !== "BUILDING") return { done: true, nextCursor: null as string | null };
+
+  const campaign = await ctx.db.get(snapshot.campaignId);
+  if (!campaign) {
+    await ctx.db.patch(snapshotId, { status: "FAILED", updatedAt: Date.now() });
+    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 orderedSteps = [...steps].sort((a, b) => a.order - b.order);
+  if (orderedSteps.length === 0) {
+    await ctx.db.patch(snapshotId, { status: "FAILED", updatedAt: Date.now() });
+    return { done: true, nextCursor: null as string | null };
+  }
+
+  const runConfig = resolveRunConfig(snapshot.runConfig);
+  const cursor = forcedCursor ?? snapshot.nextCursor ?? null;
+  const { patients, nextCursor } = await patientDataPort.queryCandidates(
+    ctx,
+    { scopeType: campaign.scopeType, scopeClinicIds: campaign.scopeClinicIds },
+    snapshot.segmentationRules as any,
+    cursor,
+  );
+
+  const now = Date.now();
+  let deltaTotal = 0;
+  let deltaEligible = 0;
+  let deltaQueued = 0;
+  const suppressedByReason: Record<string, number> = {};
+
+  for (const p of patients) {
+    deltaTotal += 1;
+    const consent = await consentPort.getConsent(ctx, p.patientId);
+    const existingMember = await ctx.db
+      .query("audience_members")
+      .withIndex("by_snapshot_patient", (q: any) =>
+        q.eq("snapshotId", snapshot._id).eq("patientId", p.patientId),
+      )
+      .first();
+
+    if (!existingMember) {
+      await ctx.db.insert("audience_members", {
+        snapshotId: snapshot._id,
+        campaignId: campaign._id,
+        patientId: p.patientId,
+        clinicId: p.clinicId,
+        contactRefs: { email: p.email, phone: p.phone },
+        eligibility: {
+          email: consent.email,
+          sms: consent.sms,
+          phone: consent.phone,
+          blacklisted: consent.blacklisted,
+        },
+        createdAt: now,
+      });
+    }
+
+    const activeLock = await ctx.db
+      .query("contact_locks")
+      .withIndex("by_patient", (q: any) => q.eq("patientId", p.patientId))
+      .first();
+    const lockedByOther =
+      Boolean(activeLock) &&
+      (activeLock?.until ?? 0) > now &&
+      activeLock?.lockedByCampaignId !== campaign._id;
+
+    const contactCount = await countRecentContacts(
+      ctx,
+      p.patientId,
+      now - runConfig.capWindowDays * 24 * 60 * 60 * 1000,
+    );
+    const capExceeded = contactCount >= runConfig.capMaxContacts;
+
+    let patientHasAtLeastOneEligibleStep = false;
+    for (const step of orderedSteps) {
+      const suppression = await resolveSuppressionReason({
+        lockedByOther,
+        capExceeded,
+        consent,
+        stepType: step.type,
+        hasEmail: Boolean(p.email),
+        hasPhone: Boolean(p.phone),
+      });
+
+      if (suppression) {
+        suppressedByReason[suppression] = (suppressedByReason[suppression] ?? 0) + 1;
+        await upsertRecipientState(ctx, {
+          snapshotId: snapshot._id,
+          campaignId: campaign._id,
+          patientId: p.patientId,
+          stepId: step._id,
+          state: "SUPPRESSED",
+          reason: suppression,
+        });
+        continue;
+      }
+
+      const dueAt = computeDueAt(step.scheduleSpec, snapshot.createdAt, now);
+      const nextState = dueAt <= now ? "QUEUED" : "ELIGIBLE";
+      if (nextState === "QUEUED") deltaQueued += 1;
+      patientHasAtLeastOneEligibleStep = true;
+
+      await upsertRecipientState(ctx, {
+        snapshotId: snapshot._id,
+        campaignId: campaign._id,
+        patientId: p.patientId,
+        stepId: step._id,
+        state: nextState,
+        dueAt,
+      });
+    }
+
+    if (patientHasAtLeastOneEligibleStep && !lockedByOther) {
+      deltaEligible += 1;
+      if (!activeLock || activeLock.lockedByCampaignId !== campaign._id) {
+        const until = now + runConfig.lockDays * 24 * 60 * 60 * 1000;
+        if (!activeLock) {
+          await ctx.db.insert("contact_locks", {
+            patientId: p.patientId,
+            lockedByCampaignId: campaign._id,
+            until,
+            reason: "campaign_snapshot",
+            createdAt: now,
+            updatedAt: now,
+          });
+        } else {
+          await ctx.db.patch(activeLock._id, {
+            lockedByCampaignId: campaign._id,
+            until,
+            reason: "campaign_snapshot",
+            updatedAt: now,
+          });
+        }
+      }
+    } else if (lockedByOther) {
+      await ctx.db.insert("event_log", {
+        campaignId: campaign._id,
+        snapshotId: snapshot._id,
+        patientId: p.patientId,
+        type: "recipient_suppressed",
+        payload: { reason: "LOCKED" },
+        createdAt: now,
+      });
+    }
+  }
+
+  const mergedSuppressed = { ...snapshot.stats.suppressedByReason };
+  for (const [reason, count] of Object.entries(suppressedByReason)) {
+    mergedSuppressed[reason] = (mergedSuppressed[reason] ?? 0) + count;
+  }
+
+  const finished = nextCursor === null;
+  await ctx.db.patch(snapshot._id, {
+    nextCursor: nextCursor ?? undefined,
+    status: finished ? "READY" : "BUILDING",
+    updatedAt: now,
+    stats: {
+      ...snapshot.stats,
+      totalCandidates: snapshot.stats.totalCandidates + deltaTotal,
+      eligible: snapshot.stats.eligible + deltaEligible,
+      queued: snapshot.stats.queued + deltaQueued,
+      suppressedByReason: mergedSuppressed,
+    },
+  });
+
+  if (finished) {
+    await ctx.db.insert("event_log", {
+      campaignId: campaign._id,
+      snapshotId: snapshot._id,
+      type: "audience_snapshot_built",
+      payload: { totalCandidates: deltaTotal },
+      createdAt: now,
+    });
+  }
+
+  return { done: finished, nextCursor };
+}
+
+async function enqueueStepJobsCore(
+  ctx: any,
+  snapshotId: Id<"audience_snapshots">,
+  stepId: Id<"campaign_steps">,
+  cursor?: string,
+) {
+  const step = await ctx.db.get(stepId);
+  const snapshot = await ctx.db.get(snapshotId);
+  if (!step || !snapshot) return { nextCursor: null as string | null, processed: 0 };
+
+  const now = Date.now();
+  const allQueued = await ctx.db
+    .query("recipient_states")
+    .withIndex("by_snapshot_step_state", (q: any) =>
+      q.eq("snapshotId", snapshotId).eq("stepId", stepId).eq("state", "QUEUED"),
+    )
+    .collect();
+  const due = allQueued.filter((r: any) => (r.dueAt ?? 0) <= now);
+  const offset = cursor ? Number(cursor) : 0;
+  const batch = due.slice(offset, offset + 100);
+
+  let sent = 0;
+  let taskCreated = 0;
+  let failed = 0;
+
+  for (const rs of batch) {
+    try {
+      const dedupeKey = `${snapshotId}:${stepId}:${rs.patientId}:${step.type}`;
+      if (step.type === "EMAIL") {
+        await messagingPort.enqueueEmail(ctx, {
+          campaignId: rs.campaignId,
+          snapshotId,
+          patientId: rs.patientId,
+          stepId,
+          dedupeKey,
+          payload: { templateRef: step.templateRef, patientId: rs.patientId },
+        });
+        await ctx.db.patch(rs._id, { state: "SENT", updatedAt: now, lastEventAt: now });
+        sent += 1;
+        await ctx.db.insert("event_log", {
+          campaignId: rs.campaignId,
+          snapshotId,
+          patientId: rs.patientId,
+          type: "message_queued",
+          payload: { channel: "EMAIL", stepId },
+          createdAt: now,
+        });
+      } else if (step.type === "SMS") {
+        await messagingPort.enqueueSms(ctx, {
+          campaignId: rs.campaignId,
+          snapshotId,
+          patientId: rs.patientId,
+          stepId,
+          dedupeKey,
+          payload: { templateRef: step.templateRef, patientId: rs.patientId },
+        });
+        await ctx.db.patch(rs._id, { state: "SENT", updatedAt: now, lastEventAt: now });
+        sent += 1;
+        await ctx.db.insert("event_log", {
+          campaignId: rs.campaignId,
+          snapshotId,
+          patientId: rs.patientId,
+          type: "message_queued",
+          payload: { channel: "SMS", stepId },
+          createdAt: now,
+        });
+      } else {
+        await callCenterPort.createOutboxTasks(ctx, [
+          {
+            patientId: rs.patientId,
+            clinicId: undefined,
+            campaignId: rs.campaignId,
+            snapshotId,
+            stepId,
+            dueAt: now,
+            priority: 0,
+            script: step.templateRef,
+            dedupeKey,
+          },
+        ]);
+        await ctx.db.patch(rs._id, { state: "TASK_CREATED", updatedAt: now, lastEventAt: now });
+        taskCreated += 1;
+        await ctx.db.insert("event_log", {
+          campaignId: rs.campaignId,
+          snapshotId,
+          patientId: rs.patientId,
+          type: "call_task_created",
+          payload: { stepId, channel: step.type },
+          createdAt: now,
+        });
+      }
+    } catch (error) {
+      await ctx.db.patch(rs._id, {
+        state: "FAILED",
+        reason: `enqueue_failed:${(error as Error).message}`,
+        updatedAt: now,
+        lastEventAt: now,
+      });
+      failed += 1;
+      await ctx.db.insert("event_log", {
+        campaignId: rs.campaignId,
+        snapshotId,
+        patientId: rs.patientId,
+        type: "message_failed",
+        payload: { stepId, error: (error as Error).message },
+        createdAt: now,
+      });
+    }
+  }
+
+  await ctx.db.patch(snapshotId, {
+    updatedAt: now,
+    stats: {
+      ...snapshot.stats,
+      sent: snapshot.stats.sent + sent,
+      taskCreated: snapshot.stats.taskCreated + taskCreated,
+      failed: snapshot.stats.failed + failed,
+    },
+  });
+
+  const next = offset + batch.length;
+  return { nextCursor: next < due.length ? String(next) : null, processed: batch.length };
+}
+
+export const _buildSnapshotChunk = internalMutation({
+  args: {
+    snapshotId: v.id("audience_snapshots"),
+    cursor: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing", "System"]);
+    return buildSnapshotChunkCore(ctx as any, args.snapshotId, args.cursor);
+  },
+});
+
+export const _enqueueStepJobs = internalMutation({
+  args: {
+    snapshotId: v.id("audience_snapshots"),
+    stepId: v.id("campaign_steps"),
+    cursor: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing", "System"]);
+    return enqueueStepJobsCore(ctx as any, args.snapshotId, args.stepId, args.cursor);
+  },
+});
+
+export const _runTickInternal = internalMutation({
+  args: {},
+  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();
+    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();
+
+    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 latestReady = snapshots
+        .filter((s) => s.status === "READY")
+        .sort((a, b) => 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 ordered = [...steps].sort((a, b) => a.order - b.order);
+
+      for (const step of ordered.slice(0, 5)) {
+        await enqueueStepJobsCore(ctx as any, latestReady._id, step._id);
+      }
+    }
+
+    return { ok: true, at: Date.now() };
+  },
+});