@primocaredentgroup/convex-campaigns-component 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# PrimoCore Convex Campaigns Component
+
+Pacchetto npm per distribuire il componente Convex `campaigns` di PrimoCore.
+
+## Contenuto
+
+- `convex.config.ts`: definizione componente Convex.
+- `convex/components/campaigns/*`: funzioni, schema, ports, domain.
+- `convex/campaigns.ts`: API pubblica stabile (`campaigns.*`).
+
+## Build del pacchetto
+
+Dal root del monorepo:
+
+```bash
+cd packages/convex-campaigns-component
+npm run sync:from-repo
+npm pack
+```
+
+`npm pack` esegue anche `prepack`, quindi sincronizza automaticamente i file dal repo.
+
+## Pubblicazione su npmjs
+
+```bash
+cd packages/convex-campaigns-component
+npm login
+npm publish
+```
+
+## Installazione su host PrimoCore
+
+Nel repo host:
+
+```bash
+npm install @primocaredentgroup/convex-campaigns-component
+```
+
+Poi nel `convex.config.ts` dell'host installa il componente:
+
+```ts
+import { defineApp } from "convex/server";
+import campaignsComponent from "@primocaredentgroup/convex-campaigns-component/convex.config";
+
+const app = defineApp();
+app.use(campaignsComponent, { name: "campaigns" });
+
+export default app;
+```
+
+Infine esegui:
+
+```bash
+npx convex dev
+```
+
+## Note
+
+- Il componente espone logica backend Campaigns (no UI).
+- L'autorizzazione è server-side (`assertAuthorized`) e va collegata al provider auth del deployment host in produzione.
+- La port Consent resta stub fino a disponibilità del componente consensi ufficiale.

package/convex/_generated/api.ts

@@ -0,0 +1,4 @@
+import { componentsGeneric } from "convex/server";
+
+export const internal = componentsGeneric() as any;
+export const api = {} as any;

package/convex/_generated/dataModel.ts

@@ -0,0 +1,2 @@
+export type Id<TableName extends string> = string & { __tableName: TableName };
+export type Doc<TableName extends string> = any;

package/convex/_generated/server.ts

@@ -0,0 +1,19 @@
+import {
+  actionGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  mutationGeneric,
+  queryGeneric,
+} from "convex/server";
+
+export const query = queryGeneric;
+export const internalQuery = internalQueryGeneric;
+export const mutation = mutationGeneric;
+export const internalMutation = internalMutationGeneric;
+export const action = actionGeneric;
+export const internalAction = internalActionGeneric;
+
+export type QueryCtx = any;
+export type MutationCtx = any;
+export type ActionCtx = any;

package/convex/campaigns.ts

@@ -0,0 +1,22 @@
+export {
+  listCampaigns,
+  getCampaign,
+  getSnapshot,
+  getCampaignReport,
+} from "./components/campaigns/functions/queries";
+
+export {
+  createCampaign,
+  updateCampaign,
+  setCampaignStatus,
+  addOrUpdateSteps,
+  previewAudience,
+  buildAudienceSnapshot,
+} from "./components/campaigns/functions/mutations";
+
+export {
+  ingestCallOutcome,
+  ingestAppointmentBooked,
+  ingestDeliveryStatus,
+  runTick,
+} from "./components/campaigns/functions/actions";

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

@@ -0,0 +1,21 @@
+import type { RecipientState } from "./types";
+
+const ALLOWED_TRANSITIONS: Record<RecipientState, RecipientState[]> = {
+  ELIGIBLE: ["SUPPRESSED", "QUEUED", "CONVERTED"],
+  SUPPRESSED: ["QUEUED", "CONVERTED"],
+  QUEUED: ["SENT", "TASK_CREATED", "FAILED", "CONVERTED"],
+  SENT: ["DELIVERED", "FAILED", "CONVERTED"],
+  TASK_CREATED: ["COMPLETED", "FAILED", "CONVERTED"],
+  DELIVERED: ["COMPLETED", "CONVERTED"],
+  FAILED: ["QUEUED", "CONVERTED"],
+  COMPLETED: ["CONVERTED"],
+  CONVERTED: [],
+};
+
+export function canTransitionRecipientState(
+  from: RecipientState,
+  to: RecipientState,
+): boolean {
+  if (from === to) return true;
+  return ALLOWED_TRANSITIONS[from].includes(to);
+}

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

@@ -0,0 +1,109 @@
+import { v } from "convex/values";
+
+export const CAMPAIGN_SCOPE_TYPES = ["HQ", "CLINIC"] as const;
+export const CAMPAIGN_STATUSES = ["DRAFT", "RUNNING", "PAUSED", "COMPLETED", "ARCHIVED"] as const;
+export const STEP_TYPES = ["EMAIL", "SMS", "CALL_CLINIC", "CALL_CENTER"] as const;
+export const SNAPSHOT_STATUSES = ["BUILDING", "READY", "FAILED"] as const;
+export const SEGMENT_TYPES = ["RECALL", "QUOTE_FOLLOWUP", "NO_SHOW", "CUSTOM_IDS"] as const;
+export const RECIPIENT_STATES = [
+  "ELIGIBLE",
+  "SUPPRESSED",
+  "QUEUED",
+  "SENT",
+  "TASK_CREATED",
+  "DELIVERED",
+  "FAILED",
+  "COMPLETED",
+  "CONVERTED",
+] as const;
+export const SUPPRESSION_REASONS = [
+  "NO_CONSENT",
+  "BLACKLIST",
+  "INVALID_CONTACT",
+  "CAP",
+  "LOCKED",
+  "LOWER_PRIORITY",
+] as const;
+
+export const scopeTypeValidator = v.union(v.literal("HQ"), v.literal("CLINIC"));
+export const campaignStatusValidator = v.union(
+  v.literal("DRAFT"),
+  v.literal("RUNNING"),
+  v.literal("PAUSED"),
+  v.literal("COMPLETED"),
+  v.literal("ARCHIVED"),
+);
+export const stepTypeValidator = v.union(
+  v.literal("EMAIL"),
+  v.literal("SMS"),
+  v.literal("CALL_CLINIC"),
+  v.literal("CALL_CENTER"),
+);
+export const snapshotStatusValidator = v.union(
+  v.literal("BUILDING"),
+  v.literal("READY"),
+  v.literal("FAILED"),
+);
+export const segmentTypeValidator = v.union(
+  v.literal("RECALL"),
+  v.literal("QUOTE_FOLLOWUP"),
+  v.literal("NO_SHOW"),
+  v.literal("CUSTOM_IDS"),
+);
+export const recipientStateValidator = v.union(
+  v.literal("ELIGIBLE"),
+  v.literal("SUPPRESSED"),
+  v.literal("QUEUED"),
+  v.literal("SENT"),
+  v.literal("TASK_CREATED"),
+  v.literal("DELIVERED"),
+  v.literal("FAILED"),
+  v.literal("COMPLETED"),
+  v.literal("CONVERTED"),
+);
+export const suppressionReasonValidator = v.union(
+  v.literal("NO_CONSENT"),
+  v.literal("BLACKLIST"),
+  v.literal("INVALID_CONTACT"),
+  v.literal("CAP"),
+  v.literal("LOCKED"),
+  v.literal("LOWER_PRIORITY"),
+);
+
+export const segmentationRulesValidator = v.object({
+  segmentType: segmentTypeValidator,
+  params: v.optional(v.any()),
+});
+
+export const runConfigValidator = v.object({
+  capWindowDays: v.optional(v.number()),
+  capMaxContacts: v.optional(v.number()),
+  lockDays: v.optional(v.number()),
+  quietHours: v.optional(
+    v.object({
+      startHour: v.number(),
+      endHour: v.number(),
+      timezone: v.optional(v.string()),
+    }),
+  ),
+});
+
+export const scheduleSpecValidator = v.object({
+  mode: v.union(v.literal("IMMEDIATE"), v.literal("AT"), v.literal("DELAY")),
+  at: v.optional(v.number()),
+  delayMinutes: v.optional(v.number()),
+});
+
+export type CampaignScopeType = (typeof CAMPAIGN_SCOPE_TYPES)[number];
+export type CampaignStatus = (typeof CAMPAIGN_STATUSES)[number];
+export type StepType = (typeof STEP_TYPES)[number];
+export type SnapshotStatus = (typeof SNAPSHOT_STATUSES)[number];
+export type SegmentType = (typeof SEGMENT_TYPES)[number];
+export type RecipientState = (typeof RECIPIENT_STATES)[number];
+export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
+
+export const DEFAULT_RUN_CONFIG = {
+  capWindowDays: 7,
+  capMaxContacts: 1,
+  lockDays: 7,
+};

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

@@ -0,0 +1,95 @@
+import { v } from "convex/values";
+import { action } from "../../../_generated/server";
+import { internal } from "../../../_generated/api";
+import { assertAuthorized } from "../permissions";
+
+async function isDuplicateByIdempotencyKey(ctx: any, idempotencyKey?: string) {
+  if (!idempotencyKey) return false;
+  const existing = await ctx.runQuery(
+    (internal as any).components.campaigns.functions.ingestionInternal.findEventByIdempotencyKey,
+    { idempotencyKey },
+  );
+  return Boolean(existing);
+}
+
+export const ingestCallOutcome: any = action({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      campaignId: v.id("campaigns"),
+      snapshotId: v.id("audience_snapshots"),
+      patientId: v.id("patients"),
+      stepId: v.id("campaign_steps"),
+      outcome: v.union(v.literal("COMPLETED"), v.literal("FAILED")),
+      notes: v.optional(v.string()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["System", "Admin", "Marketing"]);
+    if (await isDuplicateByIdempotencyKey(ctx, args.payload.idempotencyKey)) {
+      return { deduplicated: true };
+    }
+    return ctx.runMutation(
+      (internal as any).components.campaigns.functions.ingestionInternal.ingestCallOutcomeInternal,
+      args,
+    );
+  },
+});
+
+export const ingestAppointmentBooked: any = action({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      appointmentId: v.optional(v.string()),
+      campaignId: v.optional(v.id("campaigns")),
+      snapshotId: v.optional(v.id("audience_snapshots")),
+      patientId: v.id("patients"),
+      releaseLock: v.optional(v.boolean()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["System", "Admin", "Marketing"]);
+    if (await isDuplicateByIdempotencyKey(ctx, args.payload.idempotencyKey)) {
+      return { deduplicated: true };
+    }
+    return ctx.runMutation(
+      (internal as any).components.campaigns.functions.ingestionInternal.ingestAppointmentBookedInternal,
+      args,
+    );
+  },
+});
+
+export const ingestDeliveryStatus: any = action({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      campaignId: v.id("campaigns"),
+      snapshotId: v.id("audience_snapshots"),
+      patientId: v.id("patients"),
+      stepId: v.id("campaign_steps"),
+      status: v.union(v.literal("DELIVERED"), v.literal("FAILED")),
+      providerMessageId: v.optional(v.string()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    await assertAuthorized(ctx, ["System", "Admin", "Marketing"]);
+    if (await isDuplicateByIdempotencyKey(ctx, args.payload.idempotencyKey)) {
+      return { deduplicated: true };
+    }
+    return ctx.runMutation(
+      (internal as any).components.campaigns.functions.ingestionInternal.ingestDeliveryStatusInternal,
+      args,
+    );
+  },
+});
+
+export const runTick: any = action({
+  args: {},
+  handler: async (ctx) => {
+    await assertAuthorized(ctx, ["System", "Admin", "Marketing"]);
+    return ctx.runMutation(
+      (internal as any).components.campaigns.functions.internal._runTickInternal,
+      {},
+    );
+  },
+});

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

@@ -0,0 +1,60 @@
+import { v } from "convex/values";
+import { internalQuery } from "../../../_generated/server";
+
+function normalizeRole(role: string | undefined): string | null {
+  const value = (role ?? "").trim().toLowerCase();
+  return value.length > 0 ? value : null;
+}
+
+export const resolveRolesForIdentity = internalQuery({
+  args: {
+    subject: v.optional(v.string()),
+    email: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    let user = null;
+
+    if (args.subject) {
+      user = await ctx.db
+        .query("users")
+        .withIndex("by_auth0", (q) => q.eq("auth0Id", args.subject))
+        .first();
+    }
+
+    if (!user && args.email) {
+      user = await ctx.db
+        .query("users")
+        .withIndex("by_email", (q) => q.eq("email", args.email!))
+        .first();
+    }
+
+    if (!user || !user.isActive) {
+      return {
+        userId: null,
+        roles: [] as string[],
+      };
+    }
+
+    const roles = new Set<string>();
+    const directRole = normalizeRole(user.role);
+    if (directRole) roles.add(directRole);
+
+    const userClinicRoles = await ctx.db
+      .query("user_clinic_roles")
+      .withIndex("by_user", (q) => q.eq("userId", user._id))
+      .collect();
+
+    for (const userClinicRole of userClinicRoles) {
+      if (!userClinicRole.isActive) continue;
+      const roleDoc = await ctx.db.get(userClinicRole.roleId);
+      if (!roleDoc || !roleDoc.isActive) continue;
+      const code = normalizeRole(roleDoc.code);
+      if (code) roles.add(code);
+    }
+
+    return {
+      userId: user._id,
+      roles: [...roles],
+    };
+  },
+});

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

@@ -0,0 +1,157 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "../../../_generated/server";
+
+export const findEventByIdempotencyKey = internalQuery({
+  args: { idempotencyKey: v.string() },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("event_log")
+      .withIndex("by_idempotency_key", (q) => q.eq("idempotencyKey", args.idempotencyKey))
+      .first();
+  },
+});
+
+export const ingestCallOutcomeInternal = internalMutation({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      campaignId: v.id("campaigns"),
+      snapshotId: v.id("audience_snapshots"),
+      patientId: v.id("patients"),
+      stepId: v.id("campaign_steps"),
+      outcome: v.union(v.literal("COMPLETED"), v.literal("FAILED")),
+      notes: v.optional(v.string()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const state = await ctx.db
+      .query("recipient_states")
+      .withIndex("by_snapshot_patient_step", (q) =>
+        q
+          .eq("snapshotId", args.payload.snapshotId)
+          .eq("patientId", args.payload.patientId)
+          .eq("stepId", args.payload.stepId),
+      )
+      .first();
+    if (state) {
+      await ctx.db.patch(state._id, {
+        state: args.payload.outcome,
+        reason: args.payload.notes,
+        updatedAt: now,
+        lastEventAt: now,
+      });
+    }
+
+    await ctx.db.insert("event_log", {
+      campaignId: args.payload.campaignId,
+      snapshotId: args.payload.snapshotId,
+      patientId: args.payload.patientId,
+      type: "call_task_completed",
+      payload: { outcome: args.payload.outcome, notes: args.payload.notes },
+      idempotencyKey: args.payload.idempotencyKey,
+      createdAt: now,
+    });
+
+    return { ok: true };
+  },
+});
+
+export const ingestAppointmentBookedInternal = internalMutation({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      appointmentId: v.optional(v.string()),
+      campaignId: v.optional(v.id("campaigns")),
+      snapshotId: v.optional(v.id("audience_snapshots")),
+      patientId: v.id("patients"),
+      releaseLock: v.optional(v.boolean()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const allStates = await ctx.db.query("recipient_states").collect();
+    const toConvert = allStates.filter(
+      (s) =>
+        s.patientId === args.payload.patientId &&
+        (!args.payload.campaignId || s.campaignId === args.payload.campaignId) &&
+        (!args.payload.snapshotId || s.snapshotId === args.payload.snapshotId),
+    );
+
+    for (const rs of toConvert) {
+      await ctx.db.patch(rs._id, {
+        state: "CONVERTED",
+        reason: "APPOINTMENT_BOOKED",
+        updatedAt: now,
+        lastEventAt: now,
+      });
+    }
+
+    if (args.payload.releaseLock ?? true) {
+      const lock = await ctx.db
+        .query("contact_locks")
+        .withIndex("by_patient", (q) => q.eq("patientId", args.payload.patientId))
+        .first();
+      if (lock) {
+        await ctx.db.delete(lock._id);
+      }
+    }
+
+    await ctx.db.insert("event_log", {
+      campaignId: args.payload.campaignId,
+      snapshotId: args.payload.snapshotId,
+      patientId: args.payload.patientId,
+      type: "appointment_booked",
+      payload: { appointmentId: args.payload.appointmentId },
+      idempotencyKey: args.payload.idempotencyKey,
+      createdAt: now,
+    });
+
+    return { convertedStates: toConvert.length };
+  },
+});
+
+export const ingestDeliveryStatusInternal = internalMutation({
+  args: {
+    payload: v.object({
+      idempotencyKey: v.string(),
+      campaignId: v.id("campaigns"),
+      snapshotId: v.id("audience_snapshots"),
+      patientId: v.id("patients"),
+      stepId: v.id("campaign_steps"),
+      status: v.union(v.literal("DELIVERED"), v.literal("FAILED")),
+      providerMessageId: v.optional(v.string()),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const state = await ctx.db
+      .query("recipient_states")
+      .withIndex("by_snapshot_patient_step", (q) =>
+        q
+          .eq("snapshotId", args.payload.snapshotId)
+          .eq("patientId", args.payload.patientId)
+          .eq("stepId", args.payload.stepId),
+      )
+      .first();
+    if (state) {
+      await ctx.db.patch(state._id, {
+        state: args.payload.status,
+        updatedAt: now,
+        lastEventAt: now,
+      });
+    }
+
+    await ctx.db.insert("event_log", {
+      campaignId: args.payload.campaignId,
+      snapshotId: args.payload.snapshotId,
+      patientId: args.payload.patientId,
+      type: args.payload.status === "DELIVERED" ? "message_delivered" : "message_failed",
+      payload: { providerMessageId: args.payload.providerMessageId, stepId: args.payload.stepId },
+      idempotencyKey: args.payload.idempotencyKey,
+      createdAt: now,
+    });
+
+    return { ok: true };
+  },
+});