@ticketboothapp/booking 1.2.188 → 1.2.190

package/CHANGE_BOOKING_BE_HANDOFF.md

@@ -1,160 +0,0 @@
-# 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.
-
-## Current Pricing V2 alignment
-
-As of 2026-07-05, the frontend types and visible change-booking preview helpers consume the broader Pricing V2 quote snapshot shape used by the backend:
-
-- `pricingQuote` / `quote` may carry `PricingQuote`-style fields such as `grossSubtotal`, `discountTotal`, `paymentCreditTotal`, `netSubtotalBeforeTax`, `taxAmount`, `payableTotal`, `balanceDelta`, `amountToCharge`, `refundCandidate`, `lines`, `oldReceiptHash`, and `status`.
-- Display helpers prefer server-authored V2 totals and canonical `PricingQuote.lines` when present, then fall back to the existing `newReceipt`, `proposed`, and cent fields.
-- Gift-card credit is treated as `paymentCreditTotal` / payment credit in UI copy, not as a discount total. If a quote reports `paymentCreditTotal` without an explicit credit line, the package adds a display-only payment-credit row.
-- Change-booking amount-due/refund display prefers `balanceDelta`, `amountToCharge`, and `refundCandidate` from the canonical quote before legacy `amountDueCents` / `priceDiff`.
-- Public self-serve and admin/provider change flows clear stale quote totals while changed selections are being re-quoted and use canonical quote charge/refund fields for final payment/free-confirm guards.
-
-## 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** — `pricingQuote.lines` / `quote.lines`, then `newReceipt.lineItems` or `proposed.lineItems` (fallback `original`)
-   - Pricing V2 shape: `{ lineId?, label?, amount?, quantity?, type?, billable?, taxBehavior?, discountBehavior?, source?, metadata? }`.
-   - Legacy receipt shape: `{ label?, amount?, type?, quantity? }`.
-   - Mapped to checkout **`PriceSummary`** rows when present; non-billable Pricing V2 lines are omitted from the primary payable summary. 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`** when mapped quote lines are available and **`totals_only`** when only totals are available. UI does not gate progression on this field.
-
----
-
-## Admin / provider manual line items (signed adjustments)
-
-**Frontend (this package):** `AdminChangeBookingFlow` lets staff add custom receipt lines (label + signed amount). The same values are:
-
-1. **`POST …/change/quote`** — optional request field **`manualLineAdjustments`**: `Array<{ label: string; amount: number }>` in **major units** (same currency as the booking). Amounts are signed (credits negative). Omitted when there are no custom lines.
-2. **Provider apply** — `onChangeBooking` payload field **`pricingAdjustment`**, with **`mode: 'MANUAL_LINES'`** and **`additionalAdjustments`** equal to the **provider** inline editor rows **plus** these admin custom lines (concatenated). `newTotalAmount` remains the full proposed total (already includes those lines on the client).
-
-**Backend expectations**
-
-- **Quote:** When `manualLineAdjustments` is present, add each line to the server’s priced subtotal (before tax) for the change intent, and return quote totals / `amountDue` / line items that **include** these rows so the UI and `clientProposedTotal` stay in tolerance.
-- **Provider change API:** When `pricingAdjustment.additionalAdjustments` includes the same rows, persist them on the new receipt and charge the **same** total as `newTotalAmount` (within your rounding rules).
-
-If the server ignores `manualLineAdjustments` or `additionalAdjustments`, the customer will see the FE total but pay a different amount.
-
----
-
-## Admin FE-authoritative quote path (new)
-
-For provider dashboard / admin tooling, we need a dedicated quote route where the **frontend is authoritative** for
-the full receipt preview (totals + line items), and BE does not re-price those values.
-
-### Endpoint
-
-- **`POST /1/admin/bookings/:bookingReference/change/quote?lastName=...`**
-
-Keep the public self-serve endpoint unchanged.
-
-### Request contract (admin)
-
-Same selection fields as `ChangeBookingQuoteRequest`, plus:
-
-- `feReceipt`:
-  - `subtotal` (major units)
-  - `tax` (major units)
-  - `total` (major units)
-  - `currency?`
-  - `lineItems: Array<{ label?: string; amount?: number; type?: string; quantity?: number }>`
-- `feAmountDueMajorUnits?` (optional signed delta the FE displays; `newTotal - previousTotal`)
-
-For admin/provider cross-product changes, FE also sends:
-
-- `newParentProductId`: destination parent catalog product id (`p_...`)
-- `newProductId`: destination product option id selected from availability (`po_...` or equivalent), preserved for existing quote/apply compatibility
-
-BE should persist both the destination parent product and selected option when applying the change. Capacity checks,
-receipt pricing, add-ons, pickup locations, and itinerary display should resolve against `newParentProductId` +
-`newProductId`, not the booking’s original product. Same-parent receipt-floor rules continue only when the booking
-parent product equals `newParentProductId`; cross-parent changes should price from the destination catalog / FE
-authoritative admin receipt path.
-
-### Backend expectations
-
-- Validate admin auth + booking/availability eligibility only.
-- Persist `feReceipt` on the change intent as the quote source-of-truth.
-- Return a `ChangeBookingQuoteResponse`-compatible payload using the stored FE receipt:
-  - `newReceipt` / `proposed` line items from `feReceipt.lineItems`
-  - `newReceipt.subtotal/tax/total` from `feReceipt`
-  - `amountDueCents` / `balanceDeltaMajorUnits` / `priceDiff` coherent with stored totals
-  - `changeIntentId`, `canProceed`, `reasonIfBlocked`
-- Payment intent + apply/confirm for this change intent must use persisted FE totals/lines (no repricing).