@base44/app-plugin-commerce 0.1.8 → 0.1.12

package/src/commerce/utils/storefront.js

@@ -0,0 +1,139 @@
+/**
+ * Storefront API client — the thin layer between the visitor UI you build and
+ * the commerce/storefront-* functions. Framework-free. Create it ONCE and
+ * import that instance everywhere (wrapping it in a React context is fine —
+ * never create a second copy):
+ *
+ *   // src/lib/storefront.js
+ *   import { createStorefront } from "@/commerce/utils";
+ *   import { base44 } from "@/api/base44Client";
+ *   export const store = createStorefront(base44);
+ *
+ * It owns the two things hand-rolled clients keep getting wrong:
+ *
+ * - The cart_token lifecycle: the token is sent with every cart/checkout call
+ *   and re-persisted from every response (a stale token silently starts a
+ *   fresh cart), and it is cleared when checkout consumes the cart.
+ * - The store-info split: payment_gateways, currency, countries/currencies
+ *   live ONLY on get-store-info — the cart view never carries them.
+ *   getStoreInfo() caches the call; read them from there, never off a cart.
+ */
+
+/** The stable error code a failed storefront call carries, if any. */
+export function storefrontErrorCode(e) {
+  return e?.response?.data?.code ?? e?.data?.code ?? e?.code ?? null;
+}
+
+export function createStorefront(base44, { storageKey = "cart_token", storage } = {}) {
+  const bag = storage ?? (typeof localStorage !== "undefined" ? localStorage : null);
+
+  // Every function returns the envelope { success, data }; with the SDK the
+  // payload is res.data.data. Exposed for calls beyond the methods below.
+  const inv = (fn, payload) =>
+    base44.functions.invoke(fn, payload).then((r) => r.data.data);
+
+  const token = () => bag?.getItem(storageKey) || undefined;
+  const remember = (cart) => {
+    // ALWAYS re-persist — the backend may have started a fresh cart.
+    if (cart?.cart_token && bag) bag.setItem(storageKey, cart.cart_token);
+    return cart;
+  };
+  const forget = () => bag?.removeItem(storageKey);
+
+  const cartAction = (action, payload = {}) =>
+    inv("commerce/storefront-cart", { action, cart_token: token(), ...payload }).then(remember);
+
+  let infoPromise = null;
+
+  return {
+    inv,
+
+    // ── store info (cached) ──────────────────────────────────────────────
+    /** settings, payment_gateways, countries, currencies — this call ONLY. */
+    getStoreInfo() {
+      infoPromise ??= inv("commerce/storefront-catalog", { action: "get-store-info" })
+        .catch((e) => { infoPromise = null; throw e; });
+      return infoPromise;
+    },
+
+    // ── catalog ──────────────────────────────────────────────────────────
+    listProducts(params = {}) {
+      return inv("commerce/storefront-catalog", { action: "list-products", ...params });
+    },
+    /** getProduct("slug") or getProduct({ id }) */
+    getProduct(ref) {
+      const by = typeof ref === "string" ? { slug: ref } : ref;
+      return inv("commerce/storefront-catalog", { action: "get-product", ...by });
+    },
+    listCategories() {
+      return inv("commerce/storefront-catalog", { action: "list-categories" });
+    },
+    listRibbons() {
+      return inv("commerce/storefront-catalog", { action: "list-ribbons" });
+    },
+
+    // ── cart (token handled internally; every call returns the full view) ─
+    /** The current cart view, or null when there is none (an expired token self-clears). */
+    async getCart() {
+      if (!token()) return null;
+      try {
+        return await cartAction("get");
+      } catch (e) {
+        if (["cart_not_found", "cart_expired"].includes(storefrontErrorCode(e))) {
+          forget();
+          return null;
+        }
+        throw e;
+      }
+    },
+    /** addItem(view.addToCart) — a product with attributes needs the resolved variation_id. */
+    addItem(item) {
+      return cartAction("add-item", { quantity: 1, ...item });
+    },
+    updateItem(item_key, quantity) {
+      return cartAction("update-item", { item_key, quantity }); // ≤0 removes
+    },
+    removeItem(item_key) {
+      return cartAction("remove-item", { item_key });
+    },
+    applyCoupon(code) {
+      return cartAction("apply-coupon", { code });
+    },
+    removeCoupon() {
+      return cartAction("remove-coupon");
+    },
+    /** Recalculates shipping options + cost; 400 shipping_not_available belongs on the address form. */
+    setShippingAddress(address) {
+      return cartAction("set-shipping-address", { address });
+    },
+    chooseShippingMethod(method_id) {
+      return cartAction("choose-shipping-method", { method_id });
+    },
+
+    // ── checkout & return page ───────────────────────────────────────────
+    /** place-order; on success the cart is consumed, so the stored token is cleared. */
+    async placeOrder(details) {
+      const res = await inv("commerce/storefront-checkout", {
+        action: "place-order",
+        cart_token: token(),
+        return_url: typeof location !== "undefined" ? location.origin : undefined,
+        ...details,
+      });
+      forget();
+      return res;
+    },
+    /** The whole /order-received page in one call — pass nothing to read the URL params. */
+    completeReturn(params) {
+      const q = params ?? (typeof location !== "undefined"
+        ? new URLSearchParams(location.search)
+        : new URLSearchParams());
+      return inv("commerce/payments", {
+        action: "complete-return",
+        order_id: q.get("order_id"),
+        order_key: q.get("order_key"),
+        payment: q.get("payment") ?? undefined,
+        return_url: typeof location !== "undefined" ? location.origin : undefined,
+      });
+    },
+  };
+}