@tribe-nest/forge 3.50.0 → 3.53.0

package/src/ui/headless/cohort/useCohortCheckout.ts

@@ -0,0 +1,180 @@
+import { useMemo, useRef, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useCohortPage } from "../../../data/queries/useCohortPage";
+import { useCreateCohortEnrolment } from "../../../data/queries/useCohortEnrolment";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { readAttributionRef } from "../../../utils/attribution";
+import { rememberBookingSecret } from "../../../utils/bookingSecret";
+
+export type CohortCheckoutStep = "plan" | "details" | "payment";
+
+export interface UseCohortCheckoutOptions {
+  /**
+   * Stripe return URL for a PAID enrolment. Default
+   * `/i/cohorts/:cohortId/finalise?bookingId=...`.
+   *
+   * Put ONLY the bookingId in this URL. The booking's secret is stashed in
+   * sessionStorage by this hook and read back on the finalise page; putting it
+   * in the URL would hand it to history, referrers and shared links, which is
+   * the exact leak it exists to close.
+   */
+  finalisePath?: (cohortId: string, bookingId: string) => string;
+  /** Host-owned navigation on FREE completion (e.g. router navigate). */
+  onComplete?: (info: { cohortId: string; bookingId: string }) => void;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Headless cohort purchase: pick a plan, give buyer details, pay.
+ *
+ * THREE STEPS, NOT TWO, and the extra one is the point. A self-paced course has
+ * one price so its checkout opens on buyer details. A cohort is priced from its
+ * pricing plans, and choosing between "pay in full" and "three instalments" is
+ * the decision the buyer came to make, so it comes first and is never guessed.
+ * The default plan is preselected; nothing is bought until they say so.
+ *
+ * NO COUPON FIELD, deliberately. The cohort checkout takes a `planId` and
+ * nothing else that touches money: the plan IS the price. That is what keeps
+ * instalments 2..n, charged months later by a cron, equal to what was
+ * advertised.
+ */
+export function useCohortCheckout(cohortId?: string, opts: UseCohortCheckoutOptions = {}) {
+  const { user } = usePublicAuth();
+  const { data: page, isLoading } = useCohortPage(cohortId);
+  const createEnrolment = useCreateCohortEnrolment(cohortId);
+  const flow = usePaymentFlow({ path: `/public/cohorts/${cohortId}/start-payment`, autoStart: false });
+
+  const plans = useMemo(() => page?.data?.pricingPlans ?? [], [page]);
+
+  const [step, setStep] = useState<CohortCheckoutStep>("plan");
+  const [planId, setPlanId] = useState<string | undefined>(undefined);
+  const [firstName, setFirstName] = useState(user?.firstName ?? "");
+  const [lastName, setLastName] = useState(user?.lastName ?? "");
+  const [email, setEmail] = useState(user?.email ?? "");
+  const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  const [returnUrl, setReturnUrl] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * The per-booking credential from `createEnrolment`. A ref, not state, so it
+   * never triggers a render and never lands in a dependency array. The backend
+   * returns it once and cannot reissue it.
+   */
+  const bookingSecretRef = useRef<string | undefined>(undefined);
+
+  /**
+   * The creator's own default wins, and the first plan is only a fallback for a
+   * cohort whose plans predate `isDefault`. Preselecting nothing would make the
+   * commonest case ("one plan, pay in full") an extra click for no decision.
+   */
+  const selectedPlan = useMemo(() => {
+    if (planId) return plans.find((p) => p.id === planId);
+    return plans.find((p) => p.isDefault) ?? plans[0];
+  }, [plans, planId]);
+
+  const finalisePath = opts.finalisePath ?? ((id, bookingId) => `/i/cohorts/${id}/finalise?bookingId=${bookingId}`);
+
+  const choosePlan = (id: string) => {
+    setError(null);
+    setPlanId(id);
+    setStep("details");
+  };
+
+  const enrol = async () => {
+    setError(null);
+    if (!cohortId) return;
+    if (!selectedPlan) {
+      setError("Choose a plan before continuing.");
+      return;
+    }
+    if (!firstName.trim() || !lastName.trim() || !EMAIL.test(email)) {
+      setError("Please enter your name and a valid email.");
+      return;
+    }
+
+    try {
+      const created = await createEnrolment.mutateAsync({
+        planId: selectedPlan.id,
+        email,
+        firstName,
+        lastName,
+        questionnaire,
+        attributionRefId: readAttributionRef() ?? undefined,
+      });
+      bookingSecretRef.current = created.bookingSecret;
+      // Written the instant it arrives: this is the only time the server will
+      // ever hand it over, and the finalise page (post-redirect) has no other
+      // way to get it.
+      rememberBookingSecret(created.bookingId, created.bookingSecret);
+
+      const origin = typeof window !== "undefined" ? window.location.origin : "";
+      const ru = `${origin}${finalisePath(cohortId, created.bookingId)}`;
+      setReturnUrl(ru);
+
+      // A zero-priced plan confirms on creation and the access email fires from
+      // the server, so there is nothing to pay and nothing to wait for.
+      if (created.isFree) {
+        if (opts.onComplete) opts.onComplete({ cohortId, bookingId: created.bookingId });
+        else if (typeof window !== "undefined") window.location.href = ru;
+        return;
+      }
+
+      const result = await flow.start({
+        bookingId: created.bookingId,
+        bookingSecret: bookingSecretRef.current,
+        returnUrl: ru,
+      });
+      if (result.provider && result.provider !== "stripe") return;
+      setStep("payment");
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  return {
+    cohort: page?.data?.cohort,
+    course: page?.data?.course,
+    isLoading,
+    plans,
+    selectedPlan,
+    planId: selectedPlan?.id,
+    choosePlan,
+    step,
+    setStep,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    questionnaire,
+    setQuestionnaire,
+    enrol,
+    clientSecret: flow.clientSecret,
+    /** Paystack: the started inline-checkout session and the way back into it. */
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
+    /** The whole plan. */
+    totalAmount: flow.result?.totalAmount ?? (selectedPlan ? Number(selectedPlan.totalAmount) : undefined),
+    /** What THIS charge takes: the first instalment, or the whole plan. */
+    installmentAmount: flow.result?.installmentAmount,
+    installmentCount: selectedPlan?.installmentCount ?? 1,
+    /**
+     * Stripe needs a second confirmation before instalment 1 on a multi-payment
+     * plan: the consent to be charged again off-session. Render it, or the
+     * later instalments have no payment method to hit.
+     */
+    setupRequiresAction: flow.result?.setupRequiresAction ?? false,
+    setupClientSecret: flow.result?.setupClientSecret ?? null,
+    /** Authoritative sales-tax quote from start-payment (display only). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    returnUrl,
+    isProcessing: createEnrolment.isPending || flow.isStarting,
+    error,
+  };
+}

package/src/ui/index.ts

@@ -197,6 +197,13 @@ export {
 export { ConfirmSubscription, type ConfirmSubscriptionProps } from "./styled/ConfirmSubscription";
 export { LeadMagnet, type LeadMagnetProps } from "./styled/LeadMagnet";
 export { CohortPage, type CohortPageProps } from "./styled/CohortPage";
+export { CohortCheckout, type CohortCheckoutProps } from "./styled/CohortCheckout";
+export { CohortConfirmation, type CohortConfirmationProps } from "./styled/CohortConfirmation";
+export {
+  useCohortCheckout,
+  type UseCohortCheckoutOptions,
+  type CohortCheckoutStep,
+} from "./headless/cohort/useCohortCheckout";
 export { CourseAccess, type CourseAccessProps } from "./styled/CourseAccess";
 // A student's live calls, scoped to the course or cohort the page is standing
 // on. A thin wrapper over `MemberCallsCalendar`, not a second calendar.

package/src/ui/styled/AccountDashboard.tsx

@@ -18,7 +18,9 @@ import {
   useSavedPosts,
   useNotificationPreferences,
   useUpdateNotificationPreference,
+  useMyCourses,
   useMyFilmRentals,
+  type MyCourse,
   useCancelMembership,
   useMembershipAccess,
   useOpenBillingPortal,
@@ -62,6 +64,11 @@ export const ACCOUNT_TABS = [
   // Drawn only when the fan actually holds a rental (see `visibleTabs`), so the
   // tab does not appear on the account page of every site that never sells one.
   "rentals",
+  // Courses this fan has bought. Beside the other purchase surfaces because it
+  // answers the same question they do, and it was the ONE purchase with no
+  // answer on this page: a creator's most expensive product, invisible once
+  // bought. Drawn only when they hold one (see `visibleTabs`).
+  "courses",
   "saved",
   "account",
   "notifications",
@@ -79,6 +86,7 @@ const TAB_LABEL_KEYS: Record<AccountTabKey, string> = {
   waitlist: "forge.account_dashboard.tab_waitlist",
   bookings: "forge.account_dashboard.tab_bookings",
   rentals: "forge.account_dashboard.tab_rentals",
+  courses: "forge.account_dashboard.tab_courses",
   saved: "forge.account_dashboard.tab_saved",
   account: "forge.account_dashboard.tab_account",
   notifications: "forge.account_dashboard.tab_notifications",
@@ -116,6 +124,17 @@ export interface AccountDashboardProps {
    * full-page visit, which works on any site and is merely slower.
    */
   onNavigateFilm?: (href: string) => void;
+  /**
+   * Open a course the fan owns.
+   *
+   * It must go to the CLASSROOM, keyed by `accessId`, never to the course's
+   * sales page. The sales page is where someone decides whether to buy, which
+   * is a dead end for a person who already owns it and came here to carry on.
+   *
+   * Left out, a course row is inert - so a host that draws the tab and omits
+   * this gives the fan something that looks clickable and does nothing.
+   */
+  onNavigateCourse?: (course: MyCourse) => void;
   /**
    * Optional currency formatter override. Defaults to Forge's `useFormatCurrency`
    * (which honors the visitor's selected currency + tenant exchange rates), so the
@@ -183,6 +202,15 @@ interface TabContext {
   onNavigateMembership?: () => void;
   onNavigateCommunity?: () => void;
   onNavigateFilm?: (href: string) => void;
+  /**
+   * Open a course the fan owns. Host-supplied, like every other navigation
+   * target here, because the route shape belongs to the site not to Forge.
+   *
+   * It must go to the CLASSROOM (`accessId`), never to the course's sales page
+   * (`courseId`). The sales page is where someone decides whether to buy, which
+   * is a dead end for someone who already owns it and came here to carry on.
+   */
+  onNavigateCourse?: (course: MyCourse) => void;
 }
 
 // ---- page -------------------------------------------------------------------
@@ -198,6 +226,7 @@ export function AccountDashboard({
   onNavigateMembership,
   onNavigateCommunity,
   onNavigateFilm,
+  onNavigateCourse,
   formatAmount,
   formatDate,
   currency,
@@ -219,6 +248,13 @@ export function AccountDashboard({
    * react-query serves both from one request rather than two.
    */
   const { data: rentals } = useMyFilmRentals(user?.id);
+  /**
+   * Resolved by account OR verified email on the server, so a buyer who never
+   * clicked the claim link still sees the course they paid for. Before that,
+   * this tab would have been empty for exactly the people who ask where their
+   * course went.
+   */
+  const { data: courses } = useMyCourses({ accountId: user?.id });
 
   const fmtAmount = useAmountFormatter(formatAmount);
   const fmtDate = formatDate ?? defaultFormatDate;
@@ -232,6 +268,7 @@ export function AccountDashboard({
     onNavigateMembership,
     onNavigateCommunity,
     onNavigateFilm,
+    onNavigateCourse,
   };
 
   /**
@@ -241,7 +278,12 @@ export function AccountDashboard({
    * panel underneath it.
    */
   const hasRentals = (rentals?.total ?? 0) > 0;
-  const visibleTabs = ACCOUNT_TABS.filter((key) => key !== "rentals" || hasRentals || tab === "rentals");
+  const hasCourses = (courses?.length ?? 0) > 0;
+  const visibleTabs = ACCOUNT_TABS.filter(
+    (key) =>
+      (key !== "rentals" || hasRentals || tab === "rentals") &&
+      (key !== "courses" || hasCourses || tab === "courses"),
+  );
 
   if (!user) return <Loading fullPage />;
 
@@ -289,6 +331,7 @@ export function AccountDashboard({
       {tab === "waitlist" && <WaitlistTab ctx={ctx} />}
       {tab === "bookings" && <BookingsTab ctx={ctx} />}
       {tab === "rentals" && <RentalsTab ctx={ctx} />}
+      {tab === "courses" && <CoursesTab ctx={ctx} courses={courses ?? []} />}
       {tab === "saved" && <SavedTab />}
       {tab === "account" && <AccountTab ctx={ctx} />}
       {tab === "notifications" && <NotificationsTab />}
@@ -1357,6 +1400,64 @@ function RentalsTab({ ctx }: { ctx: TabContext }) {
   );
 }
 
+// ---- Courses tab ------------------------------------------------------------
+
+/**
+ * What this fan has bought and can open, with a way in.
+ *
+ * `claimed: false` means they never used the claim link. The course is theirs
+ * either way - the server resolves the grant by verified email - so the row says
+ * so plainly rather than staying silent, because "did my purchase register?" is
+ * the question this whole tab exists to stop someone asking.
+ */
+function CoursesTab({ ctx, courses }: { ctx: TabContext; courses: MyCourse[] }) {
+  const { t, card } = useCardStyles();
+  const tr = useForgeT();
+
+  return (
+    <div style={card}>
+      <h2 style={{ fontSize: 18, fontWeight: 700, marginBottom: 16, fontFamily: t.headingFontFamily }}>
+        {tr("forge.account_dashboard.courses_title")}
+      </h2>
+
+      {courses.length === 0 ? (
+        <p style={{ color: t.muted }}>{tr("forge.account_dashboard.courses_empty")}</p>
+      ) : (
+        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+          {courses.map((course) => (
+            <button
+              key={course.accessId}
+              type="button"
+              onClick={() => ctx.onNavigateCourse?.(course)}
+              style={{
+                textAlign: "left",
+                background: t.surface,
+                border: `1px solid ${t.border}`,
+                borderRadius: t.cornerRadius,
+                padding: 16,
+                cursor: ctx.onNavigateCourse ? "pointer" : "default",
+                color: t.text,
+              }}
+            >
+              <div style={{ fontWeight: 600 }}>{course.title}</div>
+              {/* No description. It is rich text: as a string it shows its own
+                  markup, as HTML it drags a sales page's formatting into a list
+                  row. The row carries the title and the state instead. */}
+              <div style={{ color: t.muted, fontSize: 12, marginTop: 8 }}>
+                {course.completedAt
+                  ? tr("forge.account_dashboard.courses_completed")
+                  : course.currentLessonId
+                    ? tr("forge.account_dashboard.courses_continue")
+                    : tr("forge.account_dashboard.courses_start")}
+              </div>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 // ---- Orders tab -------------------------------------------------------------
 
 function OrdersTab({ ctx }: { ctx: TabContext }) {

package/src/ui/styled/AiAgentWidget.tsx

@@ -21,8 +21,9 @@ export interface AiAgentWidgetProps {
  * own config for the site's profile, renders a fixed-position bubble + panel,
  * and streams answers grounded in the artist's content + knowledge base. Render
  * it once (e.g. in __root); it renders nothing when the agent is disabled for
- * the profile. Appearance-only props let authors restyle it without touching
- * behavior. For custom UI, use the `useAiAgent()` hook instead.
+ * the profile, or when the visitor is on a page the artist excluded.
+ * Appearance-only props let authors restyle it without touching behavior. For
+ * custom UI, use the `useAiAgent()` hook instead.
  */
 export function AiAgentWidget({ position = "bottom-right", accentColor, title, zIndex = 9999 }: AiAgentWidgetProps) {
   const t = useForgeT();

package/src/ui/styled/BlogPost.tsx

@@ -157,7 +157,7 @@ export function BlogPost({ slug, blogHref = "/i/blog", initialPost }: BlogPostPr
 
       {/* `rich-text` = shared baseline content styles (WYSIWYG with the editor),
           bundled with Forge via the ./rich-text.css import above. */}
-      <div className="rich-text" dangerouslySetInnerHTML={{ __html: post.content || "" }} />
+      <div className="fg:rich-text" dangerouslySetInnerHTML={{ __html: post.content || "" }} />
     </article>
   );
 }

package/src/ui/styled/ChatRoom.tsx

@@ -124,7 +124,7 @@ export function ChatRoom(_props: ChatRoomProps) {
     >
       {/* Channel list: full-width on mobile, fixed rail on desktop */}
       <aside
-        className={`${showSidebar ? "flex" : "hidden"} md:flex w-full md:w-[260px] flex-col`}
+        className={`${showSidebar ? "fg:flex" : "fg:hidden"} fg:md:flex fg:w-full fg:md:w-[260px] fg:flex-col`}
         style={{ borderRight: border, overflowY: "auto" }}
       >
         <div
@@ -174,7 +174,7 @@ export function ChatRoom(_props: ChatRoomProps) {
       </aside>
 
       {/* Message panel */}
-      <section className={`${showSidebar ? "hidden" : "flex"} md:flex flex-1 flex-col min-w-0`}>
+      <section className={`${showSidebar ? "fg:hidden" : "fg:flex"} fg:md:flex fg:flex-1 fg:flex-col fg:min-w-0`}>
         {room.selectedChannel ? (
           <MessagePanel room={room} onBack={() => setShowSidebar(true)} border={border} />
         ) : (