@bash-app/bash-common 30.314.0 → 30.316.0

package/src/hostCrmSegments.ts

@@ -1,5 +1,10 @@
 import type { SocialEventCadence } from "@prisma/client";
 
+import type {
+  RelationshipHealthResult,
+  RelationshipHealthStatus,
+} from "./relationshipHealth.js";
+
 /** Rule-based CRM segment (stored as JSON on HostCrmSavedSegment.rules). */
 export type HostCrmSegmentRules = {
   tag?: string;
@@ -14,10 +19,30 @@ export type HostCrmSegmentRules = {
   tierTitle?: string;
   /** Match attendee city (case-insensitive substring) */
   city?: string;
-  /** Built-in preset id (e.g. cadence_often) when rules alone are insufficient */
+  /** Built-in preset id (e.g. top_spenders) when rules alone are insufficient */
   presetId?: string;
+  /** Relationship Health status (New/Steady/Cooling/AtRisk) */
+  healthStatus?: RelationshipHealthStatus;
+  /** Lifetime spend across host bashes, in cents */
+  minTotalSpendCents?: number;
+  /** Bought a ticket but never checked in to an ended bash */
+  noShow?: boolean;
+  /** UI label: "Uses Promo Codes" — redeemed a promo code on a host bash */
+  discountResponsive?: boolean;
+  /** UI label: "Last-Minute Buyer" — typically buys within 48h of the event */
+  fastDecider?: boolean;
+  /** UI label: "Series Regular" — attended 2+ events in the same EventSeries */
+  seriesLoyalist?: boolean;
+  /** Refunded/cancelled a ticket and hasn't been back since */
+  refundChurn?: boolean;
+  /** UI label: "Brings Friends" — buys multiple tickets per checkout or brings plus-ones */
+  bringsGuests?: boolean;
+  /** Ticket buyers for any of these bash event ids (e.g. the host's 3 most recently ended bashes — see the last3Events preset) */
+  sourceEventIdIn?: string[];
 };
 
+export type HostCrmDiscoverySource = "promoter" | "referral" | "direct";
+
 export type HostCrmAudienceMember = {
   userId: string | null;
   email: string | null;
@@ -32,19 +57,41 @@ export type HostCrmAudienceMember = {
   reachableEmail: boolean;
   reachableSms: boolean;
   lastAttendedAt: string | null;
+  /** First attended bash time, used to derive this attendee's own cadence for Relationship Health. */
+  firstAttendedAt: string | null;
   city: string | null;
   tierTitles: string[];
   /** Bash event ids this person attended (for cohort / source filters) */
   sourceEventIds?: string[];
   /** True when row is email-only (guest checkout) without a linked user id */
   emailOnly: boolean;
+  /** Lifetime spend across host bashes, in cents (paidUnitPriceCents when set, else tier price). */
+  totalSpendCents: number;
+  /** Ended bashes where they bought a ticket but never checked in. */
+  noShowCount: number;
+  /** UI label: "Uses Promo Codes" */
+  discountResponsive: boolean;
+  /** UI label: "Last-Minute Buyer" — majority of purchases within 48h of the event start */
+  fastDecider: boolean;
+  /** UI label: "Series Regular" — attended 2+ events sharing an EventSeries */
+  seriesLoyalist: boolean;
+  /** Refunded/cancelled a ticket on a host bash and hasn't bought again since */
+  refundChurn: boolean;
+  /** UI label: "Brings Friends" — multi-ticket checkouts, group tiers, or RSVP plus-ones */
+  bringsGuests: boolean;
+  /** How this attendee was attributed to the host's audience, when known. */
+  discoverySource: HostCrmDiscoverySource;
+  /** This attendee's own derived cadence in days, or null when there isn't enough history to personalize it. */
+  expectedGapDays: number | null;
+  /** Predicted next-attendance date (now + expectedGapDays from lastAttendedAt), or null when unknown. */
+  nextExpectedAt: string | null;
 };
 
-export function applyHostCrmSegmentRules(
-  audience: HostCrmAudienceMember[],
+export function applyHostCrmSegmentRules<T extends HostCrmAudienceMember>(
+  audience: T[],
   rules: HostCrmSegmentRules,
   now: Date = new Date()
-): HostCrmAudienceMember[] {
+): T[] {
   let rows = audience;
 
   if (rules.tag?.trim()) {
@@ -78,6 +125,11 @@ export function applyHostCrmSegmentRules(
     rows = rows.filter((r) => !r.sourceEventIds?.includes(excludeId));
   }
 
+  if (rules.sourceEventIdIn && rules.sourceEventIdIn.length > 0) {
+    const idSet = new Set(rules.sourceEventIdIn);
+    rows = rows.filter((r) => r.sourceEventIds?.some((id) => idSet.has(id)));
+  }
+
   if (rules.tierTitle?.trim()) {
     const tier = rules.tierTitle.trim().toLowerCase();
     rows = rows.filter((r) =>
@@ -90,6 +142,43 @@ export function applyHostCrmSegmentRules(
     rows = rows.filter((r) => (r.city ?? "").toLowerCase().includes(cityNeedle));
   }
 
+  if (typeof rules.minTotalSpendCents === "number" && rules.minTotalSpendCents > 0) {
+    rows = rows.filter((r) => r.totalSpendCents >= rules.minTotalSpendCents!);
+  }
+
+  if (rules.noShow) {
+    rows = rows.filter((r) => r.noShowCount > 0);
+  }
+
+  if (rules.discountResponsive) {
+    rows = rows.filter((r) => r.discountResponsive);
+  }
+
+  if (rules.fastDecider) {
+    rows = rows.filter((r) => r.fastDecider);
+  }
+
+  if (rules.seriesLoyalist) {
+    rows = rows.filter((r) => r.seriesLoyalist);
+  }
+
+  if (rules.refundChurn) {
+    rows = rows.filter((r) => r.refundChurn);
+  }
+
+  if (rules.bringsGuests) {
+    rows = rows.filter((r) => r.bringsGuests);
+  }
+
+  if (rules.healthStatus) {
+    rows = rows.filter((r) => {
+      const health = (
+        r as HostCrmAudienceMember & { relationshipHealth?: RelationshipHealthResult }
+      ).relationshipHealth;
+      return health?.status === rules.healthStatus;
+    });
+  }
+
   return rows;
 }
 
@@ -105,6 +194,12 @@ export const HOST_CRM_PRESET_SEGMENTS: Array<{
     description: "People who have been to at least two of your bashes",
     rules: { minEventCount: 2 },
   },
+  {
+    id: "frequent_guest",
+    label: "Frequent guest (3+ bashes)",
+    description: "People who have been to at least three of your bashes",
+    rules: { minEventCount: 3 },
+  },
   {
     id: "lapsed_90",
     label: "Haven't been in 90 days",
@@ -118,9 +213,103 @@ export const HOST_CRM_PRESET_SEGMENTS: Array<{
     rules: { lapsedDays: 180 },
   },
   {
-    id: "cadence_often",
-    label: "Goes out often",
-    description: "Self-reported cadence: Often or Always",
+    id: "top_spenders",
+    label: "Top spenders",
+    description: "Your top quartile of attendees by lifetime spend",
+    // Computed at query time from the full audience — see filterHostCrmAudience's presetId branch.
+    rules: {},
+  },
+  {
+    id: "no_show",
+    label: "Bought, didn't check in",
+    description: "Bought a ticket to a past bash but never checked in",
+    rules: { noShow: true },
+  },
+  {
+    id: "uses_promo_codes",
+    label: "Uses promo codes",
+    description: "Has redeemed a promo code on one of your bashes",
+    rules: { discountResponsive: true },
+  },
+  {
+    id: "last_minute_buyer",
+    label: "Last-minute buyer",
+    description: "Typically buys within 48 hours of the event",
+    rules: { fastDecider: true },
+  },
+  {
+    id: "refund_churn",
+    label: "Refunded and hasn't been back",
+    description: "Refunded or cancelled a ticket and hasn't returned since",
+    rules: { refundChurn: true },
+  },
+  {
+    id: "series_regular",
+    label: "Series regular",
+    description: "Attended two or more events in the same series",
+    rules: { seriesLoyalist: true },
+  },
+  {
+    id: "brings_friends",
+    label: "Brings friends",
+    description: "Usually buys multiple tickets or brings plus-ones",
+    rules: { bringsGuests: true },
+  },
+  {
+    id: "last3Events",
+    label: "Last 3 events",
+    description: "People who came to any of your 3 most recently ended bashes",
+    // Computed at query time from the host's finished events — see filterHostCrmAudience's presetId branch.
     rules: {},
   },
 ];
+
+/**
+ * One chronological entry in an attendee's relationship timeline (detail
+ * drawer). Deliberately a discriminated union of discrete facts rather than
+ * pre-rendered prose: the drawer renders it directly, and any future
+ * AI-drafted-message feature can consume the same structured facts to build
+ * a prompt without re-deriving them (see `buildAttendeeCrmContext`).
+ */
+export type HostCrmTimelineEntryType =
+  | "TicketPurchased"
+  | "CheckedIn"
+  | "Refunded"
+  | "DiscountApplied"
+  | "EmailSent"
+  | "SmsSent"
+  | "NoteAdded"
+  | "NoteUpdated"
+  | "TagAdded"
+  | "TagRemoved";
+
+export type HostCrmTimelineEntry = {
+  type: HostCrmTimelineEntryType;
+  /** ISO timestamp. */
+  at: string;
+  /** Short human-readable detail (event title, discount code, tag name, etc.). */
+  detail?: string;
+  /** Rendering-only flag: true when a TicketPurchased entry was for a VIP-titled tier. */
+  isVip?: boolean;
+};
+
+/** Drawer-only behavioral badges, kept off the always-visible attendee row. */
+export type HostCrmAttendeeDetailBadges = {
+  fastDecider: boolean;
+  discountResponsive: boolean;
+  seriesLoyalist: boolean;
+  refundChurn: boolean;
+};
+
+/**
+ * Full detail payload for one attendee's drawer — the response shape for
+ * `GET /attendee-audience/:attendeeUserId/detail`, built by the shared
+ * `buildAttendeeCrmContext` function so a future AI compose endpoint can
+ * reuse the same assembly without refactoring this contract.
+ */
+export type HostCrmAttendeeDetail = {
+  member: HostCrmAudienceMember;
+  relationshipHealth: RelationshipHealthResult;
+  badges: HostCrmAttendeeDetailBadges;
+  timeline: HostCrmTimelineEntry[];
+};

package/src/index.ts

@@ -30,6 +30,9 @@ export * from "./entertainmentNotableVenues.js";
 export * from "./productLaunch.js";
 export * from "./accessScreening.js";
 export * from "./hostCrmSegments.js";
+export * from "./hostCrmInsights.js";
+export * from "./hostCrmAutomation.js";
+export * from "./relationshipHealth.js";
 export * from "./hostCrmConstants.js";
 export * from "./userReportTypes.js";
 export * from "./mirroredPrismaEnums.js";

package/src/membershipDefinitions.ts

@@ -807,6 +807,8 @@ export const MEMBERSHIP_FEATURES = {
   FEATURED_EVENTS_PAID: 'featured_events_paid',
   BETA_FEATURES: 'beta_features',
   BASIC_NOTIFICATIONS: 'basic_notifications',
+  /** Host CRM: predictive insight cards (most-likely-to-return, attendance trend, day-of-week retention). */
+  HOST_CRM_INSIGHTS: 'host_crm_insights',
   
   // Pro features
   FREE_FEATURED_EVENTS: 'free_featured_events',
@@ -850,6 +852,7 @@ export function hasFeatureAccess(userTier: MembershipTier, feature: string): boo
     case MEMBERSHIP_FEATURES.FEATURED_EVENTS_PAID:
     case MEMBERSHIP_FEATURES.BETA_FEATURES:
     case MEMBERSHIP_FEATURES.BASIC_NOTIFICATIONS:
+    case MEMBERSHIP_FEATURES.HOST_CRM_INSIGHTS:
       return tierIndex >= 1; // Creator+
       
     case MEMBERSHIP_FEATURES.FREE_FEATURED_EVENTS:

package/src/relationshipHealth.ts

@@ -0,0 +1,134 @@
+/**
+ * Per-attendee Relationship Health — one deterministic, inspectable signal for
+ * the Attendee CRM, replacing the narrower "lapsed VIP alert" idea with a
+ * status every attendee gets. Deliberately rule-based (not LLM-guessed) so a
+ * host can see exactly why a status fired via `reasons`.
+ */
+
+export type RelationshipHealthStatus = "New" | "Steady" | "Cooling" | "AtRisk";
+
+export const RELATIONSHIP_HEALTH_LABELS: Record<RelationshipHealthStatus, string> = {
+  New: "New",
+  Steady: "Steady",
+  Cooling: "Cooling",
+  AtRisk: "At risk",
+};
+
+export type RelationshipHealthInputs = {
+  eventCount: number;
+  /** ISO date of the most recent attended bash, if any. */
+  lastAttendedAt: string | null;
+  /** ISO date of the first attended bash, if any (used to derive this attendee's own cadence). */
+  firstAttendedAt: string | null;
+  tags: string[];
+  /** ISO date of the most recent host outreach (CRM email/SMS) to this attendee, if any. Display-only input — does not change the bucket. */
+  lastOutreachAt: string | null;
+};
+
+export type RelationshipHealthResult = {
+  status: RelationshipHealthStatus;
+  /** Ordered, human-readable trace of the exact signals behind this status — shown on hover/click, never hidden. */
+  reasons: string[];
+  daysSinceLastAttended: number | null;
+  /** This attendee's own derived cadence in days, or null when there isn't enough history to personalize it. */
+  expectedGapDays: number | null;
+};
+
+const DEFAULT_EXPECTED_GAP_DAYS = 60;
+const MIN_EXPECTED_GAP_DAYS = 14;
+const NEW_WINDOW_DAYS = 45;
+const SINGLE_EVENT_COOLING_DAYS = 120;
+const STEADY_RATIO = 1.5;
+const COOLING_RATIO = 3;
+
+function isVip(tags: string[]): boolean {
+  return tags.some((t) => t.trim().toLowerCase() === "vip");
+}
+
+function daysBetween(later: Date, earlier: Date): number {
+  return Math.round((later.getTime() - earlier.getTime()) / (24 * 60 * 60 * 1000));
+}
+
+function plural(n: number): string {
+  return n === 1 ? "" : "s";
+}
+
+export function computeRelationshipHealth(
+  inputs: RelationshipHealthInputs,
+  now: Date = new Date()
+): RelationshipHealthResult {
+  const reasons: string[] = [];
+  const vip = isVip(inputs.tags);
+
+  if (inputs.eventCount === 0) {
+    reasons.push("No attended bashes on record yet");
+    return { status: "New", reasons, daysSinceLastAttended: null, expectedGapDays: null };
+  }
+
+  const lastAttended = inputs.lastAttendedAt ? new Date(inputs.lastAttendedAt) : null;
+  const daysSinceLastAttended = lastAttended ? daysBetween(now, lastAttended) : null;
+  if (daysSinceLastAttended !== null) {
+    reasons.push(
+      `Last attended ${daysSinceLastAttended} day${plural(daysSinceLastAttended)} ago`
+    );
+  }
+
+  let status: RelationshipHealthStatus;
+  let expectedGapDays: number | null = null;
+
+  if (inputs.eventCount === 1) {
+    reasons.push("Attended 1 bash so far");
+    if (daysSinceLastAttended === null || daysSinceLastAttended <= NEW_WINDOW_DAYS) {
+      status = "New";
+    } else if (daysSinceLastAttended <= SINGLE_EVENT_COOLING_DAYS) {
+      status = "Cooling";
+    } else {
+      status = "AtRisk";
+    }
+  } else {
+    const first = inputs.firstAttendedAt ? new Date(inputs.firstAttendedAt) : null;
+    expectedGapDays = DEFAULT_EXPECTED_GAP_DAYS;
+    if (first && lastAttended) {
+      const spanDays = daysBetween(lastAttended, first);
+      if (spanDays > 0) {
+        expectedGapDays = Math.max(
+          MIN_EXPECTED_GAP_DAYS,
+          Math.round(spanDays / (inputs.eventCount - 1))
+        );
+        reasons.push(
+          `Typically attends every ~${expectedGapDays} days (based on ${inputs.eventCount} bashes)`
+        );
+      }
+    }
+    if (expectedGapDays === DEFAULT_EXPECTED_GAP_DAYS) {
+      reasons.push(
+        `Using a default ${DEFAULT_EXPECTED_GAP_DAYS}-day cadence — not enough history to personalize yet`
+      );
+    }
+
+    const ratio = daysSinceLastAttended === null ? 0 : daysSinceLastAttended / expectedGapDays;
+    if (ratio <= STEADY_RATIO) {
+      status = "Steady";
+    } else if (ratio <= COOLING_RATIO) {
+      status = "Cooling";
+    } else {
+      status = "AtRisk";
+    }
+  }
+
+  if (vip && status === "Cooling") {
+    status = "AtRisk";
+    reasons.push("Tagged VIP — escalated from Cooling");
+  }
+
+  if (inputs.lastOutreachAt) {
+    const daysSinceOutreach = daysBetween(now, new Date(inputs.lastOutreachAt));
+    reasons.push(
+      `Last contacted ${daysSinceOutreach} day${plural(daysSinceOutreach)} ago`
+    );
+  } else if (status === "Cooling" || status === "AtRisk") {
+    reasons.push("No outreach on record");
+  }
+
+  return { status, reasons, daysSinceLastAttended, expectedGapDays };
+}

package/src/utils/__tests__/slugUtils.test.ts

@@ -10,6 +10,7 @@ import {
   generateUniqueSlug,
   generateBashDetailUrl,
   getPublicBashDetailPath,
+  getPublicBashMemoriesPath,
   getBashEventWizardStepPath,
   getBashEventWizardPayoutStepPath,
   parseBashUrlParams,
@@ -79,6 +80,20 @@ describe("getPublicBashDetailPath", () => {
   });
 });
 
+describe("getPublicBashMemoriesPath", () => {
+  test("nests /memories under the slug detail path", () => {
+    expect(getPublicBashMemoriesPath("abc123", "summer-bash")).toBe(
+      "/bash/abc123-summer-bash/memories"
+    );
+  });
+
+  test("nests /memories under the id-only path when slug is missing", () => {
+    expect(getPublicBashMemoriesPath("abc123", null)).toBe(
+      `${BASH_DETAIL_URL}/abc123/memories`
+    );
+  });
+});
+
 describe("getBashEventWizardStepPath", () => {
   test("builds wizard step path", () => {
     expect(getBashEventWizardStepPath("evt-1", 3, 2)).toBe(

package/src/utils/slugUtils.ts

@@ -52,6 +52,19 @@ export function getPublicBashDetailPath(
   return `${BASH_DETAIL_URL}/${bashEventId}`;
 }
 
+/**
+ * Public, shareable Memories recap path for a bash — nested under the bash
+ * detail path so it inherits the same id/slug parsing (`/bash/{id}-{slug}/memories`).
+ * No-login-required by design: the whole point of Memories is that a shared
+ * link works for people who aren't signed in yet.
+ */
+export function getPublicBashMemoriesPath(
+  bashEventId: string,
+  slug: string | null | undefined
+): string {
+  return `${getPublicBashDetailPath(bashEventId, slug)}/memories`;
+}
+
 /** Wizard URL with explicit step (see bash-app `/bash-event-wizard/$id/$major/$sub`). */
 export function getBashEventWizardStepPath(
   bashEventId: string,