@bash-app/bash-common 30.432.0 → 30.434.0

package/src/intros/intents.ts

@@ -0,0 +1,49 @@
+export const INTROS_INTENTS = [
+  "Friends",
+  "Professional",
+  "MentorSeek",
+  "MentorOffer",
+  "Collaborator",
+  "Romance",
+] as const;
+
+export type IntrosIntent = (typeof INTROS_INTENTS)[number];
+
+export const INTROS_INTENT_LABELS: Record<IntrosIntent, string> = {
+  Friends: "Making friends",
+  Professional: "Professional networking",
+  MentorSeek: "Finding a mentor",
+  MentorOffer: "Offering mentorship",
+  Collaborator: "Finding collaborators",
+  Romance: "Romance",
+};
+
+export function isIntrosIntent(value: string): value is IntrosIntent {
+  return (INTROS_INTENTS as readonly string[]).includes(value);
+}
+
+/** Complementary intents. Romance only matches Romance. */
+export function intentsComplement(
+  a: readonly string[],
+  b: readonly string[]
+): IntrosIntent | null {
+  const left = new Set(a.filter(isIntrosIntent));
+  const right = new Set(b.filter(isIntrosIntent));
+  if (left.has("Romance") && right.has("Romance")) return "Romance";
+  if (left.has("MentorSeek") && right.has("MentorOffer")) return "MentorSeek";
+  if (left.has("MentorOffer") && right.has("MentorSeek")) return "MentorOffer";
+  if (
+    (left.has("Collaborator") &&
+      (right.has("Collaborator") || right.has("Professional"))) ||
+    (left.has("Professional") && right.has("Collaborator"))
+  ) {
+    return "Collaborator";
+  }
+  if (left.has("Professional") && right.has("Professional")) return "Professional";
+  if (left.has("Friends") && right.has("Friends")) return "Friends";
+  return null;
+}
+
+export function isRomanceIntent(intent: string | null | undefined): boolean {
+  return intent === "Romance";
+}

package/src/intros/psychExperiment.ts

@@ -0,0 +1,130 @@
+export type PsychAttributeConsent = {
+  kind: string;
+  allowExperimentalMatching: boolean;
+  value?: unknown;
+};
+
+export type PsychExperimentInput = {
+  experimentConsent: boolean;
+  attributes: readonly PsychAttributeConsent[];
+};
+
+export type ExperimentContribution = {
+  /** Privacy-safe codes. Never a score, type name, or theme name. */
+  codes: string[];
+  /** 0–2. Reorders people who already matched. It is not a compatibility score. */
+  rankBoost: number;
+};
+
+const EMPTY: ExperimentContribution = { codes: [], rankBoost: 0 };
+const EXTRAVERSION_NEAR = 20;
+
+function usable(person: PsychExperimentInput): PsychAttributeConsent[] {
+  if (!person.experimentConsent) return [];
+  return person.attributes.filter(
+    (attribute) => attribute.allowExperimentalMatching && attribute.kind !== "HumanDesign"
+  );
+}
+
+function kind(person: PsychAttributeConsent[], name: string): PsychAttributeConsent | undefined {
+  return person.find((attribute) => attribute.kind === name);
+}
+
+function extraversion(value: unknown): number | null {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return null;
+  const score = (value as Record<string, unknown>).extraversion;
+  return typeof score === "number" ? score : null;
+}
+
+function themes(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+/**
+ * Separate from baseline intent and topic matching.
+ * Uses only attributes both people explicitly allowed, and only as a small reorder.
+ * Human Design is ignored. No score is returned.
+ */
+export function experimentContribution(
+  a: PsychExperimentInput,
+  b: PsychExperimentInput
+): ExperimentContribution {
+  const left = usable(a);
+  const right = usable(b);
+  if (left.length === 0 || right.length === 0) return EMPTY;
+
+  const signals: string[] = [];
+
+  const leftExtra = extraversion(kind(left, "BigFive")?.value);
+  const rightExtra = extraversion(kind(right, "BigFive")?.value);
+  if (leftExtra != null && rightExtra != null && Math.abs(leftExtra - rightExtra) <= EXTRAVERSION_NEAR) {
+    signals.push("PSYCH_SIGNAL:similar_social_energy");
+  }
+
+  const leftLocus = kind(left, "LocusOfControl")?.value;
+  const rightLocus = kind(right, "LocusOfControl")?.value;
+  if (
+    (leftLocus === "internal" || leftLocus === "external") &&
+    leftLocus === rightLocus
+  ) {
+    signals.push("PSYCH_SIGNAL:similar_outlook");
+  }
+
+  const sharedTheme = themes(kind(left, "CliftonStrengths")?.value).some((theme) =>
+    themes(kind(right, "CliftonStrengths")?.value).includes(theme)
+  );
+  if (sharedTheme) signals.push("PSYCH_SIGNAL:shared_theme");
+
+  const leftType = kind(left, "MyersBriggs")?.value;
+  const rightType = kind(right, "MyersBriggs")?.value;
+  if (
+    typeof leftType === "string" &&
+    typeof rightType === "string" &&
+    leftType.length === 4 &&
+    rightType.length === 4 &&
+    leftType[0]?.toUpperCase() === rightType[0]?.toUpperCase()
+  ) {
+    signals.push("PSYCH_SIGNAL:self_reported_social_style");
+  }
+
+  const leftEi = kind(left, "EmotionalIntelligence")?.value;
+  const rightEi = kind(right, "EmotionalIntelligence")?.value;
+  if (typeof leftEi === "number" && typeof rightEi === "number" && Math.abs(leftEi - rightEi) <= 1) {
+    signals.push("PSYCH_SIGNAL:self_reported_emotional_note");
+  }
+
+  if (signals.length === 0) return EMPTY;
+  return { codes: ["PSYCH_SHARED", ...signals], rankBoost: Math.min(2, signals.length) };
+}
+
+/** A shared experimental note. Never includes scores, types, or names. */
+export function psychExperimentCode(
+  a: PsychExperimentInput,
+  b: PsychExperimentInput
+): "PSYCH_SHARED" | null {
+  return experimentContribution(a, b).rankBoost > 0 ? "PSYCH_SHARED" : null;
+}
+
+export function appendPsychExperiment(
+  codes: readonly string[],
+  a: PsychExperimentInput,
+  b: PsychExperimentInput,
+  enabled: boolean
+): string[] {
+  if (!enabled) return [...codes];
+  return [...codes, ...experimentContribution(a, b).codes];
+}
+
+export function rankWithExperiment<T>(
+  candidates: readonly T[],
+  contributionFor: (item: T) => ExperimentContribution,
+  enabled: boolean
+): Array<{ item: T; contribution: ExperimentContribution }> {
+  if (!enabled) {
+    return candidates.map((item) => ({ item, contribution: EMPTY }));
+  }
+  return candidates
+    .map((item) => ({ item, contribution: contributionFor(item) }))
+    .sort((left, right) => right.contribution.rankBoost - left.contribution.rankBoost);
+}

package/src/intros/reasons.ts

@@ -0,0 +1,187 @@
+import { ageInYears } from "./age.js";
+import { intentsComplement, type IntrosIntent } from "./intents.js";
+
+export type MatchProfile = {
+  intents: readonly string[];
+  topics: readonly string[];
+  work: readonly string[];
+};
+
+export type RomanceFit = {
+  consented: boolean;
+  dob: Date | string | null;
+  gender: string | null;
+  seekingGenders: readonly string[];
+  ageMin: number | null;
+  ageMax: number | null;
+};
+
+function ageOf(dob: Date | string | null, now: Date): number | null {
+  if (!dob) return null;
+  const date = dob instanceof Date ? dob : new Date(dob);
+  if (Number.isNaN(date.getTime())) return null;
+  return ageInYears(date, now);
+}
+
+function ageFits(seeker: RomanceFit, other: RomanceFit, now: Date): boolean {
+  if (seeker.ageMin == null && seeker.ageMax == null) return true;
+  const age = ageOf(other.dob, now);
+  if (age == null) return false;
+  if (seeker.ageMin != null && age < seeker.ageMin) return false;
+  if (seeker.ageMax != null && age > seeker.ageMax) return false;
+  return true;
+}
+
+function genderFits(seeker: RomanceFit, other: RomanceFit): boolean {
+  if (seeker.seekingGenders.length === 0) return true;
+  if (!other.gender) return false;
+  return seeker.seekingGenders.includes(other.gender);
+}
+
+/** Both consented, and each person's age and gender fit the other's limits when those limits are set. */
+export function romancePairFits(a: RomanceFit, b: RomanceFit, now = new Date()): boolean {
+  if (!a.consented || !b.consented) return false;
+  return ageFits(a, b, now) && ageFits(b, a, now) && genderFits(a, b) && genderFits(b, a);
+}
+
+export type MatchReason = {
+  intent: IntrosIntent;
+  codes: string[];
+};
+
+function overlap(a: readonly string[], b: readonly string[]): string[] {
+  const right = new Set(b.map((item) => item.toLowerCase()));
+  return a.filter((item) => right.has(item.toLowerCase())).slice(0, 2);
+}
+
+/** Global matches need a specific reason. Same broad intent is not enough. Romance is specific when both people fit. */
+export function pairMatchReason(
+  a: MatchProfile,
+  b: MatchProfile,
+  romance?: { a: RomanceFit; b: RomanceFit },
+  now = new Date()
+): MatchReason | null {
+  const intent = intentsComplement(a.intents, b.intents);
+  if (!intent) return null;
+  if (intent === "Romance") {
+    if (!romance || !romancePairFits(romance.a, romance.b, now)) return null;
+    return { intent, codes: ["INTENT:Romance"] };
+  }
+  const topics = overlap(a.topics, b.topics);
+  const work = overlap(a.work, b.work);
+  const specific =
+    intent === "MentorSeek" ||
+    intent === "MentorOffer" ||
+    topics.length > 0 ||
+    work.length > 0;
+  if (!specific) return null;
+  return {
+    intent,
+    codes: [
+      ...topics.map((topic) => `SHARED_TOPIC:${topic}`),
+      ...work.map((item) => `SHARED_WORK:${item}`),
+      `INTENT:${intent}`,
+    ],
+  };
+}
+
+export function eventScopedReason(
+  a: MatchProfile,
+  b: MatchProfile,
+  romanceAllowed: boolean,
+  romance?: { a: RomanceFit; b: RomanceFit },
+  now = new Date()
+): MatchReason | null {
+  const intent = intentsComplement(a.intents, b.intents);
+  if (!intent) return null;
+  if (intent === "Romance" && (!romanceAllowed || (romance != null && !romancePairFits(romance.a, romance.b, now)))) {
+    return null;
+  }
+  const topics = overlap(a.topics, b.topics);
+  const work = overlap(a.work, b.work);
+  return {
+    intent,
+    codes: [
+      ...topics.map((topic) => `SHARED_TOPIC:${topic}`),
+      ...work.map((item) => `SHARED_WORK:${item}`),
+      `INTENT:${intent}`,
+    ],
+  };
+}
+
+/** Higher means a more specific reason. A broad intent still matches. */
+export function eventReasonSpecificity(reason: MatchReason): number {
+  if (reason.intent === "MentorSeek" || reason.intent === "MentorOffer" || reason.intent === "Romance") {
+    return 3;
+  }
+  if (reason.codes.some((code) => code.startsWith("SHARED_TOPIC:") || code.startsWith("SHARED_WORK:"))) {
+    return 2;
+  }
+  return 1;
+}
+
+function baselineHint(codes: readonly string[]): string | null {
+  const topic = codes.find((code) => code.startsWith("SHARED_TOPIC:"));
+  if (topic) return `You both mentioned ${topic.slice("SHARED_TOPIC:".length)}.`;
+  const work = codes.find((code) => code.startsWith("SHARED_WORK:"));
+  if (work) return `You both listed ${work.slice("SHARED_WORK:".length)}.`;
+  const intent = codes.find((code) => code.startsWith("INTENT:"))?.slice("INTENT:".length);
+  if (intent === "MentorSeek" || intent === "MentorOffer") {
+    return "A mentor and someone looking for one.";
+  }
+  if (intent === "Collaborator") return "You're both open to collaborating.";
+  if (intent === "Professional") return "You're both open to meeting people in your field.";
+  if (intent === "Friends") return "You're both open to making friends here.";
+  if (intent === "Romance") return "You both turned on romance.";
+  return null;
+}
+
+function experimentHint(codes: readonly string[]): string | null {
+  if (codes.includes("PSYCH_SIGNAL:similar_social_energy")) {
+    return "You both allowed a note about social energy. It is not a compatibility score.";
+  }
+  if (codes.includes("PSYCH_SIGNAL:similar_outlook")) {
+    return "You both allowed a note about how you approach situations. It is not a compatibility score.";
+  }
+  if (codes.includes("PSYCH_SIGNAL:shared_theme")) {
+    return "You both allowed a shared strengths theme. It is not a compatibility score.";
+  }
+  if (codes.includes("PSYCH_SIGNAL:self_reported_social_style")) {
+    return "You both allowed a self-reported social-style note. It is not a compatibility score.";
+  }
+  if (codes.includes("PSYCH_SIGNAL:self_reported_emotional_note")) {
+    return "You both allowed a self-reported emotional note. It is not a compatibility score.";
+  }
+  if (codes.includes("PSYCH_SHARED")) {
+    return "You both chose to include a personality note. It is not a compatibility score.";
+  }
+  return null;
+}
+
+export function introHint(codes: readonly string[]): string {
+  const baseline = baselineHint(codes);
+  const experiment = experimentHint(codes);
+  if (baseline && experiment) return `${baseline} ${experiment}`;
+  return baseline ?? experiment ?? "Bash thinks you might get along at this bash.";
+}
+
+export function rankEventForPair(
+  events: readonly { id: string; eventType: string; city: string | null }[],
+  codes: readonly string[]
+): string | null {
+  if (events.length === 0) return null;
+  const needles = codes
+    .filter((code) => code.startsWith("SHARED_TOPIC:") || code.startsWith("SHARED_WORK:"))
+    .map((code) => code.split(":").slice(1).join(":").toLowerCase());
+  let best = events[0];
+  let bestScore = -1;
+  for (const event of events) {
+    const haystack = `${event.eventType} ${event.city ?? ""}`.toLowerCase();
+    const score = needles.reduce((sum, needle) => sum + (haystack.includes(needle) ? 2 : 0), 0);
+    if (score > bestScore) {
+      best = event;
+      bestScore = score;
+    }
+  }
+  return best?.id ?? null;
+}

package/src/intros/sharedNotes.ts

@@ -0,0 +1,59 @@
+import {
+  attributeEvidenceTier,
+  isIntrosAttributeKind,
+  type IntrosAttributeKind,
+} from "./attributeCatalog.js";
+
+export type SharedPsychNote = {
+  kind: IntrosAttributeKind;
+  label: string;
+  tier: "Research-backed construct" | "Self-reported framework" | "Exploratory";
+  text: string;
+};
+
+const LABELS: Record<IntrosAttributeKind, string> = {
+  BigFive: "Big Five",
+  MyersBriggs: "Myers-Briggs",
+  LocusOfControl: "Locus of control",
+  CliftonStrengths: "CliftonStrengths",
+  EmotionalIntelligence: "Emotional intelligence",
+  HumanDesign: "Human Design",
+};
+
+function tierLabel(kind: IntrosAttributeKind): SharedPsychNote["tier"] {
+  const tier = attributeEvidenceTier(kind);
+  if (tier === "ResearchBackedConstruct") return "Research-backed construct";
+  if (tier === "Exploratory") return "Exploratory";
+  return "Self-reported framework";
+}
+
+function bigFiveText(value: unknown): string | null {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  const keys = ["openness", "conscientiousness", "extraversion", "agreeableness", "neuroticism"] as const;
+  const parts: string[] = [];
+  for (const key of keys) {
+    const score = Reflect.get(record, key);
+    if (typeof score !== "number") return null;
+    const label = key.charAt(0).toUpperCase() + key.slice(1);
+    parts.push(`${label} ${score}`);
+  }
+  return parts.join(", ");
+}
+
+/** A note the owner allowed a revealed partner to read. Not a compatibility score. */
+export function describeSharedNote(kind: string, value: unknown): SharedPsychNote | null {
+  if (!isIntrosAttributeKind(kind)) return null;
+  let text: string | null = null;
+  if (kind === "BigFive") text = bigFiveText(value);
+  else if (kind === "MyersBriggs" && typeof value === "string") text = value;
+  else if (kind === "LocusOfControl" && typeof value === "string") text = value;
+  else if (kind === "EmotionalIntelligence" && typeof value === "number") text = `Self-reported ${value} of 5`;
+  else if (kind === "HumanDesign" && typeof value === "string") text = value;
+  else if (kind === "CliftonStrengths" && Array.isArray(value)) {
+    const themes = value.filter((item): item is string => typeof item === "string");
+    text = themes.length > 0 ? themes.join(", ") : null;
+  }
+  if (!text) return null;
+  return { kind, label: LABELS[kind], tier: tierLabel(kind), text };
+}

package/src/intros/transitions.ts

@@ -0,0 +1,172 @@
+export const INTRODUCTION_STATES = ["Open", "Mutual", "Revealed", "Closed"] as const;
+export type IntroductionState = (typeof INTRODUCTION_STATES)[number];
+
+export const CLOSED_REASONS = [
+  "Declined",
+  "Withdrawn",
+  "Expired",
+  "NotRegistered",
+  "Blocked",
+  "EventCancelled",
+  "IntrosDisabled",
+  "ConsentRevoked",
+] as const;
+export type IntroductionClosedReason = (typeof CLOSED_REASONS)[number];
+
+export const PARTICIPANT_ACTIONS = [
+  "interested",
+  "sounds_good",
+  "decline",
+  "postpone",
+  "withdraw",
+  "hide_person",
+  "mute",
+  "unmute",
+  "say_hi",
+  "facilitation_ok",
+  "request_early_reveal",
+  "approve_early_reveal",
+  "decline_early_reveal",
+  "cancel_early_reveal",
+] as const;
+
+export type ParticipantAction = (typeof PARTICIPANT_ACTIONS)[number];
+export type IntroSide = "low" | "high";
+
+export interface TransitionIntro {
+  source: "BashSuggested" | "Warm";
+  mode: "Mystery" | "Known";
+  state: IntroductionState;
+  closedReason: IntroductionClosedReason | null;
+  interestLow: string;
+  interestHigh: string;
+}
+
+export type TransitionResult =
+  | {
+      ok: true;
+      state: IntroductionState;
+      closedReason: IntroductionClosedReason | null;
+      interestLow: string;
+      interestHigh: string;
+      revealNow: boolean;
+    }
+  | { ok: false; error: string };
+
+function withInterest(
+  intro: TransitionIntro,
+  side: IntroSide,
+  value: string
+): Pick<TransitionIntro, "interestLow" | "interestHigh"> {
+  return side === "low"
+    ? { interestLow: value, interestHigh: intro.interestHigh }
+    : { interestLow: intro.interestLow, interestHigh: value };
+}
+
+function unchanged(intro: TransitionIntro): TransitionResult {
+  return {
+    ok: true,
+    state: intro.state,
+    closedReason: intro.closedReason,
+    interestLow: intro.interestLow,
+    interestHigh: intro.interestHigh,
+    revealNow: false,
+  };
+}
+
+export function applyIntroductionAction(
+  intro: TransitionIntro,
+  side: IntroSide,
+  action: ParticipantAction
+): TransitionResult {
+  const finished = intro.state === "Revealed" || intro.state === "Closed";
+  if (finished && action !== "say_hi" && action !== "hide_person") {
+    return { ok: false, error: "This intro is already finished" };
+  }
+
+  if (action === "withdraw" || action === "decline") {
+    if (intro.state === "Revealed") {
+      return { ok: false, error: "This intro is already finished" };
+    }
+    return {
+      ok: true,
+      state: "Closed",
+      closedReason: action === "decline" ? "Declined" : "Withdrawn",
+      ...withInterest(intro, side, action === "decline" ? "Declined" : "Withdrawn"),
+      revealNow: false,
+    };
+  }
+
+  if (action === "postpone") {
+    if (intro.state !== "Open") return { ok: false, error: "You can only postpone an open intro" };
+    return {
+      ok: true,
+      state: "Open",
+      closedReason: null,
+      ...withInterest(intro, side, "Postponed"),
+      revealNow: false,
+    };
+  }
+
+  if (action === "interested") {
+    if (intro.source !== "BashSuggested") {
+      return { ok: false, error: "This intro uses a different response" };
+    }
+    if (intro.state !== "Open") return { ok: false, error: "This intro is no longer open" };
+    const interests = withInterest(intro, side, "Interested");
+    const both = interests.interestLow === "Interested" && interests.interestHigh === "Interested";
+    return {
+      ok: true,
+      state: both ? "Mutual" : "Open",
+      closedReason: null,
+      ...interests,
+      revealNow: false,
+    };
+  }
+
+  if (action === "sounds_good") {
+    if (intro.source !== "Warm") return { ok: false, error: "This intro uses a different response" };
+    if (intro.state !== "Open") return { ok: false, error: "This intro is no longer open" };
+    const interests = withInterest(intro, side, "Interested");
+    const both = interests.interestLow === "Interested" && interests.interestHigh === "Interested";
+    return {
+      ok: true,
+      state: both ? "Revealed" : "Open",
+      closedReason: null,
+      ...interests,
+      revealNow: both,
+    };
+  }
+
+  if (action === "say_hi") {
+    if (intro.state !== "Revealed") {
+      return { ok: false, error: "Say hi is available after you both can see each other" };
+    }
+    return unchanged(intro);
+  }
+
+  if (action === "mute" || action === "unmute" || action === "hide_person" || action === "facilitation_ok") {
+    return unchanged(intro);
+  }
+
+  if (
+    action === "request_early_reveal" ||
+    action === "approve_early_reveal" ||
+    action === "decline_early_reveal" ||
+    action === "cancel_early_reveal"
+  ) {
+    if (intro.source !== "BashSuggested" || intro.mode !== "Mystery") {
+      return { ok: false, error: "Early reveal is only for mystery intros" };
+    }
+    if (intro.state !== "Mutual") {
+      return { ok: false, error: "Early reveal opens once you are both interested" };
+    }
+    return unchanged(intro);
+  }
+
+  return { ok: false, error: "Unknown action" };
+}
+
+export function isParticipantAction(value: string): value is ParticipantAction {
+  return (PARTICIPANT_ACTIONS as readonly string[]).includes(value);
+}