@tribe-nest/forge 2.2.0 → 3.4.0

package/src/ui/headless/checkout/useCheckout.ts

@@ -11,7 +11,13 @@ import {
   type ShippingCountry,
 } from "../../../data/queries/useShipping";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
-import { useCreateCheckout, cartToCheckoutLines } from "../../../data/queries/useCheckouts";
+import {
+  useCreateCheckout,
+  useApplyCheckoutCoupon,
+  cartToCheckoutLines,
+  type ApplyCheckoutCouponResult,
+} from "../../../data/queries/useCheckouts";
+import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -52,6 +58,12 @@ interface AppliedCoupon {
   code: string;
   discountType: string | null;
   discountValue: number | null;
+  /**
+   * MAJOR units. Set for the BUNDLE path only, where the endpoint reports what
+   * came off (`discountCents`) but not the coupon's type or rate — so "10% off"
+   * cannot be rendered and the cash figure is the honest thing to show.
+   */
+  discountAmount?: number;
 }
 
 interface CouponPaymentUpdate {
@@ -96,6 +108,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   const createOrder = useCreateOrder();
   const createCheckout = useCreateCheckout();
   const applyCouponMutation = useApplyCoupon();
+  const applyCheckoutCouponMutation = useApplyCheckoutCoupon();
 
   const hasPhysicalProduct = useMemo(
     () => cartItems.some((item) => item.deliveryType === ProductDeliveryType.Physical),
@@ -153,6 +166,12 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   const [created, setCreated] = useState<CreateOrderResult | null>(null);
   /** Set instead of `created` when the cart is a bundle. */
   const [checkoutId, setCheckoutId] = useState<string | null>(null);
+  /**
+   * A bundle a discount took to zero. Applying such a code settles it on the
+   * server (there is no intent to mint), so there is nothing left to pay and the
+   * caller has to move the buyer straight to the finalise page.
+   */
+  const [settledCheckoutId, setSettledCheckoutId] = useState<string | null>(null);
   const [startError, setStartError] = useState("");
   const startedRef = useRef(false);
 
@@ -184,6 +203,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     // both settle on one payment. Every single-surface cart keeps the flow it
     // has always had, below.
     if (isBundle) {
+      const enteredCode = couponCode.trim() || undefined;
       createCheckout
         .mutateAsync({
           firstName: guestUserData?.firstName || user?.firstName || "",
@@ -194,10 +214,41 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
           selectedShippingRates: selectedShippingRates.length ? selectedShippingRates : undefined,
           attributionRefId: readAttributionRef() ?? undefined,
           ...(readLanding() ?? {}),
+          // A code typed BEFORE this call still travels with it — that is the
+          // cheapest path and the only one available to a guest, whose bundle
+          // does not exist yet. A code typed AFTERWARDS goes through
+          // `/public/checkouts/apply-coupon`, which is what stops the field
+          // freezing for a signed-in buyer whose digital-only cart enters the
+          // payment stage on mount.
+          couponCode: enteredCode,
           lines: cartToCheckoutLines(cartItems, ticketItems),
         })
-        .then((r) => setCheckoutId(r.checkoutId))
-        .catch((e) => setStartError(messageOf(e) || "An error occurred"));
+        .then((r) => {
+          setCheckoutId(r.checkoutId);
+          // Minor → major. The bundle is the only endpoint answering in minor units.
+          const off = (r.discountCents ?? 0) / 100;
+          setDiscountAmount(off);
+          // `appliedCoupons` names what came off, so an AUTOMATIC discount the
+          // buyer never typed is labelled rather than being an unexplained
+          // amount. The typed code is the fallback for an older API.
+          const named = r.appliedCoupons?.[0];
+          setAppliedCoupon(
+            off > 0
+              ? {
+                  code: named?.code ?? enteredCode ?? "Discount applied",
+                  discountType: null,
+                  discountValue: null,
+                  discountAmount: off,
+                }
+              : null,
+          );
+        })
+        .catch((e) => {
+          // A refused code fails the whole bundle, so with one entered the
+          // reason belongs at the field the buyer used — verbatim from the API.
+          if (enteredCode) setCouponError(messageOf(e) || "This code could not be applied.");
+          else setStartError(messageOf(e) || "An error occurred");
+        });
       return;
     }
 
@@ -243,7 +294,10 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
   // and start-payment have resolved.
   const effectivePayment = useMemo<CouponPaymentUpdate | null>(() => {
     if (couponPaymentUpdate) return couponPaymentUpdate;
-    if (created && flow.result?.paymentSecret && flow.result?.paymentId) {
+    // `checkoutId` as well as `created`: a BUNDLE has no `created` order, and
+    // gating on that alone left a bundle buyer with no payment element at all
+    // unless a coupon happened to re-mint one.
+    if ((created || checkoutId) && flow.result?.paymentSecret && flow.result?.paymentId) {
       return {
         paymentSecret: flow.result.paymentSecret,
         paymentId: flow.result.paymentId,
@@ -252,7 +306,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
       };
     }
     return null;
-  }, [created, flow.result, couponPaymentUpdate]);
+  }, [created, checkoutId, flow.result, couponPaymentUpdate]);
 
   // Surface the charged total (for the summary) as soon as a payment resolves.
   useEffect(() => {
@@ -317,8 +371,66 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     setCurrentStage("payment");
   }, [shippingGroups, selections]);
 
-  // ── Coupon (applied against the created order) ──────────────────────────────
+  // ── Coupon (applied against the created order / bundle) ─────────────────────
+  /**
+   * Whether the code field can still be changed.
+   *
+   * Both shapes are now re-priceable in place: a single-surface order through
+   * `/public/orders/apply-coupon`, a bundle through
+   * `/public/checkouts/apply-coupon`. A bundle's field used to freeze the moment
+   * the checkout was created — which for a signed-in buyer with a digital-only
+   * cart was on mount, so the code could never be typed at all.
+   */
+  const isCouponEditable = isBundle ? !settledCheckoutId : !!orderId;
+
+  /** Fold an apply/remove answer for a bundle back into the summary + payment. */
+  const absorbBundleCoupon = useCallback((data: ApplyCheckoutCouponResult) => {
+    const next = bundleCouponSummary(data);
+    setDiscountAmount(next.discountAmount);
+    setAppliedCoupon(
+      next.appliedCoupon
+        ? {
+            code: next.appliedCoupon.code,
+            discountType: null,
+            discountValue: null,
+            discountAmount: next.appliedCoupon.discountAmount,
+          }
+        : null,
+    );
+    setCouponPaymentUpdate(next.paymentUpdate);
+    if (next.chargedTotal) setChargedTotal(next.chargedTotal);
+    if (next.settledCheckoutId) setSettledCheckoutId(next.settledCheckoutId);
+  }, []);
+
   const applyCoupon = useCallback(async () => {
+    if (isBundle) {
+      if (!couponCode.trim()) return;
+      setCouponError("");
+      // Not created yet (a guest, or a cart with a shipping stage still ahead):
+      // the code travels with `createCheckout`, which is the one call that can
+      // price it without leaving an abandoned bundle behind.
+      if (!checkoutId) {
+        setAppliedCoupon({ code: couponCode.trim(), discountType: null, discountValue: null });
+        return;
+      }
+      setIsApplyingCoupon(true);
+      try {
+        const data = await applyCheckoutCouponMutation.mutateAsync({
+          checkoutId,
+          returnUrl: bundleReturnUrl(window.location.origin, finalisePath, checkoutId),
+          couponCode: couponCode.trim(),
+        });
+        absorbBundleCoupon(data);
+      } catch (e) {
+        // The API answers a refused code with the real reason, already
+        // translated. Collapsing it into "invalid code" throws away the only
+        // thing that tells the buyer what to do next.
+        setCouponError(messageOf(e) || "Invalid coupon code");
+      } finally {
+        setIsApplyingCoupon(false);
+      }
+      return;
+    }
     if (!couponCode.trim() || !orderId) return;
     setCouponError("");
     setIsApplyingCoupon(true);
@@ -344,9 +456,37 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [couponCode, orderId, finalisePath, applyCouponMutation]);
+  }, [couponCode, orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
 
   const removeCoupon = useCallback(async () => {
+    if (isBundle) {
+      setCouponError("");
+      // Nothing created yet — the staged code simply never travels.
+      if (!checkoutId) {
+        setAppliedCoupon(null);
+        setCouponCode("");
+        setShowCouponInput(false);
+        setDiscountAmount(0);
+        return;
+      }
+      setIsApplyingCoupon(true);
+      try {
+        // No code sent: the bundle is re-priced with none, which restores the
+        // original total rather than freezing the last discounted one.
+        const data = await applyCheckoutCouponMutation.mutateAsync({
+          checkoutId,
+          returnUrl: bundleReturnUrl(window.location.origin, finalisePath, checkoutId),
+        });
+        absorbBundleCoupon(data);
+        setCouponCode("");
+        setShowCouponInput(false);
+      } catch (e) {
+        setCouponError(messageOf(e) || "Failed to remove coupon");
+      } finally {
+        setIsApplyingCoupon(false);
+      }
+      return;
+    }
     if (!orderId) return;
     setCouponError("");
     setIsApplyingCoupon(true);
@@ -372,7 +512,7 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     } finally {
       setIsApplyingCoupon(false);
     }
-  }, [orderId, finalisePath, applyCouponMutation]);
+  }, [orderId, checkoutId, finalisePath, applyCouponMutation, applyCheckoutCouponMutation, absorbBundleCoupon, isBundle]);
 
   // ── Free checkout (nothing to charge) ───────────────────────────────────────
   /** Create the (free) order and return its id so the caller can navigate to the
@@ -439,6 +579,12 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     orderId,
     /** Set instead of `orderId` when the cart spans surfaces. */
     checkoutId,
+    /**
+     * Set when a discount took the bundle to zero: it is already paid and
+     * fulfilled server-side, so the caller must send the buyer to the finalise
+     * page instead of waiting for a payment that will never be asked for.
+     */
+    settledCheckoutId,
     isBundle,
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
@@ -463,6 +609,8 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     isApplyingCoupon,
     applyCoupon,
     removeCoupon,
+    /** False once the code can no longer be changed (a created bundle). */
+    isCouponEditable,
     // ── Errors ─────────────────────────────────────────────────────────────────
     pageError,
     setPageError,

package/src/ui/headless/coaching/useCoachingBooking.ts

@@ -8,6 +8,7 @@ import {
   useUnreserveCoachingBooking,
 } from "../../../data/queries/useCoachingAvailability";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -93,6 +94,37 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
   const finalisePath =
     opts.finalisePath ?? ((s, bId) => `/i/coaching/${s}/finalise?orderId=${bId}`);
 
+  /**
+   * Discount code — genuinely quoted, because `booking/update` re-derives the
+   * gross price from the PRODUCT on every call. Applying re-prices the held
+   * booking and removing (no code) puts the original total back rather than
+   * netting a second time off an already-netted figure.
+   *
+   * `confirmIfFree` is deliberately false here: pricing a code must never be
+   * able to complete the booking. Only "Continue" confirms.
+   */
+  const quoteCoupon: CouponQuoteFn = useCallback(
+    async (code) => {
+      if (!bookingId) throw new Error("Reserve a time slot before entering a code.");
+      if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new Error("Enter your name and a valid email before applying a code.");
+      }
+      return update.mutateAsync({
+        bookingId,
+        email,
+        firstName,
+        lastName,
+        confirmIfFree: false,
+        questionnaire,
+        couponCode: code ?? undefined,
+      });
+    },
+    // `update` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [bookingId, firstName, lastName, email, questionnaire],
+  );
+  const coupon = useCouponField(quoteCoupon);
+
   // Highlight a slot (no server hold yet — the slot is reserved on "Continue").
   const selectSlot = (slotId: string) => {
     setError(null);
@@ -139,8 +171,12 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setBookingId(null);
     setSelectedSlotId(null);
     setReservationExpiresAt(null);
+    // The quote belonged to a booking that no longer exists — keeping it would
+    // show a discount against a price nothing has agreed to.
+    coupon.reset();
     setStep("slot");
-  }, [bookingId, unreserve]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [bookingId, unreserve, coupon.reset]);
 
   /** Release the hold and surface a notice — call when the reservation timer runs out. */
   const expireReservation = useCallback(async () => {
@@ -163,9 +199,12 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
         lastName,
         confirmIfFree: true,
         questionnaire,
+        // Re-sent so the booking is confirmed at the price the buyer was shown.
+        couponCode: coupon.submittedCode,
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
+      coupon.record(updated);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, bookingId)}`;
       setReturnUrl(ru);
@@ -180,7 +219,10 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
       if (result.provider && result.provider !== "stripe") return;
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // With a code entered, the API's rejection reason belongs at the field the
+      // buyer used, not in the generic error slot.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
@@ -213,7 +255,15 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setQuestionnaire,
     continueToPayment,
     clientSecret: flow.clientSecret,
-    totalAmount: flow.result?.totalAmount,
+    // The booking quote WINS over start-payment: every `continueToPayment`
+    // re-quotes before starting the payment, and applying or removing a code
+    // re-quotes again — so the quote is never staler, and preferring the
+    // payment result would leave a removed discount on screen.
+    totalAmount: coupon.quote?.totalAmount ?? flow.result?.totalAmount,
+    /** GROSS session price, before any discount. Undefined until quoted. */
+    subTotal: coupon.quote?.subTotal,
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     returnUrl,

package/src/ui/headless/coupon/_tests/couponFailureMessage.spec.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { apiErrorMessage, couponFailureMessage } from "../useCouponField";
+
+/**
+ * The one decision that determines whether a buyer learns anything from a
+ * refused code. The backend answers with the reason ALREADY translated —
+ * "This coupon has expired", "Your order does not reach this coupon's minimum
+ * spend" — so the only correct behaviour is to pass that string through.
+ */
+
+/** An axios-shaped rejection, which is what every checkout actually catches. */
+const axiosError = (message: string) => {
+  const e = new Error("Request failed with status code 400") as Error & {
+    response: { status: number; data: { status: number; message: string } };
+  };
+  e.response = { status: 400, data: { status: 400, message } };
+  return e;
+};
+
+describe("apiErrorMessage", () => {
+  it("reads the server's message off the response body", () => {
+    expect(apiErrorMessage(axiosError("This coupon has expired"))).toBe("This coupon has expired");
+  });
+
+  it("returns nothing for a failure that carried no server message", () => {
+    expect(apiErrorMessage(new Error("boom"))).toBeUndefined();
+    expect(apiErrorMessage(undefined)).toBeUndefined();
+    expect(apiErrorMessage(null)).toBeUndefined();
+    expect(apiErrorMessage({ response: {} })).toBeUndefined();
+  });
+});
+
+describe("couponFailureMessage", () => {
+  it("shows the API's reason verbatim, never the house fallback", () => {
+    // Every distinct reason the three pillars can produce for an ENTERED code.
+    for (const reason of [
+      "This coupon is no longer active",
+      "This coupon is not available yet",
+      "This coupon has expired",
+      "This coupon is not valid for your email",
+      "This coupon can only be used with an email address",
+      "Your order does not reach this coupon's minimum spend",
+      "Your order does not reach this coupon's minimum quantity",
+      "This coupon is only valid on a first order",
+      "This coupon is only available to members of a specific tier",
+      "This coupon is not available to you",
+      "This coupon has reached its maximum redemptions",
+      "You have already used this coupon the maximum number of times",
+      "This coupon does not apply to anything in this order",
+      "This coupon is not set up correctly and cannot be used",
+      "This coupon cannot be combined with another discount on this order",
+      "Invalid coupon code",
+      "This coupon cannot be used here",
+    ]) {
+      expect(couponFailureMessage(axiosError(reason), "This code could not be applied.")).toBe(reason);
+    }
+  });
+
+  it("never surfaces axios's own transport wording", () => {
+    // `Error.message` on a 400 is "Request failed with status code 400" — a
+    // string that tells the buyer nothing and looks like a bug.
+    const shown = couponFailureMessage(axiosError("This coupon has expired"), "fallback");
+    expect(shown).not.toContain("status code");
+    expect(shown).not.toBe("fallback");
+  });
+
+  it("suppresses the transport wording even when the body carried no message", () => {
+    const e = new Error("Request failed with status code 500") as Error & { response: { data: unknown } };
+    e.response = { data: {} };
+    expect(couponFailureMessage(e, "This code could not be applied.")).toBe("This code could not be applied.");
+  });
+
+  it("keeps a locally thrown precondition, which is ours to word", () => {
+    // "Reserve a slot first" is not a coupon rejection and has no server key.
+    expect(couponFailureMessage(new Error("Reserve a time slot before entering a code."), "fallback")).toBe(
+      "Reserve a time slot before entering a code.",
+    );
+  });
+
+  it("falls back only when there is genuinely nothing to say", () => {
+    expect(couponFailureMessage({}, "This code could not be applied.")).toBe("This code could not be applied.");
+    expect(couponFailureMessage(undefined, "This code could not be applied.")).toBe("This code could not be applied.");
+  });
+});

package/src/ui/headless/coupon/useCouponField.ts

@@ -0,0 +1,164 @@
+import { useCallback, useState } from "react";
+import type { AppliedDiscountCoupon, PillarDiscountQuote } from "../../../types/models";
+
+/**
+ * Re-quote a pillar with (or, with `null`, without) a discount code and return
+ * what the SERVER says the buyer now owes.
+ *
+ * Only the pillars whose pre-payment step is re-runnable can supply one:
+ * coaching and courses both hang a `booking/update` endpoint off an already
+ * reserved booking, and that endpoint re-derives the gross price from the
+ * product on every call precisely so it can be fired repeatedly.
+ *
+ * Event tickets and bundles have no such endpoint — `POST /public/events/:id/orders`
+ * and `POST /public/checkouts` CREATE the record, so calling either one twice
+ * to preview a code would leave a real abandoned order behind. Those two pass
+ * no quote function and instead stage the code, hand it to the one call they do
+ * make, and record the quote that call returns via `record()`.
+ */
+export type CouponQuoteFn = (code: string | null) => Promise<PillarDiscountQuote>;
+
+/**
+ * The API's own message for a failed request.
+ *
+ * A coupon rejection comes back as a 400 whose body carries the reason ALREADY
+ * translated ("This coupon has expired", "Your order does not reach this
+ * coupon's minimum spend", …) — the server sends the rendered string, not the
+ * `errors.coupon.*` key, so there is nothing to map and nothing to invent.
+ * Replacing it with a house "invalid code" would throw away the only
+ * explanation the buyer is ever given.
+ */
+export function apiErrorMessage(e: unknown): string | undefined {
+  return (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+}
+
+/**
+ * The message to show for a failure: the API's own wording when the failure
+ * came from the server, otherwise a locally thrown precondition ("reserve a
+ * slot first"). A transport `Error` from axios carries a `response`, so its
+ * useless "Request failed with status code 400" is never surfaced.
+ */
+export function couponFailureMessage(e: unknown, fallback: string): string {
+  const fromApi = apiErrorMessage(e);
+  if (fromApi) return fromApi;
+  const hasResponse = !!(e as { response?: unknown })?.response;
+  if (!hasResponse && e instanceof Error && e.message) return e.message;
+  return fallback;
+}
+
+export interface CouponField {
+  /** The raw code in the input (upper-cased by the UI, trimmed on send). */
+  code: string;
+  setCode: (code: string) => void;
+  /** Trimmed code, or `undefined` when the field is empty — send this. */
+  submittedCode: string | undefined;
+  /** Whether the "Have a discount code?" affordance has been expanded. */
+  showInput: boolean;
+  setShowInput: (show: boolean) => void;
+  /** The API's verbatim rejection message, or a local precondition message. */
+  error: string | null;
+  setError: (message: string | null) => void;
+  isApplying: boolean;
+  /** The server's last pricing answer — `null` until something has quoted. */
+  quote: PillarDiscountQuote | null;
+  /** Every discount that applied, entered OR automatic. */
+  appliedCoupons: AppliedDiscountCoupon[];
+  /** MAJOR units. `0` when nothing applied. */
+  discountAmount: number;
+  /** True once the server has confirmed a discount is on this checkout. */
+  hasDiscount: boolean;
+  /** Re-quote with the entered code. No-op without a quote function. */
+  apply: () => Promise<void>;
+  /** Re-quote with NO code, restoring the undiscounted total. */
+  remove: () => Promise<void>;
+  /** Record a quote produced by a call this field did not make. */
+  record: (quote: PillarDiscountQuote | null) => void;
+  /** Report a failure, taking the API's own wording. */
+  fail: (e: unknown, fallback?: string) => void;
+  /** Forget everything — used when the underlying record is discarded. */
+  reset: () => void;
+  /** Whether an Apply/Remove button should be offered at all. */
+  canQuote: boolean;
+}
+
+/**
+ * The discount-code field shared by every checkout: the input, the API's
+ * rejection message, and the server-computed quote that lets the summary show
+ * the buyer a Discount LINE rather than a total that silently shrank.
+ */
+export function useCouponField(quoteFn?: CouponQuoteFn): CouponField {
+  const [code, setCode] = useState("");
+  const [showInput, setShowInput] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isApplying, setIsApplying] = useState(false);
+  const [quote, setQuote] = useState<PillarDiscountQuote | null>(null);
+
+  const submittedCode = code.trim() ? code.trim() : undefined;
+
+  const fail = useCallback((e: unknown, fallback = "Something went wrong.") => {
+    setError(couponFailureMessage(e, fallback));
+  }, []);
+
+  const run = useCallback(
+    async (next: string | null) => {
+      if (!quoteFn) return;
+      setError(null);
+      setIsApplying(true);
+      try {
+        setQuote(await quoteFn(next));
+      } catch (e) {
+        // The failed code is NOT retained as applied: the previous quote stands
+        // (or none does), so the total on screen keeps matching the server.
+        setError(couponFailureMessage(e, "This code could not be applied."));
+      } finally {
+        setIsApplying(false);
+      }
+    },
+    [quoteFn],
+  );
+
+  const apply = useCallback(async () => {
+    const trimmed = code.trim();
+    if (!trimmed) return;
+    await run(trimmed);
+  }, [code, run]);
+
+  const remove = useCallback(async () => {
+    await run(null);
+    setCode("");
+    setShowInput(false);
+  }, [run]);
+
+  const record = useCallback((next: PillarDiscountQuote | null) => {
+    setError(null);
+    setQuote(next);
+  }, []);
+
+  const reset = useCallback(() => {
+    setCode("");
+    setShowInput(false);
+    setError(null);
+    setQuote(null);
+  }, []);
+
+  return {
+    code,
+    setCode,
+    submittedCode,
+    showInput,
+    setShowInput,
+    error,
+    setError,
+    isApplying,
+    quote,
+    appliedCoupons: quote?.appliedCoupons ?? [],
+    discountAmount: quote?.discountAmount ?? 0,
+    hasDiscount: (quote?.discountAmount ?? 0) > 0,
+    apply,
+    remove,
+    record,
+    fail,
+    reset,
+    canQuote: !!quoteFn,
+  };
+}