@base44/app-plugin-commerce 0.1.0

package/src/commerce/admin/hooks/useAsync.js

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Run an async function on mount / when deps change.
+ * Returns { data, loading, error, refetch, refetchQuiet, setData }.
+ *
+ * `refetchQuiet` re-runs without flipping `loading`, so a background refresh
+ * (e.g. a realtime update) updates the numbers in place instead of flashing
+ * skeletons over content the user is already reading.
+ */
+export default function useAsync(fn, deps = []) {
+  const [state, setState] = useState({ data: null, loading: true, error: null });
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  const run = useCallback(async ({ quiet = false } = {}) => {
+    if (!quiet) setState((s) => ({ ...s, loading: true, error: null }));
+    try {
+      const data = await fnRef.current();
+      setState({ data, loading: false, error: null });
+      return data;
+    } catch (error) {
+      setState((s) => ({ ...s, loading: false, error }));
+      return undefined;
+    }
+  }, []);
+
+  useEffect(() => {
+    run();
+    // eslint-disable-next-line -- deps intentionally partial
+  }, deps);
+
+  // Note: `refetch` deliberately takes no arguments, so it stays safe to pass
+  // straight to an onClick handler without the event being read as options.
+  const refetch = useCallback(() => run(), [run]);
+  const refetchQuiet = useCallback(() => run({ quiet: true }), [run]);
+
+  const setData = useCallback((updater) => {
+    setState((s) => ({
+      ...s,
+      data: typeof updater === "function" ? updater(s.data) : updater,
+    }));
+  }, []);
+
+  return { ...state, refetch, refetchQuiet, setData };
+}

package/src/commerce/admin/hooks/useDebounce.js

@@ -0,0 +1,11 @@
+import { useEffect, useState } from "react";
+
+/** Debounce a changing value (default 300ms). */
+export default function useDebounce(value, delay = 300) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(t);
+  }, [value, delay]);
+  return debounced;
+}

package/src/commerce/admin/hooks/useMoney.js

@@ -0,0 +1,52 @@
+import { useCallback, useMemo } from "react";
+import { useSettings } from "../context/SettingsContext";
+import { CURRENCIES } from "../lib/constants";
+
+/**
+ * Currency formatter driven by the `general` settings group.
+ * Returns { format(n), symbol, code, decimals }.
+ */
+export default function useMoney() {
+  const settings = useSettings();
+
+  const cfg = useMemo(() => {
+    const get = settings?.get || (() => undefined);
+    const code = get("general", "currency", "USD");
+    const currency = CURRENCIES.find((cc) => cc.code === code);
+    return {
+      code,
+      symbol: currency?.symbol || code,
+      position: get("general", "currency_position", "left"),
+      thousandSep: get("general", "thousand_sep", ","),
+      decimalSep: get("general", "decimal_sep", "."),
+      decimals: get("general", "num_decimals", currency?.decimals ?? 2),
+    };
+  }, [settings]);
+
+  const format = useCallback(
+    (n) => {
+      const num = Number(n);
+      const val = isNaN(num) ? 0 : num;
+      const negative = val < 0;
+      const fixed = Math.abs(val).toFixed(cfg.decimals);
+      const [intPart, decPart] = fixed.split(".");
+      const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, cfg.thousandSep);
+      const amount = decPart ? grouped + cfg.decimalSep + decPart : grouped;
+      const sign = negative ? "-" : "";
+      switch (cfg.position) {
+        case "right":
+          return `${sign}${amount}${cfg.symbol}`;
+        case "left_space":
+          return `${sign}${cfg.symbol} ${amount}`;
+        case "right_space":
+          return `${sign}${amount} ${cfg.symbol}`;
+        case "left":
+        default:
+          return `${sign}${cfg.symbol}${amount}`;
+      }
+    },
+    [cfg]
+  );
+
+  return { format, symbol: cfg.symbol, code: cfg.code, decimals: cfg.decimals };
+}

package/src/commerce/admin/hooks/usePagedList.js

@@ -0,0 +1,83 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Paged listing over a fetcher(limit, skip, sortString) that returns an array.
+ * Uses the limit+1 probe to detect a next page (the SDK has no total count).
+ *
+ * Returns:
+ *   { rows, loading, error, page (1-based), hasNext, next, prev,
+ *     sort, setSort, refetch, refetchQuiet }
+ *
+ * `refetchQuiet` reloads the current page without flipping `loading` and keeps
+ * the existing rows if the request fails — so a background refresh (e.g. a
+ * realtime update) never blanks or flickers a table the user is reading.
+ *
+ * `deps`: when any dep changes (e.g. a filter), the list resets to page 1.
+ */
+export default function usePagedList(fetcher, { pageSize = 20, initialSort = "-created_date", deps = [] } = {}) {
+  const [page, setPage] = useState(0); // 0-based internally
+  const [sort, setSortState] = useState(initialSort);
+  const [state, setState] = useState({ rows: [], hasNext: false, loading: true, error: null });
+
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+
+  const load = useCallback(
+    async (p, s, { quiet = false } = {}) => {
+      if (!quiet) setState((st) => ({ ...st, loading: true }));
+      try {
+        const rows = (await fetcherRef.current(pageSize + 1, p * pageSize, s)) || [];
+        setState({
+          rows: rows.slice(0, pageSize),
+          hasNext: rows.length > pageSize,
+          loading: false,
+          error: null,
+        });
+      } catch (error) {
+        // A failed background refresh must not destroy what is on screen.
+        setState((st) =>
+          quiet
+            ? { ...st, loading: false, error }
+            : { rows: [], hasNext: false, loading: false, error }
+        );
+      }
+    },
+    [pageSize]
+  );
+
+  // Reset to first page when external deps (filters/search) change.
+  const depsKey = JSON.stringify(deps);
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    if (page !== 0) setPage(0);
+    else load(0, sort);
+    // eslint-disable-next-line -- deps intentionally partial
+  }, [depsKey]);
+
+  useEffect(() => {
+    load(page, sort);
+  }, [page, sort, load]);
+
+  const setSort = useCallback((s) => {
+    setPage(0);
+    setSortState(s);
+  }, []);
+
+  return {
+    rows: state.rows,
+    loading: state.loading,
+    error: state.error,
+    hasNext: state.hasNext,
+    page: page + 1,
+    next: () => state.hasNext && setPage((p) => p + 1),
+    prev: () => setPage((p) => Math.max(0, p - 1)),
+    sort,
+    setSort,
+    refetch: () => load(page, sort),
+    refetchQuiet: () => load(page, sort, { quiet: true }),
+  };
+}

package/src/commerce/admin/hooks/usePaymentProvider.js

@@ -0,0 +1,27 @@
+import useAsync from "./useAsync";
+import { call } from "../lib/api";
+
+/**
+ * Whether the store can take an online payment right now.
+ *
+ * Availability is a **live fact about the connected provider**, never a stored
+ * flag, so every payment affordance in the admin derives from this instead of
+ * hardcoding a "not wired" state. Which provider is wired is a backend concern
+ * (`base44/shared/commerce/payments.ts`); the UI only needs `connected`, and
+ * shows "No payment provider connected" rather than naming one.
+ *
+ * @returns {{connected: boolean, gatewaySlug: string, provider: string,
+ *            providerLabel: string, loading: boolean, refetch: Function}}
+ */
+export default function usePaymentProvider() {
+  const status = useAsync(() => call("admin-tools", "payment-connector-status", {}, { silent: true }), []);
+  return {
+    connected: !!status.data?.connected,
+    // "" until the backend answers — no provider name is hardcoded here.
+    gatewaySlug: status.data?.gateway_slug ?? "",
+    provider: status.data?.provider ?? "",
+    providerLabel: status.data?.provider_label ?? "",
+    loading: status.loading,
+    refetch: status.refetch,
+  };
+}

package/src/commerce/admin/hooks/useRealtime.js

@@ -0,0 +1,129 @@
+import { useEffect, useRef } from "react";
+import { base44 } from "../lib/api";
+
+/**
+ * Keep an admin view live: run `onChange` whenever the given entities change on
+ * the server, so new orders/refunds/stock appear without a manual refresh.
+ *
+ * Two mechanisms, deliberately belt-and-braces:
+ *
+ * 1. **Realtime push (primary).** `base44.entities[name].subscribe(cb)` joins a
+ *    socket room and receives create/update/delete events. The SDK sends the
+ *    session token on the socket handshake and the backend verifies room
+ *    access, so this only delivers for a signed-in admin — which is exactly who
+ *    sees these pages.
+ * 2. **Polling fallback (safety net).** A slow interval that **switches itself
+ *    off permanently the first time a realtime event arrives**. It exists
+ *    because push cannot be relied on for every write path: most commerce
+ *    writes happen inside backend functions under the service role, and if
+ *    those do not emit socket events, push alone would never fire. When push
+ *    works you pay one wasted poll at most; when it doesn't, the page is still
+ *    reactive.
+ *
+ * Other deliberate behaviours:
+ * - **Coalesces bursts** — one order transition can touch several entities, so
+ *   events are debounced into a single refresh.
+ * - **Respects a hidden tab** — nothing refreshes in the background; a pending
+ *   change triggers exactly one refresh when the tab is shown again. Returning
+ *   to the tab also refreshes, which is the case most users notice.
+ * - **Never breaks the page** — a missing `.subscribe` (older SDK) or a throwing
+ *   subscribe just leaves the fallback doing the work.
+ *
+ * @param {string|string[]} entities - entity name(s), e.g. "commerce.Order"
+ * @param {() => void} onChange - called (debounced) when a refresh is due
+ * @param {{enabled?: boolean, debounceMs?: number, fallbackPollMs?: number}} [options]
+ *   `fallbackPollMs` — poll cadence before push is proven; use a slower value
+ *   for scan-heavy endpoints (reports/dashboard) than for plain entity queries.
+ *   Set to 0 to disable the fallback entirely.
+ */
+export default function useRealtime(
+  entities,
+  onChange,
+  { enabled = true, debounceMs = 400, fallbackPollMs = 30000 } = {},
+) {
+  // Kept in a ref so callers can pass an inline closure without resubscribing.
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  const names = Array.isArray(entities) ? entities : [entities];
+  const namesKey = names.filter(Boolean).join("|");
+
+  useEffect(() => {
+    if (!enabled || !namesKey) return undefined;
+
+    let debounceTimer = null;
+    let pollTimer = null;
+    let pendingWhileHidden = false;
+    let sawPushEvent = false;
+    let disposed = false;
+
+    const refresh = () => {
+      if (disposed) return;
+      if (typeof document !== "undefined" && document.hidden) {
+        pendingWhileHidden = true;
+        return;
+      }
+      onChangeRef.current?.();
+    };
+
+    const schedule = () => {
+      if (disposed) return;
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(refresh, debounceMs);
+    };
+
+    // A push event proves realtime works for this deployment — stop polling.
+    const onPushEvent = () => {
+      if (!sawPushEvent) {
+        sawPushEvent = true;
+        clearInterval(pollTimer);
+        pollTimer = null;
+      }
+      schedule();
+    };
+
+    const unsubscribes = [];
+    for (const name of namesKey.split("|")) {
+      const entity = base44?.entities?.[name];
+      if (typeof entity?.subscribe !== "function") continue;
+      try {
+        const off = entity.subscribe(onPushEvent);
+        if (typeof off === "function") unsubscribes.push(off);
+      } catch {
+        /* fall back to polling */
+      }
+    }
+
+    if (fallbackPollMs > 0) {
+      pollTimer = setInterval(() => {
+        if (disposed || sawPushEvent) return;
+        if (typeof document !== "undefined" && document.hidden) return;
+        onChangeRef.current?.();
+      }, fallbackPollMs);
+    }
+
+    const onVisibilityChange = () => {
+      if (document.hidden) return;
+      // Coming back to the tab is the moment stale data is most obvious.
+      if (pendingWhileHidden || !sawPushEvent) {
+        pendingWhileHidden = false;
+        schedule();
+      }
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    return () => {
+      disposed = true;
+      clearTimeout(debounceTimer);
+      clearInterval(pollTimer);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      for (const off of unsubscribes) {
+        try {
+          off();
+        } catch {
+          /* ignore */
+        }
+      }
+    };
+  }, [namesKey, enabled, debounceMs, fallbackPollMs]);
+}

package/src/commerce/admin/index.jsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { Toaster } from "sonner";
+import AuthGuard from "./layout/AuthGuard";
+import AdminLayout from "./layout/AdminLayout";
+import AdminRoutes from "./routes";
+import { SettingsProvider } from "./context/SettingsContext";
+import { BasePathProvider } from "./context/BasePathContext";
+
+/**
+ * The store admin application.
+ *
+ * Mount inside your app's router:
+ *   <Route path="/admin/*" element={<AdminApp />} />
+ *
+ * If mounted somewhere other than /admin, pass the prefix:
+ *   <Route path="/backoffice/*" element={<AdminApp basePath="/backoffice" />} />
+ *
+ * Requires an authenticated user with role "admin" (enforced by AuthGuard,
+ * and independently by entity RLS + requireAdmin() in backend functions).
+ */
+export default function AdminApp({ basePath = "/admin" }) {
+  return (
+    <BasePathProvider value={basePath}>
+      <Toaster richColors position="top-right" />
+      <AuthGuard>
+        <SettingsProvider>
+          <AdminLayout>
+            <AdminRoutes />
+          </AdminLayout>
+        </SettingsProvider>
+      </AuthGuard>
+    </BasePathProvider>
+  );
+}

package/src/commerce/admin/layout/AccessDenied.jsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Lock, ShieldAlert } from "lucide-react";
+
+/**
+ * Access screens for the admin.
+ * variant="unauthenticated" → sign-in prompt (props: onLogin, timedOut)
+ * variant="forbidden"       → admin-role required (props: email, onLogout)
+ */
+export default function AccessDenied({ variant = "forbidden", email, onLogin, onLogout, timedOut = false }) {
+  const unauth = variant === "unauthenticated";
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-muted/30 p-4">
+      <Card className="w-full max-w-md text-center">
+        <CardHeader>
+          <div className="mx-auto mb-2 flex h-12 w-12 items-center justify-center rounded-full bg-muted">
+            {unauth ? (
+              <Lock className="h-6 w-6 text-muted-foreground" />
+            ) : (
+              <ShieldAlert className="h-6 w-6 text-destructive" />
+            )}
+          </div>
+          <CardTitle>{unauth ? "Sign in required" : "Admin access required"}</CardTitle>
+          <CardDescription>
+            {unauth
+              ? timedOut
+                ? "We couldn't confirm who you are. Sign in to continue — if this page is embedded in a preview pane, open it in its own browser tab first, since sign-in can't complete inside a frame."
+                : "You must sign in to access the store admin."
+              : "Your account does not have the admin role. Ask a store administrator to grant you access."}
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          {unauth ? (
+            <Button onClick={onLogin} className="w-full">
+              Sign in
+            </Button>
+          ) : (
+            <>
+              {email && (
+                <p className="text-sm text-muted-foreground">
+                  Signed in as <span className="font-medium">{email}</span>
+                </p>
+              )}
+              <Button variant="outline" onClick={onLogout} className="w-full">
+                Sign out
+              </Button>
+            </>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/src/commerce/admin/layout/AdminLayout.jsx

@@ -0,0 +1,33 @@
+import React, { useState } from "react";
+import { Sheet, SheetContent } from "@/components/ui/sheet";
+import Sidebar from "./Sidebar";
+import Topbar from "./Topbar";
+import StoreAdminBot from "../bot/StoreAdminBot";
+
+/** Shell: fixed sidebar (desktop) / sheet (mobile), topbar, scrollable main. */
+export default function AdminLayout({ children }) {
+  const [mobileOpen, setMobileOpen] = useState(false);
+  const [botOpen, setBotOpen] = useState(false);
+  const openBot = () => {
+    setMobileOpen(false);
+    setBotOpen(true);
+  };
+
+  return (
+    <div className="min-h-screen bg-muted/30">
+      <aside className="fixed inset-y-0 left-0 z-20 hidden w-60 border-r bg-background lg:block">
+        <Sidebar onOpenBot={openBot} />
+      </aside>
+      <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
+        <SheetContent side="left" className="w-60 p-0">
+          <Sidebar onNavigate={() => setMobileOpen(false)} onOpenBot={openBot} />
+        </SheetContent>
+      </Sheet>
+      <StoreAdminBot open={botOpen} onOpenChange={setBotOpen} />
+      <div className="flex min-h-screen flex-col lg:pl-60">
+        <Topbar onMenuClick={() => setMobileOpen(true)} />
+        <main className="flex-1 p-4 lg:p-6">{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/commerce/admin/layout/AuthGuard.jsx

@@ -0,0 +1,84 @@
+import React, { createContext, useContext, useEffect, useState } from "react";
+import { Loader2 } from "lucide-react";
+import { base44 } from "../lib/api";
+import AccessDenied from "./AccessDenied";
+
+const AuthContext = createContext(null);
+
+/** Current admin user (only available inside AuthGuard). */
+export function useAuth() {
+  return useContext(AuthContext);
+}
+
+/**
+ * How long to wait for the identity check before assuming "not signed in".
+ *
+ * `auth.me()` does not always settle: with no session the SDK may navigate to a
+ * login page instead of rejecting, and when the app is rendered inside an iframe
+ * (the Base44 editor's preview pane) that navigation is blocked — leaving the
+ * promise pending forever. Without this the whole admin sat on a spinner that
+ * looked like a broken install; now it falls through to the sign-in screen,
+ * which is both honest and actionable.
+ */
+const AUTH_CHECK_TIMEOUT_MS = 8000;
+
+/**
+ * Blocks the admin UI unless the caller is an authenticated user with
+ * role === "admin". Do NOT weaken this check — see skills/commerce/post-installation.md.
+ * (Server-side RLS + requireAdmin() in functions enforce this independently.)
+ *
+ * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants
+ * access, so the guard cannot be weakened by a slow or hanging identity check.
+ */
+export default function AuthGuard({ children }) {
+  const [state, setState] = useState({ loading: true, user: null, timedOut: false });
+
+  useEffect(() => {
+    let settled = false;
+    const finish = (next) => {
+      if (settled) return;
+      settled = true;
+      setState({ loading: false, ...next });
+    };
+    const timer = setTimeout(() => finish({ user: null, timedOut: true }), AUTH_CHECK_TIMEOUT_MS);
+
+    base44.auth
+      .me()
+      .then((user) => finish({ user, timedOut: false }))
+      .catch(() => finish({ user: null, timedOut: false }))
+      .finally(() => clearTimeout(timer));
+
+    return () => clearTimeout(timer);
+  }, []);
+
+  if (state.loading) {
+    return (
+      <div className="flex h-screen flex-col items-center justify-center gap-3">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+        <p className="text-xs text-muted-foreground">Checking your access…</p>
+      </div>
+    );
+  }
+
+  if (!state.user) {
+    return (
+      <AccessDenied
+        variant="unauthenticated"
+        timedOut={state.timedOut}
+        onLogin={() => base44.auth.loginWithProvider("google", window.location.pathname)}
+      />
+    );
+  }
+
+  if (state.user.role !== "admin") {
+    return (
+      <AccessDenied
+        variant="forbidden"
+        email={state.user.email}
+        onLogout={() => base44.auth.logout(window.location.pathname)}
+      />
+    );
+  }
+
+  return <AuthContext.Provider value={state.user}>{children}</AuthContext.Provider>;
+}