@tribe-nest/forge 3.60.0 → 3.63.0

package/src/ui/headless/siteApp/index.ts

@@ -0,0 +1,58 @@
+// The site app (one installable app per website): the bar model, the home
+// sections, and the install and notification prompts.
+export {
+  APP_BAR_HREFS,
+  buildAppBar,
+  isAppBarItemActive,
+  normaliseBarItems,
+  type AppBarItem,
+  type AppBarKey,
+  type AppBarModel,
+} from "./appBar";
+export {
+  APP_HOME_LIST_LIMIT,
+  APP_PORTAL_TILES,
+  attentionAction,
+  buildAppHomeSections,
+  buildPortalTiles,
+  courseProgress,
+  greetingPart,
+  isSafeLinkHref,
+  pickLearningCourse,
+  pickNextCall,
+  pickNextTicket,
+  upcomingEvents,
+  type AppAttentionAction,
+  type AppCommunityCard,
+  type AppCourseProgress,
+  type AppHomeData,
+  type AppHomeSectionView,
+  type AppLearningCourse,
+  type AppNextCall,
+  type AppNextTicket,
+  type AppPortalTile,
+  type AppPortalTileKey,
+} from "./appHome";
+export { useAppHome, useAppCommunityUnread, type UseAppHomeResult } from "./useAppHome";
+export { useAppInstallRequest } from "./useAppInstallRequest";
+export {
+  APP_INSTALL_CONTEXTS,
+  APP_INSTALL_SNOOZE_MS,
+  APP_PUSH_CATEGORIES,
+  clearPendingAppInstall,
+  decideAppInstall,
+  decideAppPush,
+  pushPreferencePatch,
+  readInstallDismissedAt,
+  readPendingAppInstall,
+  readPushAnswer,
+  rememberInstallDismissed,
+  rememberPushAnswer,
+  requestAppInstall,
+  subscribeAppInstallRequests,
+  type AppInstallContext,
+  type AppInstallMode,
+  type AppInstallRequest,
+  type AppPushAnswer,
+  type AppPushCategoryKey,
+} from "./appPrompts";

package/src/ui/headless/siteApp/useAppHome.ts

@@ -0,0 +1,210 @@
+import { useContext, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import {
+  SITE_APP_DEFAULT_SECTIONS,
+  useSiteApp,
+  type SiteAppHomeSection,
+  type SiteAppSectionKey,
+} from "../../../data/queries/useSiteApp";
+import { useMyCommunityMemberships, usePublicCommunities } from "../../../data/queries/useCommunities";
+import { communityKeys } from "../../../data/queries/useCommunity";
+import { useMyBookings } from "../../../data/queries/useMyBookings";
+import { useMyTickets } from "../../../data/queries/useMyTickets";
+import { useMyCourses } from "../../../data/queries/useMyCourses";
+import { useCourseAccess } from "../../../data/queries/useCourseAccess";
+import { useGetCourses } from "../../../data/queries/useCourses";
+import { useGetProducts } from "../../../data/queries/useProducts";
+import { membershipCallKeys, type MyMembershipCall } from "../../../data/queries/useMembershipCalls";
+import type { IEvent } from "../../../types/models";
+import { internalPath } from "../../../runtime/pages";
+import { getMembershipAccess } from "../../../utils/membershipAccess";
+import { usePortalSummary } from "../portal/usePortal";
+import { communityAboutPath, communityHomePath } from "../communities/paths";
+import {
+  buildAppHomeSections,
+  buildPortalTiles,
+  courseProgress,
+  pickLearningCourse,
+  pickNextCall,
+  pickNextTicket,
+  upcomingEvents,
+  type AppCommunityCard,
+  type AppHomeSectionView,
+  type AppLearningCourse,
+} from "./appHome";
+
+export interface UseAppHomeResult {
+  /** The settings or the account are still being read: draw a loading state. */
+  isLoading: boolean;
+  /** Signed out: the home is the sign-in screen. */
+  isSignedIn: boolean;
+  /** The app's name (the website's, unless the creator renamed the app). */
+  appName: string | null;
+  iconUrl: string | null;
+  /** The member's first name, for the greeting. */
+  firstName: string | null;
+  /** The sections to draw, in order. Empty while loading. */
+  sections: AppHomeSectionView[];
+}
+
+/**
+ * The data behind the site app's home (`/i/app`).
+ *
+ * Reads the website's app settings, then only what the configured sections
+ * need: a section the creator hid costs no request. Signed out, nothing
+ * member-shaped is fetched at all. Built on the same public hooks the portal
+ * and the communities use, so the home never disagrees with the page a tile
+ * opens. `buildAppHomeSections` decides order, visibility and the empty-skip.
+ */
+export function useAppHome(opts: { now?: Date } = {}): UseAppHomeResult {
+  const { client, profileId } = useForge();
+  const auth = useContext(PublicAuthContext);
+  const user = auth?.user ?? null;
+  const signedIn = !!user;
+  const now = opts.now ?? new Date();
+
+  const app = useSiteApp();
+  // An unknown host (a preview) answers 404: the contract's defaults stand in.
+  const config: readonly SiteAppHomeSection[] | undefined =
+    app.data?.homeSections ?? (app.isError ? SITE_APP_DEFAULT_SECTIONS : undefined);
+  const wants = (key: SiteAppSectionKey) =>
+    !!config?.some((entry) => entry.type === "builtin" && entry.key === key && entry.visible !== false);
+
+  const summary = usePortalSummary();
+  const sectionsCount = summary.data?.sections;
+
+  const wantsCommunities = wants("communities") || wants("explore_communities");
+  const mine = useMyCommunityMemberships({ enabled: signedIn && wantsCommunities });
+  const everyCommunity = usePublicCommunities({ enabled: wantsCommunities });
+
+  const comingUp = signedIn && wants("coming_up");
+  const calls = useQuery<MyMembershipCall[]>({
+    // The member's whole call calendar, across communities and courses.
+    queryKey: [...membershipCallKeys.mine(profileId), "now", "open", "app-home", user?.id ?? null],
+    queryFn: async () =>
+      (await client.get("/public/scheduled-calls/mine", { params: { profileId, limit: 5 } })).data as MyMembershipCall[],
+    enabled: comingUp && !!profileId && !!client,
+    refetchInterval: 60_000,
+  });
+  const bookings = useMyBookings(comingUp && (sectionsCount?.bookings ?? 0) > 0 ? user?.id : undefined, 1, 20);
+  const tickets = useMyTickets(comingUp && (sectionsCount?.tickets ?? 0) > 0 ? user?.id : undefined, 1, 20);
+
+  const myCourses = useMyCourses({ accountId: user?.id, enabled: signedIn && wants("learning") });
+  const learningCourse = pickLearningCourse(myCourses.data);
+  const access = useCourseAccess(learningCourse?.accessId);
+
+  const wantsEvents = wants("events");
+  const events = useQuery<IEvent[]>({
+    queryKey: ["events", profileId],
+    queryFn: async () => (await client.get("/public/events", { params: { profileId } })).data as IEvent[],
+    enabled: wantsEvents && !!profileId && !!client,
+  });
+  const courses = useGetCourses(undefined, wants("courses"));
+  const products = useGetProducts(undefined, wants("shop"));
+
+  const sections = useMemo(() => {
+    if (!config) return [];
+    const byId = new Map((everyCommunity.data ?? []).map((community) => [community.id, community]));
+    const memberships = (mine.data ?? []).filter(
+      (row) => getMembershipAccess({ status: row.status, cancelAtPeriodEnd: !!row.cancelAtPeriodEnd }).hasAccess,
+    );
+    const joined = new Set(memberships.map((row) => row.community.id));
+    const communities: AppCommunityCard[] = memberships.map((row) => {
+      const full = byId.get(row.community.id);
+      return {
+        id: row.community.id,
+        name: row.community.name,
+        slug: row.community.slug,
+        logoUrl: full?.logoUrl ?? null,
+        coverUrl: full?.coverUrl ?? null,
+        tierName: row.tierName ?? row.membershipTier?.name ?? null,
+        memberCount: full?.memberCount ?? null,
+        href: communityHomePath(row.community.slug),
+      };
+    });
+    // Signed out, or a membership read that failed, lists nothing as "yours";
+    // explore then shows every community rather than none.
+    const explore: AppCommunityCard[] = (everyCommunity.data ?? [])
+      .filter((community) => !joined.has(community.id) && !(mine.data ?? []).some((row) => row.community.id === community.id))
+      .map((community) => ({
+        id: community.id,
+        name: community.name,
+        slug: community.slug,
+        logoUrl: community.logoUrl,
+        coverUrl: community.coverUrl,
+        tierName: null,
+        memberCount: community.memberCount,
+        href: communityAboutPath(community.slug),
+        joinMode: community.joinMode ?? "open",
+      }));
+    const learning: AppLearningCourse | null = learningCourse
+      ? {
+          accessId: learningCourse.accessId,
+          title: learningCourse.title,
+          href: internalPath("course-access/$accessId", { accessId: learningCourse.accessId }),
+          progress: courseProgress(access.data),
+        }
+      : null;
+    return buildAppHomeSections(config, {
+      attention: summary.data?.attention ?? [],
+      portalTiles: buildPortalTiles(summary.data),
+      communities,
+      nextCall: pickNextCall(calls.data, bookings.data?.data, now),
+      nextTicket: pickNextTicket(tickets.data?.data, now),
+      learning,
+      explore,
+      events: upcomingEvents(events.data, now),
+      courses: courses.data?.data ?? [],
+      products: products.data?.data ?? [],
+    });
+    // `now` is read per render on purpose; the inputs below are what change the answer.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    config,
+    everyCommunity.data,
+    mine.data,
+    learningCourse,
+    access.data,
+    summary.data,
+    calls.data,
+    bookings.data,
+    tickets.data,
+    events.data,
+    courses.data,
+    products.data,
+  ]);
+
+  const authReady = auth ? auth.isInitialized !== false : true;
+  const isLoading = !config || !authReady || (signedIn && summary.isLoading);
+
+  return {
+    isLoading,
+    isSignedIn: signedIn,
+    appName: app.data?.appName ?? null,
+    iconUrl: app.data?.iconUrl ?? null,
+    firstName: user?.firstName?.trim() || null,
+    sections: isLoading ? [] : sections,
+  };
+}
+
+/**
+ * Unread notifications in one community, for its card on the app home. The
+ * same request and cache entry as the community's own bell, so opening the
+ * community and coming back shows the same number.
+ */
+export function useAppCommunityUnread(communityId: string | undefined, enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<number>({
+    queryKey: communityKeys.unread(communityId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/notifications", {
+        params: { profileId, communityId, page: 1, limit: 1, unreadOnly: true },
+      });
+      return res.data.unreadCount as number;
+    },
+    enabled: enabled && !!profileId && !!communityId && !!client,
+    refetchInterval: 30_000,
+  });
+}

package/src/ui/headless/siteApp/useAppInstallRequest.ts

@@ -0,0 +1,16 @@
+import { useEffect, useRef } from "react";
+import { requestAppInstall, type AppInstallContext } from "./appPrompts";
+
+/**
+ * Ask for the app install once, the first time `ready` is true (a payment
+ * confirmed, a booking confirmed). For a success that is a callback rather
+ * than a state, call `requestAppInstall` directly.
+ */
+export function useAppInstallRequest(ready: boolean, context: AppInstallContext): void {
+  const asked = useRef(false);
+  useEffect(() => {
+    if (!ready || asked.current) return;
+    asked.current = true;
+    requestAppInstall(context);
+  }, [ready, context]);
+}

package/src/ui/headless/work/index.ts

@@ -7,6 +7,8 @@ export {
   useWorkTaskAttachments,
   useWorkInvite,
   useAcceptWorkInvite,
+  rememberSignupEmail,
+  SIGNUP_EMAIL_PREFILL_KEY,
   useWorkProjectInvoices,
   useWorkSharedDocuments,
   useWorkOpenSharedDocument,

package/src/ui/headless/work/useWorkPortal.ts

@@ -129,25 +129,19 @@ export interface WorkInviteContext {
   email: string;
   firstName: string | null;
   /**
-   * The invited address already has an account, so the invite grants portal
-   * access but cannot set a credential: render "sign in", not a password
-   * form (C10).
+   * The invited address has no account yet. The invite never creates one: the
+   * page sends the person through the normal signup (which verifies the
+   * address with an emailed code) and back.
    */
+  needsAccount: boolean;
+  /** The complement of `needsAccount`: sign in, then come back. */
   requiresExistingLogin?: boolean;
 }
 
+/** POST /public/work/invite/accept, made as the signed-in invited account. */
 export interface WorkInviteAcceptResult {
-  /**
-   * True when the invited address already has an account: the invite granted
-   * portal access but issued NO session, and the person signs in normally
-   * (C10). `token` is absent in that case.
-   */
-  requiresLogin?: boolean;
-  token?: string;
-  /** Rotating refresh token for the portal session (backend §7). Persist it. */
-  refreshToken?: string;
+  accepted: true;
   projectId: string;
-  account: { id: string; email: string; firstName: string | null; lastName: string | null };
 }
 
 // ── Query keys ───────────────────────────────────────────────────────────────
@@ -410,22 +404,23 @@ export function useUploadWorkDocument(projectId: string) {
   });
 }
 
-// ── Client invite accept (public, no auth) ───────────────────────────────────
+// ── Client invite accept ─────────────────────────────────────────────────────
 
 /**
  * Fetch the branded context for an invite link (GET /public/work/invite).
- * Public: no bearer token needed; the link's token IS the credential.
- * `null`/errored when the token or project is missing/invalid/expired.
+ * Public: no bearer token needed. Sends the site's `profileId`, so a token for
+ * another tenant's project is refused here. Errors when the token or project is
+ * missing, invalid, expired or already used.
  */
 export function useWorkInvite(
   token: string | undefined,
   projectId: string | undefined,
 ): UseQueryResult<WorkInviteContext> {
-  const { client } = useForge();
+  const { client, profileId } = useForge();
   return useQuery<WorkInviteContext>({
-    queryKey: ["work-invite", token, projectId],
+    queryKey: ["work-invite", token, projectId, profileId],
     queryFn: async () => {
-      const res = await client.get(`/public/work/invite`, { params: { token, projectId } });
+      const res = await client.get(`/public/work/invite`, { params: { token, projectId, profileId } });
       return res.data as WorkInviteContext;
     },
     enabled: !!client && !!token && !!projectId,
@@ -434,20 +429,36 @@ export function useWorkInvite(
 }
 
 /**
- * Accept an invite (POST /public/work/invite/accept): set a password and
- * receive a fresh portal session token. The caller persists the token +
- * navigates. Public: no bearer token needed.
+ * Accept an invite (POST /public/work/invite/accept) as the SIGNED-IN account.
+ * The account's email must be the invited address; nothing is created and no
+ * password is involved.
  */
 export function useAcceptWorkInvite() {
-  const { client } = useForge();
-  return useMutation<WorkInviteAcceptResult, unknown, { token: string; projectId: string; password: string }>({
-    mutationFn: async ({ token, projectId, password }) => {
-      const res = await client.post(`/public/work/invite/accept`, { token, projectId, password });
+  const { client, profileId } = useForge();
+  return useMutation<WorkInviteAcceptResult, unknown, { token: string; projectId: string }>({
+    mutationFn: async ({ token, projectId }) => {
+      const res = await client.post(`/public/work/invite/accept`, { token, projectId, profileId });
       return res.data as WorkInviteAcceptResult;
     },
   });
 }
 
+/** Session-storage key the signup form reads its prefilled email from. */
+export const SIGNUP_EMAIL_PREFILL_KEY = "forge:signup-email";
+
+/**
+ * Hand an email to the next signup form in this tab, without putting it in a
+ * URL (where analytics would record it). Read once by `useSignupForm`.
+ */
+export function rememberSignupEmail(email: string | null | undefined) {
+  if (!email || typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(SIGNUP_EMAIL_PREFILL_KEY, email);
+  } catch {
+    // Storage unavailable: the person types it.
+  }
+}
+
 // ── Presentational helpers ───────────────────────────────────────────────────
 
 /** Major-unit amount → display string using the project currency symbol. */

package/src/ui/index.ts

@@ -148,7 +148,9 @@ export { ForgotPasswordForm, type ForgotPasswordFormProps } from "./styled/Forgo
 export { ResetPasswordForm, type ResetPasswordFormProps } from "./styled/ResetPasswordForm";
 export {
   AccountDashboard,
+  AccountSection,
   type AccountDashboardProps,
+  type AccountSectionProps,
   type AccountTabKey,
   ACCOUNT_TABS,
 } from "./styled/AccountDashboard";
@@ -161,6 +163,7 @@ export {
 export { AudioPlayer, type AudioPlayerProps } from "./styled/AudioPlayer";
 export { ForgeAnalytics, type ForgeAnalyticsProps } from "./analytics/ForgeAnalytics";
 export { PageMetaPixel, usePageMetaPixel, type PageMetaPixelProps } from "./analytics/PageMetaPixel";
+export { useMetaViewContent, useMetaPurchase, useMetaInitiateCheckout, type MetaViewContentInput } from "./analytics/useMetaEvents";
 export { CookieConsent, type CookieConsentProps } from "./styled/CookieConsent";
 export { Loading, type LoadingProps } from "./styled/Loading";
 /** The inventory-hold countdown + its lapsed/409 state. See `useInventoryHold`. */
@@ -374,6 +377,13 @@ export * from "./styled/communities";
 // Work (project management) client-portal styled blocks.
 export * from "./styled/work";
 
+// The client portal (`/i/account/*`): shell, home, projects, invoices, documents, activity.
+export * from "./styled/portal";
+
+// The site app (`/i/app`): its home, the bottom bar a custom start page can
+// drop in (`<AppBar />`), and the install and notification prompts.
+export * from "./styled/app";
+
 // A community's member home (`/i/communities/<slug>/home`) styled blocks.
 export * from "./styled/members";
 
@@ -385,3 +395,4 @@ export * from "./styled/ReviewRequestPage";
 // it, at BOTH the canonical `/i/documents/$token` and the older
 // `/documents/$token` that already-sent links point at.
 export * from "./styled/DocumentSigningPage";
+export * from "./styled/DownloadPage";