@ticketboothapp/booking 1.2.61 → 1.2.62

package/src/lib/booking/change-booking-server-preview.ts

@@ -0,0 +1,139 @@
+/**
+ * **Server-owned change-booking preview** — canonical shape the FE consumes when BE is the source of truth.
+ * Built from `POST .../change/quote` via {@link buildChangeBookingServerPreview}.
+ *
+ * See `CHANGE_BOOKING_BE_HANDOFF.md` in this package for fields the API should populate.
+ */
+import type { ChangeBookingQuoteResponse } from '../booking-api';
+import type { PriceSummaryLine } from '../../components/booking/PriceSummary';
+import { roundMoney, serverTotalsFromChangeQuoteResponse } from './change-flow-pricing';
+
+export type ChangeBookingPreviewCompleteness =
+  | 'totals_only'
+  /** BE sent structured picker pricing + line breakdown — FE hides no server-backed amounts. */
+  | 'full';
+
+export interface ChangeBookingServerPreview {
+  currency: string;
+  amountDue: number;
+  subtotal: number;
+  tax: number;
+  totalNewBooking: number;
+  completeness: ChangeBookingPreviewCompleteness;
+  /** Rows for {@link PriceSummary} / checkout — from quote receipt line items + BE extensions. */
+  priceSummaryLines: PriceSummaryLine[];
+  /** From quote — per-category unit prices (major units) for ticket picker when BE sends them. */
+  ticketUnitPriceByCategory?: Record<string, number>;
+  cancellationPolicyFeeByPolicyId?: Record<string, number>;
+  returnOptionPriceByReturnAvailabilityId?: Record<string, number>;
+}
+
+function lineItemsForSummary(quote: ChangeBookingQuoteResponse): NonNullable<
+  ChangeBookingQuoteResponse['newReceipt']
+>['lineItems'] {
+  return quote.newReceipt?.lineItems ?? quote.proposed?.lineItems ?? quote.original?.lineItems ?? undefined;
+}
+
+/** Map receipt-style quote line items to checkout {@link PriceSummaryLine} rows (shared with price-check drift UI). */
+export function mapQuoteLineItemsToPriceSummaryLines(
+  items:
+    | NonNullable<NonNullable<ChangeBookingQuoteResponse['newReceipt']>['lineItems']>
+    | Array<{ label?: string; amount?: number; type?: string; quantity?: number }>
+    | undefined
+    | null,
+): PriceSummaryLine[] {
+  if (!items?.length) return [];
+  const out: PriceSummaryLine[] = [];
+  for (const item of items) {
+    const amount = Number(item.amount) || 0;
+    const type = (item.type ?? '').toUpperCase();
+    const qty = Math.max(0, Number(item.quantity) || 0);
+    const label = (item.label ?? '').trim();
+    if (
+      type === 'TICKET' ||
+      type === 'ADULT' ||
+      type === 'CHILD' ||
+      type === 'INFANT' ||
+      type === 'SENIOR' ||
+      type === 'STUDENT'
+    ) {
+      const category =
+        type === 'TICKET'
+          ? (label.split(/\s+/)[0]?.replace(/[^a-zA-Z]/g, '') || 'TICKET').toUpperCase()
+          : type;
+      out.push({
+        kind: 'ticket',
+        category,
+        qty: qty > 0 ? qty : 1,
+        itemTotal: amount,
+      });
+      continue;
+    }
+
+    /** Receipt exports sometimes use type LINE + label “ADULT” + quantity — treat as ticket for drift parity. */
+    const ticketWords = new Set(['ADULT', 'CHILD', 'INFANT', 'SENIOR', 'STUDENT']);
+    const lettersOnly = label.replace(/[^a-zA-Z]/g, '').toUpperCase();
+    const wordCount = label.trim().split(/\s+/).filter(Boolean).length;
+    if (
+      qty > 0 &&
+      ticketWords.has(lettersOnly) &&
+      wordCount <= 2 &&
+      !ticketWords.has(type)
+    ) {
+      out.push({
+        kind: 'ticket',
+        category: lettersOnly,
+        qty,
+        itemTotal: amount,
+      });
+      continue;
+    }
+
+    /** Align with checkout drift keys (`ChangeBookingFlow` uses `type: 'return'`). */
+    const summaryType =
+      type === 'RETURN_OPTION' || type === 'RETURNOPTION' ? 'return' : (item.type ?? 'fee');
+    out.push({
+      kind: 'line',
+      label: label || type || 'Line',
+      amount,
+      type: summaryType,
+    });
+  }
+  return out;
+}
+
+/**
+ * Single builder: quote JSON → preview consumed by ChangeBookingFlow (no parallel FE “display math”).
+ */
+export function buildChangeBookingServerPreview(
+  quote: ChangeBookingQuoteResponse,
+  fallbackCart: { total: number; subtotal: number; tax: number },
+  currencyFallback: string,
+): ChangeBookingServerPreview | null {
+  const totals = serverTotalsFromChangeQuoteResponse(quote, fallbackCart);
+  if (!totals) return null;
+
+  const currency = (quote.currency ?? currencyFallback).trim() || currencyFallback;
+  const amountDue =
+    quote.amountDueCents != null ? quote.amountDueCents / 100 : quote.priceDiff ?? 0;
+
+  const rawLines = lineItemsForSummary(quote);
+  const priceSummaryLines =
+    rawLines && rawLines.length > 0 ? mapQuoteLineItemsToPriceSummaryLines(rawLines) : [];
+
+  /** FE assumes the change-quote contract is implemented; no `totals_only` gating in UI. */
+  const completeness: ChangeBookingPreviewCompleteness = 'full';
+
+  return {
+    currency,
+    amountDue: roundMoney(amountDue),
+    subtotal: totals.subtotal,
+    tax: totals.tax,
+    totalNewBooking: totals.total,
+    completeness,
+    priceSummaryLines,
+    ticketUnitPriceByCategory: quote.ticketUnitPriceByCategory,
+    cancellationPolicyFeeByPolicyId: quote.cancellationPolicyFeeByPolicyId,
+    returnOptionPriceByReturnAvailabilityId: quote.returnOptionPriceByReturnAvailabilityId,
+  };
+}

package/src/lib/booking/change-flow-pricing.ts

@@ -10,32 +10,42 @@
  * floors) so a cheaper date/return yields a lower total / refund via signed balance.
  *
  * ### 2. Tickets (per category)
- * For each category where we can infer an average **unit paid** from the stored receipt:
- * - Among seats **up to** the **originally booked** count for that category, **unit price** =
- *   **`max(receipt average unit, live catalog unit)`** — not the minimum; the guest never pays **below** what they paid
- *   for those seats **and** never **below** today’s list price for those seats.
- * - Any **extra** seats beyond the original count for that category: **live catalog only** (no receipt floor).
- * If we cannot infer a receipt unit for a category, that line stays **live catalog** only.
+ * **Unchanged itinerary** (same calendar departure date **and** same product option as the booking): among seats up to the
+ * originally booked count, unit price is **exactly** the receipt/booking unit — catalog moves do **not** change those seats.
+ * **Date or product option changed:** protected seats use **`max(receipt average unit, live catalog unit)`**; they never go
+ * below what was paid but may go up with catalog.
+ * **Extra** seats beyond the original count: **live catalog** only. If receipt unit is unknown, that category uses live
+ * catalog for the line.
  *
  * ### 3. Product fees (config fees, per line)
- * Split the party into **protected** headcount (≤ original total ticket count) vs **incremental** passengers.
- * For each fee line: **`max(receipt-derived fee per person, live fee per person)`** on protected passengers; incremental
- * passengers pay each line’s **live** per-person amount only.
+ * Same **unchanged vs changed itinerary** split as tickets: protected passengers use **exact receipt-derived fee** when the
+ * itinerary is unchanged, else **`max(receipt, live)`** per fee line; incremental passengers pay **live** per-person only.
  *
  * ### 4. Return option — **order total / checkout**
- * When §1 floors apply and a per-person return floor exists (API `returnUnitFloorPerPerson` or receipt RETURN lines):
- * **per person** = **`max(live catalog return for the selected slot, floor)`**; **row total** = party size × that amount.
- * Provider dashboard: **live catalog return only** (no floor).
+ * When a per-person return floor exists (API `returnUnitFloorPerPerson` or receipt RETURN / RETURN_OPTION lines), align with
+ * BE `PublicChangeBookingQuotePricing`: **baseline party** (originally booked headcount) vs **incremental** seats. **Rule A**
+ * (same `returnAvailabilityId` as the booking **and** unchanged outbound itinerary): protected pay exact locked per person;
+ * incremental pay **live catalog** return only ($0 when free). **Else Rule B:** protected pay **`max(floor, live)`**;
+ * incremental pay **live** only. Provider dashboard: **live catalog return only** (no floor).
  *
  * ### 5. Return option — **picker UI only** (BookingFlow)
- * **Self-serve:** return cards use the floored per-person price when a floor exists (aligned with §4).
+ * **Self-serve:** return cards use the floored per-person price when a floor exists (aligned with §4), for every return
+ * slot, regardless of date/option change.
  * **Provider dashboard:** cards show **catalog** prices only (no floor).
  *
  * ### 6. Quote “new booking” total & balance
  * **FE proposed total** = full cart math (subtotal + tax − promo), cent-rounded; optional **1¢ reconcile** to old receipt
- * total when the difference is only rounding noise (`resolveChangeFlowNewBookingTotal`).
- * **Customer** owes **`max(0, newTotal − oldReceipt)`**; **provider** inline pricing may show a **signed** delta.
+ * total when the difference is only rounding noise (`resolveChangeFlowNewBookingTotal`). Sent to `POST .../change/quote`
+ * as `clientProposedTotal` so the API can verify within tolerance.
+ *
+ * **Customer self-serve display:** when `POST .../change/quote` returns `newReceipt` / `proposed` / `newTotalCents`,
+ * **`serverTotalsFromChangeQuoteResponse`** becomes the **display** source for subtotal/tax/total (`resolveChangeFlowDisplayedAmounts`).
+ * Use **`sliceChangeQuoteForUi`** to map a full quote response into UI state once (debounced quote + checkout quote).
+ * Amount owed for copy/CTA uses **`amountDueCents`** / **`priceDiff`** from the same response so UI matches PaymentIntent.
+ *
+ * **Provider** inline pricing may show a **signed** delta from cart or manual overrides.
  */
+import type { ChangeBookingQuoteResponse } from '../booking-api';
 import { reconcileChangeBookingProposedTotal } from '../currency';
 
 /** Money in major units, rounded to cents (half-up). */
@@ -43,8 +53,11 @@ export function roundMoney(amount: number): number {
   return Math.round(amount * 100) / 100;
 }
 
+/** Rule A: unchanged date + product option — receipt units/fees apply exactly on protected seats. Rule B: max with catalog. */
+export type ChangeFlowProtectedReceiptPricing = 'exact_from_receipt' | 'max_with_catalog';
+
 /**
- * One ticket row: protected seats use `max(receipt unit, live unit)`; extra qty uses live only.
+ * One ticket row: protected seats follow Rule A (exact receipt unit) or Rule B (`max(receipt, live)`); extra qty uses live only.
  */
 export function changeFlowTicketLineTotalWithReceiptFloor(input: {
   qty: number;
@@ -54,6 +67,7 @@ export function changeFlowTicketLineTotalWithReceiptFloor(input: {
   receiptUnitFloor: number | undefined;
   /** Current catalog line total (before floors). */
   liveLineTotal: number;
+  protectedReceiptPricing: ChangeFlowProtectedReceiptPricing;
 }): number {
   const qty = Math.max(0, input.qty);
   if (qty <= 0) return 0;
@@ -64,18 +78,22 @@ export function changeFlowTicketLineTotalWithReceiptFloor(input: {
   const baselineQty = Math.max(0, input.baselineQtyForCategory);
   const protectedQty = Math.min(qty, baselineQty);
   const incrementalQty = Math.max(0, qty - baselineQty);
+  if (input.protectedReceiptPricing === 'exact_from_receipt') {
+    return protectedQty * input.receiptUnitFloor + incrementalQty * liveUnit;
+  }
   const protectedUnit = Math.max(input.receiptUnitFloor, liveUnit);
   return protectedQty * protectedUnit + incrementalQty * liveUnit;
 }
 
 /**
- * One fee row: first `initialTicketCount` passengers use `max(receipt per-person, live per-person)`; rest live only.
+ * One fee row: protected headcount uses Rule A (exact booked fee) or Rule B (max with live per-person); rest live only.
  */
 export function changeFlowFeeLineTotalWithReceiptFloor(input: {
   totalQuantity: number;
   initialTicketCount: number;
   bookedFeePerPerson: number | undefined;
   liveFeeLineTotal: number;
+  protectedReceiptPricing: ChangeFlowProtectedReceiptPricing;
 }): number {
   const totalQuantity = Math.max(0, input.totalQuantity);
   if (totalQuantity <= 0) return Math.max(0, Number(input.liveFeeLineTotal) || 0);
@@ -86,6 +104,9 @@ export function changeFlowFeeLineTotalWithReceiptFloor(input: {
   }
   const protectedP = Math.min(Math.max(0, input.initialTicketCount), totalQuantity);
   const incrementalP = Math.max(0, totalQuantity - protectedP);
+  if (input.protectedReceiptPricing === 'exact_from_receipt') {
+    return protectedP * input.bookedFeePerPerson + incrementalP * livePer;
+  }
   const protectedPerPerson = Math.max(input.bookedFeePerPerson, livePer);
   return protectedP * protectedPerPerson + incrementalP * livePer;
 }
@@ -103,6 +124,39 @@ export function changeFlowReturnPerPersonWithReceiptFloor(input: {
   return Math.max(live, floor);
 }
 
+/**
+ * Full return row total aligned with BE `PublicChangeBookingQuotePricing`: receipt floor applies only to **original**
+ * party headcount; extra seats pay **live catalog** return only ($0 when the slot is free).
+ *
+ * Rule A (same return id + unchanged outbound itinerary): protected pay exact receipt locked per person.
+ * Else Rule B: protected pay max(locked, live); incremental pay live only.
+ */
+export function changeFlowReturnLineTotalWithReceiptFloor(input: {
+  totalPersons: number;
+  /** Original booked ticket count (party cap), same as BE `baselineParty`. */
+  baselineParty: number;
+  /** Catalog live per person for the selected return slot (major units). */
+  livePerPerson: number;
+  receiptFloorPerPerson: number | null;
+  /** Mirrors BE `returnPricingRuleA`. */
+  returnRuleA: boolean;
+}): number {
+  const n = Math.max(0, input.totalPersons);
+  if (n <= 0) return 0;
+  const live = Number.isFinite(input.livePerPerson) ? input.livePerPerson : 0;
+  const floor = input.receiptFloorPerPerson;
+  if (floor == null || !Number.isFinite(floor)) {
+    return roundMoney(n * live);
+  }
+  const baseline = Math.max(0, input.baselineParty);
+  const protectedP = Math.min(baseline, n);
+  const incrementalP = Math.max(0, n - baseline);
+  if (input.returnRuleA) {
+    return roundMoney(protectedP * floor + incrementalP * live);
+  }
+  return roundMoney(protectedP * Math.max(floor, live) + incrementalP * live);
+}
+
 /**
  * Product: **New booking price** for a change is the same cart total as a fresh booking
  * (subtotal + tax − discounts), in cents. We send that on quotes so it matches line items and the server breakdown.
@@ -111,14 +165,10 @@ export function changeFlowReturnPerPersonWithReceiptFloor(input: {
  * total (see `reconcileChangeBookingProposedTotal`).
  */
 export function resolveChangeFlowNewBookingTotal(input: {
-  isChangeFlow: boolean;
   /** `effectiveSubtotal + effectiveTax - promo` from the live cart. */
   cartTotal: number;
   originalReceiptTotal: number | null | undefined;
 }): number {
-  if (!input.isChangeFlow) {
-    return input.cartTotal;
-  }
   const rounded = roundMoney(input.cartTotal);
   if (input.originalReceiptTotal == null) {
     return input.cartTotal;
@@ -141,8 +191,87 @@ export function changeFlowBalanceVsOriginal(input: {
 }
 
 /**
- * Product: **What we show** in the change-flow price row — either the provider’s manual preview totals, or the same
- * cart numbers as everywhere else (no second shadow total).
+ * Maps a successful change-quote API payload to display subtotal/tax/total. Prefer server fields; fill gaps from
+ * `fallbackCart` only when the API omits breakdown (scaled to match server total when needed).
+ */
+export function serverTotalsFromChangeQuoteResponse(
+  quote: Pick<ChangeBookingQuoteResponse, 'newReceipt' | 'proposed' | 'newTotalCents'>,
+  fallbackCart: { total: number; subtotal: number; tax: number }
+): { total: number; subtotal: number; tax: number } | null {
+  const nr = quote.newReceipt;
+  const prop = quote.proposed;
+  const total =
+    nr?.total ??
+    prop?.total ??
+    (quote.newTotalCents != null ? quote.newTotalCents / 100 : undefined);
+  if (total == null || !Number.isFinite(total)) return null;
+
+  let subtotal = nr?.subtotal;
+  let tax = nr?.tax;
+  if (subtotal != null && tax == null) {
+    tax = Math.max(0, roundMoney(total - subtotal));
+  } else if (tax != null && subtotal == null) {
+    subtotal = Math.max(0, roundMoney(total - tax));
+  }
+  if (subtotal != null && tax != null) {
+    return {
+      total: roundMoney(total),
+      subtotal: roundMoney(subtotal),
+      tax: roundMoney(tax),
+    };
+  }
+
+  const fb = fallbackCart;
+  const absFb = Math.abs(fb.total);
+  if (absFb < 1e-6) {
+    return {
+      total: roundMoney(total),
+      subtotal: roundMoney(fb.subtotal),
+      tax: roundMoney(fb.tax),
+    };
+  }
+  const ratio = total / fb.total;
+  return {
+    total: roundMoney(total),
+    subtotal: roundMoney(fb.subtotal * ratio),
+    tax: roundMoney(fb.tax * ratio),
+  };
+}
+
+/** Shape merged into `latestChangeQuote` after each successful `quoteChangeBooking`. */
+export interface ChangeQuoteUiSlice {
+  priceDiff: number;
+  currency: string | undefined;
+  canProceed: boolean;
+  reasonIfBlocked?: string;
+  changeIntentId?: string;
+  quotedTotal?: number;
+  serverDisplay?: { total: number; subtotal: number; tax: number };
+}
+
+/** Single mapping from `ChangeBookingQuoteResponse` → UI state (avoids duplicating parse logic in effects vs checkout). */
+export function sliceChangeQuoteForUi(
+  quote: ChangeBookingQuoteResponse,
+  fallbackCart: { total: number; subtotal: number; tax: number },
+  currencyFallback: string
+): ChangeQuoteUiSlice {
+  const priceDiff =
+    quote.amountDueCents != null ? quote.amountDueCents / 100 : quote.priceDiff ?? 0;
+  const serverDisplay = serverTotalsFromChangeQuoteResponse(quote, fallbackCart);
+  return {
+    priceDiff,
+    currency: quote.currency ?? currencyFallback,
+    canProceed: quote.canProceed !== false,
+    reasonIfBlocked: quote.reasonIfBlocked,
+    changeIntentId: quote.changeIntentId,
+    quotedTotal: quote.proposed?.total ?? quote.newReceipt?.total,
+    ...(serverDisplay ? { serverDisplay } : {}),
+  };
+}
+
+/**
+ * Product: **What we show** in the change-flow price row — provider manual preview, then **server quote** (self-serve),
+ * then cart math.
  */
 export function resolveChangeFlowDisplayedAmounts(input: {
   providerPreview: {
@@ -150,6 +279,8 @@ export function resolveChangeFlowDisplayedAmounts(input: {
     subtotalBeforeTax: number;
     taxAmount: number;
   } | null;
+  /** Customer self-serve: authoritative breakdown from last successful `quoteChangeBooking`. */
+  serverQuotePreview?: { total: number; subtotal: number; tax: number } | null;
   fromCart: { total: number; subtotal: number; tax: number };
 }): { total: number; subtotal: number; tax: number } {
   if (input.providerPreview) {
@@ -159,6 +290,9 @@ export function resolveChangeFlowDisplayedAmounts(input: {
       tax: input.providerPreview.taxAmount,
     };
   }
+  if (input.serverQuotePreview) {
+    return { ...input.serverQuotePreview };
+  }
   return { ...input.fromCart };
 }
 

package/src/lib/booking-api.ts

@@ -860,12 +860,80 @@ export interface ChangeBookingQuoteReceipt {
   }>;
 }
 
+/** Optional structured drift when `clientProposedTotal` and server pricing disagree beyond tolerance. */
+export interface ChangeBookingQuotePricingDriftLine {
+  label: string;
+  clientAmountMajorUnits?: number | null;
+  serverAmountMajorUnits?: number | null;
+}
+
+export type ChangeBookingQuotePricingDriftReceiptLine = {
+  label?: string;
+  amount?: number;
+  type?: string;
+  quantity?: number;
+};
+
+export interface ChangeBookingQuotePricingDriftDetail {
+  /** Mirror of the client-sent proposed total (major units). */
+  clientTotalMajorUnits?: number;
+  /** Server-computed new-booking total from the price check (major units). */
+  serverTotalMajorUnits?: number;
+  /** Convenience: client − server (major units). */
+  deltaMajorUnits?: number;
+  /** Pre-built rows from the API — shown as-is when present. */
+  lineComparisons?: ChangeBookingQuotePricingDriftLine[];
+  /**
+   * Temporary / extended comparison: full server price-engine lines (receipt shape). When set, drift UI prefers these
+   * over `newReceipt.lineItems` for the Server column.
+   */
+  serverLineItems?: ChangeBookingQuotePricingDriftReceiptLine[];
+  /**
+   * Optional echo of client-side lines using the same shape as {@link serverLineItems} for apples-to-apples diff.
+   * When set, drift “In app” column uses this instead of the live FE checkout breakdown.
+   */
+  clientLineItems?: ChangeBookingQuotePricingDriftReceiptLine[];
+}
+
+/** BE ticket-line recipe for debugging drift vs FE change rules (optional on quote responses). */
+export interface ChangeBookingQuoteTicketLineTrace {
+  category: string;
+  /** CATALOG_NO_LOCKED | RULE_A_* | RULE_B_* | CROSS_PARENT_* — BE-defined. */
+  rule: string;
+  liveUnitMajorUnits: number;
+  lockedUnitMajorUnits?: number | null;
+  protectedQty: number;
+  incrementalQty: number;
+  catalogLineTotalMajorUnits: number;
+  ticketLineAmountMajorUnits: number;
+}
+
+export interface ChangeBookingQuoteTicketPricingTrace {
+  bookingParentProductId: string;
+  requestedParentProductId: string;
+  bookingOptionId: string;
+  requestedOptionId: string;
+  sameParentProduct: boolean;
+  unchangedItinerary: boolean;
+  lockedTicketUnitPriceByCategory?: Record<string, number>;
+  ticketLines: ChangeBookingQuoteTicketLineTrace[];
+}
+
 export interface ChangeBookingQuoteResponse {
   changeIntentId?: string;
   previousTotalCents?: number;
   newTotalCents?: number;
   amountDueCents?: number;
   expiresAt?: string;
+  /**
+   * Optional (customer change-quote UI): per-category ticket unit prices in **major units**, display currency.
+   * Uppercase keys preferred (ADULT, CHILD, …). Enables full self-serve preview without catalog math.
+   */
+  ticketUnitPriceByCategory?: Record<string, number>;
+  /** Optional: cancellation upgrade fee per policy id (major units, same currency as quote). */
+  cancellationPolicyFeeByPolicyId?: Record<string, number>;
+  /** Optional: per-person return add-on amount per `returnAvailabilityId` (major units). */
+  returnOptionPriceByReturnAvailabilityId?: Record<string, number>;
   original?: {
     total?: number;
     currency?: string;
@@ -882,6 +950,10 @@ export interface ChangeBookingQuoteResponse {
   currency?: string;
   canProceed?: boolean;
   reasonIfBlocked?: string;
+  /** When price check fails / disagrees: optional breakdown for UI line-vs-line comparison. */
+  pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
+  /** Optional BE debug: receipt-floor vs catalog ticket math (same-parent Rule A/B). */
+  ticketPricingTrace?: ChangeBookingQuoteTicketPricingTrace | null;
 }
 
 export interface CreateChangePaymentIntentResponse {