@base44/app-plugin-commerce 0.1.15 → 0.1.16

package/src/commerce/storefront/useCheckout.jsx

@@ -0,0 +1,279 @@
+import React, { createContext, useCallback, useContext, useEffect, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { useStorefrontState } from "./StorefrontProvider";
+import {
+  REQUIRED_BILLING_FIELDS,
+  isShippingAddressComplete,
+  missingBillingFields,
+  shippingSlice,
+} from "./address";
+
+const EMPTY_ADDRESS = Object.freeze({
+  first_name: "",
+  last_name: "",
+  company: "",
+  address_1: "",
+  address_2: "",
+  city: "",
+  state: "",
+  postcode: "",
+  country: "",
+  phone: "",
+});
+
+/**
+ * useCheckout — the guided checkout state machine. It owns the parts every
+ * checkout must get right, so the page you build is only markup around it:
+ *
+ * - **Address → shipping/tax recalculation, automatic.** Edit the billing (or
+ *   separate shipping) address through `updateBilling`/`updateShipping`; the
+ *   moment the address is complete enough to price (default: country + city —
+ *   see `isShippingAddressComplete`), the hook debounces and calls
+ *   `set-shipping-address`, which recalculates every shipping option, its
+ *   cost and the taxes. Half-typed addresses are never sent, an unchanged
+ *   address is never re-sent, and an address the store doesn't ship to
+ *   surfaces as `addressError` — show it on the address fields.
+ * - **Shipping choice.** `shippingStatus` mirrors the cart's state:
+ *   `auto_selected` (one option, already applied — just display
+ *   `chosenShippingMethod`), `chosen`, `choice_required` (render
+ *   `shippingMethods` and call `chooseShippingMethod(id)`), `missing_address`
+ *   (collect the address), `not_needed` (virtual cart — render nothing).
+ * - **Payment choice.** `paymentMethods` come from store info (their ONLY
+ *   source); a store with exactly one enabled gateway gets it pre-selected.
+ * - **The gate.** `canPlaceOrder` + `blockers` say exactly what still stands
+ *   between the customer and the order — drive the button's disabled state
+ *   and the "what's missing" hints from them instead of re-deriving.
+ * - **placeOrder.** Sends the order, clears the shared cart, and (by default)
+ *   redirects to the provider's payment page when the gateway is online.
+ *   Resolves to `{ ok: true, result }` or `{ ok: false, error }`; a manual-
+ *   gateway result carries `result.payment_instructions` to render.
+ *
+ * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
+ * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
+ * `shipping_address_required`, `shipping_method_required`,
+ * `shipping_not_available`, `payment_method_required`.
+ *
+ * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
+ * country+city rule), `requiredBillingFields`, `redirectToPayment` (true).
+ */
+export function useCheckout(options = {}) {
+  const {
+    debounceMs = 600,
+    addressComplete = isShippingAddressComplete,
+    requiredBillingFields = REQUIRED_BILLING_FIELDS,
+    redirectToPayment = true,
+  } = options;
+
+  const { client, info, cart, runCart, clearCart } = useStorefrontState();
+
+  // ── form state ───────────────────────────────────────────────────────────
+  const [billing, setBilling] = useState({ ...EMPTY_ADDRESS, email: "" });
+  const [shipping, setShipping] = useState({ ...EMPTY_ADDRESS });
+  const [shipToDifferent, setShipToDifferent] = useState(false);
+  const [paymentMethod, setPaymentMethod] = useState("");
+  const [addressError, setAddressError] = useState(null);
+  const [syncing, setSyncing] = useState(false);
+  const [syncedKey, setSyncedKey] = useState(undefined);
+  const [placing, setPlacing] = useState(false);
+  const [orderError, setOrderError] = useState(null);
+
+  const updateBilling = useCallback((patch) => setBilling((b) => ({ ...b, ...patch })), []);
+  const updateShipping = useCallback((patch) => setShipping((s) => ({ ...s, ...patch })), []);
+
+  // ── address → shipping/tax recalculation ────────────────────────────────
+  const shippingAddress = shipToDifferent ? shipping : billing;
+  const slice = shippingSlice(shippingAddress);
+  const sliceKey = JSON.stringify(slice);
+  const complete = addressComplete(shippingAddress);
+
+  // Adopt whatever address the cart already carries (returning shopper) as
+  // "synced", so an untouched form doesn't resend it.
+  useEffect(() => {
+    if (syncedKey !== undefined || cart === undefined) return;
+    setSyncedKey(JSON.stringify(shippingSlice(cart?.shipping_address ?? {})));
+  }, [cart, syncedKey]);
+
+  const syncPending = syncedKey !== undefined && complete && sliceKey !== syncedKey;
+
+  useEffect(() => {
+    if (!syncPending || !cart || !cart.items?.length) return;
+    const t = setTimeout(async () => {
+      setSyncing(true);
+      setAddressError(null);
+      try {
+        await runCart(() => client.setShippingAddress(JSON.parse(sliceKey)));
+        setSyncedKey(sliceKey);
+      } catch (e) {
+        // Mark the address as seen either way — retrying the same failing
+        // address in a loop helps nobody; the customer editing it re-arms.
+        setSyncedKey(sliceKey);
+        setAddressError({
+          code: storefrontErrorCode(e) ?? "error",
+          message: storefrontErrorMessage(e),
+        });
+      } finally {
+        setSyncing(false);
+      }
+    }, debounceMs);
+    return () => clearTimeout(t);
+  }, [syncPending, sliceKey, cart, client, runCart, debounceMs]);
+
+  /** Force a re-sync of the current address (e.g. a "Recalculate" affordance). */
+  const recalculateShipping = useCallback(() => setSyncedKey("__stale__"), []);
+
+  // ── shipping choice (from the shared cart view) ──────────────────────────
+  const shippingStatus = cart?.shipping_status ?? null;
+  const shippingMethods = cart?.available_shipping_methods ?? [];
+  const chosenShippingMethod =
+    shippingMethods.find((m) => m.id === cart?.chosen_shipping_method) ?? null;
+  const chooseShippingMethod = useCallback(
+    (methodId) => runCart(() => client.chooseShippingMethod(methodId)),
+    [client, runCart],
+  );
+
+  // ── payment choice (gateways live on store info ONLY) ────────────────────
+  const paymentMethods = info?.payment_gateways ?? null;
+  useEffect(() => {
+    if (!paymentMethods) return;
+    if (paymentMethod && !paymentMethods.some((g) => g.slug === paymentMethod)) {
+      setPaymentMethod("");
+    } else if (!paymentMethod && paymentMethods.length === 1) {
+      setPaymentMethod(paymentMethods[0].slug); // one option is not a choice
+    }
+  }, [paymentMethods, paymentMethod]);
+  const selectedGateway = paymentMethods?.find((g) => g.slug === paymentMethod) ?? null;
+
+  // ── the gate ─────────────────────────────────────────────────────────────
+  const missingBilling = missingBillingFields(billing, requiredBillingFields);
+  const blockers = [];
+  if (cart === undefined) blockers.push("cart_loading");
+  else if (!cart || !cart.items?.length) blockers.push("empty_cart");
+  if (missingBilling.length) blockers.push("billing_incomplete");
+  if (shipToDifferent && !complete) blockers.push("shipping_address_incomplete");
+  if (syncPending || syncing) blockers.push("shipping_recalculating");
+  if (shippingStatus === "missing_address") blockers.push("shipping_address_required");
+  if (shippingStatus === "choice_required") blockers.push("shipping_method_required");
+  if (shippingStatus === "none_available" || addressError?.code === "shipping_not_available") {
+    blockers.push("shipping_not_available");
+  }
+  if (!paymentMethod) blockers.push("payment_method_required");
+  const canPlaceOrder = blockers.length === 0;
+
+  // ── place the order ──────────────────────────────────────────────────────
+  const placeOrder = useCallback(
+    async (extra = {}) => {
+      if (placing) return { ok: false, error: { code: "placing", message: "Order already being placed." } };
+      setPlacing(true);
+      setOrderError(null);
+      try {
+        const result = await client.placeOrder({
+          payment_method: paymentMethod,
+          billing,
+          ...(shipToDifferent ? { shipping } : {}),
+          ...extra, // customer_note, success_url/cancel_url overrides, …
+        });
+        clearCart(); // checkout consumed the cart
+        if (
+          redirectToPayment &&
+          result.payment?.status === "requires_payment" &&
+          typeof window !== "undefined"
+        ) {
+          window.location.assign(result.payment.checkout_url);
+        }
+        return { ok: true, result };
+      } catch (e) {
+        const error = {
+          code: storefrontErrorCode(e) ?? "error",
+          message: storefrontErrorMessage(e),
+        };
+        setOrderError(error);
+        // These mean the cart changed underneath the page — re-read it.
+        if (
+          ["items_unavailable", "coupon_invalid", "empty_cart",
+            "shipping_method_required", "invalid_shipping_method"].includes(error.code)
+        ) {
+          runCart(() => client.getCart()).catch(() => {});
+        }
+        return { ok: false, error };
+      } finally {
+        setPlacing(false);
+      }
+    },
+    [placing, client, paymentMethod, billing, shipToDifferent, shipping, clearCart, redirectToPayment, runCart],
+  );
+
+  return {
+    // form state
+    billing,
+    updateBilling,
+    shipping,
+    updateShipping,
+    shipToDifferent,
+    setShipToDifferent,
+    missingBillingFields: missingBilling,
+    // address → shipping/tax recalculation
+    shippingAddressComplete: complete,
+    shippingSyncing: syncPending || syncing,
+    addressError,
+    recalculateShipping,
+    // shipping choice
+    shippingStatus,
+    shippingMethods,
+    chosenShippingMethod,
+    chooseShippingMethod,
+    // payment choice
+    paymentMethods,
+    paymentMethod,
+    setPaymentMethod,
+    selectedGateway,
+    // the gate + the order
+    blockers,
+    canPlaceOrder,
+    placing,
+    orderError,
+    placeOrder,
+    // underlying data, for convenience
+    cart: cart ?? null,
+    storeInfo: info,
+  };
+}
+
+const CheckoutContext = createContext(null);
+
+/**
+ * Share one `useCheckout` between the components of a checkout page (address
+ * form, shipping step, payment step, summary, place-order button) without
+ * prop-drilling:
+ *
+ *   <CheckoutProvider>
+ *     <AddressFields />      // useCheckoutContext() inside
+ *     <ShippingMethodPicker>…</ShippingMethodPicker>
+ *     <PaymentMethodPicker>…</PaymentMethodPicker>
+ *     <PlaceOrderButton />
+ *   </CheckoutProvider>
+ *
+ * Pass `options` through to `useCheckout`, or pass an existing `checkout`
+ * object if the page already called the hook itself.
+ */
+export function CheckoutProvider({ checkout, options, children }) {
+  const own = useCheckout(options);
+  return (
+    <CheckoutContext.Provider value={checkout ?? own}>{children}</CheckoutContext.Provider>
+  );
+}
+
+/** The checkout shared by the nearest <CheckoutProvider>. */
+export function useCheckoutContext() {
+  const ctx = useContext(CheckoutContext);
+  if (!ctx) {
+    throw new Error(
+      "useCheckoutContext needs a <CheckoutProvider> above it (or pass the checkout object down yourself).",
+    );
+  }
+  return ctx;
+}
+
+/** Internal: context accessor that tolerates absence (for the pickers). */
+export function useCheckoutContextOptional() {
+  return useContext(CheckoutContext);
+}

package/src/commerce/storefront/useOrderReturn.js

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { useStorefrontState } from "./StorefrontProvider";
+
+/**
+ * useOrderReturn — the whole `/order-received` page in one hook. Mount the
+ * route (it is mandatory — every payment link returns here) and branch on
+ * `status`:
+ *
+ *   const { status, order, paymentLink, paymentInstructions, error, reload } =
+ *     useOrderReturn();
+ *   // "loading"   → spinner
+ *   // "paid"      → thank-you + order summary (the order is now marked paid)
+ *   // "unpaid"    → card order: offer paymentLink.url to pay now;
+ *   //               manual order: render paymentInstructions
+ *   //               ({ description, account_details })
+ *   // "cancelled" → payment was cancelled — offer paymentLink.url or support
+ *   // "error"     → render error.message with a retry via reload()
+ *
+ * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
+ * with the payment provider server-side — safe and idempotent on every visit.
+ *
+ * `order` carries FLAT totals — `order.total`, `order.shipping_total`,
+ * `order.total_tax`; there is no `order.totals` object on it.
+ */
+export function useOrderReturn({ auto = true } = {}) {
+  const { client } = useStorefrontState();
+  const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
+
+  const reload = useCallback(
+    async (params) => {
+      setResult({ status: "loading" });
+      try {
+        const res = await client.completeReturn(params);
+        setResult({
+          status: res.state, // "paid" | "unpaid" | "cancelled"
+          order: res.order,
+          paymentLink: res.payment_link ?? null,
+          paymentInstructions: res.payment_instructions ?? null,
+        });
+      } catch (e) {
+        setResult({
+          status: "error",
+          error: { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) },
+        });
+      }
+    },
+    [client],
+  );
+
+  useEffect(() => {
+    if (auto) reload();
+  }, [auto, reload]);
+
+  return { ...result, reload };
+}

package/src/commerce/utils/index.js

@@ -17,6 +17,12 @@
  * - `shipping-promos.js` — read the store's real free-shipping configuration so
  *   "Free shipping over €150" copy states a configured rule, not an invented
  *   number. See `.agents/skills/commerce/docs/api-storefront.md`.
+ *
+ * Building the storefront in React? `@/commerce/storefront` layers hooks on
+ * top of this module — a shared-cart provider, the guided-checkout hook
+ * (automatic shipping/tax recalculation on address changes), headless
+ * shipping/payment pickers and the order-received hook. Prefer those for cart
+ * and checkout; use this module directly for catalog views and non-React code.
  */
 export * from "./storefront.js";
 export * from "./variants.js";

package/src/commerce/utils/storefront.js

@@ -29,6 +29,13 @@ export function storefrontErrorCode(e) {
   return e?.response?.data?.code ?? e?.data?.code ?? e?.code ?? null;
 }
 
+/** The human-readable message a failed storefront call carries. */
+export function storefrontErrorMessage(e) {
+  return (
+    e?.response?.data?.error ?? e?.data?.error ?? e?.message ?? "Something went wrong."
+  );
+}
+
 export function createStorefront(base44, { storageKey = "cart_token", storage } = {}) {
   const bag = storage ?? (typeof localStorage !== "undefined" ? localStorage : null);
 
@@ -106,8 +113,8 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
     applyCoupon(code) {
       return cartAction("apply-coupon", { code });
     },
-    removeCoupon() {
-      return cartAction("remove-coupon");
+    removeCoupon(code) {
+      return cartAction("remove-coupon", { code });
     },
     /** Recalculates shipping options + cost; 400 shipping_not_available belongs on the address form. */
     setShippingAddress(address) {