@bash-app/bash-common 30.314.0 → 30.316.0

package/src/__tests__/relationshipHealth.test.ts

@@ -0,0 +1,370 @@
+import { computeRelationshipHealth, RELATIONSHIP_HEALTH_LABELS } from "../relationshipHealth.js";
+
+const NOW = new Date("2026-07-13T00:00:00Z");
+
+describe("computeRelationshipHealth", () => {
+  it("returns New with no attendance history", () => {
+    const result = computeRelationshipHealth(
+      { eventCount: 0, lastAttendedAt: null, firstAttendedAt: null, tags: [], lastOutreachAt: null },
+      NOW
+    );
+    expect(result.status).toBe("New");
+    expect(result.reasons.join(" ")).toMatch(/no attended bashes/i);
+  });
+
+  it("returns New for a single recent attendance", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-07-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-07-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("New");
+  });
+
+  it("returns Cooling for a single attendance that lapsed a few months", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("Cooling");
+  });
+
+  it("returns AtRisk for a single attendance that lapsed a long time ago", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("AtRisk");
+  });
+
+  it("returns Steady for a regular attendee within their own cadence", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 5,
+        firstAttendedAt: new Date("2026-01-13T00:00:00Z").toISOString(),
+        lastAttendedAt: new Date("2026-06-23T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("Steady");
+    expect(result.expectedGapDays).not.toBeNull();
+  });
+
+  it("returns Cooling then AtRisk as the gap relative to cadence grows", () => {
+    const base = {
+      eventCount: 4,
+      firstAttendedAt: new Date("2026-01-01T00:00:00Z").toISOString(),
+      tags: [] as string[],
+      lastOutreachAt: null,
+    };
+    // span Jan1→May1 = 120 days over 3 gaps → expectedGapDays = 40;
+    // daysSince (NOW=Jul13) = 73 → ratio ~1.83 → Cooling
+    const cooling = computeRelationshipHealth(
+      { ...base, lastAttendedAt: new Date("2026-05-01T00:00:00Z").toISOString() },
+      NOW
+    );
+    expect(cooling.status).toBe("Cooling");
+
+    // span Jan1→Feb1 = 31 days over 3 gaps → expectedGapDays clamps to the 14-day
+    // floor; daysSince = 162 → ratio ~11.6 → AtRisk
+    const atRisk = computeRelationshipHealth(
+      { ...base, lastAttendedAt: new Date("2026-02-01T00:00:00Z").toISOString() },
+      NOW
+    );
+    expect(atRisk.status).toBe("AtRisk");
+  });
+
+  it("escalates a Cooling VIP to AtRisk and records why", () => {
+    const withoutVip = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(withoutVip.status).toBe("Cooling");
+
+    const withVip = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        tags: ["VIP"],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(withVip.status).toBe("AtRisk");
+    expect(withVip.reasons.some((r) => /vip/i.test(r))).toBe(true);
+  });
+
+  it("includes outreach recency in the inspectable reasons without changing the bucket", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 5,
+        firstAttendedAt: new Date("2026-01-13T00:00:00Z").toISOString(),
+        lastAttendedAt: new Date("2026-06-23T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: new Date("2026-07-10T00:00:00Z").toISOString(),
+      },
+      NOW
+    );
+    expect(result.status).toBe("Steady");
+    expect(result.reasons.some((r) => /contacted/i.test(r))).toBe(true);
+  });
+
+  it("treats a single attendance with no lastAttendedAt as New", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: null,
+        firstAttendedAt: null,
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("New");
+    expect(result.daysSinceLastAttended).toBeNull();
+  });
+
+  it("uses the default cadence when firstAttendedAt is missing for multi-event guests", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 3,
+        firstAttendedAt: null,
+        lastAttendedAt: new Date("2026-07-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("Steady");
+    expect(result.expectedGapDays).toBe(60);
+    expect(result.reasons.some((r) => /default 60-day cadence/i.test(r))).toBe(true);
+  });
+
+  it("uses the default cadence when first and last attendance are the same day", () => {
+    const same = new Date("2026-06-01T00:00:00Z").toISOString();
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 3,
+        firstAttendedAt: same,
+        lastAttendedAt: same,
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.expectedGapDays).toBe(60);
+    expect(result.reasons.some((r) => /default 60-day cadence/i.test(r))).toBe(true);
+  });
+
+  it("clamps personalized cadence to a 14-day minimum", () => {
+    // 3 bashes over 10 days → raw gap 5, clamped to 14
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 3,
+        firstAttendedAt: new Date("2026-07-01T00:00:00Z").toISOString(),
+        lastAttendedAt: new Date("2026-07-11T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.expectedGapDays).toBe(14);
+    expect(result.status).toBe("Steady");
+  });
+
+  it("does not escalate a Steady VIP", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 5,
+        firstAttendedAt: new Date("2026-01-13T00:00:00Z").toISOString(),
+        lastAttendedAt: new Date("2026-06-23T00:00:00Z").toISOString(),
+        tags: [" VIP "],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("Steady");
+    expect(result.reasons.some((r) => /vip/i.test(r))).toBe(false);
+  });
+
+  it("notes missing outreach for Cooling and AtRisk without lastOutreachAt", () => {
+    const cooling = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-04-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(cooling.status).toBe("Cooling");
+    expect(cooling.reasons.some((r) => /no outreach/i.test(r))).toBe(true);
+
+    const atRisk = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(atRisk.status).toBe("AtRisk");
+    expect(atRisk.reasons.some((r) => /no outreach/i.test(r))).toBe(true);
+  });
+
+  it("uses singular day wording for a one-day gap", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-07-12T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2026-07-12T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: new Date("2026-07-12T00:00:00Z").toISOString(),
+      },
+      NOW
+    );
+    expect(result.reasons.some((r) => r.includes("1 day ago"))).toBe(true);
+    expect(result.reasons.some((r) => r.includes("1 days ago"))).toBe(false);
+  });
+
+  it("exposes human labels for every status", () => {
+    expect(RELATIONSHIP_HEALTH_LABELS.New).toBe("New");
+    expect(RELATIONSHIP_HEALTH_LABELS.Steady).toBe("Steady");
+    expect(RELATIONSHIP_HEALTH_LABELS.Cooling).toBe("Cooling");
+    expect(RELATIONSHIP_HEALTH_LABELS.AtRisk).toBe("At risk");
+  });
+
+  it("treats multi-event guests with no lastAttendedAt as Steady (ratio 0)", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 2,
+        firstAttendedAt: new Date("2026-01-01T00:00:00Z").toISOString(),
+        lastAttendedAt: null,
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("Steady");
+    expect(result.daysSinceLastAttended).toBeNull();
+  });
+
+  it("uses exact day boundaries for the single-attendance windows", () => {
+    const stillNew = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-05-29T00:00:00Z").toISOString(), // 45 days before NOW
+        firstAttendedAt: new Date("2026-05-29T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(stillNew.status).toBe("New");
+
+    const coolingEdge = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-05-28T00:00:00Z").toISOString(), // 46 days
+        firstAttendedAt: new Date("2026-05-28T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(coolingEdge.status).toBe("Cooling");
+
+    const stillCooling = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-03-15T00:00:00Z").toISOString(), // 120 days
+        firstAttendedAt: new Date("2026-03-15T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(stillCooling.status).toBe("Cooling");
+
+    const atRiskEdge = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2026-03-14T00:00:00Z").toISOString(), // 121 days
+        firstAttendedAt: new Date("2026-03-14T00:00:00Z").toISOString(),
+        tags: [],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(atRiskEdge.status).toBe("AtRisk");
+  });
+
+  it("keeps Steady at the 1.5x cadence ratio and Cooling just above it", () => {
+    // span Jan14→May14 = 120 days over 3 gaps → expectedGapDays = 40
+    const base = {
+      eventCount: 4,
+      firstAttendedAt: new Date("2026-01-14T00:00:00Z").toISOString(),
+      tags: [] as string[],
+      lastOutreachAt: null,
+    };
+    // daysSince (NOW=Jul13) = 60 → ratio exactly 1.5 → Steady
+    const steady = computeRelationshipHealth(
+      { ...base, lastAttendedAt: new Date("2026-05-14T00:00:00Z").toISOString() },
+      NOW
+    );
+    expect(steady.expectedGapDays).toBe(40);
+    expect(steady.status).toBe("Steady");
+
+    // one day later lapse → daysSince = 61, span drops to 119 (still rounds to
+    // the same 40-day gap) → ratio just above 1.5 → Cooling
+    const cooling = computeRelationshipHealth(
+      { ...base, lastAttendedAt: new Date("2026-05-13T00:00:00Z").toISOString() },
+      NOW
+    );
+    expect(cooling.status).toBe("Cooling");
+  });
+
+  it("does not re-escalate an AtRisk VIP (already past Cooling)", () => {
+    const result = computeRelationshipHealth(
+      {
+        eventCount: 1,
+        lastAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        firstAttendedAt: new Date("2025-01-01T00:00:00Z").toISOString(),
+        tags: ["vip"],
+        lastOutreachAt: null,
+      },
+      NOW
+    );
+    expect(result.status).toBe("AtRisk");
+    expect(result.reasons.some((r) => /escalated from Cooling/i.test(r))).toBe(false);
+  });
+});

package/src/hostCrmAutomation.ts

@@ -0,0 +1,79 @@
+import type {
+  HostCrmAutomationAudienceType as HostCrmAutomationAudienceTypeEnum,
+  HostCrmAutomationChannel as HostCrmAutomationChannelEnum,
+  HostCrmAutomationTrigger as HostCrmAutomationTriggerEnum,
+} from "@prisma/client";
+
+/** Mirrors Prisma `HostCrmAutomationTrigger` — `@prisma/client` browser bundle omits runtime enum exports. */
+export const HostCrmAutomationTrigger = {
+  Recurring: "Recurring",
+  NewlyAtRisk: "NewlyAtRisk",
+  PostEvent: "PostEvent",
+} as const satisfies Record<HostCrmAutomationTriggerEnum, HostCrmAutomationTriggerEnum>;
+
+export type HostCrmAutomationTrigger = HostCrmAutomationTriggerEnum;
+
+/** Mirrors Prisma `HostCrmAutomationChannel` — `@prisma/client` browser bundle omits runtime enum exports. */
+export const HostCrmAutomationChannel = {
+  Email: "Email",
+  Sms: "Sms",
+} as const satisfies Record<HostCrmAutomationChannelEnum, HostCrmAutomationChannelEnum>;
+
+export type HostCrmAutomationChannel = HostCrmAutomationChannelEnum;
+
+/** Mirrors Prisma `HostCrmAutomationAudienceType` — `@prisma/client` browser bundle omits runtime enum exports. */
+export const HostCrmAutomationAudienceType = {
+  Preset: "Preset",
+  Segment: "Segment",
+} as const satisfies Record<
+  HostCrmAutomationAudienceTypeEnum,
+  HostCrmAutomationAudienceTypeEnum
+>;
+
+export type HostCrmAutomationAudienceType = HostCrmAutomationAudienceTypeEnum;
+
+/** Minimum days between two runs of a Recurring automation. */
+export const HOST_CRM_AUTOMATION_MIN_CADENCE_DAYS = 1;
+/** Default cadence for a newly created Recurring automation, matching the legacy win-back cron interval. */
+export const HOST_CRM_AUTOMATION_DEFAULT_CADENCE_DAYS = 30;
+
+/**
+ * API/client shape of a `HostCrmAutomation` row — dates are ISO strings (as
+ * returned by the JSON API), not the raw Prisma `Date` type. See
+ * `api/src/api/user/privateUser/hostCrmAutomationApi.ts` for the endpoints
+ * that produce this shape and `bash-app/src/dataLayer/user/attendeeAudienceFetcher.ts`
+ * for the client fetchers.
+ */
+export type HostCrmAutomation = {
+  id: string;
+  hostUserId: string;
+  name: string;
+  trigger: HostCrmAutomationTrigger;
+  channel: HostCrmAutomationChannel;
+  /** Ignored for PostEvent — audience there is implicit (that event's ticket holders). */
+  audienceType: HostCrmAutomationAudienceType | null;
+  audiencePresetId: string | null;
+  audienceSegmentId: string | null;
+  subject: string | null;
+  body: string;
+  /** Only used by the Recurring trigger. */
+  cadenceDays: number | null;
+  enabled: boolean;
+  lastRunAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** Payload for creating or fully updating a `HostCrmAutomation`. */
+export type HostCrmAutomationInput = {
+  name: string;
+  trigger: HostCrmAutomationTrigger;
+  channel: HostCrmAutomationChannel;
+  audienceType?: HostCrmAutomationAudienceType | null;
+  audiencePresetId?: string | null;
+  audienceSegmentId?: string | null;
+  subject?: string | null;
+  body: string;
+  cadenceDays?: number | null;
+  enabled?: boolean;
+};

package/src/hostCrmInsights.ts

@@ -0,0 +1,39 @@
+import type { MembershipTier } from "./membershipDefinitions.js";
+
+/**
+ * One curated predictive-insight observation for the Attendee CRM's
+ * Recommended-actions accordion. Deliberately a discriminated union of
+ * discrete, computed facts (not prose) — same design choice already made for
+ * `HostCrmTimelineEntry` — so the drawer/card renders each fact directly and
+ * a future AI layer can consume the same structured data without re-deriving it.
+ */
+export type HostCrmInsight =
+  | {
+      type: "MostLikelyToReturn";
+      nextEventTitle: string;
+      nextEventStartsAt: string;
+      attendeeCount: number;
+    }
+  | {
+      type: "AttendanceTrend";
+      direction: "up" | "down" | "flat";
+      percent: number;
+      recentCount: number;
+      priorCount: number;
+    }
+  | {
+      type: "DayOfWeekRetention";
+      bestDay: string;
+      worstDay: string;
+      bestRepeatRate: number;
+      worstRepeatRate: number;
+    };
+
+/**
+ * Response shape for the Predictive Insights card. Gated server-side —
+ * `locked: true` hosts never receive computed `insights`, so a Basic-tier
+ * host can't see real data even by inspecting the network response.
+ */
+export type HostCrmInsightsResult =
+  | { locked: true; requiredTier: MembershipTier }
+  | { locked: false; insights: HostCrmInsight[] };