@primocaredentgroup/convex-campaigns-component 0.1.3 → 0.3.0

package/convex/components/campaigns/v2/fieldRegistry.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import type { FieldType, PatientContext } from "./types";
+
+export type FieldRegistryItem = {
+  key: string;
+  label: string;
+  type: FieldType;
+  category: "Patient" | "Consent" | "Appointments" | "Estimates" | "Treatment" | "Frequency";
+  operators: string[];
+  valueSchema: z.ZodTypeAny;
+  resolver: (ctx: PatientContext) => unknown;
+  enumValues?: string[];
+};
+
+const numberValueSchema = z.union([
+  z.number(),
+  z.object({ min: z.number(), max: z.number() }),
+  z.tuple([z.number(), z.number()]),
+]);
+const stringValueSchema = z.union([z.string(), z.array(z.string())]);
+const boolValueSchema = z.boolean();
+const dateValueSchema = z.union([
+  z.number(),
+  z.object({ from: z.number(), to: z.number() }),
+  z.tuple([z.number(), z.number()]),
+]);
+
+export const fieldRegistry: FieldRegistryItem[] = [
+  {
+    key: "patient.age",
+    label: "Eta paziente",
+    type: "number",
+    category: "Patient",
+    operators: ["gt", "gte", "lt", "lte", "between", "eq", "neq"],
+    valueSchema: numberValueSchema,
+    resolver: (ctx) => ctx.age,
+  },
+  {
+    key: "patient.city",
+    label: "Citta",
+    type: "string",
+    category: "Patient",
+    operators: ["eq", "neq", "contains", "in"],
+    valueSchema: stringValueSchema,
+    resolver: (ctx) => ctx.city,
+  },
+  {
+    key: "patient.clinicId",
+    label: "Clinic ID",
+    type: "enum",
+    category: "Patient",
+    operators: ["eq", "in"],
+    valueSchema: stringValueSchema,
+    resolver: (ctx) => ctx.clinicId,
+  },
+  {
+    key: "patient.hasCallConsent",
+    label: "Consenso chiamata",
+    type: "bool",
+    category: "Consent",
+    operators: ["is"],
+    valueSchema: boolValueSchema,
+    resolver: (ctx) => ctx.hasCallConsent,
+  },
+  {
+    key: "patient.hasPhone",
+    label: "Ha telefono",
+    type: "bool",
+    category: "Consent",
+    operators: ["is"],
+    valueSchema: boolValueSchema,
+    resolver: (ctx) => ctx.hasPhone,
+  },
+  {
+    key: "appointment.lastDate",
+    label: "Data ultimo appuntamento",
+    type: "date",
+    category: "Appointments",
+    operators: ["before", "after", "between"],
+    valueSchema: dateValueSchema,
+    resolver: (ctx) => ctx.appointment.lastDate,
+  },
+  {
+    key: "appointment.daysSinceLast",
+    label: "Giorni da ultimo appuntamento",
+    type: "number",
+    category: "Appointments",
+    operators: ["gt", "gte", "lt", "lte", "between"],
+    valueSchema: numberValueSchema,
+    resolver: (ctx) => ctx.appointment.daysSinceLast,
+  },
+  {
+    key: "appointment.missedLast30d",
+    label: "Appuntamento perso ultimi 30 giorni",
+    type: "bool",
+    category: "Appointments",
+    operators: ["is"],
+    valueSchema: boolValueSchema,
+    resolver: (ctx) => ctx.appointment.missedLast30d,
+  },
+  {
+    key: "appointment.hasUpcomingNext30d",
+    label: "Prossimo appuntamento entro 30 giorni",
+    type: "bool",
+    category: "Appointments",
+    operators: ["is"],
+    valueSchema: boolValueSchema,
+    resolver: (ctx) => ctx.appointment.hasUpcomingNext30d,
+  },
+  {
+    key: "estimate.status",
+    label: "Stato preventivo",
+    type: "enum",
+    category: "Estimates",
+    operators: ["eq", "in"],
+    enumValues: ["open", "accepted", "expired", "none"],
+    valueSchema: stringValueSchema,
+    resolver: (ctx) => ctx.estimate.status,
+  },
+  {
+    key: "estimate.amount",
+    label: "Importo preventivo",
+    type: "number",
+    category: "Estimates",
+    operators: ["gt", "gte", "lt", "lte", "between"],
+    valueSchema: numberValueSchema,
+    resolver: (ctx) => ctx.estimate.amount,
+  },
+  {
+    key: "estimate.expiredDaysAgo",
+    label: "Giorni da scadenza preventivo",
+    type: "number",
+    category: "Estimates",
+    operators: ["gt", "gte", "lt", "lte", "between"],
+    valueSchema: numberValueSchema,
+    resolver: (ctx) => ctx.estimate.expiredDaysAgo,
+  },
+  {
+    key: "treatment.hasOpenPlan",
+    label: "Piano di cura aperto",
+    type: "bool",
+    category: "Treatment",
+    operators: ["is"],
+    valueSchema: boolValueSchema,
+    resolver: (ctx) => ctx.treatment.hasOpenPlan,
+  },
+  {
+    key: "treatment.daysSinceLastActivity",
+    label: "Giorni da ultima attivita piano",
+    type: "number",
+    category: "Treatment",
+    operators: ["gt", "gte", "lt", "lte", "between"],
+    valueSchema: numberValueSchema,
+    resolver: (ctx) => ctx.treatment.daysSinceLastActivity,
+  },
+  {
+    key: "contact.lastContactAt",
+    label: "Ultimo contatto",
+    type: "date",
+    category: "Frequency",
+    operators: ["before", "after", "between", "in_last_days"],
+    valueSchema: z.union([z.number(), z.object({ from: z.number(), to: z.number() })]),
+    resolver: (ctx) => ctx.contact.lastContactAt,
+  },
+];
+
+export const fieldRegistryMap = new Map(fieldRegistry.map((item) => [item.key, item]));
+
+export function getFieldRegistryPublic() {
+  return fieldRegistry.map(({ resolver: _resolver, valueSchema, ...rest }) => ({
+    ...rest,
+    valueSchema: valueSchema._def.typeName,
+  }));
+}

package/convex/components/campaigns/v2/rules.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { fieldRegistryMap } from "./fieldRegistry";
+import type { PatientContext, RuleCondition, RuleGroup } from "./types";
+
+const conditionSchema: z.ZodType<RuleCondition> = z.object({
+  fieldKey: z.string().min(1),
+  operator: z.string().min(1),
+  value: z.any().optional(),
+});
+
+const ruleGroupSchema: z.ZodType<RuleGroup> = z.lazy(() =>
+  z.object({
+    op: z.enum(["AND", "OR"]),
+    rules: z.array(z.union([ruleGroupSchema, conditionSchema])).min(1),
+  }),
+);
+
+function isRuleGroup(value: RuleGroup | RuleCondition): value is RuleGroup {
+  return (value as RuleGroup).op !== undefined;
+}
+
+function getBetweenRange(value: unknown): { min: number; max: number } | null {
+  if (Array.isArray(value) && value.length === 2) {
+    const [min, max] = value;
+    if (typeof min === "number" && typeof max === "number") return { min, max };
+  }
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof (value as any).min === "number" &&
+    typeof (value as any).max === "number"
+  ) {
+    return { min: (value as any).min, max: (value as any).max };
+  }
+  return null;
+}
+
+function getDateRange(value: unknown): { from: number; to: number } | null {
+  if (Array.isArray(value) && value.length === 2) {
+    const [from, to] = value;
+    if (typeof from === "number" && typeof to === "number") return { from, to };
+  }
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof (value as any).from === "number" &&
+    typeof (value as any).to === "number"
+  ) {
+    return { from: (value as any).from, to: (value as any).to };
+  }
+  return null;
+}
+
+function evaluateCondition(condition: RuleCondition, ctx: PatientContext): { ok: boolean; reason?: string } {
+  const field = fieldRegistryMap.get(condition.fieldKey);
+  if (!field) return { ok: false };
+  if (!field.operators.includes(condition.operator)) return { ok: false };
+  const valueCheck = field.valueSchema.safeParse(condition.value);
+  if (!valueCheck.success && condition.operator !== "is") return { ok: false };
+
+  const current = field.resolver(ctx);
+  const value = condition.value;
+  let ok = false;
+
+  switch (condition.operator) {
+    case "is":
+      ok = Boolean(current) === Boolean(value);
+      break;
+    case "eq":
+      ok = current === value;
+      break;
+    case "neq":
+      ok = current !== value;
+      break;
+    case "contains":
+      ok = typeof current === "string" && typeof value === "string" && current.includes(value);
+      break;
+    case "in":
+      ok = Array.isArray(value) && value.map(String).includes(String(current));
+      break;
+    case "gt":
+      ok = typeof current === "number" && typeof value === "number" && current > value;
+      break;
+    case "gte":
+      ok = typeof current === "number" && typeof value === "number" && current >= value;
+      break;
+    case "lt":
+      ok = typeof current === "number" && typeof value === "number" && current < value;
+      break;
+    case "lte":
+      ok = typeof current === "number" && typeof value === "number" && current <= value;
+      break;
+    case "between": {
+      const range = field.type === "date" ? getDateRange(value) : getBetweenRange(value);
+      if (range && typeof current === "number") {
+        const min = (range as any).min ?? (range as any).from;
+        const max = (range as any).max ?? (range as any).to;
+        ok = current >= min && current <= max;
+      }
+      break;
+    }
+    case "before":
+      ok = typeof current === "number" && typeof value === "number" && current < value;
+      break;
+    case "after":
+      ok = typeof current === "number" && typeof value === "number" && current > value;
+      break;
+    case "in_last_days":
+      ok =
+        typeof current === "number" &&
+        typeof value === "number" &&
+        current >= Date.now() - value * 24 * 60 * 60 * 1000;
+      break;
+    default:
+      ok = false;
+  }
+
+  return {
+    ok,
+    reason: ok ? `${condition.fieldKey} ${condition.operator} ${JSON.stringify(condition.value)}` : undefined,
+  };
+}
+
+export function validateRuleDsl(rules: unknown): { ok: true; data: RuleGroup } | { ok: false; errors: string[] } {
+  const parsed = ruleGroupSchema.safeParse(rules);
+  if (!parsed.success) {
+    return { ok: false, errors: parsed.error.issues.map((i) => i.message) };
+  }
+
+  const errors: string[] = [];
+  const walk = (group: RuleGroup) => {
+    for (const item of group.rules) {
+      if (isRuleGroup(item)) {
+        walk(item);
+        continue;
+      }
+      const field = fieldRegistryMap.get(item.fieldKey);
+      if (!field) {
+        errors.push(`Field '${item.fieldKey}' non supportato.`);
+        continue;
+      }
+      if (!field.operators.includes(item.operator)) {
+        errors.push(`Operatore '${item.operator}' non supportato per '${item.fieldKey}'.`);
+        continue;
+      }
+      if (item.value !== undefined) {
+        const check = field.valueSchema.safeParse(item.value);
+        if (!check.success && item.operator !== "is") {
+          errors.push(`Valore non valido per '${item.fieldKey}'.`);
+        }
+      }
+    }
+  };
+  walk(parsed.data);
+
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, data: parsed.data };
+}
+
+export function evaluateRuleGroup(rules: RuleGroup, ctx: PatientContext): { match: boolean; reasons: string[] } {
+  const reasons: string[] = [];
+
+  const evalGroup = (group: RuleGroup): boolean => {
+    const results = group.rules.map((item) => {
+      if (isRuleGroup(item)) return evalGroup(item);
+      const result = evaluateCondition(item, ctx);
+      if (result.ok && result.reason) reasons.push(result.reason);
+      return result.ok;
+    });
+    return group.op === "AND" ? results.every(Boolean) : results.some(Boolean);
+  };
+
+  const match = evalGroup(rules);
+  return { match, reasons: match ? reasons.slice(0, 5) : [] };
+}

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

@@ -0,0 +1,62 @@
+import type { OutcomeCategory } from "../domain/types";
+
+export type RuleOp = "AND" | "OR";
+
+export type CampaignOutcome = {
+  id: string;
+  label: string;
+  category: OutcomeCategory;
+  isActive: boolean;
+};
+
+export type CampaignCallPolicy = {
+  dailyQuotaByClinic: Record<string, number>;
+  maxAttempts: number;
+  retryDelaysDays: number[];
+  outcomes: CampaignOutcome[];
+};
+
+export type RuleCondition = {
+  fieldKey: string;
+  operator: string;
+  value?: unknown;
+};
+
+export type RuleGroup = {
+  op: RuleOp;
+  rules: Array<RuleGroup | RuleCondition>;
+};
+
+export type FieldType = "string" | "number" | "bool" | "date" | "enum";
+
+export type PatientContext = {
+  orgId: string;
+  clinicId: string;
+  patientId: string;
+  firstName: string;
+  lastName: string;
+  city: string;
+  birthDate: string;
+  hasCallConsent: boolean;
+  phoneMasked?: string;
+  age: number | null;
+  hasPhone: boolean;
+  appointment: {
+    lastDate: number | null;
+    daysSinceLast: number | null;
+    missedLast30d: boolean;
+    hasUpcomingNext30d: boolean;
+  };
+  estimate: {
+    status: "open" | "accepted" | "expired" | "none";
+    amount: number | null;
+    expiredDaysAgo: number | null;
+  };
+  treatment: {
+    hasOpenPlan: boolean;
+    daysSinceLastActivity: number | null;
+  };
+  contact: {
+    lastContactAt: number | null;
+  };
+};

package/convex/playground.ts

@@ -0,0 +1,149 @@
+/**
+ * Wrapper app-level per esporre le funzioni playground del component campaigns.
+ * Le funzioni del component non sono direttamente accessibili da HTTP/client,
+ * quindi le ri-esponiamo come API pubbliche dell'app.
+ *
+ * @see https://docs.convex.dev/components/authoring#re-exporting-component-functions
+ */
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { components } from "./_generated/api";
+
+const c = components as {
+  campaigns?: {
+    campaignsPlayground?: {
+      listCampaignsV2: (args: { orgId: string; status?: "draft" | "ready" | "archived" }) => Promise<unknown>;
+      getPlaygroundBootstrap: (args: { orgId: string }) => Promise<unknown>;
+      listCampaignVersions: (args: { campaignId: string }) => Promise<unknown>;
+      previewCampaignAudience: (args: Record<string, unknown>) => Promise<unknown>;
+      getAudiencePage: (args: Record<string, unknown>) => Promise<unknown>;
+      getPatientCampaignMemberships: (args: { orgId: string; patientId: string }) => Promise<unknown>;
+      getCampaignCallPolicy: (args: { campaignId: string }) => Promise<unknown>;
+      upsertCampaign: (args: Record<string, unknown>) => Promise<unknown>;
+      setCampaignLifecycleStatus: (args: Record<string, unknown>) => Promise<unknown>;
+      publishCampaignVersion: (args: Record<string, unknown>) => Promise<unknown>;
+      seedDemoData: (args: Record<string, unknown>) => Promise<unknown>;
+      updateCampaignCallPolicy: (args: Record<string, unknown>) => Promise<unknown>;
+    };
+  };
+};
+
+export const listCampaignsV2 = query({
+  args: {
+    orgId: v.string(),
+    status: v.optional(v.union(v.literal("draft"), v.literal("ready"), v.literal("archived"))),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.listCampaignsV2, args);
+  },
+});
+
+export const getPlaygroundBootstrap = query({
+  args: { orgId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.getPlaygroundBootstrap, args);
+  },
+});
+
+export const listCampaignVersions = query({
+  args: { campaignId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.listCampaignVersions, {
+      campaignId: args.campaignId,
+    });
+  },
+});
+
+export const previewCampaignAudience = query({
+  args: {
+    campaignId: v.optional(v.string()),
+    orgId: v.optional(v.string()),
+    clinicIds: v.optional(v.array(v.string())),
+    rules: v.optional(v.any()),
+    frequencyCapDays: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.previewCampaignAudience, args);
+  },
+});
+
+export const getAudiencePage = query({
+  args: {
+    versionId: v.string(),
+    clinicId: v.optional(v.string()),
+    cursor: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.getAudiencePage, args);
+  },
+});
+
+export const getPatientCampaignMemberships = query({
+  args: { orgId: v.string(), patientId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.getPatientCampaignMemberships, args);
+  },
+});
+
+export const getCampaignCallPolicy = query({
+  args: { campaignId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.runQuery(c.campaigns!.campaignsPlayground!.getCampaignCallPolicy, args);
+  },
+});
+
+export const upsertCampaign = mutation({
+  args: {
+    id: v.optional(v.string()),
+    orgId: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    priority: v.number(),
+    status: v.union(v.literal("draft"), v.literal("ready"), v.literal("archived")),
+    clinicIds: v.array(v.string()),
+    rules: v.any(),
+    frequencyCapDays: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runMutation(c.campaigns!.campaignsPlayground!.upsertCampaign, args);
+  },
+});
+
+export const setCampaignLifecycleStatus = mutation({
+  args: { campaignId: v.string(), status: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.runMutation(c.campaigns!.campaignsPlayground!.setCampaignLifecycleStatus, args);
+  },
+});
+
+export const publishCampaignVersion = mutation({
+  args: {
+    campaignId: v.string(),
+    label: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runMutation(c.campaigns!.campaignsPlayground!.publishCampaignVersion, args);
+  },
+});
+
+export const seedDemoData = mutation({
+  args: {
+    orgId: v.string(),
+    clinicIds: v.array(v.string()),
+    nPatients: v.number(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runMutation(c.campaigns!.campaignsPlayground!.seedDemoData, args);
+  },
+});
+
+export const updateCampaignCallPolicy = mutation({
+  args: {
+    campaignId: v.string(),
+    callPolicy: v.any(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.runMutation(c.campaigns!.campaignsPlayground!.updateCampaignCallPolicy, args);
+  },
+});

package/convex.config.ts

@@ -1,6 +1,13 @@
-import { defineComponent } from "convex/server";
+import { defineApp, defineComponent } from "convex/server";
 
-// Convex component definition entrypoint for npm distribution.
-const component = defineComponent("campaigns");
+const campaignsComponent = defineComponent("campaigns");
 
-export default component;
+// App per npx convex dev dalla root del package (sviluppo standalone).
+// L'host che installa da npm usa: import campaignsComponent from "package/convex.config"
+// e fa app.use(campaignsComponent) - quindi serve il componente.
+const app = defineApp();
+app.use(campaignsComponent, { name: "campaigns" });
+
+export default app;
+// Per host npm: import { campaignsComponent } from "package/convex.config"
+export { campaignsComponent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primocaredentgroup/convex-campaigns-component",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Convex Campaigns backend component for PrimoCore",
   "license": "UNLICENSED",
   "type": "module",
@@ -8,16 +8,30 @@
   "files": [
     "convex.config.ts",
     "README.md",
-    "convex/**"
+    "CHANGELOG.md",
+    "convex/**",
+    "scripts/**"
   ],
   "scripts": {
     "sync:from-repo": "node ./scripts/sync-from-repo.mjs",
-    "prepack": "npm run sync:from-repo"
+    "prepack": "npm run sync:from-repo",
+    "test": "tsx --test tests/**/*.test.ts",
+    "smoke": "node scripts/smoke-test.mjs"
   },
   "peerDependencies": {
     "convex": "^1.14.0"
   },
+  "peerDependenciesMeta": {
+    "convex": { "optional": true }
+  },
+  "devDependencies": {
+    "convex": "^1.14.0",
+    "tsx": "^4.20.6"
+  },
   "publishConfig": {
     "access": "restricted"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
   }
 }