@osimart/create-storefront 1.0.3 → 1.0.7

package/app/composables/useCheckout.js

@@ -1,76 +1,955 @@
-import CheckoutServices from "#osi/services/CheckoutServices";
-import UtilsServices from "#osi/services/UtilsServices";
-import UserServices from "#osi/services/UserServices";
-import { authBus } from "#osi/services/AuthBus";
+import checkoutServices from "~/services/CheckoutServices";
+import utilsServices from "~/services/UtilsServices";
+import paymentServices from "~/services/PaymentServices";
+import { authBus } from "~/services/AuthBus";
 import { useToast } from "vue-toastification";
+import { eventBus } from "~/utils/eventBus";
+import { scrollToFirstError } from "~/utils/scrollToError";
+import { useUserStore } from "~/stores/userStore";
+import { analytics } from "~/utils/analytics";
 
+// ------------------------------------------------------------------
+// Helpers
+// ------------------------------------------------------------------
+export function extractErrorMessage(error) {
+  const data = error?.data ?? error?.response?.data ?? error;
+
+  if (Array.isArray(data) && data.length > 0) {
+    return data.length === 1 ? data[0] : data.map((e) => `• ${e}`).join("\n");
+  }
+  if (data && typeof data === "object") {
+    const messages = Object.values(data).flat().filter(Boolean);
+    if (messages.length > 0) {
+      return messages.length === 1
+        ? messages[0]
+        : messages.map((m) => `• ${m}`).join("\n");
+    }
+  }
+  if (typeof data === "string" && data) return data;
+
+  return error?.message || "An error occurred";
+}
+
+export function errorData(error) {
+  return error?.data ?? error?.response?.data ?? null;
+}
+
+// Paginated { results: [...] } or a bare array -> array.
+function unwrapList(response) {
+  return response?.results || (Array.isArray(response) ? response : []);
+}
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function emptyAddress() {
+  return {
+    country: "",
+    city: "",
+    address: "",
+    address_line2: "",
+    zone: "",
+    postal_code: "",
+  };
+}
+
+/**
+ * Everything the checkout page does: cart view, details/address form,
+ * shipping + free delivery, server-computed promo, extra fees, payment
+ * method, order placement and gateway handoff.
+ *
+ * State is local refs (not useState) on purpose: a promo, address or
+ * payment choice must not survive navigating away and back.
+ *
+ * Call once, from pages/checkout.vue. Registers its own onMounted.
+ */
 export function useCheckout() {
+  const toast = useToast();
   const router = useRouter();
-  const isLoading = useState("checkout-loading", () => false);
-  const cartData = useState("checkout-cart-data", () => null);
-  const countries = useState("checkout-countries", () => []);
-  const paymentMethods = useState("checkout-payment-methods", () => []);
-  const promoCodeData = useState("checkout-promo-code", () => null);
+  const userStore = useUserStore();
+  const { store } = useStorefront();
+  const { mediaUrl } = useMediaUrl();
+
+  // The one cart. Every mutation writes through useCart(), so the drawer
+  // and header badge move with the checkout page.
+  const {
+    cart: rawCart,
+    cartItems,
+    cartTotal,
+    loading: cartLoading,
+    isUpdating,
+    fetchCart,
+    editItem,
+    removeItem,
+  } = useCart();
+
+  const currency = computed(
+    () => store.value?.default_currency?.symbol || store.value?.default_currency?.code || "$",
+  );
+
+  // ================================================================
+  // STATE
+  // ================================================================
+
+  // --- UI ---
+  const mobileSummaryOpen = ref(false);
+  const bottomDiscountOpen = ref(false); // bottom pay bar: line items + promo, Shopify-style
+
+  // --- user ---
+  const isLoggedIn = ref(false);
+  const needsUserInfo = ref(true);
+  const userAddresses = ref([]);
+
+  // --- reference data ---
+  const countries = ref([]);
+  const paymentMethods = ref([]);
+  const extraFees = ref([]);
+
+  // --- form ---
+  const formData = reactive({
+    first_name: "",
+    last_name: "",
+    email: "",
+    mobile_number: "",
+    signedUpForExclusiveContent: false,
+    payment_method_id: "",
+    // object = new address, string = saved address id, null = nothing selected
+    address: emptyAddress(),
+  });
+  const formErrors = ref({}); // keyed by each field's data-field name
+  const phoneNumberResults = ref(null); // validity payload from PhoneNumInput @update
+
+  // --- address / shipping ---
+  const selectedCountry = ref("");
+  const selectedZone = ref("");
+  const countryAutoSet = ref(false);
+  const selectedAddressIndex = ref(null);
+  const showAddressForm = ref(false);
+  const isShippingLoading = ref(false);
+  const isFreeDelivery = ref(false);
+  const freeDeliveryId = ref(null);
+
+  // --- extra fees (donations) ---
+  const extraFeesPayload = ref([]);
+  const extraFeesTotal = ref(0);
+  const extraFeesValid = ref(true);
+  const extraFeeLines = ref([]);
+
+  // --- payment / order ---
+  const selectedPaymentMethod = ref(null);
+  const isCheckingOut = ref(false);
+  const activePayment = ref(null); // set once an order is placed and a gateway takes over
+  const placedOrderId = ref(null); // read by onPaymentSettled after the modal closes
+
+  // --- promo (server-computed; the frontend never calculates the discount) ---
+  const promoCode = ref(""); // what the user typed
+  const appliedPromoCode = ref(""); // code the server accepted
+  const promoId = ref(null); // sent as promo_id at checkout
+  const discount = ref(0); // discount_total from the server, in currency
+  const totalAfterDiscount = ref(null); // subtotal after discount, from the server
+  const promoError = ref("");
+  const isCodeLoading = ref(false);
+  let promoSeq = 0; // drops stale responses when requests overlap
+
+  const isNewAddress = () =>
+    !!formData.address && typeof formData.address === "object";
+
+  // ================================================================
+  // COMPUTED
+  // ================================================================
+  // Template keeps its original names.
+  const CartItems = computed(() => cartItems.value);
+  const total_price = computed(() => cartTotal.value);
+
+  const totalItemsCount = computed(() =>
+    CartItems.value.reduce((sum, item) => sum + Number(item.quantity || 0), 0),
+  );
+
+  const isLoading = computed(() => cartLoading.value || needsUserInfo.value);
+
+  const selectedAddress = computed(() =>
+    selectedAddressIndex.value !== null
+      ? userAddresses.value[selectedAddressIndex.value]
+      : null,
+  );
+
+  const zoneRequired = computed(
+    () =>
+      !!(
+        selectedCountry.value &&
+        selectedCountry.value.has_zones &&
+        selectedCountry.value.shipping_zones?.length
+      ),
+  );
+
+  const countryOptions = computed(() =>
+    (countries.value || []).map((country) => ({
+      label: country.country_name,
+      value: country,
+    })),
+  );
+
+  const zoneOptions = computed(() =>
+    (selectedCountry.value?.shipping_zones || []).map((zone) => ({
+      label: zone.name,
+      value: zone,
+    })),
+  );
+
+  const shippingCost = computed(() => {
+    if (selectedAddress.value) return selectedAddress.value.shipping_fee || 0;
+    if (selectedZone.value?.shipment_price) return selectedZone.value.shipment_price;
+    if (selectedCountry.value) return selectedCountry.value.shipment_price || 0;
+    return 0;
+  });
+
+  const effectiveShipping = computed(() =>
+    isFreeDelivery.value ? 0 : Number(shippingCost.value || 0),
+  );
+
+  // Total before the promo, for the strike-through.
+  const originalTotal = computed(() =>
+    Number(
+      (
+        Number(total_price.value || 0) +
+        effectiveShipping.value +
+        Number(extraFeesTotal.value || 0)
+      ).toFixed(2),
+    ),
+  );
+
+  // Discount comes from the server (total_after_discount); never computed here.
+  const totalPrice = computed(() => {
+    const base =
+      promoId.value && totalAfterDiscount.value !== null
+        ? totalAfterDiscount.value
+        : Number(total_price.value || 0);
+    return Number(
+      (base + effectiveShipping.value + Number(extraFeesTotal.value || 0)).toFixed(2),
+    );
+  });
+
+  const anyItemUpdating = computed(() =>
+    CartItems.value.some((item) => isUpdating(item)),
+  );
+
+  // Block paying while the cart or promo is mid-update (stale total).
+  const canPay = computed(
+    () => !isCheckingOut.value && !isCodeLoading.value && !anyItemUpdating.value,
+  );
+
+  // --- validation messages ---
+  const detailsErrorFields = computed(() => {
+    const labels = {
+      email_required: "Email",
+      first_name: "First name",
+      last_name: "Last name",
+      ...(isLoggedIn.value ? {} : { mobile_number_required: "Phone number" }),
+    };
+    return Object.keys(labels)
+      .filter((key) => formErrors.value[key])
+      .map((key) => labels[key]);
+  });
+
+  const deliveryErrorFields = computed(() => {
+    const labels = {
+      country: "Country",
+      zone: "Zone",
+      city: "City",
+      address: "Street & area",
+    };
+    return Object.keys(labels)
+      .filter((key) => formErrors.value[key])
+      .map((key) => labels[key]);
+  });
+
+  // Standalone message only for a filled-but-wrong email; an empty one joins
+  // the combined "fill all required fields" line instead.
+  const emailErrorMessage = computed(() => formErrors.value.email || "");
+  const emailHasError = computed(
+    () => !!(formErrors.value.email || formErrors.value.email_required),
+  );
+  const phoneErrorMessage = computed(() =>
+    isLoggedIn.value ? "" : formErrors.value.mobile_number || "",
+  );
+  const phoneHasError = computed(
+    () =>
+      !isLoggedIn.value &&
+      !!(formErrors.value.mobile_number || formErrors.value.mobile_number_required),
+  );
+
+  // ================================================================
+  // MEDIA / CART
+  // ================================================================
+  const imageUrl = (path) => mediaUrl(path);
+  const isItemUpdating = (item) => isUpdating(item);
 
-  const isLoggedIn = computed(() => authBus.isLoggedIn);
+  // Quantity changes go through useCart(). The resulting subtotal change
+  // triggers the promo re-check and free-delivery refresh (watch below).
+  async function mutateCart(fn, label) {
+    try {
+      await fn();
+    } catch (error) {
+      console.error(label, error);
+      toast.error(extractErrorMessage(error));
+    }
+  }
+  const increaseQuantity = (item) =>
+    mutateCart(() => editItem(item, "add"), "Error adding to cart:");
+  const decreaseQuantity = (item) =>
+    mutateCart(() => editItem(item, "remove"), "Error decreasing quantity:");
+  const deleteItem = (item) =>
+    mutateCart(() => removeItem(item), "Error removing from cart:");
+
+  // ================================================================
+  // REFERENCE DATA
+  // ================================================================
+  async function loadCountries() {
+    try {
+      countries.value = unwrapList(await utilsServices.getCountries());
+    } catch (error) {
+      console.error("[useCheckout] countries:", error);
+      countries.value = [];
+    }
+  }
 
-  async function loadCheckoutData() {
-    isLoading.value = true;
+  // /payments/methods/ only returns active, fully configured methods.
+  async function loadPaymentMethods() {
     try {
-      const [cartRes, countriesRes, paymentsRes] = await Promise.allSettled([
-        CheckoutServices.fetchCart(),
-        UtilsServices.getCountries(),
-        UtilsServices.getAvailablePaymentMethods(),
-      ]);
-
-      if (cartRes.status === "fulfilled") cartData.value = cartRes.value;
-      if (countriesRes.status === "fulfilled") countries.value = countriesRes.value?.results || countriesRes.value || [];
-      if (paymentsRes.status === "fulfilled") paymentMethods.value = paymentsRes.value?.results || paymentsRes.value || [];
+      paymentMethods.value = unwrapList(await paymentServices.getMethods());
     } catch (error) {
-      console.error("[useCheckout] Error loading checkout data:", error);
+      paymentMethods.value = [];
+      toast.error("Payment methods could not be loaded.");
+    }
+  }
+
+  async function loadExtraFees() {
+    try {
+      extraFees.value = unwrapList(await checkoutServices.extraFees());
+    } catch (error) {
+      extraFees.value = [];
+    }
+  }
+
+  // ================================================================
+  // USER
+  // ================================================================
+  function handleUserInfo() {
+    if (!authBus || !authBus.isLoggedIn) {
+      needsUserInfo.value = false;
+      isLoggedIn.value = false;
+      return;
+    }
+    if (authBus.userInfo) {
+      const info = authBus.userInfo;
+      isLoggedIn.value = authBus.isLoggedIn;
+      userAddresses.value = info.customer_addresses || [];
+      formData.first_name = info.first_name || "";
+      formData.last_name = info.last_name || "";
+      formData.email = info.email || "";
+      formData.mobile_number = info.mobile_number || "";
+    }
+  }
+
+  async function waitForUserInfoIfNeeded() {
+    if (!authBus.isLoggedIn) return;
+
+    await new Promise((resolve) => {
+      const checkInterval = setInterval(() => {
+        if (authBus.userInfo) {
+          clearInterval(checkInterval);
+          handleUserInfo();
+          resolve();
+        }
+      }, 0);
+
+      // Fallback in case user info never arrives
+      setTimeout(() => {
+        clearInterval(checkInterval);
+        needsUserInfo.value = false;
+        resolve();
+      }, 0);
+    });
+  }
+
+  // ================================================================
+  // ADDRESS / SHIPPING
+  // ================================================================
+  async function checkFreeDelivery(countryId) {
+    isShippingLoading.value = true;
+    isFreeDelivery.value = false;
+    freeDeliveryId.value = null;
+    try {
+      const results = unwrapList(await checkoutServices.freeDeliveries(countryId));
+      const rule = results.find((r) => total_price.value >= r.minimum_order_amount);
+      if (rule) {
+        isFreeDelivery.value = true;
+        freeDeliveryId.value = rule.id;
+      }
+    } catch (error) {
+      console.error(error);
+      isFreeDelivery.value = false;
+      freeDeliveryId.value = null;
     } finally {
-      isLoading.value = false;
+      isShippingLoading.value = false;
+    }
+  }
+
+  // Free delivery depends on the subtotal, so re-evaluate when the cart changes.
+  async function refreshFreeDelivery() {
+    const countryId = selectedAddress.value?.country || selectedCountry.value?.id;
+    if (countryId) await checkFreeDelivery(countryId);
+  }
+
+  async function selectAddress(index) {
+    if (showAddressForm.value) return;
+
+    if (selectedAddressIndex.value === index) {
+      selectedAddressIndex.value = null;
+      formData.address = null;
+      isFreeDelivery.value = false;
+      freeDeliveryId.value = null;
+      return;
+    }
+
+    const address = userAddresses.value[index];
+    formData.address = address.id;
+    selectedAddressIndex.value = index;
+    if (address.country) await checkFreeDelivery(address.country);
+  }
+
+  function toggleAddressForm() {
+    selectedCountry.value = null;
+    selectedZone.value = null;
+    selectedAddressIndex.value = null;
+
+    if (showAddressForm.value) {
+      showAddressForm.value = false;
+      return;
+    }
+    formData.address = emptyAddress();
+    showAddressForm.value = true;
+    countryAutoSet.value = false;
+    syncCountry();
+  }
+
+  // Silently select the hidden "Default Zone" for countries that don't
+  // expose zones, so it still goes out in the payload.
+  function applyDefaultZone(country) {
+    const zones = country?.shipping_zones || [];
+    if (country && !country.has_zones && zones.length) {
+      selectedZone.value = zones[0];
+      if (isNewAddress()) formData.address.zone = zones[0].id;
+    } else {
+      selectedZone.value = "";
+      if (isNewAddress()) formData.address.zone = "";
+    }
+  }
+
+  async function selectCountry(country) {
+    countryAutoSet.value = true;
+    if (selectedCountry.value === country) {
+      selectedCountry.value = "";
+      if (isNewAddress()) formData.address.country = "";
+      isFreeDelivery.value = false;
+      applyDefaultZone(null);
+      return;
+    }
+    selectedCountry.value = country;
+    if (isNewAddress()) formData.address.country = country.id;
+    applyDefaultZone(country);
+    await checkFreeDelivery(country.id);
+  }
+
+  function selectZone(zone) {
+    if (selectedZone.value === zone) {
+      selectedZone.value = "";
+      if (isNewAddress()) formData.address.zone = "";
+    } else {
+      selectedZone.value = zone;
+      if (isNewAddress()) formData.address.zone = zone.id;
+    }
+  }
+
+  // Pre-select the country from the visitor's IP, once.
+  function syncCountry() {
+    const ipCountryName =
+      userStore?.clientIpInfo?.country_name || userStore?.clientIpInfo?.country;
+    if (!ipCountryName || !countries.value?.length) return;
+    if (countryAutoSet.value || selectedCountry.value) return;
+
+    const target = String(ipCountryName).trim().toLowerCase();
+    const match = countries.value.find(
+      (c) =>
+        c.country_name?.trim().toLowerCase() === target ||
+        c.country_code?.trim().toLowerCase() === target ||
+        c.code?.trim().toLowerCase() === target,
+    );
+    if (match) {
+      selectCountry(match);
+      countryAutoSet.value = true;
     }
   }
 
-  async function applyPromoCode(code) {
-    const toast = useToast();
+  // ================================================================
+  // PAYMENT METHOD
+  // ================================================================
+  const isSelected = (option) => selectedPaymentMethod.value === option.id;
+
+  function setPaymentMethod(optionId) {
+    const next = selectedPaymentMethod.value === optionId ? null : optionId;
+    selectedPaymentMethod.value = next;
+    formData.payment_method_id = next;
+  }
+
+  // ================================================================
+  // EXTRA FEES
+  // ================================================================
+  function onExtraFeesChange({ payload, total, valid, lines }) {
+    extraFeesPayload.value = payload;
+    extraFeesTotal.value = total;
+    extraFeesValid.value = valid;
+    extraFeeLines.value = lines;
+  }
+
+  // ================================================================
+  // PROMO
+  // ================================================================
+  async function checkPromo(code, { silent = false } = {}) {
+    const seq = ++promoSeq;
+    const wasApplied = !!promoId.value;
+    isCodeLoading.value = true;
+    promoError.value = "";
     try {
-      const res = await CheckoutServices.promoCode(code);
-      promoCodeData.value = res;
-      toast.success("Promo code applied successfully!");
-      return res;
+      const res = await checkoutServices.applyPromoCode(code);
+      if (seq !== promoSeq) return;
+      promoId.value = res.id;
+      appliedPromoCode.value = res.code;
+      discount.value = Number(res.discount_total) || 0;
+      totalAfterDiscount.value =
+        res.total_after_discount != null ? Number(res.total_after_discount) : null;
+      if (!silent) toast.success("Promo code applied");
     } catch (error) {
-      toast.error(error?.data?.detail || "Invalid promo code");
-      throw error;
+      if (seq !== promoSeq) return;
+      const message = extractErrorMessage(error);
+      clearPromo();
+      promoCode.value = code; // keep it visible so the user sees what was removed
+      promoError.value = message;
+      if (silent && wasApplied) toast.warning(`Promo removed: ${message}`);
+    } finally {
+      if (seq === promoSeq) isCodeLoading.value = false;
+    }
+  }
+
+  function applyPromoCode() {
+    const code = (promoCode.value || "").trim();
+    if (!code || isCodeLoading.value) return;
+    return checkPromo(code);
+  }
+
+  // Re-validate the applied code against the current cart.
+  function recheckPromo() {
+    if (!promoId.value || !appliedPromoCode.value) return;
+    return checkPromo(appliedPromoCode.value, { silent: true });
+  }
+
+  function clearPromo() {
+    promoSeq++; // ignore any in-flight response
+    promoId.value = null;
+    appliedPromoCode.value = "";
+    discount.value = 0;
+    totalAfterDiscount.value = null;
+    isCodeLoading.value = false;
+  }
+
+  function removePromo() {
+    clearPromo();
+    promoCode.value = "";
+    promoError.value = "";
+  }
+
+  // placeOrder rejected the promo (expired, limit reached, no longer applies):
+  // drop it so the totals match what the server will charge.
+  function handleOrderPromoError(error) {
+    const data = errorData(error);
+    if (!data?.promo_id) return false;
+    const message = [].concat(data.promo_id)[0];
+    clearPromo();
+    promoError.value = message;
+    toast.error(`${message} The promo was removed, please review your total.`);
+    return true;
+  }
+
+  // ================================================================
+  // VALIDATION
+  // ================================================================
+  function validateForm() {
+    const errors = {};
+
+    if (!formData.first_name) errors.first_name = "First name is required.";
+    if (!formData.last_name) errors.last_name = "Last name is required.";
+    if (!formData.email) {
+      errors.email_required = true;
+    } else if (!EMAIL_PATTERN.test(formData.email)) {
+      errors.email = "Enter a valid email address.";
+    }
+    if (!formData.payment_method_id)
+      errors.payment_method_id = "Payment method is required.";
+    if (!isLoggedIn.value) {
+      if (!formData.mobile_number) {
+        errors.mobile_number_required = true;
+      } else if (!phoneNumberResults.value?.isValid) {
+        errors.mobile_number = "This phone number is not valid.";
+      }
+    }
+
+    // New address (object) needs validating; a saved address id is complete.
+    if (!formData.address) {
+      errors.country = "Country is required.";
+      errors.city = "City is required.";
+      errors.address = "Street & area is required.";
+    } else if (isNewAddress()) {
+      if (!formData.address.country) errors.country = "Country is required.";
+      if (!formData.address.city) errors.city = "City is required.";
+      if (!formData.address.address) errors.address = "Street & area is required.";
+      if (zoneRequired.value && !selectedZone.value?.id)
+        errors.zone = "Please select a zone.";
+    }
+
+    formErrors.value = errors;
+    return Object.keys(errors).length === 0;
+  }
+
+  function clearFieldError(field) {
+    if (formErrors.value[field]) {
+      formErrors.value = { ...formErrors.value, [field]: "" };
+    }
+  }
+
+  // Only lifts the red state once the email is actually valid.
+  function validateEmailField() {
+    if (formData.email) clearFieldError("email_required");
+    if (formErrors.value.email && EMAIL_PATTERN.test(formData.email || "")) {
+      clearFieldError("email");
+    }
+  }
+
+  // PhoneNumInput emits on every keystroke; errors only show on submit.
+  function onPhoneUpdate(results) {
+    phoneNumberResults.value = { ...results };
+    if (formData.mobile_number) clearFieldError("mobile_number_required");
+  }
+
+  // ================================================================
+  // ORDER
+  // ================================================================
+  function buildPayload() {
+    const cart = Object.fromEntries(
+      Object.entries(rawCart.value?.cart ?? {}).map(([id, item]) => [
+        id,
+        { name: item.name, quantity: item.quantity, price: item.price, image: item.image },
+      ]),
+    );
+
+    const payload = { payment_method_id: formData.payment_method_id, cart };
+
+    // Validated server-side against the store's own origins.
+    if (typeof window !== "undefined") {
+      payload.return_url = `${window.location.origin}/checkout/result`;
+    }
+    if (promoId.value) payload.promo_id = promoId.value;
+    if (freeDeliveryId.value) payload.freedelivery_id = freeDeliveryId.value;
+    if (extraFeesPayload.value.length > 0) payload.extra_fees = extraFeesPayload.value;
+
+    if (typeof formData.address === "string") {
+      payload.address_id = formData.address;
+    } else {
+      payload.address = { ...formData.address };
+      if (selectedZone.value?.id) payload.address.zone = selectedZone.value.id;
+      else delete payload.address.zone;
+      if (!payload.address.address_line2) delete payload.address.address_line2;
     }
+
+    if (!isLoggedIn.value) {
+      payload.guest = {
+        first_name: formData.first_name,
+        last_name: formData.last_name,
+        email: formData.email,
+        mobile_number: formData.mobile_number,
+      };
+    }
+    return payload;
+  }
+
+  function trackFunnel() {
+    const coupon = promoId.value ? appliedPromoCode.value || undefined : undefined;
+    const chosenMethod = paymentMethods.value.find(
+      (m) => m.id === formData.payment_method_id,
+    );
+    analytics.addShippingInfo(CartItems.value, {
+      tier:
+        selectedZone.value?.name ||
+        selectedCountry.value?.country_name ||
+        selectedAddress.value?.country_name ||
+        undefined,
+      coupon,
+    });
+    analytics.addPaymentInfo(CartItems.value, {
+      paymentType: chosenMethod?.name,
+      coupon,
+    });
   }
 
-  async function submitOrder(orderPayload) {
-    const toast = useToast();
-    isLoading.value = true;
+  async function submitForm() {
+    if (!canPay.value) return;
+
+    if (!validateForm()) {
+      await nextTick();
+      scrollToFirstError(formErrors.value);
+      return;
+    }
+    if (extraFeesPayload.value.length > 0 && !extraFeesValid.value) {
+      toast.error("Check the donation amount before completing your order.");
+      return;
+    }
+
+    const payload = buildPayload();
+    trackFunnel();
+
     try {
-      const response = await CheckoutServices.placeOrder(orderPayload);
-      toast.success("Order placed successfully!");
-      router.push(`/ordersummary?order_id=${response.id || response.order_id}`);
-      return response;
+      isCheckingOut.value = true;
+      const response = await checkoutServices.placeOrder(payload);
+      placedOrderId.value = response.order_id;
+      sessionStorage.setItem("orderId", response.order_id);
+
+      // No fallback to OFFLINE: treating an unknown response as paid would
+      // clear the bag for an order nobody has paid for.
+      const payment = response.payment;
+      if (!payment?.flow) {
+        console.error("checkout returned no payment object", response);
+        toast.error("Payment could not be started. Please try again.");
+        return;
+      }
+      if (payment.reference) paymentServices.setReference(payment.reference);
+
+      if (payment.flow === "OFFLINE") {
+        toast.success("Order added successfully!");
+        paymentServices.clearReference();
+        eventBus.emit("cartUpdated");
+        router.replace({
+          path: "/order-detail",
+          query: { id: placedOrderId.value, placed: "1" },
+        });
+        return;
+      }
+
+      // Card / redirect: hand off to the gateway.
+      activePayment.value = payment;
     } catch (error) {
-      toast.error(error?.data?.detail || "Failed to place order");
-      throw error;
+      console.error("Error placing order:", error);
+      if (handleOrderPromoError(error)) return;
+      toast.error(extractErrorMessage(error));
     } finally {
-      isLoading.value = false;
+      isCheckingOut.value = false;
     }
   }
 
+  // ================================================================
+  // GATEWAY HANDOFF
+  // ================================================================
+  function onPaymentError(message) {
+    toast.error(message);
+  }
+
+  // Fired ONLY when the server confirmed the charge. Goes straight to the
+  // order: this flow already verified in the modal, and clearReference()
+  // leaves /checkout/result with nothing to check.
+  function onPaymentSettled() {
+    paymentServices.clearReference();
+    eventBus.emit("cartUpdated");
+    activePayment.value = null;
+    router.replace({
+      path: "/order-detail",
+      query: { id: placedOrderId.value, placed: "1" },
+    });
+  }
+
+  // Bank refused: the order exists unpaid, the bag stays. A retry needs a
+  // fresh capture context, so return to the form.
+  function onPaymentDeclined(reason) {
+    activePayment.value = null;
+    isCheckingOut.value = false;
+    toast.error(reason || "Your payment was declined. Please try another card.");
+  }
+
+  function closePayment() {
+    activePayment.value = null;
+    isCheckingOut.value = false;
+    toast.info("Your order is saved but unpaid. You can pay again.");
+  }
+
+  // ================================================================
+  // ACCORDION (height-based enter/leave for the mobile summaries)
+  // ================================================================
+  function onAccordionEnd(el, done) {
+    let finished = false;
+    const finish = (event) => {
+      if (event && (event.target !== el || event.propertyName !== "height")) return;
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      el.removeEventListener("transitionend", finish);
+      done();
+    };
+    const timer = setTimeout(finish, 400);
+    el.addEventListener("transitionend", finish);
+  }
+
+  function accordionEnter(el, done) {
+    el.style.overflow = "hidden";
+    el.style.height = "0px";
+    el.style.opacity = "0";
+    void el.offsetHeight;
+    el.style.transition = "height 0.3s ease, opacity 0.25s ease";
+    el.style.height = `${el.scrollHeight}px`;
+    el.style.opacity = "1";
+    onAccordionEnd(el, done);
+  }
+
+  function accordionLeave(el, done) {
+    el.style.overflow = "hidden";
+    el.style.height = `${el.scrollHeight}px`;
+    el.style.opacity = "1";
+    void el.offsetHeight;
+    el.style.transition = "height 0.3s ease, opacity 0.25s ease";
+    el.style.height = "0px";
+    el.style.opacity = "0";
+    onAccordionEnd(el, done);
+  }
+
+  function accordionAfterEnter(el) {
+    el.style.transition = "";
+    el.style.height = "";
+    el.style.opacity = "";
+    el.style.overflow = "";
+  }
+
+  // ================================================================
+  // WATCHERS + LIFECYCLE
+  // ================================================================
+  // Subtotal changed (checkout steppers or the drawer): re-validate the promo
+  // and free-delivery threshold against the server.
+  watch(total_price, (next, prev) => {
+    if (next === prev) return;
+    recheckPromo();
+    refreshFreeDelivery();
+  });
+
+  watch(phoneNumberResults, (results) => {
+    if (formErrors.value.mobile_number && results?.isValid) {
+      clearFieldError("mobile_number");
+    }
+  });
+
+  watch(() => userStore.clientIpInfo, syncCountry, { deep: true, immediate: true });
+
+  watch(selectedCountry, (next, prev) => {
+    if (next && prev && next.id !== prev.id) applyDefaultZone(next);
+  });
+
+  onMounted(async () => {
+    await Promise.all([loadPaymentMethods(), loadCountries()]);
+    syncCountry();
+    handleUserInfo();
+    await Promise.all([fetchCart(), waitForUserInfoIfNeeded(), loadExtraFees()]);
+    // begin_checkout / InitiateCheckout: the page is open and the bag is loaded.
+    analytics.beginCheckout(CartItems.value);
+  });
+
+  // ================================================================
   return {
+    // display
+    currency,
+    imageUrl,
     isLoading,
-    cartData,
-    countries,
-    paymentMethods,
-    promoCodeData,
+    mobileSummaryOpen,
+    bottomDiscountOpen,
+    accordionEnter,
+    accordionLeave,
+    accordionAfterEnter,
+
+    // cart
+    CartItems,
+    total_price,
+    totalItemsCount,
+    isItemUpdating,
+    increaseQuantity,
+    decreaseQuantity,
+    deleteItem,
+
+    // user + form
     isLoggedIn,
-    loadCheckoutData,
+    formData,
+    formErrors,
+    clearFieldError,
+    validateEmailField,
+    onPhoneUpdate,
+    detailsErrorFields,
+    deliveryErrorFields,
+    emailErrorMessage,
+    emailHasError,
+    phoneErrorMessage,
+    phoneHasError,
+
+    // address + shipping
+    userAddresses,
+    selectedAddressIndex,
+    selectedAddress,
+    showAddressForm,
+    selectAddress,
+    toggleAddressForm,
+    countryOptions,
+    zoneOptions,
+    zoneRequired,
+    selectedCountry,
+    selectedZone,
+    selectCountry,
+    selectZone,
+    shippingCost,
+    isShippingLoading,
+    isFreeDelivery,
+
+    // payment method
+    paymentMethods,
+    isSelected,
+    setPaymentMethod,
+
+    // extra fees
+    extraFees,
+    extraFeeLines,
+    onExtraFeesChange,
+
+    // promo
+    promoCode,
+    appliedPromoCode,
+    promo_id: promoId,
+    discount,
+    promoError,
+    isCodeLoading,
     applyPromoCode,
-    submitOrder,
+    removePromo,
+
+    // totals + order
+    originalTotal,
+    totalPrice,
+    canPay,
+    isCheckingOut,
+    submitForm,
+
+    // gateway
+    activePayment,
+    onPaymentError,
+    onPaymentSettled,
+    onPaymentDeclined,
+    closePayment,
   };
-}
+}