@bash-app/bash-common 30.284.0 → 30.285.0

package/src/venueMatch.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared shapes for the Venue Match pipeline (retrieve → score → explain).
+ *
+ * The api worker owns the Zod runtime validation (api/src/services/venueMatch/);
+ * this file is the type-only source of truth read by both the api and bash-app
+ * (host suggestion cards + admin supply-leads pipeline).
+ *
+ * Persisted JSON columns map exactly to these interfaces:
+ *  - `VenueMatchRun.intent`            → `VenueMatchIntent`
+ *  - `VenueMatchCandidate.scoreBreakdown` → `VenueMatchScoreBreakdown`
+ *  - `VenueMatchCandidate.reasons`     → `string[]` (host-facing copy)
+ *  - `VenueMatchCandidate.displaySnapshot` → `VenueCandidateDisplay`
+ */
+
+/** Where a candidate came from. Mirrors prisma enum `VenueMatchCandidateSource`. */
+export const VENUE_MATCH_SOURCES = {
+  Marketplace: "Marketplace",
+  GooglePlaces: "GooglePlaces",
+} as const;
+export type VenueMatchCandidateSource =
+  (typeof VENUE_MATCH_SOURCES)[keyof typeof VENUE_MATCH_SOURCES];
+
+/** Host interaction with a surfaced candidate. Mirrors prisma enum `VenueMatchHostAction`. */
+export const VENUE_MATCH_HOST_ACTIONS = {
+  None: "None",
+  Viewed: "Viewed",
+  Accepted: "Accepted",
+  AcceptedOffPlatform: "AcceptedOffPlatform",
+  Dismissed: "Dismissed",
+  CalledPhone: "CalledPhone",
+  InvitedVenue: "InvitedVenue",
+} as const;
+export type VenueMatchHostAction =
+  (typeof VENUE_MATCH_HOST_ACTIONS)[keyof typeof VENUE_MATCH_HOST_ACTIONS];
+
+/** Sales pipeline stage. Mirrors prisma enum `VenueSupplyLeadStage`. */
+export const VENUE_SUPPLY_LEAD_STAGES = {
+  Surfaced: "Surfaced",
+  Prioritized: "Prioritized",
+  Queued: "Queued",
+  Contacted: "Contacted",
+  Interested: "Interested",
+  DemoScheduled: "DemoScheduled",
+  Listed: "Listed",
+  Declined: "Declined",
+  DoNotContact: "DoNotContact",
+} as const;
+export type VenueSupplyLeadStage =
+  (typeof VENUE_SUPPLY_LEAD_STAGES)[keyof typeof VENUE_SUPPLY_LEAD_STAGES];
+
+/** Admin display labels — single source for the pipeline UI + CSV export. */
+export const VenueSupplyLeadStageLabel: Record<VenueSupplyLeadStage, string> = {
+  Surfaced: "Surfaced",
+  Prioritized: "Hot lead",
+  Queued: "Queued for outreach",
+  Contacted: "Contacted",
+  Interested: "Interested",
+  DemoScheduled: "Demo scheduled",
+  Listed: "Listed on Bash",
+  Declined: "Declined",
+  DoNotContact: "Do not contact",
+};
+
+/** Stages a rep can manually transition to from the admin UI. */
+export const VENUE_SUPPLY_LEAD_REP_STAGES: VenueSupplyLeadStage[] = [
+  "Queued",
+  "Contacted",
+  "Interested",
+  "DemoScheduled",
+  "Declined",
+  "DoNotContact",
+];
+
+/**
+ * Structured intent extracted from the host's prompt + current event fields.
+ * Persisted as `VenueMatchRun.intent` (Json column).
+ * All fields nullable — the scorer omits weights for missing signals.
+ */
+export interface VenueMatchIntent {
+  /** e.g. "bachelor party", "baby shower" — free text, lowercased */
+  occasion: string | null;
+  /** From amountOfGuests.expected or parsed from prompt */
+  guestCount: number | null;
+  city: string | null;
+  state: string | null;
+  /** Geocoded anchor for distance scoring (host geo → profile city → event city) */
+  anchorLat: number | null;
+  anchorLng: number | null;
+  /** e.g. "upscale", "casual" */
+  vibe: string | null;
+  /** Total budget in cents if the host mentioned one */
+  budgetCents: number | null;
+  /** BashEvent.eventType at run time */
+  eventType: string | null;
+}
+
+/** Per-factor contribution. `weight` is the normalized weight actually applied (0..1). */
+export interface VenueMatchFactorScore {
+  /** Raw factor score 0..100 before weighting */
+  score: number;
+  weight: number;
+}
+
+/**
+ * Persisted as `VenueMatchCandidate.scoreBreakdown` (Json).
+ * A factor is null when its signal was unavailable and its weight
+ * was re-distributed across the others.
+ */
+export interface VenueMatchScoreBreakdown {
+  distance: VenueMatchFactorScore | null;
+  capacity: VenueMatchFactorScore | null;
+  occasion: VenueMatchFactorScore | null;
+  rating: VenueMatchFactorScore | null;
+  price: VenueMatchFactorScore | null;
+  platformQuality: VenueMatchFactorScore | null;
+}
+
+/**
+ * Snapshot of everything the host card needs, captured at run time so
+ * `GET /venue-match` never re-hits Google. Persisted as
+ * `VenueMatchCandidate.displaySnapshot` (Json).
+ */
+export interface VenueCandidateDisplay {
+  name: string;
+  photoUrl: string | null;
+  formattedAddress: string | null;
+  city: string | null;
+  state: string | null;
+  /** Bash rating for marketplace, Google rating for off-platform */
+  rating: number | null;
+  reviewCount: number | null;
+  capacity: number | null;
+  distanceMiles: number | null;
+  phone: string | null;
+  /** Marketplace only — deep link target */
+  serviceDetailPath: string | null;
+}
+
+/** One candidate as served to the host UI. */
+export interface VenueMatchCandidateView {
+  id: string;
+  rank: number;
+  score: number;
+  source: VenueMatchCandidateSource;
+  serviceId: string | null;
+  /** Venue model id (for bashEvent.venueId) when marketplace */
+  venueId: string | null;
+  googlePlaceId: string | null;
+  reasons: string[];
+  scoreBreakdown: VenueMatchScoreBreakdown;
+  display: VenueCandidateDisplay;
+  hostAction: VenueMatchHostAction;
+}
+
+/** Response of `GET /event/:id/venue-match`. */
+export interface VenueMatchRunView {
+  runId: string;
+  createdAt: string;
+  intent: VenueMatchIntent;
+  candidates: VenueMatchCandidateView[];
+}
+
+/** Row shape for the admin supply-leads table + CSV export. */
+export interface VenueSupplyLeadRow {
+  id: string;
+  name: string;
+  phoneE164: string | null;
+  city: string | null;
+  state: string | null;
+  fullAddress: string | null;
+  rating: number | null;
+  reviewCount: number | null;
+  category: string | null;
+  website: string | null;
+  googlePlaceId: string | null;
+  distinctEventCount: number;
+  topOccasions: string[];
+  firstSurfacedAt: string;
+  lastSurfacedAt: string;
+  stage: VenueSupplyLeadStage;
+  assignedToUserId: string | null;
+  assignedToName: string | null;
+  notes: string | null;
+  /** Set once the venue lists on Bash (conversion) */
+  serviceId: string | null;
+  catalogSource: string | null;
+}
+
+export interface VenueSupplyLeadStats {
+  byStage: Record<VenueSupplyLeadStage, number>;
+  total: number;
+  hotLeads: number;
+  convertedTotal: number;
+}
+
+/** Feature flag values for `VENUE_MATCH_MODE`. */
+export const VENUE_MATCH_MODES = [
+  "off",
+  "marketplace_only",
+  "marketplace_and_google",
+] as const;
+export type VenueMatchMode = (typeof VENUE_MATCH_MODES)[number];