@bash-app/bash-common 30.292.0 → 30.295.0

package/src/membershipDefinitions.ts

@@ -219,6 +219,17 @@ export const BASHPOINTS_REWARDS: Record<MembershipTier, {
   },
 } as const;
 
+/** Referral tier qualification thresholds — single source of truth for grant + stats UI. */
+export const AMBASHADOR_QUALIFICATION = {
+  freeSignups: 1,
+  paidSignups: 1,
+} as const;
+
+export const INSIDER_QUALIFICATION = {
+  freeSignups: 100,
+  paidSignups: 10,
+} as const;
+
 /**
  * BashPoints system rules and limits
  * 
@@ -233,7 +244,7 @@ export const BASHPOINTS_CONFIG = {
   paymentVerificationBonus: 500,
 
   // Tier achievement bonuses (one-time when user reaches each tier)
-  ambashadorAchievementBonus: 500,      // Ambashador: 3 free or 1 paid referral
+  ambashadorAchievementBonus: 500,      // Ambashador: 1 free or 1 paid referral
   scoutAchievementBonus: 250,           // Scout: first service profile referral
   insiderAchievementBonus: 1000,       // Bash Insider: 10 paid or 100 free referrals
   agentAchievementBonus: 500,           // Agent: 5+ service profile referrals

package/src/utils/__tests__/reputationUtils.serviceListing.test.ts

@@ -33,4 +33,28 @@ describe("getServiceListingReputation", () => {
       })?.sourceLabel
     ).toBeUndefined();
   });
+
+  it("uses Bash sourceLabel when native reviews exist", () => {
+    expect(
+      getServiceListingReputation({
+        serviceRating: 4.6,
+        totalRatings: 12,
+        externalReviewSource: "google",
+      })
+    ).toEqual({
+      averageRating: 4.6,
+      totalRatings: 12,
+      sourceLabel: "Bash",
+    });
+  });
+
+  it("returns null below threshold even with google external source", () => {
+    expect(
+      getServiceListingReputation({
+        serviceRating: 4.9,
+        totalRatings: 0,
+        externalReviewSource: "google",
+      })
+    ).toBeNull();
+  });
 });

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

@@ -0,0 +1,65 @@
+import {
+  averageNullable,
+  parseOptionalDimensionRating,
+  parseRequiredOverallRating,
+  percentTrue,
+} from "../reviewDimensionUtils.js";
+
+describe("reviewDimensionUtils", () => {
+  describe("parseRequiredOverallRating", () => {
+    it("accepts integers 1–5", () => {
+      expect(parseRequiredOverallRating(4)).toBe(4);
+    });
+
+    it("rejects out of range", () => {
+      expect(() => parseRequiredOverallRating(0)).toThrow();
+      expect(() => parseRequiredOverallRating(6)).toThrow();
+    });
+  });
+
+  describe("parseOptionalDimensionRating", () => {
+    it("returns null when omitted", () => {
+      expect(parseOptionalDimensionRating(undefined, "communication")).toBeNull();
+    });
+
+    it("parses valid optional ratings", () => {
+      expect(parseOptionalDimensionRating(3, "communication")).toBe(3);
+    });
+  });
+
+  describe("averageNullable", () => {
+    it("returns null for empty input", () => {
+      expect(averageNullable([])).toBeNull();
+    });
+
+    it("averages present values", () => {
+      expect(averageNullable([4, 5, null])).toBe(4.5);
+    });
+  });
+
+  describe("percentTrue", () => {
+    it("returns null when no booleans", () => {
+      expect(percentTrue([null, undefined])).toBeNull();
+    });
+
+    it("computes yes percentage", () => {
+      expect(percentTrue([true, false, true])).toBe(67);
+    });
+
+    it("returns 100 when all true", () => {
+      expect(percentTrue([true, true])).toBe(100);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("parseOptionalDimensionRating rejects non-integers", () => {
+      expect(() =>
+        parseOptionalDimensionRating(3.5, "qualityRating")
+      ).toThrow(/integer/i);
+    });
+
+    it("averageNullable ignores NaN", () => {
+      expect(averageNullable([4, Number.NaN, 2])).toBe(3);
+    });
+  });
+});

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

@@ -0,0 +1,105 @@
+import { computeTrustScoreFromInputs } from "../trustScoreUtils.js";
+
+describe("trustScoreUtils", () => {
+  it("returns a score between 0 and 100 for services", () => {
+    const result = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: 4.5,
+      completedVolume: 25,
+      cancellationRate: 0.05,
+      responseRate: 1,
+      identityVerified: true,
+      verifiedCompletionRate: 0.9,
+      accountAgeDays: 400,
+      disputeRate: 0,
+      repeatCustomerRate: 0.2,
+    });
+    expect(result.score).not.toBeNull();
+    expect(result.score!).toBeGreaterThanOrEqual(0);
+    expect(result.score!).toBeLessThanOrEqual(100);
+    expect(result.components.reviews).toBeGreaterThan(0);
+  });
+
+  it("uses host weights including attendance signal", () => {
+    const result = computeTrustScoreFromInputs("host", {
+      bayesianReviewScore: 4,
+      completedVolume: 10,
+      cancellationRate: 0.1,
+      responseRate: 0.8,
+      identityVerified: false,
+      verifiedAttendanceRate: 0.75,
+      accountAgeDays: 30,
+      disputeRate: 0.02,
+      repeatCustomerRate: 0.1,
+    });
+    expect(result.weights.attendance).toBe(0.05);
+    expect(result.score).not.toBeNull();
+  });
+
+  it("returns null score when insufficient review signal defaults", () => {
+    const result = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: null,
+      completedVolume: 0,
+      cancellationRate: 0,
+      responseRate: 1,
+      identityVerified: false,
+      verifiedCompletionRate: 0,
+      accountAgeDays: 1,
+      disputeRate: 0,
+      repeatCustomerRate: 0,
+    });
+    expect(result.score).not.toBeNull();
+    expect(result.components.reviews).toBe(0.5);
+  });
+
+  it("penalizes high cancellation and dispute rates", () => {
+    const good = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: 4.5,
+      completedVolume: 50,
+      cancellationRate: 0.05,
+      responseRate: 1,
+      identityVerified: true,
+      verifiedCompletionRate: 0.9,
+      accountAgeDays: 500,
+      disputeRate: 0,
+      repeatCustomerRate: 0.3,
+    });
+    const bad = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: 4.5,
+      completedVolume: 50,
+      cancellationRate: 0.5,
+      responseRate: 0.5,
+      identityVerified: true,
+      verifiedCompletionRate: 0.2,
+      accountAgeDays: 500,
+      disputeRate: 0.2,
+      repeatCustomerRate: 0,
+    });
+    expect(good.score!).toBeGreaterThan(bad.score!);
+  });
+
+  it("boosts score when identity is verified", () => {
+    const verified = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: 4,
+      completedVolume: 10,
+      cancellationRate: 0.1,
+      responseRate: 1,
+      identityVerified: true,
+      verifiedCompletionRate: 0.5,
+      accountAgeDays: 200,
+      disputeRate: 0,
+      repeatCustomerRate: 0.1,
+    });
+    const unverified = computeTrustScoreFromInputs("service", {
+      bayesianReviewScore: 4,
+      completedVolume: 10,
+      cancellationRate: 0.1,
+      responseRate: 1,
+      identityVerified: false,
+      verifiedCompletionRate: 0.5,
+      accountAgeDays: 200,
+      disputeRate: 0,
+      repeatCustomerRate: 0.1,
+    });
+    expect(verified.score!).toBeGreaterThan(unverified.score!);
+  });
+});

package/src/utils/reputationUtils.ts

@@ -85,7 +85,13 @@ export function getServiceListingReputation(service: {
     return null;
   }
   const sourceLabel =
-    service.externalReviewSource === "google" ? "Google" : undefined;
+    service.externalReviewSource === "google" && (service.totalRatings ?? 0) === 0
+      ? "Google"
+      : (service.totalRatings ?? 0) > 0
+        ? "Bash"
+        : service.externalReviewSource === "google"
+          ? "Google"
+          : undefined;
   return {
     averageRating: summary.averageRating,
     totalRatings: summary.totalRatings,

package/src/utils/reviewDimensionUtils.ts

@@ -0,0 +1,70 @@
+/** Optional 1–5 dimension rating from API/UI payloads. */
+export type OptionalDimensionRating = number | null | undefined;
+
+export interface EventReviewDimensionsInput {
+  organizationRating?: OptionalDimensionRating;
+  atmosphereRating?: OptionalDimensionRating;
+  valueRating?: OptionalDimensionRating;
+  safetyRating?: OptionalDimensionRating;
+  wouldAttendAgain?: boolean | null;
+}
+
+export interface ServiceReviewDimensionsInput {
+  communicationRating?: OptionalDimensionRating;
+  professionalismRating?: OptionalDimensionRating;
+  qualityRating?: OptionalDimensionRating;
+  wouldHireAgain?: boolean | null;
+}
+
+export interface ReviewDimensionAverages {
+  organization?: number | null;
+  atmosphere?: number | null;
+  value?: number | null;
+  safety?: number | null;
+  communication?: number | null;
+  professionalism?: number | null;
+  quality?: number | null;
+  wouldAttendAgainPercent?: number | null;
+  wouldHireAgainPercent?: number | null;
+  wouldWorkAgainPercent?: number | null;
+}
+
+const MIN_DIM = 1;
+const MAX_DIM = 5;
+
+/** Validate optional 1–5 dimension; returns null when omitted. */
+export function parseOptionalDimensionRating(
+  value: OptionalDimensionRating,
+  fieldName: string
+): number | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < MIN_DIM || n > MAX_DIM) {
+    throw new Error(`${fieldName} must be an integer from ${MIN_DIM} to ${MAX_DIM}`);
+  }
+  return n;
+}
+
+export function parseRequiredOverallRating(value: unknown): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < MIN_DIM || n > MAX_DIM) {
+    throw new Error(`Overall rating must be an integer from ${MIN_DIM} to ${MAX_DIM}`);
+  }
+  return n;
+}
+
+export function averageNullable(values: (number | null | undefined)[]): number | null {
+  const nums = values.filter((v): v is number => typeof v === "number" && !Number.isNaN(v));
+  if (nums.length === 0) return null;
+  const sum = nums.reduce((a, b) => a + b, 0);
+  return Math.round((sum / nums.length) * 100) / 100;
+}
+
+export function percentTrue(values: (boolean | null | undefined)[]): number | null {
+  const defined = values.filter((v): v is boolean => typeof v === "boolean");
+  if (defined.length === 0) return null;
+  const yes = defined.filter(Boolean).length;
+  return Math.round((yes / defined.length) * 100);
+}

package/src/utils/trustScoreUtils.ts

@@ -0,0 +1,136 @@
+import { bayesianAverage } from "./reputationUtils.js";
+
+export type TrustScoreActorType = "host" | "service";
+
+export interface TrustScoreInputs {
+  bayesianReviewScore: number | null;
+  completedVolume: number;
+  cancellationRate: number;
+  responseRate: number;
+  identityVerified: boolean;
+  verifiedAttendanceRate?: number;
+  verifiedCompletionRate?: number;
+  accountAgeDays: number;
+  disputeRate: number;
+  repeatCustomerRate: number;
+}
+
+export interface TrustScoreBreakdown {
+  score: number | null;
+  components: Record<string, number>;
+  weights: Record<string, number>;
+}
+
+const HOST_WEIGHTS: Record<string, number> = {
+  reviews: 0.35,
+  volume: 0.15,
+  cancellation: 0.1,
+  response: 0.1,
+  identity: 0.1,
+  attendance: 0.05,
+  accountAge: 0.05,
+  disputes: 0.05,
+  repeat: 0.05,
+};
+
+const SERVICE_WEIGHTS: Record<string, number> = {
+  reviews: 0.4,
+  volume: 0.15,
+  cancellation: 0.1,
+  response: 0.1,
+  identity: 0.1,
+  completion: 0.1,
+  accountAge: 0.05,
+  disputes: 0.05,
+  repeat: 0.05,
+};
+
+function clamp01(n: number): number {
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+function logScaledVolume(count: number, cap = 100): number {
+  if (count <= 0) return 0;
+  return clamp01(Math.log10(count + 1) / Math.log10(cap + 1));
+}
+
+function accountAgeScore(days: number): number {
+  return clamp01(Math.log10(Math.max(days, 1) + 1) / Math.log10(365 * 3 + 1));
+}
+
+function inverseRate(rate: number): number {
+  return clamp01(1 - clamp01(rate));
+}
+
+/**
+ * Compute a 0–100 trust score from normalized component signals (0–1 each).
+ */
+export function computeTrustScoreFromInputs(
+  actorType: TrustScoreActorType,
+  inputs: TrustScoreInputs
+): TrustScoreBreakdown {
+  const weights = actorType === "host" ? HOST_WEIGHTS : SERVICE_WEIGHTS;
+
+  const reviewComponent =
+    inputs.bayesianReviewScore != null
+      ? clamp01(inputs.bayesianReviewScore / 5)
+      : 0.5;
+
+  const components: Record<string, number> = {
+    reviews: reviewComponent,
+    volume: logScaledVolume(inputs.completedVolume),
+    cancellation: inverseRate(inputs.cancellationRate),
+    response: clamp01(inputs.responseRate),
+    identity: inputs.identityVerified ? 1 : 0,
+    accountAge: accountAgeScore(inputs.accountAgeDays),
+    disputes: inverseRate(inputs.disputeRate),
+    repeat: clamp01(inputs.repeatCustomerRate),
+  };
+
+  if (actorType === "host") {
+    components.attendance = clamp01(inputs.verifiedAttendanceRate ?? 0);
+  } else {
+    components.completion = clamp01(inputs.verifiedCompletionRate ?? 0);
+  }
+
+  let weighted = 0;
+  let weightSum = 0;
+  for (const [key, weight] of Object.entries(weights)) {
+    const val = components[key];
+    if (val == null) continue;
+    weighted += val * weight;
+    weightSum += weight;
+  }
+
+  if (weightSum === 0) {
+    return { score: null, components, weights };
+  }
+
+  const normalized = weighted / weightSum;
+  const score = Math.round(normalized * 100);
+  return { score, components, weights };
+}
+
+/** Convenience when only review stats are available (early bootstrap). */
+export function trustScoreFromReviewAverage(
+  actorType: TrustScoreActorType,
+  averageRating: number | null | undefined,
+  totalRatings: number | null | undefined
+): number | null {
+  const bayesian = bayesianAverage(averageRating, totalRatings);
+  const result = computeTrustScoreFromInputs(actorType, {
+    bayesianReviewScore: bayesian,
+    completedVolume: totalRatings ?? 0,
+    cancellationRate: 0,
+    responseRate: 1,
+    identityVerified: false,
+    accountAgeDays: 30,
+    disputeRate: 0,
+    repeatCustomerRate: 0,
+    verifiedAttendanceRate: 0,
+    verifiedCompletionRate: 0,
+  });
+  return result.score;
+}