@ticketboothapp/booking 1.2.75 → 1.2.76

package/package.json

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

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -126,6 +126,9 @@ function mergeQuoteSliceWithServerPreview(
     serverPreview: buildChangeBookingServerPreview(quote, fallbackCart, currency),
     pricingDriftDetail: normalizePricingDriftDetailFromQuote(quote),
     ticketPricingTrace: normalizeTicketPricingTraceFromQuote(quote),
+    /** Same cent pair the BE uses for `amountDueCents` / intent & receipt "New Booking Difference" — use for signed refund display. */
+    quotePreviousTotalCents: quote.previousTotalCents,
+    quoteNewTotalCents: quote.newTotalCents,
   };
 }
 
@@ -852,9 +855,10 @@ export function AdminChangeBookingFlow({
   const lockedPromoCode = initialValues?.promoCode?.trim()
     ? initialValues.promoCode.trim().toUpperCase()
     : null;
-  /** Public self-serve only: cannot reduce tickets below original counts. */
+  /** Public self-serve only: cannot reduce tickets below original counts. Provider-dashboard admins may reduce party size. */
   const changeBookingMinimumQuantities = useMemo(() => {
     if (!isCustomerSelfServeChange || !initialValues?.bookingItems?.length) return undefined;
+    if (isAdmin && isProviderDashboardChange) return undefined;
     const m: Record<string, number> = {};
     for (const item of initialValues.bookingItems) {
       const key = item.category?.trim();
@@ -862,7 +866,7 @@ export function AdminChangeBookingFlow({
       m[key] = Math.max(0, Number(item.count) || 0);
     }
     return m;
-  }, [isCustomerSelfServeChange, initialValues?.bookingItems]);
+  }, [isCustomerSelfServeChange, initialValues?.bookingItems, isAdmin, isProviderDashboardChange]);
   const [adminChoiceData, setAdminChoiceData] = useState<{
     reservationReference: string;
     reservationExpiration?: string;
@@ -895,6 +899,9 @@ export function AdminChangeBookingFlow({
     quotedTotal?: number;
     /** From `quoteChangeBooking` receipt fields — drives PriceSummary when self-serve. */
     serverDisplay?: { total: number; subtotal: number; tax: number };
+    /** Server quote cents — authoritative vs `serverDisplay` scaling (aligns with receipt difference line). */
+    quotePreviousTotalCents?: number;
+    quoteNewTotalCents?: number;
     /** Parsed from last quote — unified server-owned preview for lines + picker overrides. */
     serverPreview: ReturnType<typeof buildChangeBookingServerPreview>;
     pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
@@ -3687,6 +3694,23 @@ export function AdminChangeBookingFlow({
     providerHasAdditionalAdjustments ||
     Math.abs(adminCustomAdjustmentTotal) >= 0.005;
 
+  /**
+   * True until `quoteChangeBooking` returns a confirmed `serverDisplay` for the current selection.
+   * Named so manual price-line UI can align with “still settling final price” without touching ticket/receipt math.
+   */
+  const changeFlowFinalPricePending =
+    suppressSelfServeCurrencyUi &&
+    selectedAvailability != null &&
+    totalQuantity > 0 &&
+    !selfServePricingConfirmed;
+
+  /**
+   * Provider inline edits + admin custom lines: show while waiting on or after the authoritative quote.
+   * UI-only gate — does not alter ticket line items or receipt-floor rules.
+   */
+  const showChangeFlowManualPriceLines =
+    changeFlowFinalPricePending || selfServePricingConfirmed;
+
   const displayedChangeAmountsRaw = resolveChangeFlowDisplayedAmounts({
     providerPreview: providerTotalsPreview,
     serverQuotePreview:
@@ -3713,25 +3737,112 @@ export function AdminChangeBookingFlow({
   );
   const displayChangeFlowTax = roundMoney(displayedChangeAmountsRaw.tax + adminTaxDeltaForExternalDisplay);
   const displayChangeFlowProposedTotal = roundMoney(
-    displayedChangeAmountsRaw.total + adminCustomAdjustmentTotal + adminTaxDeltaForExternalDisplay
+    displayLayerUsesExternalPricing
+      ? displayedChangeAmountsRaw.total + adminCustomAdjustmentTotal + adminTaxDeltaForExternalDisplay
+      : displayedChangeAmountsRaw.total
   );
 
   const changeFlowClientEstimateDue = (() => {
     if (!originalReceipt) return totalPrice;
-    // Customer self-serve: amount due comes from POST .../change/quote (`amountDueCents` / priceDiff), not FE delta math.
+    // Self-serve quote: match BE receipt / intent: (newTotalCents − previousTotalCents) / 100.
     if (isCustomerSelfServeChange && latestChangeQuote != null && !changeQuoteFetchError) {
+      const pq = latestChangeQuote.quotePreviousTotalCents;
+      const nq = latestChangeQuote.quoteNewTotalCents;
+      if (pq != null && nq != null) {
+        return normalizeNearZeroOwed(roundMoney((nq - pq) / 100));
+      }
+      if (latestChangeQuote.serverDisplay != null) {
+        return normalizeNearZeroOwed(
+          roundMoney(latestChangeQuote.serverDisplay.total - originalReceipt.total),
+        );
+      }
       return normalizeNearZeroOwed(latestChangeQuote.priceDiff);
     }
     return changeFlowBalanceVsOriginal({
       newTotal: displayChangeFlowProposedTotal,
       originalReceiptTotal: originalReceipt.total,
-      audience: isProviderDashboardChange ? 'provider' : 'customer',
+      audience: 'admin',
     });
   })();
 
   const changeFlowAmountDueRaw = changeFlowClientEstimateDue;
   const changeFlowAmountDue = normalizeNearZeroOwed(changeFlowAmountDueRaw);
 
+  const changeFlowAdminPricingDebugPanel = useMemo(() => {
+    if (!isAdmin || !selectedAvailability || totalQuantity <= 0) return null;
+    const fmt = (n: number) => formatCurrencyAmount(roundMoney(n), currency, locale as 'en' | 'fr');
+    const path = (() => {
+      if (!originalReceipt) return 'totalPrice (no original receipt)';
+      if (isCustomerSelfServeChange && latestChangeQuote != null && !changeQuoteFetchError) {
+        if (
+          latestChangeQuote.quotePreviousTotalCents != null &&
+          latestChangeQuote.quoteNewTotalCents != null
+        ) {
+          return 'POST /change/quote: (quoteNewTotalCents − quotePreviousTotalCents) / 100';
+        }
+        if (latestChangeQuote.serverDisplay != null) {
+          return 'POST /change/quote: serverDisplay.total − originalReceipt.total';
+        }
+        return 'POST /change/quote: priceDiff (API balance delta)';
+      }
+      return 'FE: displayChangeFlowProposedTotal − originalReceipt.total (signed; used when quote not driving amount-due)';
+    })();
+    const quoteTotalPreview =
+      latestChangeQuote?.serverDisplay != null ? fmt(latestChangeQuote.serverDisplay.total) : '—';
+    return (
+      <details className="mt-3 rounded-md border border-amber-200/80 bg-amber-50/50 p-2 text-left text-xs text-amber-950">
+        <summary className="cursor-pointer select-none font-medium text-stone-800">
+          Price calculation (admin debug)
+        </summary>
+        <pre className="mt-2 max-h-64 overflow-auto whitespace-pre-wrap break-words font-mono text-[11px] leading-relaxed text-stone-800">
+          {[
+            `Amount-due path: ${path}`,
+            `displayLayerUsesExternalPricing: ${String(displayLayerUsesExternalPricing)} (server/provider totals omit FE admin lines until overlaid)`,
+            `selfServePricingConfirmed: ${String(selfServePricingConfirmed)} · changeQuoteLoading: ${String(changeQuoteLoading)}`,
+            `Cart subtotal (excl. admin custom lines): ${fmt(effectiveSubtotal)}`,
+            `Admin custom lines (sum): ${fmt(adminCustomAdjustmentTotal)}`,
+            `Checkout subtotal (incl. admin lines): ${fmt(effectiveSubtotalForCheckout)}`,
+            `effectiveTax · promo discount: ${fmt(effectiveTax)} · ${fmt(effectivePromoDiscountAmount)}`,
+            `totalPrice (subtotal + tax − promo): ${fmt(totalPrice)}`,
+            `changeFlowNewBookingTotal (after cent reconcile vs receipt): ${fmt(changeFlowNewBookingTotal)}`,
+            `Displayed layer subtotal / tax / total: ${fmt(displayedChangeAmountsRaw.subtotal)} / ${fmt(displayedChangeAmountsRaw.tax)} / ${fmt(displayedChangeAmountsRaw.total)}`,
+            `displayChangeFlowProposedTotal (summary / preview footer): ${fmt(displayChangeFlowProposedTotal)}`,
+            originalReceipt ? `originalReceipt.total: ${fmt(originalReceipt.total)}` : 'originalReceipt: —',
+            `Quote serverDisplay.total (if any): ${quoteTotalPreview}`,
+            `changeFlowClientEstimateDue (before near-zero): ${fmt(changeFlowClientEstimateDue)}`,
+            `changeFlowAmountDue (PriceSummary total row): ${fmt(changeFlowAmountDue)}`,
+          ].join('\n')}
+        </pre>
+      </details>
+    );
+  }, [
+    isAdmin,
+    selectedAvailability,
+    totalQuantity,
+    currency,
+    locale,
+    originalReceipt,
+    isCustomerSelfServeChange,
+    latestChangeQuote,
+    changeQuoteFetchError,
+    displayLayerUsesExternalPricing,
+    selfServePricingConfirmed,
+    changeQuoteLoading,
+    effectiveSubtotal,
+    adminCustomAdjustmentTotal,
+    effectiveSubtotalForCheckout,
+    effectiveTax,
+    effectivePromoDiscountAmount,
+    totalPrice,
+    changeFlowNewBookingTotal,
+    displayedChangeAmountsRaw.subtotal,
+    displayedChangeAmountsRaw.tax,
+    displayedChangeAmountsRaw.total,
+    displayChangeFlowProposedTotal,
+    changeFlowClientEstimateDue,
+    changeFlowAmountDue,
+  ]);
+
   const changeCheckoutButtonLabel = (() => {
     if (!hasEffectiveChangeSelection) return undefined;
     if (isProviderDashboardChange) {
@@ -3759,7 +3870,9 @@ export function AdminChangeBookingFlow({
         const d = Math.round(changeFlowClientEstimateDue * 100) / 100;
         return d > 0
           ? `Change booking (${formatCurrencyAmount(d, currency, locale as 'en' | 'fr')})`
-          : 'Change booking (no charge)';
+          : d < 0
+            ? `Change booking (${formatCurrencyAmount(d, currency, locale as 'en' | 'fr')})`
+            : 'Change booking (no charge)';
       }
       const tr = t('booking.changeBooking');
       return tr !== 'booking.changeBooking' ? tr : 'Change booking';
@@ -3767,7 +3880,9 @@ export function AdminChangeBookingFlow({
     const est = Math.round(changeFlowClientEstimateDue * 100) / 100;
     return est > 0
       ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
-      : 'Change booking (no charge)';
+      : est < 0
+        ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
+        : 'Change booking (no charge)';
   })();
   /** Partner deferred-invoice path applies to {@link NewBookingFlow} only. */
   const deferredInvoiceSubmitLabel = undefined;
@@ -4611,30 +4726,41 @@ export function AdminChangeBookingFlow({
           quote.proposed?.total ??
           quote.newReceipt?.total ??
           changeFlowNewBookingTotal;
-        const feChangeDue = changeFlowBalanceVsOriginal({
-          newTotal: serverNewTotalForGuard,
-          originalReceiptTotal: originalReceipt?.total ?? 0,
-          audience: 'customer',
-        });
-        const serverAmountDue =
-          quote.amountDueCents != null
-            ? Math.max(0, quote.amountDueCents / 100)
-            : Math.max(0, quote.priceDiff ?? 0);
-        if (feChangeDue > 0.02 && serverAmountDue <= 0.009) {
+        /** Signed proposed − previous (major units). Matches quote slices when cents present; refund owed < 0. */
+        const signedBalanceMajor =
+          quote.previousTotalCents != null && quote.newTotalCents != null
+            ? (quote.newTotalCents - quote.previousTotalCents) / 100
+            : quote.balanceDeltaMajorUnits ?? null;
+        const chargeDue =
+          signedBalanceMajor != null
+            ? Math.max(0, signedBalanceMajor)
+            : quote.amountDueCents != null
+              ? quote.amountDueCents / 100
+              : Math.max(0, quote.priceDiff ?? 0);
+        const feChangeDue =
+          signedBalanceMajor ??
+          changeFlowBalanceVsOriginal({
+            newTotal: serverNewTotalForGuard,
+            originalReceiptTotal: originalReceipt?.total ?? 0,
+            audience: 'admin',
+          });
+        if (feChangeDue > 0.02 && chargeDue <= 0.009) {
           throw new Error(
             'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
           );
         }
-        // No-payment change: FE shows nothing owed — still require server agreement so we never confirm free when a charge is due.
-        if (serverAmountDue <= 0.009) {
+        // No additional charge (includes refund-owed / downgrade): confirm-free apply only when server agrees no payment due.
+        if (chargeDue <= 0.009) {
           if (feChangeDue > 0.02) {
             throw new Error(
               'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
             );
           }
-          const p = quote.proposed?.total ?? quote.newReceipt?.total;
-          const o = quote.original?.total ?? quote.originalReceipt?.total;
-          if (p != null && o != null && p - o > 0.01) {
+          const upgradeWithoutCharge =
+            quote.newTotalCents != null &&
+            quote.previousTotalCents != null &&
+            quote.newTotalCents > quote.previousTotalCents + 1;
+          if (upgradeWithoutCharge) {
             throw new Error(
               'This change requires payment, but the price could not be confirmed. Please refresh and try again.'
             );
@@ -4686,11 +4812,14 @@ export function AdminChangeBookingFlow({
       // Backend will charge totalAmount and store this as the receipt so /manage matches.
       const taxForBreakdown = effectivePromoDiscountAmount > 0 ? effectiveTax : tax;
       const amountDueForCheckout = isCustomerSelfServeChange
-        ? changeFlowBalanceVsOriginal({
-            newTotal: changeFlowNewBookingTotal,
-            originalReceiptTotal: originalReceipt?.total ?? 0,
-            audience: 'customer',
-          })
+        ? Math.max(
+            0,
+            changeFlowBalanceVsOriginal({
+              newTotal: changeFlowNewBookingTotal,
+              originalReceiptTotal: originalReceipt?.total ?? 0,
+              audience: 'admin',
+            }),
+          )
         : totalPrice;
       const lines = [
         ...ticketLineItemsForChangeFlowDisplay.map((line) => ({
@@ -5406,10 +5535,12 @@ export function AdminChangeBookingFlow({
                 replacePriceSummary={selfServeCheckoutPlaceholder}
                 totalPrice={changeFlowAmountDue}
                 totalSummaryLabel={
-                  t('booking.totalOwedForBookingChange') &&
-                  t('booking.totalOwedForBookingChange') !== 'booking.totalOwedForBookingChange'
-                    ? t('booking.totalOwedForBookingChange')
-                    : 'Total owed for booking difference'
+                  changeFlowAmountDue < -0.005
+                    ? 'Refund owed (vs original booking)'
+                    : t('booking.totalOwedForBookingChange') &&
+                        t('booking.totalOwedForBookingChange') !== 'booking.totalOwedForBookingChange'
+                      ? t('booking.totalOwedForBookingChange')
+                      : 'Total owed for booking difference'
                 }
                 subtotal={displayChangeFlowSubtotal}
                 taxAmount={
@@ -5438,9 +5569,11 @@ export function AdminChangeBookingFlow({
                     !providerPricingUi.error ? (
                       <div className="mt-2 text-xs text-stone-500">{providerPricingUi.helperText}</div>
                     ) : null}
+                    {changeFlowAdminPricingDebugPanel}
                   </>
                 }
                 extraBeforeSubtotal={
+                  showChangeFlowManualPriceLines ? (
                   <>
                     {showProviderPricingInlineEditor && (providerPricingUi?.additionalAdjustments?.length ?? 0) > 0 ? (
                       <div className="space-y-1">
@@ -5623,6 +5756,7 @@ export function AdminChangeBookingFlow({
                       })}
                     </div>
                   </>
+                  ) : null
                 }
                 firstName={firstName}
                 lastName={lastName}

package/src/components/booking/CheckoutForm.tsx

@@ -146,6 +146,7 @@ export function CheckoutForm({
       <div className={styles.summaryWrapper}>
         {replacePriceSummary ? (
           <>
+            {extraBeforeSubtotal ? <div className="mb-4 min-w-0">{extraBeforeSubtotal}</div> : null}
             {replacePriceSummary}
             <div className="mt-4">{extraBetweenTaxAndTotal}</div>
           </>

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

@@ -178,16 +178,16 @@ export function resolveChangeFlowNewBookingTotal(input: {
 
 /**
  * Product: **What the customer owes** for the difference is `max(0, newTotal − oldReceipt)`.
- * **Provider dashboard** may show a signed delta (credits/refunds as negative).
+ * **Provider dashboard** and **admin change booking** may show a signed delta (refund owed as negative).
  */
 export function changeFlowBalanceVsOriginal(input: {
   newTotal: number;
   originalReceiptTotal: number;
-  /** `customer` = self-serve & admin change; `provider` = provider inline editor (can owe the guest). */
-  audience: 'customer' | 'provider';
+  /** `customer` = self-serve change only; `provider` | `admin` = signed newTotal − original receipt total. */
+  audience: 'customer' | 'provider' | 'admin';
 }): number {
   const delta = input.newTotal - input.originalReceiptTotal;
-  return input.audience === 'provider' ? delta : Math.max(0, delta);
+  return input.audience === 'customer' ? Math.max(0, delta) : delta;
 }
 
 /**
@@ -255,8 +255,13 @@ export function sliceChangeQuoteForUi(
   fallbackCart: { total: number; subtotal: number; tax: number },
   currencyFallback: string
 ): ChangeQuoteUiSlice {
+  /** Staff JWT on quote: signed new − previous (refund owed negative). Otherwise same as legacy nonnegative amount-due. */
   const priceDiff =
-    quote.amountDueCents != null ? quote.amountDueCents / 100 : quote.priceDiff ?? 0;
+    quote.balanceDeltaMajorUnits != null
+      ? quote.balanceDeltaMajorUnits
+      : quote.amountDueCents != null
+        ? quote.amountDueCents / 100
+        : quote.priceDiff ?? 0;
   const serverDisplay = serverTotalsFromChangeQuoteResponse(quote, fallbackCart);
   return {
     priceDiff,

package/src/lib/booking-api.ts

@@ -987,6 +987,11 @@ export interface ChangeBookingQuoteResponse {
   originalReceipt?: ChangeBookingQuoteReceipt;
   newReceipt?: ChangeBookingQuoteReceipt;
   priceDiff: number;
+  /**
+   * Present when the quote was requested with a **staff** JWT: signed (new total − previous receipt total) in major units.
+   * Negative = refund owed to the guest. Omitted for unauthenticated / customer-only quotes.
+   */
+  balanceDeltaMajorUnits?: number;
   currency?: string;
   canProceed?: boolean;
   reasonIfBlocked?: string;