@bash-app/bash-common 30.236.0 → 30.238.0

package/src/utils/service/billingCapUtils.ts

@@ -0,0 +1,145 @@
+/**
+ * Phase 0 adoption guardrails — host-side soft cap on variable-pricing bookings.
+ *
+ * Any booking whose `pricingModel` is not flat/hourly/daily can run up the host's
+ * tab if turnout exceeds expectations. `maxBillableCents` lets the host put a
+ * dollar ceiling on each booking. The default ceiling is `1.5x` of
+ * `expectedAttendees * baseRateCents`, rounded up to the nearest $10 — generous
+ * enough that hosts almost never trip it on a good night, but tight enough to
+ * protect against a runaway viral bash.
+ *
+ * Snapshotted on `ServiceBooking.maxBillableCents` at booking time so settlement
+ * math stays stable even if platform defaults change.
+ *
+ * Kept dependency-free so the wizard, api validators, and offer-suggestion AI
+ * can share one source of truth.
+ */
+
+/** Default ceiling multiplier on `expectedAttendees * baseRateCents`. */
+export const DEFAULT_MAX_BILLABLE_MULTIPLIER = 1.5;
+
+/** Default rounding granularity for the soft cap, in cents. ($10 = 1000 cents). */
+export const DEFAULT_MAX_BILLABLE_ROUNDING_CENTS = 1000;
+
+export interface DefaultMaxBillableCentsInput {
+  /**
+   * Expected attendees at booking time (snapshot from
+   * `bashEvent.expectedAttendees`). Zero / negative is treated as zero.
+   */
+  expectedAttendees: number | null | undefined;
+  /**
+   * Per-unit rate the booking is priced at (cents). For PER_ATTENDEE this is
+   * cents-per-attendee; for PER_PAID_ATTENDEE / PER_BASHPOINTS_ATTENDEE the
+   * caller passes the matching unit. Returns `null` when this is missing.
+   */
+  baseRateCents: number | null | undefined;
+  /**
+   * Optional override of the 1.5x multiplier (e.g. wizard lets host loosen the
+   * cap to 2x). Falls back to `DEFAULT_MAX_BILLABLE_MULTIPLIER`.
+   */
+  multiplier?: number;
+  /**
+   * Optional override of the rounding granularity in cents. Falls back to
+   * `DEFAULT_MAX_BILLABLE_ROUNDING_CENTS`.
+   */
+  roundingCents?: number;
+}
+
+/**
+ * Computes the default Phase 0 soft cap for a variable-pricing booking.
+ *
+ * Returns `null` when `baseRateCents` is unusable. Returns `0` when
+ * `expectedAttendees` is zero or absent — caller decides whether that means
+ * "skip the cap" (free / comp-only bash) or "force the host to set one explicitly".
+ *
+ * Worked example: 200 expected attendees @ $5 each → 200 * 500 * 1.5 = $1500 →
+ * already a multiple of $10 → cap = $1500. With 217 expected → 217 * 500 * 1.5
+ * = $1627.50 → round up to $1630.
+ */
+export function defaultMaxBillableCents(
+  input: DefaultMaxBillableCentsInput
+): number | null {
+  const { baseRateCents } = input;
+  if (
+    baseRateCents == null ||
+    !Number.isFinite(baseRateCents) ||
+    baseRateCents <= 0
+  ) {
+    return null;
+  }
+  const expected = Math.max(0, Math.floor(input.expectedAttendees ?? 0));
+  const multiplier =
+    input.multiplier != null && input.multiplier > 0
+      ? input.multiplier
+      : DEFAULT_MAX_BILLABLE_MULTIPLIER;
+  const roundingCents =
+    input.roundingCents != null && input.roundingCents > 0
+      ? Math.floor(input.roundingCents)
+      : DEFAULT_MAX_BILLABLE_ROUNDING_CENTS;
+
+  const raw = expected * baseRateCents * multiplier;
+  if (raw <= 0) return 0;
+  return Math.ceil(raw / roundingCents) * roundingCents;
+}
+
+/**
+ * Parallel cap for `PER_BASHPOINTS_ATTENDEE` bookings — same formula, BashPoints
+ * units. Rounds up to the nearest 100 BashPoints by default since BashPoints
+ * are integer-only.
+ */
+export function defaultMaxBillableBashPoints(input: {
+  expectedAttendees: number | null | undefined;
+  baseRateBashPoints: number | null | undefined;
+  multiplier?: number;
+  /** Defaults to 100 BashPoints. */
+  roundingBashPoints?: number;
+}): number | null {
+  const { baseRateBashPoints } = input;
+  if (
+    baseRateBashPoints == null ||
+    !Number.isFinite(baseRateBashPoints) ||
+    baseRateBashPoints <= 0
+  ) {
+    return null;
+  }
+  const expected = Math.max(0, Math.floor(input.expectedAttendees ?? 0));
+  const multiplier =
+    input.multiplier != null && input.multiplier > 0
+      ? input.multiplier
+      : DEFAULT_MAX_BILLABLE_MULTIPLIER;
+  const rounding =
+    input.roundingBashPoints != null && input.roundingBashPoints > 0
+      ? Math.floor(input.roundingBashPoints)
+      : 100;
+  const raw = expected * baseRateBashPoints * multiplier;
+  if (raw <= 0) return 0;
+  return Math.ceil(raw / rounding) * rounding;
+}
+
+/**
+ * Default snippet to snapshot onto `ServiceBooking.payoutTimingNote` at booking
+ * time for any variable-pricing booking. Keep concise — surfaces in offer
+ * sheets, booking detail, and email summaries.
+ */
+export const DEFAULT_VARIABLE_PAYOUT_TIMING_NOTE =
+  "Variable pricing payout: final settlement ~3 business days after the bash, after attendee numbers are locked.";
+
+/**
+ * Pricing models that DO NOT need a `maxBillableCents` guardrail because the
+ * total is known at booking time. Used by the wizard to decide whether to
+ * surface the cap editor + payout-timing copy.
+ */
+export const FLAT_PRICING_MODELS = ["FLAT_FEE", "HOURLY", "PER_DAY"] as const;
+
+export type FlatPricingModel = (typeof FLAT_PRICING_MODELS)[number];
+
+/**
+ * Returns true if the given pricing-model string is one of the FLAT models
+ * that don't need a variable-pricing cap or payout-timing banner.
+ */
+export function isFlatPricingModel(
+  model: string | null | undefined
+): model is FlatPricingModel {
+  if (!model) return false;
+  return (FLAT_PRICING_MODELS as readonly string[]).includes(model);
+}

package/src/utils/service/cancellationPolicyRefundResolver.ts

@@ -1,4 +1,4 @@
-import { ServiceCancellationPolicy } from "@prisma/client";
+import { ServiceCancellationPolicy } from "../../mirroredPrismaEnums.js";
 import {
   SERVICE_CANCELLATION_POLICY_DATA,
   type ServiceCancellationRefundPolicy,