@primocaredentgroup/convex-campaigns-component 0.1.1

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

@@ -0,0 +1,225 @@
+import { v } from "convex/values";
+import { mutation } from "../../../_generated/server";
+import { assertAuthorized } from "../permissions";
+import {
+  campaignStatusValidator,
+  runConfigValidator,
+  scheduleSpecValidator,
+  segmentationRulesValidator,
+  stepTypeValidator,
+  DEFAULT_RUN_CONFIG,
+} from "../domain/types";
+import * as consentPort from "../ports/consent";
+import * as patientDataPort from "../ports/patientData";
+
+function withDefaultRunConfig(input?: {
+  capWindowDays?: number;
+  capMaxContacts?: number;
+  lockDays?: number;
+  quietHours?: { startHour: number; endHour: number; timezone?: string };
+}) {
+  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,
+  };
+}
+
+export const createCampaign = mutation({
+  args: {
+    input: v.object({
+      name: v.string(),
+      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")),
+      priority: v.number(),
+      defaultRunConfig: v.optional(runConfigValidator),
+    }),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    const now = Date.now();
+    return ctx.db.insert("campaigns", {
+      ...args.input,
+      defaultRunConfig: withDefaultRunConfig(args.input.defaultRunConfig),
+      status: "DRAFT",
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const updateCampaign = mutation({
+  args: {
+    campaignId: v.id("campaigns"),
+    patch: v.object({
+      name: v.optional(v.string()),
+      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"))),
+      priority: v.optional(v.number()),
+      defaultRunConfig: v.optional(runConfigValidator),
+    }),
+  },
+  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");
+    await ctx.db.patch(args.campaignId, {
+      ...args.patch,
+      defaultRunConfig: args.patch.defaultRunConfig
+        ? withDefaultRunConfig(args.patch.defaultRunConfig)
+        : campaign.defaultRunConfig,
+      updatedAt: Date.now(),
+    });
+    return { success: true };
+  },
+});
+
+export const setCampaignStatus = mutation({
+  args: {
+    campaignId: v.id("campaigns"),
+    status: campaignStatusValidator,
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    await ctx.db.patch(args.campaignId, { status: args.status, updatedAt: Date.now() });
+    await ctx.db.insert("event_log", {
+      campaignId: args.campaignId,
+      type: "campaign_status_changed",
+      payload: { status: args.status },
+      createdAt: Date.now(),
+    });
+    return { success: true };
+  },
+});
+
+export const addOrUpdateSteps = mutation({
+  args: {
+    campaignId: v.id("campaigns"),
+    steps: v.array(
+      v.object({
+        stepId: v.optional(v.id("campaign_steps")),
+        order: v.number(),
+        type: stepTypeValidator,
+        templateRef: v.optional(v.string()),
+        scheduleSpec: scheduleSpecValidator,
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    const now = Date.now();
+    const createdOrUpdated: string[] = [];
+    for (const step of args.steps) {
+      if (step.stepId) {
+        await ctx.db.patch(step.stepId, {
+          order: step.order,
+          type: step.type,
+          templateRef: step.templateRef,
+          scheduleSpec: step.scheduleSpec,
+          updatedAt: now,
+        });
+        createdOrUpdated.push(step.stepId);
+      } else {
+        const id = await ctx.db.insert("campaign_steps", {
+          campaignId: args.campaignId,
+          order: step.order,
+          type: step.type,
+          templateRef: step.templateRef,
+          scheduleSpec: step.scheduleSpec,
+          createdAt: now,
+          updatedAt: now,
+        });
+        createdOrUpdated.push(id);
+      }
+    }
+    return { stepIds: createdOrUpdated };
+  },
+});
+
+export const previewAudience = mutation({
+  args: {
+    campaignId: v.id("campaigns"),
+    segmentationRules: segmentationRulesValidator,
+  },
+  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");
+
+    let cursor: string | null = null;
+    let total = 0;
+    let withEmail = 0;
+    let withPhone = 0;
+    let blacklisted = 0;
+    const maxPages = 5;
+    let pages = 0;
+
+    while (pages < maxPages) {
+      const page = await patientDataPort.queryCandidates(
+        ctx,
+        { scopeType: campaign.scopeType, scopeClinicIds: campaign.scopeClinicIds },
+        args.segmentationRules as any,
+        cursor,
+      );
+      for (const p of page.patients) {
+        total += 1;
+        const consent = await consentPort.getConsent(ctx, p.patientId);
+        if (p.email && consent.email) withEmail += 1;
+        if (p.phone && consent.phone) withPhone += 1;
+        if (consent.blacklisted) blacklisted += 1;
+      }
+      cursor = page.nextCursor;
+      pages += 1;
+      if (!cursor) break;
+    }
+
+    return {
+      counts: { total, withEmail, withPhone, blacklisted },
+      warnings: cursor
+        ? ["Preview limited to first pages for performance. Build snapshot for full results."]
+        : [],
+    };
+  },
+});
+
+export const buildAudienceSnapshot = mutation({
+  args: {
+    campaignId: v.id("campaigns"),
+    segmentationRules: segmentationRulesValidator,
+    runConfig: v.optional(runConfigValidator),
+  },
+  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 now = Date.now();
+    const snapshotId = await ctx.db.insert("audience_snapshots", {
+      campaignId: args.campaignId,
+      createdAt: now,
+      createdBy: undefined,
+      status: "BUILDING",
+      segmentationRules: args.segmentationRules as any,
+      runConfig: withDefaultRunConfig(args.runConfig ?? campaign.defaultRunConfig),
+      nextCursor: undefined,
+      stats: {
+        totalCandidates: 0,
+        eligible: 0,
+        suppressedByReason: {},
+        queued: 0,
+        sent: 0,
+        taskCreated: 0,
+        completed: 0,
+        converted: 0,
+        failed: 0,
+      },
+      updatedAt: now,
+    });
+    return { snapshotId };
+  },
+});

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

@@ -0,0 +1,131 @@
+import { v } from "convex/values";
+import { query } from "../../../_generated/server";
+import { assertAuthorized } from "../permissions";
+import { campaignStatusValidator, scopeTypeValidator } from "../domain/types";
+
+export const listCampaigns = query({
+  args: {
+    filters: v.optional(
+      v.object({
+        status: v.optional(campaignStatusValidator),
+        scopeType: v.optional(scopeTypeValidator),
+        clinicId: v.optional(v.id("clinics")),
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    let campaigns = args.filters?.status
+      ? await ctx.db
+          .query("campaigns")
+          .withIndex("by_status", (q) => q.eq("status", args.filters!.status!))
+          .collect()
+      : await ctx.db.query("campaigns").collect();
+
+    if (args.filters?.scopeType) {
+      campaigns = campaigns.filter((c) => c.scopeType === args.filters?.scopeType);
+    }
+    if (args.filters?.clinicId) {
+      campaigns = campaigns.filter((c) => c.scopeClinicIds.includes(args.filters!.clinicId!));
+    }
+    return campaigns.sort((a, b) => b.updatedAt - a.updatedAt);
+  },
+});
+
+export const getCampaign = query({
+  args: { campaignId: v.id("campaigns") },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    const campaign = await ctx.db.get(args.campaignId);
+    if (!campaign) return null;
+
+    const steps = await ctx.db
+      .query("campaign_steps")
+      .withIndex("by_campaign", (q) => q.eq("campaignId", args.campaignId))
+      .collect();
+
+    const snapshots = await ctx.db
+      .query("audience_snapshots")
+      .withIndex("by_campaign_createdAt", (q) => q.eq("campaignId", args.campaignId))
+      .collect();
+
+    return {
+      campaign,
+      steps: steps.sort((a, b) => a.order - b.order),
+      snapshots: snapshots.sort((a, b) => b.createdAt - a.createdAt),
+    };
+  },
+});
+
+export const getSnapshot = query({
+  args: { snapshotId: v.id("audience_snapshots") },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    const snapshot = await ctx.db.get(args.snapshotId);
+    if (!snapshot) return null;
+
+    const members = await ctx.db
+      .query("audience_members")
+      .withIndex("by_snapshot", (q) => q.eq("snapshotId", args.snapshotId))
+      .collect();
+
+    return {
+      snapshot,
+      membersCount: members.length,
+    };
+  },
+});
+
+export const getCampaignReport = query({
+  args: {
+    campaignId: v.id("campaigns"),
+    range: v.object({
+      from: v.number(),
+      to: v.number(),
+    }),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["Admin", "Marketing"]);
+    const snapshots = await ctx.db
+      .query("audience_snapshots")
+      .withIndex("by_campaign_createdAt", (q) => q.eq("campaignId", args.campaignId))
+      .collect();
+
+    const inRange = snapshots.filter(
+      (s) => s.createdAt >= args.range.from && s.createdAt <= args.range.to,
+    );
+    const counters = {
+      totalCandidates: 0,
+      eligible: 0,
+      queued: 0,
+      sent: 0,
+      taskCreated: 0,
+      completed: 0,
+      converted: 0,
+      failed: 0,
+      suppressedByReason: {} as Record<string, number>,
+    };
+
+    for (const snapshot of inRange) {
+      counters.totalCandidates += snapshot.stats.totalCandidates;
+      counters.eligible += snapshot.stats.eligible;
+      counters.queued += snapshot.stats.queued;
+      counters.sent += snapshot.stats.sent;
+      counters.taskCreated += snapshot.stats.taskCreated;
+      counters.completed += snapshot.stats.completed;
+      counters.converted += snapshot.stats.converted;
+      counters.failed += snapshot.stats.failed;
+      for (const [reason, count] of Object.entries(snapshot.stats.suppressedByReason)) {
+        counters.suppressedByReason[reason] =
+          (counters.suppressedByReason[reason] ?? 0) + count;
+      }
+    }
+
+    return {
+      campaignId: args.campaignId,
+      range: args.range,
+      snapshotsCount: inRange.length,
+      counters,
+    };
+  },
+});

package/convex/components/campaigns/index.ts

@@ -0,0 +1,4 @@
+export * as campaignsQueries from "./functions/queries";
+export * as campaignsMutations from "./functions/mutations";
+export * as campaignsActions from "./functions/actions";
+export * as campaignsInternal from "./functions/internal";

package/convex/components/campaigns/permissions.ts

@@ -0,0 +1,112 @@
+import type { Id } from "../../_generated/dataModel";
+import { internal } from "../../_generated/api";
+
+type Role = "Admin" | "Marketing" | "System";
+type AnyCtx = {
+  auth: { getUserIdentity: () => Promise<any> };
+  db?: any;
+  runQuery?: (fn: any, args: any) => Promise<any>;
+};
+
+function normalizeRole(value: string | undefined): string {
+  return (value ?? "").trim().toLowerCase();
+}
+
+async function resolveCurrentUserWithDb(ctx: AnyCtx) {
+  if (!ctx.db) return null;
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) return null;
+
+  if (identity.subject) {
+    const byAuth0 = await ctx.db
+      .query("users")
+      .withIndex("by_auth0", (q: any) => q.eq("auth0Id", identity.subject))
+      .first();
+    if (byAuth0?.isActive) return byAuth0;
+  }
+
+  if (identity.email) {
+    const byEmail = await ctx.db
+      .query("users")
+      .withIndex("by_email", (q: any) => q.eq("email", identity.email!))
+      .first();
+    if (byEmail?.isActive) return byEmail;
+  }
+
+  return null;
+}
+
+async function getUserRoleCodes(ctx: AnyCtx, userId: Id<"users">): Promise<Set<string>> {
+  if (!ctx.db) return new Set<string>();
+  const roles = new Set<string>();
+
+  const user = await ctx.db.get(userId);
+  if (user?.role) {
+    roles.add(normalizeRole(user.role));
+  }
+
+  const userClinicRoles = await ctx.db
+    .query("user_clinic_roles")
+    .withIndex("by_user", (q: any) => q.eq("userId", userId))
+    .collect();
+  for (const userClinicRole of userClinicRoles) {
+    if (!userClinicRole.isActive) continue;
+    const roleDoc = await ctx.db.get(userClinicRole.roleId);
+    if (roleDoc?.isActive && roleDoc.code) {
+      roles.add(normalizeRole(roleDoc.code));
+    }
+  }
+
+  return roles;
+}
+
+/**
+ * MVP authorization guard.
+ * - If auth identity is available: enforces required roles.
+ * - If auth identity is missing: currently allows access to avoid blocking service calls
+ *   while host identity wiring is being finalized.
+ * TODO: tighten unauthenticated fallback once host auth is fully configured.
+ */
+export async function assertAuthorized(ctx: AnyCtx, requiredRoles: Role[]): Promise<void> {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) {
+    if (requiredRoles.includes("System")) {
+      return;
+    }
+    throw new Error("Unauthorized: missing identity");
+  }
+
+  let userRoles = new Set<string>();
+  if (ctx.db) {
+    const user = await resolveCurrentUserWithDb(ctx);
+    if (!user) {
+      throw new Error("Unauthorized: authenticated identity not mapped to active user");
+    }
+    userRoles = await getUserRoleCodes(ctx, user._id);
+  } else if (ctx.runQuery) {
+    const resolved = await ctx.runQuery(
+      (internal as any).components.campaigns.functions.authzInternal.resolveRolesForIdentity,
+      {
+        subject: identity.subject ?? undefined,
+        email: identity.email ?? undefined,
+      },
+    );
+    userRoles = new Set<string>((resolved?.roles ?? []) as string[]);
+    if (userRoles.size === 0) {
+      throw new Error("Unauthorized: identity has no mapped active roles");
+    }
+  } else {
+    throw new Error("Unauthorized: unsupported execution context");
+  }
+
+  const required = requiredRoles.map((r) => normalizeRole(r));
+  const hasRole = required.some((role) => userRoles.has(role));
+
+  if (!hasRole) {
+    throw new Error(
+      `Forbidden: required one of roles [${requiredRoles.join(", ")}], user roles: [${[
+        ...userRoles,
+      ].join(", ")}]`,
+    );
+  }
+}

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

@@ -0,0 +1,47 @@
+import type { MutationCtx } from "../../../_generated/server";
+import type { Id } from "../../../_generated/dataModel";
+
+export async function createOutboxTasks(
+  ctx: MutationCtx,
+  tasks: Array<{
+    patientId: Id<"patients">;
+    clinicId?: Id<"clinics">;
+    campaignId: Id<"campaigns">;
+    snapshotId: Id<"audience_snapshots">;
+    stepId: Id<"campaign_steps">;
+    dueAt: number;
+    priority: number;
+    script?: string;
+    dedupeKey: string;
+  }>,
+) {
+  const ids: Id<"call_tasks_outbox">[] = [];
+  for (const task of tasks) {
+    const existing = await ctx.db
+      .query("call_tasks_outbox")
+      .withIndex("by_dedupe_key", (q) => q.eq("dedupeKey", task.dedupeKey))
+      .first();
+    if (existing) {
+      ids.push(existing._id);
+      continue;
+    }
+
+    const id = await ctx.db.insert("call_tasks_outbox", {
+      patientId: task.patientId,
+      clinicId: task.clinicId,
+      campaignId: task.campaignId,
+      snapshotId: task.snapshotId,
+      stepId: task.stepId,
+      dueAt: task.dueAt,
+      priority: task.priority,
+      script: task.script,
+      attempt: 0,
+      status: "PENDING",
+      dedupeKey: task.dedupeKey,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+    ids.push(id);
+  }
+  return ids;
+}

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

@@ -0,0 +1,37 @@
+import type { QueryCtx, MutationCtx } from "../../../_generated/server";
+import type { Id } from "../../../_generated/dataModel";
+
+export type ConsentResult = {
+  email: boolean;
+  sms: boolean;
+  phone: boolean;
+  blacklisted: boolean;
+};
+
+export async function getConsent(
+  ctx: QueryCtx | MutationCtx,
+  patientId: Id<"patients">,
+): Promise<ConsentResult> {
+  // TODO: Replace with real Consent component port call:
+  // consents.getConsent(patientId) -> { email, sms, phone, blacklisted }
+  const patient = await ctx.db.get(patientId);
+  const p = patient as
+    | (typeof patient & {
+        consentEmail?: boolean;
+        consentSms?: boolean;
+        consentPhone?: boolean;
+        blacklisted?: boolean;
+      })
+    | null;
+
+  if (!patient) {
+    return { email: false, sms: false, phone: false, blacklisted: false };
+  }
+
+  return {
+    email: p?.consentEmail ?? Boolean(patient.email),
+    sms: p?.consentSms ?? Boolean(patient.phone),
+    phone: p?.consentPhone ?? Boolean(patient.phone),
+    blacklisted: p?.blacklisted ?? false,
+  };
+}

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

@@ -0,0 +1,64 @@
+import type { MutationCtx } from "../../../_generated/server";
+import type { Id } from "../../../_generated/dataModel";
+
+export async function enqueueEmail(
+  ctx: MutationCtx,
+  input: {
+    campaignId: Id<"campaigns">;
+    snapshotId: Id<"audience_snapshots">;
+    patientId: Id<"patients">;
+    stepId: Id<"campaign_steps">;
+    dedupeKey: string;
+    payload: Record<string, any>;
+  },
+) {
+  const existing = await ctx.db
+    .query("message_jobs")
+    .withIndex("by_dedupe_key", (q) => q.eq("dedupeKey", input.dedupeKey))
+    .first();
+  if (existing) return existing._id;
+
+  return ctx.db.insert("message_jobs", {
+    channel: "EMAIL",
+    campaignId: input.campaignId,
+    snapshotId: input.snapshotId,
+    patientId: input.patientId,
+    stepId: input.stepId,
+    payload: input.payload,
+    status: "QUEUED",
+    dedupeKey: input.dedupeKey,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  });
+}
+
+export async function enqueueSms(
+  ctx: MutationCtx,
+  input: {
+    campaignId: Id<"campaigns">;
+    snapshotId: Id<"audience_snapshots">;
+    patientId: Id<"patients">;
+    stepId: Id<"campaign_steps">;
+    dedupeKey: string;
+    payload: Record<string, any>;
+  },
+) {
+  const existing = await ctx.db
+    .query("message_jobs")
+    .withIndex("by_dedupe_key", (q) => q.eq("dedupeKey", input.dedupeKey))
+    .first();
+  if (existing) return existing._id;
+
+  return ctx.db.insert("message_jobs", {
+    channel: "SMS",
+    campaignId: input.campaignId,
+    snapshotId: input.snapshotId,
+    patientId: input.patientId,
+    stepId: input.stepId,
+    payload: input.payload,
+    status: "QUEUED",
+    dedupeKey: input.dedupeKey,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  });
+}