@tribe-nest/forge 1.13.0

package/src/contexts/PublicAuthContext.tsx

@@ -0,0 +1,333 @@
+"use client";
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useReducer, useState } from "react";
+import {
+  type ApiError,
+  type PublicAuthUser,
+  type UpdateLocalUserPayload,
+  type ActionMap,
+  type PublicAuthState,
+  type PublicAuthContextType,
+  type LoginInput,
+  type PublicCreateAccountInput,
+  Currency,
+} from "../types/models";
+import { useForge } from "../provider/ForgeProvider";
+import { useQuery } from "@tanstack/react-query";
+
+enum Types {
+  Initial = "INITIALIZE",
+  Login = "LOGIN",
+  Logout = "LOGOUT",
+  Register = "REGISTER",
+  Loading = "LOADING",
+  UpdateUser = "UPDATE_USER",
+  UpdateErrorMessage = "UPDATE_ERROR_MESSAGE",
+}
+export const ACCESS_TOKEN_KEY = "public-access-token";
+export const PUBLIC_ACCESS_TOKEN_KEY = "public-access-token";
+
+type AuthPayload = {
+  [Types.Initial]: { isAuthenticated: boolean; user: PublicAuthUser | null };
+  [Types.Login]: { user: PublicAuthUser | null };
+  [Types.Logout]: undefined;
+  [Types.Register]: { user: PublicAuthUser | null };
+  [Types.Loading]: { isLoading: boolean };
+  [Types.UpdateUser]: { data: UpdateLocalUserPayload };
+  [Types.UpdateErrorMessage]: { errorMessage: string | null };
+};
+
+export type AuthActions = ActionMap<AuthPayload>[keyof ActionMap<AuthPayload>];
+
+const initialState: PublicAuthState = {
+  isAuthenticated: false,
+  isInitialized: false,
+  user: null,
+  isLoading: false,
+  errorMessage: null,
+  initialize: () => Promise.resolve(false),
+  currencies: null,
+  userSelectedCurrency: null,
+  setUserSelectedCurrency: () => {},
+};
+
+const AuthReducer = (state: PublicAuthState, action: AuthActions): PublicAuthState => {
+  switch (action.type) {
+    case "INITIALIZE":
+      return {
+        ...state,
+        isAuthenticated: action.payload.isAuthenticated,
+        isInitialized: true,
+        user: action.payload.user,
+        isLoading: false,
+      };
+    case "LOGIN":
+      return {
+        ...state,
+        isAuthenticated: true,
+        user: action.payload.user,
+        isLoading: false,
+        errorMessage: null,
+      };
+    case "LOGOUT":
+      return {
+        ...state,
+        isAuthenticated: false,
+        user: null,
+        isLoading: false,
+        errorMessage: null,
+      };
+    case "REGISTER":
+      return {
+        ...state,
+        isAuthenticated: true,
+        user: action.payload.user,
+        isLoading: false,
+        errorMessage: null,
+      };
+    case Types.Loading:
+      return {
+        ...state,
+        isLoading: action.payload.isLoading,
+        errorMessage: action.payload.isLoading ? null : state.errorMessage,
+      };
+    case Types.UpdateUser:
+      return { ...state, user: { ...state.user!, ...action.payload.data } };
+    case Types.UpdateErrorMessage:
+      return { ...state, errorMessage: action.payload.errorMessage };
+    default:
+      return state;
+  }
+};
+
+const PublicAuthContext = createContext<PublicAuthContextType | null>(null);
+
+// ----------------------------------------------------------------------
+
+type AuthProviderProps = {
+  children: ReactNode;
+};
+
+function PublicAuthProvider({ children }: AuthProviderProps) {
+  // Root-level tenant/config comes from the single ForgeProvider (AppContext),
+  // not props or the Craft editor context.
+  const { client, profileId, setToken } = useForge();
+  const [state, dispatch] = useReducer(AuthReducer, initialState);
+  const [userSelectedCurrency, setUserSelectedCurrencyState] = useState<Currency | null>(null);
+
+  const setUserSelectedCurrency = useCallback((currency: Currency) => {
+    setUserSelectedCurrencyState(currency);
+    localStorage.setItem("userSelectedCurrency", currency);
+  }, []);
+
+  const { data: currencies } = useQuery({
+    // profileId scopes the cache — supportedCurrencies is narrowed to the tenant's
+    // connected account (must match useCurrencies' key so they share one fetch).
+    queryKey: ["public-currencies", profileId],
+    queryFn: async () => {
+      const response = await client.get("/public/currencies", { params: { profileId } });
+      return response.data;
+    },
+
+    enabled: !!client,
+    staleTime: 1000 * 60 * 60 * 2, // 2 hours
+  });
+
+  useEffect(() => {
+    if (currencies) {
+      const localStorageUserSelectedCurrency = localStorage.getItem("userSelectedCurrency") as Currency | null;
+      if (
+        localStorageUserSelectedCurrency &&
+        currencies?.supportedCurrencies.includes(localStorageUserSelectedCurrency as Currency)
+      ) {
+        setUserSelectedCurrencyState(localStorageUserSelectedCurrency as Currency);
+      } else {
+        const defaultCurrency = currencies?.supportedCurrencies.includes(currencies?.userCurrency ?? "")
+          ? currencies?.userCurrency
+          : "USD";
+        setUserSelectedCurrencyState(defaultCurrency);
+        if (defaultCurrency) {
+          localStorage.setItem("userSelectedCurrency", defaultCurrency);
+        }
+      }
+    }
+  }, [currencies]);
+
+  const initialize = useCallback(async () => {
+    try {
+      const accessToken = localStorage.getItem(ACCESS_TOKEN_KEY);
+      if (accessToken) {
+        setToken(accessToken);
+        const response = await client.get("/public/accounts/me", {
+          params: {
+            profileId: profileId,
+          },
+        });
+
+        dispatch({
+          type: Types.Initial,
+          payload: { isAuthenticated: true, user: response.data },
+        });
+        return true;
+      } else {
+        dispatch({
+          type: Types.Initial,
+          payload: { isAuthenticated: false, user: null },
+        });
+        return false;
+      }
+    } catch (error) {
+      console.error(error);
+      dispatch({
+        type: Types.Initial,
+        payload: { isAuthenticated: false, user: null },
+      });
+      return false;
+    }
+  }, [client, setToken, profileId]);
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  // Context-aware public auth: login runs against /public/sessions (scoped to
+  // this profile via associations). The global /sessions surface is left for the
+  // dashboard; it's also backwards-compatible (association-aware when a profileId
+  // is sent), so old sites keep working during the transition.
+  const login = async (data: LoginInput & { profileId: string }) => {
+    dispatch({ type: Types.Loading, payload: { isLoading: true } });
+
+    try {
+      const response = await client.post("/public/sessions", data);
+      const { token, account, smartLinkPath } = response.data;
+      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      setToken(token);
+      dispatch({ type: Types.Login, payload: { user: account } });
+      return { smartLinkPath };
+    } catch (err: unknown) {
+      const error = err as ApiError;
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      throw error;
+    }
+  };
+
+  const validateLoginCredentials = async (data: LoginInput & { profileId: string }) => {
+    const response = await client.post("/public/sessions", data);
+    return response.data.email as string;
+  };
+
+  const verifyLoginCode = async (email: string, code: string, profileId: string) => {
+    dispatch({ type: Types.Loading, payload: { isLoading: true } });
+
+    try {
+      const response = await client.post("/public/sessions/verify", { email, code, profileId });
+      const { token, account, smartLinkPath } = response.data;
+      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      setToken(token);
+      dispatch({ type: Types.Login, payload: { user: account } });
+      return { smartLinkPath };
+    } catch (err: unknown) {
+      const error = err as ApiError;
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      throw error;
+    }
+  };
+
+  const resendLoginCode = async (email: string) => {
+    // /public/sessions requires the profile context.
+    await client.post("/public/sessions/resend-code", { email, profileId });
+  };
+
+  const refetchUser = async () => {
+    try {
+      const response = await client.get("/accounts/me", {
+        params: {
+          profileId: profileId,
+        },
+      });
+      dispatch({
+        type: Types.Initial,
+        payload: { isAuthenticated: true, user: response.data },
+      });
+    } catch (error: unknown) {
+      console.error(error);
+      dispatch({
+        type: Types.Initial,
+        payload: { isAuthenticated: false, user: null },
+      });
+    }
+  };
+
+  const register = async (data: PublicCreateAccountInput) => {
+    dispatch({ type: Types.Loading, payload: { isLoading: true } });
+
+    try {
+      const response = await client.post("/public/accounts", {
+        ...data,
+      });
+      const { token, account, smartLinkPath } = response.data;
+      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      setToken(token);
+
+      dispatch({ type: Types.Register, payload: { user: account } });
+      return { smartLinkPath };
+    } catch (err: unknown) {
+      const error = err as ApiError;
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      throw error;
+    }
+  };
+
+  const logout = async (persist = true) => {
+    try {
+      localStorage.removeItem(ACCESS_TOKEN_KEY);
+      dispatch({ type: Types.Logout });
+      if (persist) await client.delete("/sessions");
+    } catch (error) {
+      console.error();
+    }
+  };
+
+  const updateLocalUser = (data: UpdateLocalUserPayload) => {
+    dispatch({ type: Types.UpdateUser, payload: { data } });
+  };
+
+  const clearErrorMessage = () => {
+    dispatch({
+      type: Types.UpdateErrorMessage,
+      payload: { errorMessage: null },
+    });
+  };
+
+  return (
+    <PublicAuthContext.Provider
+      value={{
+        ...state,
+        login,
+        validateLoginCredentials,
+        verifyLoginCode,
+        resendLoginCode,
+        logout,
+        register,
+        updateLocalUser,
+        clearErrorMessage,
+        refetchUser,
+        initialize,
+        currencies,
+        userSelectedCurrency,
+        setUserSelectedCurrency,
+      }}
+    >
+      {children}
+    </PublicAuthContext.Provider>
+  );
+}
+
+export const usePublicAuth = () => {
+  const context = useContext(PublicAuthContext);
+  if (!context) {
+    throw new Error("usePublicAuth must be used within a PublicAuthProvider");
+  }
+  return context;
+};
+
+export { PublicAuthContext, PublicAuthProvider };

package/src/contexts/useAppAdminGuard.ts

@@ -0,0 +1,56 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { useForge } from "../provider/ForgeProvider";
+import { usePublicAuth } from "./PublicAuthContext";
+
+// Guards a mini-app's /admin routes. App admins are NOT app users — they are the
+// owner + profile team members with a Work grant on the app (see §19). They log
+// into the app site with their normal TribeNest account (the profile public-auth
+// flow, usePublicAuth), and this hook asks the backend whether that account may
+// reach /admin: GET /public/apps/:appId/admin-access → { isAdmin, permission }.
+//
+// Usage in the app-starter's /admin layout:
+//   const { isAdmin, isLoading, isAuthenticated } = useAppAdminGuard();
+//   if (isLoading) return <Spinner/>;
+//   if (!isAuthenticated) return <Navigate to="/admin/login"/>;
+//   if (!isAdmin) return <NotAuthorized/>;
+
+export interface AppAdminGuardResult {
+  /** True while auth is initializing or the access check is in flight. */
+  isLoading: boolean;
+  /** Whether a TribeNest account is logged in (via the profile public-auth flow). */
+  isAuthenticated: boolean;
+  /** Whether the logged-in account may access this app's /admin. */
+  isAdmin: boolean;
+  /** The highest permission the account holds on the app (or null). */
+  permission: string | null;
+  appName: string | null;
+  refetch: () => void;
+}
+
+export function useAppAdminGuard(): AppAdminGuardResult {
+  const { appId, client } = useForge();
+  const { isAuthenticated, isInitialized } = usePublicAuth();
+
+  const query = useQuery({
+    queryKey: ["app-admin-access", appId],
+    // Only ask once we know there's a logged-in account and we have an appId.
+    enabled: !!appId && isInitialized && isAuthenticated,
+    staleTime: 60_000,
+    queryFn: async () => {
+      const res = await client.get(`/public/apps/${appId}/admin-access`);
+      return res.data as { isAdmin: boolean; permission: string | null; appName: string | null };
+    },
+  });
+
+  const isLoading = !isInitialized || (isAuthenticated && query.isPending);
+
+  return {
+    isLoading,
+    isAuthenticated,
+    isAdmin: isAuthenticated ? !!query.data?.isAdmin : false,
+    permission: query.data?.permission ?? null,
+    appName: query.data?.appName ?? null,
+    refetch: query.refetch,
+  };
+}

package/src/css.d.ts

@@ -0,0 +1,5 @@
+// Ambient declaration so Forge source can side-effect-import .css files
+// (e.g. ui/styled/rich-text.css) under `tsc --noEmit` and vitest. Consumer apps
+// (site-starter forks) already cover this via `vite/client` types; this file
+// covers Forge's own type-check, which doesn't load Vite's ambient types.
+declare module "*.css";

package/src/data/collectionParams.ts

@@ -0,0 +1,57 @@
+import type { CollectionQueryParams, CollectionQuery } from "../types/models";
+
+// Serialize the flat CollectionQueryParams into bracketed query keys that the
+// backend's qs parser re-nests (filter[key]=a,b / range[key][gte]=5 / near=lat,lng).
+// Used by the simple GET /entries reads (useCollectionEntries + SSR). React-free
+// so the hook and the SSR server fetcher share it.
+export function collectionParamsToQuery(
+  profileId: string | undefined,
+  params?: CollectionQueryParams,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (profileId) out.profileId = profileId;
+  out.page = String(params?.page ?? 1);
+  out.limit = String(params?.limit ?? 20);
+
+  if (params?.q) out.q = params.q;
+  if (params?.sort) out.sort = params.sort;
+  if (params?.facets?.length) out.facets = params.facets.join(",");
+
+  if (params?.near) {
+    out.near = `${params.near.lat},${params.near.lng}`;
+    if (params.near.radius != null) out.radius = String(params.near.radius);
+  }
+
+  for (const [key, val] of Object.entries(params?.filter ?? {})) {
+    const values = Array.isArray(val) ? val : [val];
+    const cleaned = values.filter((v) => v != null && v !== "");
+    if (cleaned.length) out[`filter[${key}]`] = cleaned.join(",");
+  }
+
+  for (const [key, r] of Object.entries(params?.range ?? {})) {
+    if (r?.gte != null) out[`range[${key}][gte]`] = String(r.gte);
+    if (r?.lte != null) out[`range[${key}][lte]`] = String(r.lte);
+  }
+
+  return out;
+}
+
+/** Stable key for React Query caching (sorted so param order doesn't matter). */
+export function collectionParamsKey(params?: CollectionQueryParams): string {
+  const q = collectionParamsToQuery(undefined, params);
+  return Object.keys(q)
+    .sort()
+    .map((k) => `${k}=${q[k]}`)
+    .join("&");
+}
+
+/** Split a rich CollectionQuery into the { scope, query } POST body shape. */
+export function splitCollectionQuery(query?: CollectionQuery): { scope?: "public" | "mine"; query: Omit<CollectionQuery, "scope"> } {
+  const { scope, ...rest } = query ?? {};
+  return { scope, query: rest };
+}
+
+/** Stable cache key for a rich CollectionQuery. */
+export function collectionQueryKey(query?: CollectionQuery): string {
+  return JSON.stringify(query ?? {});
+}

package/src/data/queries/useAccount.ts

@@ -0,0 +1,71 @@
+import type { IPublicOrder, IPublicPost, PaginatedData } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+/** Orders placed by the signed-in member on this profile. */
+export function useUserOrders(accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<IPublicOrder[]>({
+    queryKey: ["user-orders", accountId, profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/orders", {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+/** Posts the signed-in member has saved/bookmarked. */
+export function useSavedPosts(accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<IPublicPost>>({
+    queryKey: ["saved-posts", accountId, profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/posts/saved", {
+        params: { accountId, profileId },
+      });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+export type NotificationPreferences = {
+  newPosts: boolean;
+  chatMessages: boolean;
+};
+
+/** The member's notification-type preferences for this profile. */
+export function useNotificationPreferences(enabled = true) {
+  const { client, profileId } = useForge();
+
+  return useQuery<{ preferences?: Partial<NotificationPreferences> }>({
+    queryKey: ["notification-preferences", profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/notifications/preferences`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && enabled,
+  });
+}
+
+/** Update one notification-type preference. */
+export function useUpdateNotificationPreference() {
+  const { client, profileId } = useForge();
+
+  return useMutation<unknown, unknown, { key: keyof NotificationPreferences; value: boolean }>({
+    mutationFn: async ({ key, value }) => {
+      const res = await client.put(`/public/notifications/preferences`, {
+        profileId,
+        preferences: { [key]: value },
+      });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useAccountSettings.ts

@@ -0,0 +1,82 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useMutation, useQuery } from "@tanstack/react-query";
+
+// Self-service account management for the signed-in member.
+
+export type AccountDeletionStatus = {
+  deletionRequest?: { scheduledDeletionAt: string } | null;
+};
+
+/** Whether the member has a pending account-deletion request. */
+export function useAccountDeletionStatus(enabled = true) {
+  const { client } = useForge();
+
+  return useQuery<AccountDeletionStatus>({
+    queryKey: ["account-deletion-status"],
+    queryFn: async () => {
+      const res = await client.get("/public/accounts/me/deletion-status");
+      return res.data;
+    },
+    enabled: !!client && enabled,
+  });
+}
+
+/** Export the member's data (returns the JSON payload to download). */
+export function useExportAccountData() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.get("/public/accounts/me/export");
+      return res.data;
+    },
+  });
+}
+
+/** Request account deletion (30-day grace). Returns the scheduled date. */
+export function useRequestAccountDeletion() {
+  const { client } = useForge();
+
+  return useMutation<{ scheduledDeletionAt: string }, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.post("/public/accounts/me/request-deletion");
+      return res.data;
+    },
+  });
+}
+
+/** Cancel a pending account-deletion request. */
+export function useCancelAccountDeletion() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, void>({
+    mutationFn: async () => {
+      const res = await client.post("/public/accounts/me/cancel-deletion");
+      return res.data;
+    },
+  });
+}
+
+/** Update the member's profile (name). */
+export function useUpdateAccount() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { firstName: string; lastName: string }>({
+    mutationFn: async (body) => {
+      const res = await client.put("/public/accounts/me", body);
+      return res.data;
+    },
+  });
+}
+
+/** Change the member's password. */
+export function useChangePassword() {
+  const { client } = useForge();
+
+  return useMutation<unknown, unknown, { currentPassword: string; newPassword: string }>({
+    mutationFn: async (body) => {
+      const res = await client.put("/public/accounts/password", body);
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useAnalytics.ts

@@ -0,0 +1,86 @@
+import { useCallback } from "react";
+import { useForge } from "../../provider/ForgeProvider";
+
+/** Generate an id for de-duping a browser-side Meta pixel event against its
+ * server-side CAPI twin, and for correlating first-party events. */
+export function newEventId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  // Fallback for older runtimes — not cryptographically strong, only needs to be
+  // unique enough to pair a pixel + CAPI event.
+  return `evt_${Date.now().toString(36)}_${Math.abs(hashString(String(performance?.now?.() ?? Date.now()))).toString(36)}`;
+}
+
+function hashString(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+  return h;
+}
+
+/**
+ * Read (creating if absent) the per-visitor session id. Scoped to the tenant
+ * subdomain and stored in `sessionStorage`, matching the platform's website
+ * analytics so a code site's visits aggregate alongside CMS sites in the same
+ * admin dashboard. Returns `null` on the server.
+ */
+export function getAnalyticsSessionId(subdomain: string): string | null {
+  if (typeof window === "undefined" || !subdomain) return null;
+  const key = `tribe_nest_website_${subdomain}_session_id`;
+  try {
+    let sessionId = window.sessionStorage.getItem(key);
+    if (!sessionId) {
+      sessionId = `${subdomain}_${Date.now()}`;
+      window.sessionStorage.setItem(key, sessionId);
+    }
+    return sessionId;
+  } catch {
+    // Private mode / storage disabled — fall back to an ephemeral per-load id.
+    return `${subdomain}_${Date.now()}`;
+  }
+}
+
+export interface TrackEventOptions {
+  /** Override the tenant subdomain (defaults to the one on ForgeProvider). */
+  subdomain?: string;
+  /**
+   * Store a session id in `sessionStorage` and send it with events. Default
+   * `true`. Set `false` for cookieless, Plausible-style analytics: nothing is
+   * written to the device and no id is sent — the backend derives a rotating
+   * per-day visitor hash instead, so the "visits" metric still works without
+   * needing storage consent.
+   */
+  storeSession?: boolean;
+}
+
+/**
+ * The first-party website-analytics primitive. Returns a `track(eventType,
+ * eventData)` function that posts to `POST /public/websites/track-event` — the
+ * same feed the platform's admin analytics dashboard reads (visits, page views,
+ * clicks, geo). The backend enriches each event with geo-IP + user agent.
+ *
+ * This is the headless building block behind `<ForgeAnalytics />`; a creator (or
+ * the agent) can call it directly to record custom events, e.g.
+ * `const { track } = useTrackEvent(); track("cta_click", { id: "hero" })`.
+ */
+export function useTrackEvent(opts?: TrackEventOptions) {
+  const { client, subdomain: ctxSubdomain } = useForge();
+  const subdomain = opts?.subdomain ?? ctxSubdomain;
+  const storeSession = opts?.storeSession ?? true;
+
+  const track = useCallback(
+    (eventType: string, eventData: Record<string, unknown> = {}) => {
+      if (typeof window === "undefined" || !client || !subdomain) return;
+      // Cookieless mode omits the sessionId entirely — the backend derives a
+      // rotating per-day visitor hash so nothing touches the device.
+      const sessionId = storeSession ? getAnalyticsSessionId(subdomain) : undefined;
+      const payload: Record<string, unknown> = { ...eventData };
+      if (sessionId) payload.sessionId = sessionId;
+      // Fire-and-forget: analytics must never block the UI or surface errors.
+      client
+        .post("/public/websites/track-event", { subdomain, eventType, eventData: payload })
+        .catch(() => {});
+    },
+    [client, subdomain, storeSession],
+  );
+
+  return { track };
+}