@bash-app/bash-common 30.330.0 → 30.333.0

package/src/__tests__/hostPromoter.test.ts

@@ -0,0 +1,133 @@
+/**
+ * hostPromoter — kind/subtype mapping, hireable guards, deep links, influencer tiers.
+ */
+import { describe, expect, test } from "@jest/globals";
+import {
+  HOST_PROMOTER_KIND,
+  buildHireStreetTeamServiceDeepLink,
+  eventServiceSubTypeFromHostPromoterKind,
+  hostPromoterKindFromEventServiceSubType,
+  isHostPromoterHireableKind,
+  isHostPromoterInfluencerTier,
+  isHostPromoterSyncServiceSubType,
+} from "../hostPromoter.js";
+
+describe("hostPromoterKindFromEventServiceSubType", () => {
+  test("maps known EventService subtypes to host promoter kinds", () => {
+    expect(hostPromoterKindFromEventServiceSubType("Promoter")).toBe(
+      HOST_PROMOTER_KIND.EventPromoter
+    );
+    expect(hostPromoterKindFromEventServiceSubType("Influencer")).toBe(
+      HOST_PROMOTER_KIND.Influencer
+    );
+    expect(hostPromoterKindFromEventServiceSubType("ContentCreator")).toBe(
+      HOST_PROMOTER_KIND.ContentCreator
+    );
+    expect(hostPromoterKindFromEventServiceSubType("Model")).toBe(
+      HOST_PROMOTER_KIND.Model
+    );
+    expect(hostPromoterKindFromEventServiceSubType("BrandAmbassador")).toBe(
+      HOST_PROMOTER_KIND.BrandAmbassador
+    );
+  });
+
+  test("returns null for unknown or empty subtypes", () => {
+    expect(hostPromoterKindFromEventServiceSubType("DJ")).toBeNull();
+    expect(hostPromoterKindFromEventServiceSubType(null)).toBeNull();
+    expect(hostPromoterKindFromEventServiceSubType(undefined)).toBeNull();
+  });
+});
+
+describe("eventServiceSubTypeFromHostPromoterKind", () => {
+  test("maps hireable kinds back to EventService subtypes", () => {
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(HOST_PROMOTER_KIND.EventPromoter)
+    ).toBe("Promoter");
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(HOST_PROMOTER_KIND.Influencer)
+    ).toBe("Influencer");
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(HOST_PROMOTER_KIND.ContentCreator)
+    ).toBe("ContentCreator");
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(HOST_PROMOTER_KIND.Model)
+    ).toBe("Model");
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(
+        HOST_PROMOTER_KIND.BrandAmbassador
+      )
+    ).toBe("BrandAmbassador");
+  });
+
+  test("PromoCode and unknown kinds have no hireable subtype", () => {
+    expect(
+      eventServiceSubTypeFromHostPromoterKind(HOST_PROMOTER_KIND.PromoCode)
+    ).toBeNull();
+    expect(eventServiceSubTypeFromHostPromoterKind("Nope")).toBeNull();
+    expect(eventServiceSubTypeFromHostPromoterKind(null)).toBeNull();
+  });
+});
+
+describe("isHostPromoterHireableKind / isHostPromoterSyncServiceSubType", () => {
+  test("hireable kinds exclude PromoCode", () => {
+    expect(isHostPromoterHireableKind(HOST_PROMOTER_KIND.Influencer)).toBe(
+      true
+    );
+    expect(isHostPromoterHireableKind(HOST_PROMOTER_KIND.PromoCode)).toBe(
+      false
+    );
+    expect(isHostPromoterHireableKind(null)).toBe(false);
+    expect(isHostPromoterHireableKind("")).toBe(false);
+  });
+
+  test("sync subtypes match marketplace EventService values", () => {
+    expect(isHostPromoterSyncServiceSubType("Promoter")).toBe(true);
+    expect(isHostPromoterSyncServiceSubType("PromoCode")).toBe(false);
+    expect(isHostPromoterSyncServiceSubType(undefined)).toBe(false);
+  });
+});
+
+describe("buildHireStreetTeamServiceDeepLink", () => {
+  test("builds service detail path without bash query", () => {
+    expect(
+      buildHireStreetTeamServiceDeepLink({
+        serviceId: "svc-1",
+        eventServiceId: "es-1",
+      })
+    ).toBe("/services/svc-1/EventServices/es-1");
+  });
+
+  test("appends encoded bashEventId when provided", () => {
+    expect(
+      buildHireStreetTeamServiceDeepLink({
+        serviceId: "svc-1",
+        eventServiceId: "es-1",
+        bashEventId: "bash/with spaces",
+      })
+    ).toBe(
+      "/services/svc-1/EventServices/es-1?bashEventId=bash%2Fwith%20spaces"
+    );
+  });
+
+  test("omits query when bashEventId is null", () => {
+    expect(
+      buildHireStreetTeamServiceDeepLink({
+        serviceId: "svc-1",
+        eventServiceId: "es-1",
+        bashEventId: null,
+      })
+    ).toBe("/services/svc-1/EventServices/es-1");
+  });
+});
+
+describe("isHostPromoterInfluencerTier", () => {
+  test("accepts known audience tiers", () => {
+    expect(isHostPromoterInfluencerTier("Nano")).toBe(true);
+    expect(isHostPromoterInfluencerTier("Mega")).toBe(true);
+  });
+
+  test("rejects empty and unknown values", () => {
+    expect(isHostPromoterInfluencerTier(null)).toBe(false);
+    expect(isHostPromoterInfluencerTier("Huge")).toBe(false);
+  });
+});

package/src/definitions.ts

@@ -42,31 +42,48 @@ import type { UtmFields } from "./utmAttribution.js";
 /**
  * Prisma's `index-browser` bundle (used by Vite in bash-app) omits some enums as runtime
  * values — importing them from `@prisma/client` yields `undefined` and crashes on first
- * property access. These mirrors match the Prisma schema / full client enum strings.
- */
-/**
+ * property access. Incomplete Jest `@prisma/client` mocks hit the same landmine.
+ * These mirrors match the Prisma schema / full client enum strings.
+ *
  * "Also list as [complementary type]" — a one-time identity-field prefill copy
  * (see Service.complementaryOfServiceId), not an ongoing synced link. Scoped to
  * the Vendors <-> EventServices pairing only (e.g. a food truck that vends
  * publicly at festivals and is also paid a flat fee at private weddings).
  */
-export const COMPLEMENTARY_SERVICE_TYPE: Partial<
-  Record<ServiceTypes, ServiceTypes>
-> = {
-  [ServiceTypes.Vendors]: ServiceTypes.EventServices,
-  [ServiceTypes.EventServices]: ServiceTypes.Vendors,
-};
+export const COMPLEMENTARY_SERVICE_TYPE = {
+  Vendors: "EventServices",
+  EventServices: "Vendors",
+} as const satisfies Partial<Record<ServiceTypes, ServiceTypes>>;
+
+export type ComplementaryServiceSourceType = keyof typeof COMPLEMENTARY_SERVICE_TYPE;
+
+export function isComplementaryServiceSourceType(
+  serviceType: ServiceTypes
+): serviceType is ComplementaryServiceSourceType {
+  // String compares — avoid ServiceTypes.* enum access (undefined in Vite's
+  // @prisma/client index-browser bundle).
+  return serviceType === "Vendors" || serviceType === "EventServices";
+}
+
+/** Vendors ↔ EventServices only; other types return undefined. */
+export function complementaryServiceTypeFor(
+  serviceType: ServiceTypes
+): ServiceTypes | undefined {
+  if (!isComplementaryServiceSourceType(serviceType)) {
+    return undefined;
+  }
+  return COMPLEMENTARY_SERVICE_TYPE[serviceType];
+}
 
 /**
  * Human-readable label for a ServiceTypes value — the raw enum ("EventServices")
  * is not fit for display copy. Only covers the values COMPLEMENTARY_SERVICE_TYPE
  * can produce; extend as more callers need display labels for other types.
  */
-export const SERVICE_TYPE_DISPLAY_LABEL: Partial<Record<ServiceTypes, string>> =
-  {
-    [ServiceTypes.Vendors]: "Vendor",
-    [ServiceTypes.EventServices]: "Event Service",
-  };
+export const SERVICE_TYPE_DISPLAY_LABEL = {
+  Vendors: "Vendor",
+  EventServices: "Event Service",
+} as const satisfies Partial<Record<ServiceTypes, string>>;
 
 /** Picks "a"/"an" for the given word, e.g. for "a Vendor" vs "an Event Service". */
 export function articleFor(word: string): "a" | "an" {

package/src/hostPromoter.ts

@@ -0,0 +1,321 @@
+/**
+ * Host street-team roster (Community Builder → Promoters).
+ * Distinct from per-bash `Promoter` promo-code rows and hireable marketing bookings.
+ */
+
+import type { InfluencerAudienceTier } from "@prisma/client";
+
+import {
+  INFLUENCER_AUDIENCE_TIERS,
+  type InfluencerAudienceTierId,
+} from "./influencerAudience.js";
+
+export const HOST_PROMOTER_KIND = {
+  PromoCode: "PromoCode",
+  EventPromoter: "EventPromoter",
+  Influencer: "Influencer",
+  ContentCreator: "ContentCreator",
+  Model: "Model",
+  BrandAmbassador: "BrandAmbassador",
+} as const;
+
+export type HostPromoterKind =
+  (typeof HOST_PROMOTER_KIND)[keyof typeof HOST_PROMOTER_KIND];
+
+export const HOST_PROMOTER_KIND_LABELS: Record<HostPromoterKind, string> = {
+  PromoCode: "Promo code",
+  EventPromoter: "Event Promoter",
+  Influencer: "Influencer",
+  ContentCreator: "Content creator",
+  Model: "Model",
+  BrandAmbassador: "Brand ambassador",
+};
+
+/** Hireable Promotion & Marketing subtypes that sync onto the street-team roster. */
+export const HOST_PROMOTER_SYNC_SERVICE_SUBTYPES = [
+  "Promoter",
+  "Influencer",
+  "ContentCreator",
+  "Model",
+  "BrandAmbassador",
+] as const;
+
+export type HostPromoterSyncServiceSubType =
+  (typeof HOST_PROMOTER_SYNC_SERVICE_SUBTYPES)[number];
+
+export function hostPromoterKindFromEventServiceSubType(
+  subType: string | null | undefined
+): HostPromoterKind | null {
+  switch (subType) {
+    case "Promoter":
+      return HOST_PROMOTER_KIND.EventPromoter;
+    case "Influencer":
+      return HOST_PROMOTER_KIND.Influencer;
+    case "ContentCreator":
+      return HOST_PROMOTER_KIND.ContentCreator;
+    case "Model":
+      return HOST_PROMOTER_KIND.Model;
+    case "BrandAmbassador":
+      return HOST_PROMOTER_KIND.BrandAmbassador;
+    default:
+      return null;
+  }
+}
+
+/** Inverse of sync mapping — PromoCode has no hireable EventService subtype. */
+export function eventServiceSubTypeFromHostPromoterKind(
+  kind: HostPromoterKind | string | null | undefined
+): HostPromoterSyncServiceSubType | null {
+  switch (kind) {
+    case HOST_PROMOTER_KIND.EventPromoter:
+      return "Promoter";
+    case HOST_PROMOTER_KIND.Influencer:
+      return "Influencer";
+    case HOST_PROMOTER_KIND.ContentCreator:
+      return "ContentCreator";
+    case HOST_PROMOTER_KIND.Model:
+      return "Model";
+    case HOST_PROMOTER_KIND.BrandAmbassador:
+      return "BrandAmbassador";
+    default:
+      return null;
+  }
+}
+
+/** Kinds that can be hired via EventService marketplace booking. */
+export const HOST_PROMOTER_HIREABLE_KINDS = [
+  HOST_PROMOTER_KIND.EventPromoter,
+  HOST_PROMOTER_KIND.Influencer,
+  HOST_PROMOTER_KIND.ContentCreator,
+  HOST_PROMOTER_KIND.Model,
+  HOST_PROMOTER_KIND.BrandAmbassador,
+] as const;
+
+export function isHostPromoterHireableKind(
+  kind: string | null | undefined
+): kind is (typeof HOST_PROMOTER_HIREABLE_KINDS)[number] {
+  return (
+    !!kind &&
+    (HOST_PROMOTER_HIREABLE_KINDS as readonly string[]).includes(kind)
+  );
+}
+
+/**
+ * Deep link into a hireable EventService detail page, optionally preselecting a bash.
+ */
+export function buildHireStreetTeamServiceDeepLink(args: {
+  serviceId: string;
+  eventServiceId: string;
+  bashEventId?: string | null;
+}): string {
+  const base = `/services/${args.serviceId}/EventServices/${args.eventServiceId}`;
+  if (!args.bashEventId) return base;
+  return `${base}?bashEventId=${encodeURIComponent(args.bashEventId)}`;
+}
+
+export type HostPromoterHireableService = {
+  serviceId: string;
+  eventServiceId: string;
+  eventServiceSubType: string;
+  title: string | null;
+};
+
+export function isHostPromoterSyncServiceSubType(
+  subType: string | null | undefined
+): subType is HostPromoterSyncServiceSubType {
+  return (
+    !!subType &&
+    (HOST_PROMOTER_SYNC_SERVICE_SUBTYPES as readonly string[]).includes(subType)
+  );
+}
+
+export const HOST_PROMOTER_SOURCE = {
+  Manual: "Manual",
+  PastPromoCode: "PastPromoCode",
+  PastEventBooking: "PastEventBooking",
+} as const;
+
+export type HostPromoterSource =
+  (typeof HOST_PROMOTER_SOURCE)[keyof typeof HOST_PROMOTER_SOURCE];
+
+/** Mirrors Prisma `HostPromoterStatus` for browser-safe imports. */
+export const HostPromoterStatus = {
+  Active: "Active",
+  Archived: "Archived",
+} as const;
+export type HostPromoterStatus =
+  (typeof HostPromoterStatus)[keyof typeof HostPromoterStatus];
+
+/** Mirrors Prisma `HostPromoterPayoutStatus`. */
+export const HostPromoterPayoutStatus = {
+  Unpaid: "Unpaid",
+  Paid: "Paid",
+  Cancelled: "Cancelled",
+} as const;
+export type HostPromoterPayoutStatus =
+  (typeof HostPromoterPayoutStatus)[keyof typeof HostPromoterPayoutStatus];
+
+/** Mirrors Prisma `HostPromoterPayoutMethod`. */
+export const HostPromoterPayoutMethod = {
+  Venmo: "Venmo",
+  Zelle: "Zelle",
+  CashApp: "CashApp",
+  Cash: "Cash",
+  Other: "Other",
+} as const;
+export type HostPromoterPayoutMethod =
+  (typeof HostPromoterPayoutMethod)[keyof typeof HostPromoterPayoutMethod];
+
+/** Mirrors Prisma `HostPromoterPayoutChannel`. */
+export const HostPromoterPayoutChannel = {
+  OffPlatform: "OffPlatform",
+  Platform: "Platform",
+} as const;
+export type HostPromoterPayoutChannel =
+  (typeof HostPromoterPayoutChannel)[keyof typeof HostPromoterPayoutChannel];
+
+/** Re-export influencer tier ids for roster forms (Nano / Micro / Macro / Mega). */
+export const HOST_PROMOTER_INFLUENCER_TIERS = INFLUENCER_AUDIENCE_TIERS;
+export type HostPromoterInfluencerTier = InfluencerAudienceTierId;
+
+export function isHostPromoterInfluencerTier(
+  value: string | null | undefined
+): value is HostPromoterInfluencerTier {
+  return (
+    !!value &&
+    (INFLUENCER_AUDIENCE_TIERS as readonly string[]).includes(value)
+  );
+}
+
+export type HostPromoterPayoutSummary = {
+  id: string;
+  amountCents: number;
+  currency: string;
+  status: HostPromoterPayoutStatus;
+  method: HostPromoterPayoutMethod;
+  channel: HostPromoterPayoutChannel;
+  stripeCheckoutSessionId: string | null;
+  platformFeeCents: number;
+  paidAt: string | null;
+  note: string | null;
+  bashEventId: string | null;
+  bashEventTitle: string | null;
+  serviceBookingId: string | null;
+  createdAt: string;
+};
+
+export type HostPromoterPayoutReadiness = {
+  payable: boolean;
+  reason?: "no_bash_account" | "not_connected" | "onboarding_incomplete";
+};
+
+export type HostPromoterStripePayoutCreateInput = {
+  amountCents: number;
+  bashEventId?: string | null;
+  note?: string | null;
+};
+
+export type HostPromoterListItem = {
+  id: string;
+  email: string;
+  displayName: string | null;
+  promoterUserId: string | null;
+  kinds: HostPromoterKind[];
+  status: HostPromoterStatus;
+  notes: string | null;
+  defaultBashPointsRewardPerTicket: number | null;
+  /** Nano / Micro / Macro / Mega when this person is (also) an Influencer. */
+  influencerAudienceTier: InfluencerAudienceTier | null;
+  sources: HostPromoterSource[];
+  lastPromotedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Known Venmo/Zelle/CashApp handle from User.paymentHandle when linked. */
+  paymentHandle: string | null;
+  /** Distinct bashes this person had a Promoter / marketing booking on for this host. */
+  bashesPromotedCount: number;
+  /** Non-cancelled tickets attributed via this person's promo codes on host bashes. */
+  ticketsAttributed: number;
+  /** Sum of Promoter.creditsGenerated across host bashes (BashPoints). */
+  bashPointsEarned: number;
+  unpaidCashCents: number;
+  /** Open (non-Settled) Event Promoter booking count for this person. */
+  openEventPromoterBookings: number;
+  payouts: HostPromoterPayoutSummary[];
+};
+
+export type HostPromoterCreateInput = {
+  email: string;
+  displayName?: string | null;
+  kinds?: HostPromoterKind[];
+  notes?: string | null;
+  defaultBashPointsRewardPerTicket?: number | null;
+  influencerAudienceTier?: HostPromoterInfluencerTier | null;
+};
+
+export type HostPromoterUpdateInput = {
+  displayName?: string | null;
+  kinds?: HostPromoterKind[];
+  status?: HostPromoterStatus;
+  notes?: string | null;
+  defaultBashPointsRewardPerTicket?: number | null;
+  influencerAudienceTier?: HostPromoterInfluencerTier | null;
+};
+
+export type HostPromoterInviteToBashInput = {
+  hostPromoterIds: string[];
+  bashEventId: string;
+  ticketTierId: string;
+  codePrefix?: string | null;
+  bashPointsRewardPerTicket?: number | null;
+  discountAmountPercentage?: number | null;
+};
+
+export type HostPromoterInviteResult = {
+  hostPromoterId: string;
+  email: string;
+  promoCodeId: string;
+  code: string;
+  error?: string;
+};
+
+export type HostPromoterPayoutCreateInput = {
+  amountCents: number;
+  method?: HostPromoterPayoutMethod;
+  note?: string | null;
+  bashEventId?: string | null;
+  serviceBookingId?: string | null;
+  channel?: HostPromoterPayoutChannel;
+};
+
+export type HostPromoterPayoutUpdateInput = {
+  status?: HostPromoterPayoutStatus;
+  method?: HostPromoterPayoutMethod;
+  note?: string | null;
+  paidAt?: string | null;
+};
+
+export type HostPromoterEventBookingSummary = {
+  id: string;
+  bashEventId: string | null;
+  bashEventTitle: string | null;
+  promoterUserId: string | null;
+  promoterName: string;
+  promoterEmail: string | null;
+  hostPromoterId: string | null;
+  eventServiceSubType: string | null;
+  expectedAttendeesAtBooking: number | null;
+  checkedInAttendeesAtSettle: number | null;
+  maxAttendeesAttributable: number | null;
+  depositCents: number | null;
+  settlementDeltaCents: number | null;
+  settlementStatus: string;
+  settledAt: string | null;
+};
+
+export type HostPromoterSettlementSummary = {
+  unpaidCashCents: number;
+  unpaidCashCount: number;
+  openEventPromoterBookings: HostPromoterEventBookingSummary[];
+  totalBashPointsEarned: number;
+};

package/src/index.ts

@@ -35,6 +35,7 @@ export * from "./hostCrmInsights.js";
 export * from "./hostCrmAutomation.js";
 export * from "./relationshipHealth.js";
 export * from "./hostCrmConstants.js";
+export * from "./hostPromoter.js";
 export * from "./bashEventCancellationPolicy.js";
 export * from "./userReportTypes.js";
 export * from "./mirroredPrismaEnums.js";