@ticketboothapp/booking 1.2.153 → 1.2.155

package/package.json

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

package/src/components/booking/AdminChangeBookingFlow.tsx

@@ -56,7 +56,10 @@ import { useAdminChangeProductReset } from './useAdminChangeProductReset';
 import { useBookingQuantityCapTrim } from './useBookingQuantityCapTrim';
 import { useBookingViewItemAnalytics } from './useBookingViewItemAnalytics';
 import { buildAdminChangeQuoteRequestKey } from './admin-change-quote-request-key';
-import type { AdminReleaseRefundDisposition } from './admin-refund-disposition';
+import {
+  buildDefaultRefundDispositionsByOperationId,
+  type AdminReleaseRefundDisposition,
+} from './admin-refund-disposition';
 
 type AdminRefundDecisionContext = {
   selectionKey: string;
@@ -730,6 +733,39 @@ export function AdminChangeBookingFlow({
     : refundDecisionContext?.selectionKey === refundDecisionSelectionKey
       ? refundDecisionContext
       : null;
+  /** Seed a disposition once per booking-selection key; operator can still override the dropdown. */
+  const refundDispositionAutoDefaultKeyRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!activeRefundDecisionContext || activeRefundDecisionContext.operations.length === 0) return;
+    if (refundDispositionAutoDefaultKeyRef.current === activeRefundDecisionContext.selectionKey) {
+      return;
+    }
+    refundDispositionAutoDefaultKeyRef.current = activeRefundDecisionContext.selectionKey;
+
+    const sameProductAndOutboundSelection =
+      !changeSelectionDetails.dateChanged &&
+      !changeSelectionDetails.productChanged &&
+      !changeSelectionDetails.optionChanged &&
+      !changeSelectionDetails.countsChanged &&
+      !changeSelectionDetails.addOnsChanged;
+    const defaults = buildDefaultRefundDispositionsByOperationId({
+      operations: activeRefundDecisionContext.operations,
+      allowedByOperationId: activeRefundDecisionContext.allowedByOperationId,
+      sameProductAndOutboundSelection,
+    });
+    if (Object.keys(defaults).length === 0) return;
+
+    setRefundDispositionsByOperationId((current) => {
+      let changed = false;
+      const next = { ...current };
+      for (const [operationId, disposition] of Object.entries(defaults)) {
+        if (next[operationId] != null) continue;
+        next[operationId] = disposition;
+        changed = true;
+      }
+      return changed ? next : current;
+    });
+  }, [activeRefundDecisionContext, changeSelectionDetails]);
   const activeRefundDispositionsByOperationId = useMemo(() => Object.fromEntries(
     (activeRefundDecisionContext?.operations ?? []).flatMap((operation) => {
       const disposition = refundDispositionsByOperationId[operation.operationId];
@@ -1058,7 +1094,11 @@ export function AdminChangeBookingFlow({
         serverAmendmentLines: latestChangeQuote?.serverPreview?.priceSummaryLines ?? null,
         serverAmountDue: latestChangeQuote?.serverPreview?.amountDue ?? null,
         serverUpdatedTotal: latestChangeQuote?.serverPreview?.totalNewBooking ?? null,
-        serverQuoteError: changeQuoteFetchError,
+        serverQuoteError:
+          changeQuoteFetchError ??
+          (isChangeQuoteBlocked
+            ? (latestChangeQuote?.reasonIfBlocked ?? 'This change cannot be priced right now.')
+            : null),
         refundDecisionOperations: activeRefundDecisionContext?.operations ?? [],
         allowedRefundDispositionsByOperationId:
           activeRefundDecisionContext?.allowedByOperationId ?? {},

package/src/components/booking/AdminChangeReceiptComparison.tsx

@@ -155,7 +155,7 @@ export function AdminChangeReceiptComparison({
           <div className="mb-3">
             <h3 className="text-sm font-semibold text-stone-900">Choose refund treatment</h3>
             <p className="mt-1 text-xs text-stone-600">
-              Removed paid value is never refunded automatically. Choose an explicit treatment, then the server will recalculate the settlement.
+              Removed paid value is never refunded automatically. Choose an explicit treatment (return-only changes default to no refund), then the server will recalculate the settlement.
             </p>
           </div>
           <div className="space-y-3">

package/src/components/booking/admin-refund-disposition.ts

@@ -27,6 +27,9 @@ const RELEASE_OPTIONS: AdminRefundDispositionOption[] = [
   },
 ];
 
+/** Server ops whose removed value is only a return-time substitution. */
+const RETURN_ONLY_REFUND_OPERATION_TYPES = new Set(['CHANGE_RETURN']);
+
 export function releaseRefundDispositionOptions(
   allowed: readonly AdminAmendmentRefundDisposition[] | undefined,
 ): AdminRefundDispositionOption[] {
@@ -34,6 +37,59 @@ export function releaseRefundDispositionOptions(
   return RELEASE_OPTIONS.filter((option) => allowed.includes(option.value));
 }
 
+/**
+ * True when every refund-decision operation is a return substitution.
+ * Combined with an unchanged product/outbound selection, this is the common
+ * "cheaper/later return" admin case that should default to no refund.
+ */
+export function isReturnOnlyRefundDecision(
+  operations: readonly AdminAmendmentOperationSnapshot[],
+): boolean {
+  return (
+    operations.length > 0 &&
+    operations.every((operation) => RETURN_ONLY_REFUND_OPERATION_TYPES.has(operation.type))
+  );
+}
+
+/**
+ * Only auto-default the low-stakes return-only case (same product/outbound → NO_REFUND).
+ * Other removals stay undecided so the operator must choose explicitly.
+ */
+export function preferredAdminRefundDisposition(args: {
+  operations: readonly AdminAmendmentOperationSnapshot[];
+  /** Same parent product, option, date/time, passengers, and add-ons — only return differs. */
+  sameProductAndOutboundSelection: boolean;
+  allowed?: readonly AdminAmendmentRefundDisposition[];
+}): AdminReleaseRefundDisposition | null {
+  if (
+    !args.sameProductAndOutboundSelection ||
+    !isReturnOnlyRefundDecision(args.operations)
+  ) {
+    return null;
+  }
+  const options = releaseRefundDispositionOptions(args.allowed);
+  return options.some((option) => option.value === 'NO_REFUND') ? 'NO_REFUND' : null;
+}
+
+export function buildDefaultRefundDispositionsByOperationId(args: {
+  operations: readonly AdminAmendmentOperationSnapshot[];
+  allowedByOperationId?: Readonly<
+    Record<string, readonly AdminAmendmentRefundDisposition[] | undefined>
+  >;
+  sameProductAndOutboundSelection: boolean;
+}): Record<string, AdminReleaseRefundDisposition> {
+  return Object.fromEntries(
+    args.operations.flatMap((operation) => {
+      const disposition = preferredAdminRefundDisposition({
+        operations: args.operations,
+        sameProductAndOutboundSelection: args.sameProductAndOutboundSelection,
+        allowed: args.allowedByOperationId?.[operation.operationId],
+      });
+      return disposition ? [[operation.operationId, disposition] as const] : [];
+    }),
+  );
+}
+
 export function adminRemovalOperationLabel(operation: AdminAmendmentOperationSnapshot): string {
   const component = operation.componentKey.split(':').slice(1).join(':') || operation.componentKey;
   const quantity = operation.quantityDelta ? ` (${Math.abs(operation.quantityDelta)})` : '';

package/src/components/booking/useAdminChangeQuotePreview.ts

@@ -153,7 +153,9 @@ export function useAdminChangeQuotePreview({
     !!initialValues?.bookingReference?.trim() &&
     !!lastName.trim();
 
-  const isChangeQuoteBlocked = isCustomerSelfServeChange && latestChangeQuote?.canProceed === false;
+  const isChangeQuoteBlocked =
+    latestChangeQuote?.canProceed === false &&
+    (latestChangeQuote.refundDecisionOperations?.length ?? 0) === 0;
   const refundDecisionRequired = (latestChangeQuote?.refundDecisionOperations?.length ?? 0) > 0;
   const changeQuoteInputsKey = useMemo(() => buildAdminChangeQuoteRequestKey({
     bookingReference: initialValues?.bookingReference,
@@ -192,11 +194,19 @@ export function useAdminChangeQuotePreview({
   const changeCheckoutButtonLabel = (() => {
     if (!hasEffectiveChangeSelection) return undefined;
     if (isProviderDashboardChange) {
-      const est = Math.round(changeFlowClientEstimateDue * 100) / 100;
-      return est > 0
-        ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
-        : est < 0
-          ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
+      if (isChangeQuoteBlocked) {
+        const tr = t('booking.changeBookingNotAvailable');
+        return tr !== 'booking.changeBookingNotAvailable' ? tr : 'Change not available';
+      }
+      // Prefer authoritative V2 signed due (charge positive / refund negative). Do not use the
+      // FE cart estimate once a server quote exists — receipt total deltas can disagree with
+      // floored/settlement amounts (DEFECT-PV2-018 follow-up).
+      const serverDue = latestChangeQuote?.serverPreview?.amountDue;
+      const due = Math.round((serverDue ?? changeFlowClientEstimateDue) * 100) / 100;
+      return due > 0
+        ? `Change booking (${formatCurrencyAmount(due, currency, locale as 'en' | 'fr')})`
+        : due < 0
+          ? `Change booking (${formatCurrencyAmount(due, currency, locale as 'en' | 'fr')})`
           : 'Change booking (no charge)';
     }
     if (changeFlowNeedsServerPrice) {
@@ -234,10 +244,10 @@ export function useAdminChangeQuotePreview({
   const checkoutFormError =
     (error || '') ||
     (missingRequiredReturnSelection ? 'Please select a return time for this product.' : '') ||
-    (isCustomerSelfServeChange && isChangeQuoteBlocked && !refundDecisionRequired
-      ? (latestChangeQuote?.reasonIfBlocked ?? '')
+    (isChangeQuoteBlocked && !refundDecisionRequired
+      ? (latestChangeQuote?.reasonIfBlocked ?? 'This change cannot be priced right now.')
       : '') ||
-    (isCustomerSelfServeChange ? changeQuoteFetchError ?? '' : '');
+    (changeQuoteFetchError ?? '');
 
   const changeFlowSelectionPreview = useMemo((): ChangeFlowSelectionPreview | null => {
     if (!selectedAvailability || totalQuantity <= 0) return null;

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

@@ -251,12 +251,14 @@ export function mapQuoteLineItemsToPriceSummaryLines(
 
 function signedAmountDueFromQuote(quote: ChangeBookingQuoteResponse): number {
   const pricingQuote = quote.pricingQuote ?? quote.quote;
-  if (quote.balanceDeltaMajorUnits != null) return quote.balanceDeltaMajorUnits;
-  if (quote.balanceDelta != null) return quote.balanceDelta;
-  if (pricingQuote?.balanceDelta != null) return pricingQuote.balanceDelta;
+  // Prefer explicit settlement fields over balanceDelta. Receipt-total math and balanceDelta
+  // can disagree with charge/refund when value is removed but not yet dispositioned.
   const charge = pricingQuote?.amountToCharge ?? quote.amountToCharge;
   const refund = pricingQuote?.refundCandidate ?? quote.refundCandidate;
   if (charge != null || refund != null) return (charge ?? 0) - (refund ?? 0);
+  if (quote.balanceDeltaMajorUnits != null) return quote.balanceDeltaMajorUnits;
+  if (quote.balanceDelta != null) return quote.balanceDelta;
+  if (pricingQuote?.balanceDelta != null) return pricingQuote.balanceDelta;
   if (quote.amountDueCents != null) return quote.amountDueCents / 100;
   return quote.priceDiff ?? 0;
 }

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

@@ -271,12 +271,14 @@ export function sliceChangeQuoteForUi(
   const pricingQuote = quote.pricingQuote ?? quote.quote;
   /** Staff JWT on quote: signed new − previous (refund owed negative). Otherwise same as legacy nonnegative amount-due. */
   const priceDiff = (() => {
+    const charge = quote.amountToCharge ?? pricingQuote?.amountToCharge;
+    const refund = quote.refundCandidate ?? pricingQuote?.refundCandidate;
+    if (charge != null || refund != null) {
+      return (charge ?? 0) - (refund ?? 0);
+    }
     if (quote.balanceDeltaMajorUnits != null) return quote.balanceDeltaMajorUnits;
     if (quote.balanceDelta != null) return quote.balanceDelta;
     if (pricingQuote?.balanceDelta != null) return pricingQuote.balanceDelta;
-    if (quote.amountToCharge != null || quote.refundCandidate != null) {
-      return (quote.amountToCharge ?? 0) - (quote.refundCandidate ?? 0);
-    }
     if (quote.amountDueCents != null) return quote.amountDueCents / 100;
     return quote.priceDiff ?? 0;
   })();

package/src/lib/booking-api.ts

@@ -1291,7 +1291,11 @@ export interface ChangeBookingQuoteRequest {
     previousAvailabilityId?: string | null;
     previousReturnAvailabilityId?: string | null;
   } | null;
-  /** Explicit admin treatment for server-classified removed paid value. Never defaulted by the client. */
+  /**
+   * Explicit admin treatment for server-classified removed paid value.
+   * The dashboard may pre-select NO_REFUND for return-only changes (still overridable);
+   * other removals stay undecided until chosen. The value is always sent explicitly on quote/apply.
+   */
   refundDispositionsByOperationId?: Record<string, AdminAmendmentRefundDisposition>;
 }
 

package/test/change-booking-helpers.test.ts

@@ -15,7 +15,10 @@ import {
 } from '../src/lib/booking-api';
 import { buildAdminChangeQuoteRequestKey } from '../src/components/booking/admin-change-quote-request-key';
 import {
+  buildDefaultRefundDispositionsByOperationId,
+  isReturnOnlyRefundDecision,
   noRefundRemovedValue,
+  preferredAdminRefundDisposition,
   refundDecisionsComplete,
   releaseRefundDispositionOptions,
 } from '../src/components/booking/admin-refund-disposition';
@@ -186,6 +189,64 @@ test('admin removal quote preserves explicit release refund decisions for the pr
   );
 });
 
+test('admin refund disposition defaults only for return-only → no refund', () => {
+  const changeReturn = {
+    operationId: 'op_change_return',
+    type: 'CHANGE_RETURN',
+    componentKey: 'return',
+  };
+  const removeAdult = {
+    operationId: 'op_remove_adult',
+    type: 'REMOVE_QUANTITY',
+    componentKey: 'ticket:ADULT',
+    quantityDelta: -1,
+  };
+
+  assert.equal(isReturnOnlyRefundDecision([changeReturn]), true);
+  assert.equal(isReturnOnlyRefundDecision([changeReturn, removeAdult]), false);
+  assert.equal(
+    preferredAdminRefundDisposition({
+      operations: [changeReturn],
+      sameProductAndOutboundSelection: true,
+    }),
+    'NO_REFUND',
+  );
+  assert.equal(
+    preferredAdminRefundDisposition({
+      operations: [changeReturn],
+      sameProductAndOutboundSelection: false,
+    }),
+    null,
+  );
+  assert.equal(
+    preferredAdminRefundDisposition({
+      operations: [removeAdult],
+      sameProductAndOutboundSelection: true,
+    }),
+    null,
+  );
+  assert.deepEqual(
+    buildDefaultRefundDispositionsByOperationId({
+      operations: [changeReturn],
+      sameProductAndOutboundSelection: true,
+      allowedByOperationId: {
+        [changeReturn.operationId]: ['PENDING_REFUND', 'NO_REFUND'],
+      },
+    }),
+    { [changeReturn.operationId]: 'NO_REFUND' },
+  );
+  assert.deepEqual(
+    buildDefaultRefundDispositionsByOperationId({
+      operations: [removeAdult],
+      sameProductAndOutboundSelection: false,
+      allowedByOperationId: {
+        [removeAdult.operationId]: ['PENDING_REFUND', 'NO_REFUND'],
+      },
+    }),
+    {},
+  );
+});
+
 test('changing admin refund treatment creates a distinct authoritative quote request', () => {
   const base = {
     bookingReference: 'DE8H04DX',