@ticketboothapp/booking 1.2.61 → 1.2.63

package/CHANGE_BOOKING_BE_HANDOFF.md

@@ -0,0 +1,86 @@
+# Backend handoff: customer change-booking quote (full UI preview)
+
+This document describes what the **booking API** should return so the website’s customer **self-serve change flow** can show **server-authored** dollar amounts in checkout lines and optional picker overrides.
+
+Existing endpoint (names may vary in your stack): **`POST …/change/quote`** — response type `ChangeBookingQuoteResponse` in `@ticketboothapp/booking` / shared client types.
+
+## Already required for “totals confirmed” UI
+
+The frontend treats pricing as confirmed when the quote includes receipt-style totals (via `newReceipt` / `proposed` / `newTotalCents`, etc.) and `amountDueCents` or `priceDiff` for the amount owed. That unlocks subtotal/tax/total rows and replaces the pre-quote placeholder block.
+
+## Ticket pricing on change (authoritative product rules)
+
+These rules apply when changing an existing booking for the **same parent catalog product** (self-serve). Use **booking snapshot + original receipt** to know what was sold; use **live catalog** for the **currently selected** departure date and product option.
+
+### Inputs (per ticket category `y`)
+
+| Symbol | Meaning |
+| --- | --- |
+| `x_y` | Original booked count for category `y` on the **original** booking (protected headcount cap). |
+| `lockedUnit_y` | Unit price those tickets were sold at (from receipt / booking line items), major currency units. |
+| `liveUnit_y` | Live catalog unit for category `y` at the **currently selected** departure date + product option (+ availability slot as modeled). |
+| `q_y` | Current quantity selected in the change UI for category `y`. |
+
+Define:
+
+- `protected_y = min(q_y, x_y)` — seats that correspond to **original** tickets still present.
+- `incremental_y = max(0, q_y - x_y)` — **new** seats added in this change session.
+
+Define **unchanged itinerary** as: selected departure **date** equals the original booking’s date **and** selected **product option** equals the original booking’s product option (same IDs / same comparison rules you use elsewhere for “same PO”).
+
+### Rule A — unchanged itinerary (same date **and** same product option)
+
+For each category `y`:
+
+- **`protected_y` seats:** unit price is **`lockedUnit_y` exactly** — no adjustment up or down based on today’s catalog. Catalog price changes **do not** move those seats.
+- **`incremental_y` seats:** unit price is **`liveUnit_y`** (live catalog for the current selection).
+
+Adding passengers or changing **return** does **not** re-price those protected seats; only net-new seats follow live catalog. **Return add-ons** keep the separate return-floor behavior already agreed (per-person floor from what was paid; incremental passengers pay live return pricing where applicable).
+
+### Rule B — itinerary changed (date changed **or** product option changed)
+
+For each category `y`:
+
+- **`protected_y` seats:** unit price is **`max(lockedUnit_y, liveUnit_y)`** — they never go **below** what they paid (**floor**), but they **may go up** if the new date or option prices higher.
+- **`incremental_y` seats:** unit price is **`liveUnit_y`**.
+
+### Fees
+
+Fee lines should follow the **same structural split** as tickets (protected vs incremental headcount). Align fee formulas with whatever you implement alongside these ticket rules.
+
+### Backend / reconciliation
+
+`POST …/change/quote` should compute ticket line totals with **Rule A vs Rule B** from **server-held booking state + selected date/PO + live catalog**, not from trusting the browser alone. **`clientProposedTotal`** remains a cross-check when the client sends it.
+
+### Current website package (FYI)
+
+The `@ticketboothapp/booking` change flow implements Rule **A** vs **B** for ticket and config-fee lines when self‑serve receipt pricing applies (same parent product): **exact** receipt units on protected seats/fees when calendar date **and** product option match the booking; otherwise **`max(locked, live)`** for protected headcount.
+
+---
+
+## Recommended fields for server-owned detail
+
+Pickers show **catalog** prices by default (same booking **currency** as the original receipt — the change UI does not switch currency). These optional fields **override** display when present on the quote:
+
+1. **`ticketUnitPriceByCategory`** — `Record<string, number>`  
+   - Keys: ticket categories (`ADULT`, `CHILD`, …), uppercase preferred.  
+   - Values: **unit price in major units** (e.g. dollars), display currency.  
+   - When present, these update ticket **picker** display units on self‑serve change; totals must still follow **Rule A / Rule B** above unless the quote fully replaces breakdown.
+
+2. **Line items** — `newReceipt.lineItems` or `proposed.lineItems` (fallback `original`)  
+   - Shape: `{ label?, amount?, type?, quantity? }`.  
+   - Mapped to checkout **`PriceSummary`** rows when present; otherwise checkout falls back to FE-built lines after totals confirm.
+
+### Additional optional maps
+
+| Field | Purpose |
+| --- | --- |
+| **`returnOptionPriceByReturnAvailabilityId`** | `Record<returnAvailabilityId, number>` — **per-person** return add-on in major units; overrides catalog return card amounts for matching ids. The FE still **floors** per-person return at what was paid on the original receipt when applicable — values below that floor are raised client-side. |
+| **`cancellationPolicyFeeByPolicyId`** | Optional passthrough on the quote type / `serverPreview` for future use or tooling. **Not used** to drive cancellation UI in change flow today — cancellation policy is **fixed** to the existing booking; there is no policy picker. |
+
+## Notes for implementers
+
+- **`clientProposedTotal`** (existing): FE still sends this as a hint for reconciliation; display should follow **quote response**, not the client-only cart.  
+- **Currency**: align optional maps and line `amount` values with `currency` / receipt currency; change booking stays in the booking’s sold currency end-to-end on FE.  
+- **Cancellation policy on change**: FE sends the booked policy on reserve/confirm paths; it is **not** chosen from product config during change — preserve the booking’s policy server-side unless product rules say otherwise.  
+- **`serverPreview.completeness`**: the package sets this to **`full`** whenever a preview is built (informational); UI does not gate on `totals_only` vs `full`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticketboothapp/booking",
-  "version": "1.2.61",
+  "version": "1.2.63",
   "private": false,
   "sideEffects": [
     "**/*.css",

package/src/components/booking/AddOnsSection.tsx

@@ -15,6 +15,7 @@ interface AddOnsSectionProps {
   locale: string;
   onSelectionsChange: (selections: AddOnSelection[] | ((prev: AddOnSelection[]) => AddOnSelection[])) => void;
   minimumTotalByAddOnId?: Map<string, number>;
+  suppressPrices?: boolean;
 }
 
 export function AddOnsSection({
@@ -24,6 +25,7 @@ export function AddOnsSection({
   locale,
   onSelectionsChange,
   minimumTotalByAddOnId,
+  suppressPrices = false,
 }: AddOnsSectionProps) {
   return (
     <div className="border-t border-stone-200 pt-6 space-y-4">
@@ -60,7 +62,7 @@ export function AddOnsSection({
                   {isSelected ? `Yes, add ${addOn.name}` : `No ${addOn.name}`}
                 </span>
                 <span className="text-sm font-semibold text-stone-700">
-                  +{formatCurrencyAmount(addOn.price ?? 0, currency, locale as 'en' | 'fr')}
+                  {suppressPrices ? '—' : `+${formatCurrencyAmount(addOn.price ?? 0, currency, locale as 'en' | 'fr')}`}
                 </span>
               </button>
             </div>
@@ -77,6 +79,7 @@ export function AddOnsSection({
                 currency={currency}
                 locale={locale as 'en' | 'fr'}
                 minimumTotal={minTotalForAddOn}
+                suppressPrices={suppressPrices}
               />
             );
           }
@@ -128,7 +131,7 @@ export function AddOnsSection({
                           +
                         </button>
                         <span className="text-sm font-medium text-stone-700 w-16 text-right">
-                          {formatCurrencyAmount(price, currency, locale as 'en' | 'fr')} ea
+                          {suppressPrices ? '—' : `${formatCurrencyAmount(price, currency, locale as 'en' | 'fr')} ea`}
                         </span>
                       </div>
                     </div>
@@ -168,7 +171,7 @@ export function AddOnsSection({
                     >
                       <span className="text-sm font-medium text-stone-800">{variant.label}</span>
                       <span className="text-sm font-semibold text-stone-700">
-                        +{formatCurrencyAmount(price, currency, locale as 'en' | 'fr')}
+                        {suppressPrices ? '—' : `+${formatCurrencyAmount(price, currency, locale as 'en' | 'fr')}`}
                       </span>
                     </button>
                   );