@tribe-nest/forge 3.50.0 → 3.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.50.0",
+  "version": "3.52.0",
   "publishConfig": {
     "access": "public"
   },
@@ -17,7 +17,7 @@
     "src"
   ],
   "scripts": {
-    "build:css": "tailwindcss -i tailwind.input.css -o src/ui/styled/forge-utilities.css && node scripts/wrapForgeCss.mjs",
+    "build:css": "tailwindcss -i tailwind.input.css -o src/ui/styled/forge-utilities.css",
     "prepack": "npm run build:css",
     "check-types": "tsc --noEmit",
     "test": "vitest run",

package/src/data/queries/useCohortEnrolment.ts

@@ -0,0 +1,87 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import type { CourseBooking } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Buying a seat on a cohort.
+ *
+ * A DIFFERENT CHECKOUT FROM THE SELF-PACED ONE, and not by preference. A cohort
+ * is priced from its `course_pricing_plans` rows, so the buyer picks a PLAN and
+ * the plan is the price: there is no amount, no currency and no coupon field on
+ * this body. `courses.price` is 0 on every cohort course, which is exactly why
+ * the self-paced endpoint refuses one outright rather than selling it for
+ * nothing.
+ *
+ * The plan also decides whether this is one payment or several. An instalment
+ * plan takes a second consent at `start-payment` ("charge me again when nobody
+ * is here"), because instalments 2..n are taken months later by a cron.
+ */
+
+export type CreateCohortEnrolmentInput = {
+  planId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+  browserSessionId?: string;
+};
+
+export type CreateCohortEnrolmentResult = {
+  bookingId: string;
+  /**
+   * The per-booking credential, returned EXACTLY ONCE and never re-readable.
+   * Every later call on this booking must present it. Persist it the instant it
+   * arrives - see `utils/bookingSecret`.
+   */
+  bookingSecret?: string;
+  cohortId: string;
+  planId: string;
+  courseId: string;
+  totalAmount: number;
+  currency: string;
+  installmentCount: number;
+  /** What is charged TODAY. Equals `totalAmount` on a single-payment plan. */
+  firstPaymentAmount: number;
+  isFree: boolean;
+};
+
+/** Reserve a seat on a cohort against one pricing plan. */
+export function useCreateCohortEnrolment(cohortId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<CreateCohortEnrolmentResult, unknown, CreateCohortEnrolmentInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/cohorts/${cohortId}/enrollments`, {
+        profileId,
+        cohortId,
+        ...body,
+      });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Finalize a cohort enrolment (`/public/cohorts/:cohortId/finalize`).
+ *
+ * Same shape and same reasoning as the self-paced finalize: the confirmation
+ * page is reached through a provider redirect, so the caller reads the booking
+ * secret back out of `utils/bookingSecret` rather than off in-memory state.
+ */
+export function useCohortEnrolmentFinalize(cohortId?: string, bookingId?: string, bookingSecret?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<CourseBooking>({
+    queryKey: ["cohortEnrolmentStatus", profileId, bookingId],
+    queryFn: async () => {
+      const res = await client.post(`/public/cohorts/${cohortId}/finalize`, {
+        profileId,
+        bookingId,
+        bookingSecret,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!cohortId && !!bookingId,
+  });
+}

package/src/i18n/de.json

@@ -529,6 +529,51 @@
   "forge.coaching_detail.about_title": "Über diese Session",
   "forge.coaching_detail.duration_minutes": "{minutes} Minuten",
   "forge.coaching_detail.not_found": "Coaching-Session nicht gefunden.",
+  "forge.cohort_checkout.aria_close": "Schließen",
+  "forge.cohort_checkout.authorise_future_payments": "Autorisiere die späteren Zahlungen dieses Plans.",
+  "forge.cohort_checkout.back": "Zurück",
+  "forge.cohort_checkout.confirm_leave": "Ohne Abschluss verlassen? Dein Platz ist noch nicht reserviert.",
+  "forge.cohort_checkout.continue_to_payment": "Weiter zur Zahlung",
+  "forge.cohort_checkout.details_subtitle": "Wir senden deinen Zugang an diese Adresse.",
+  "forge.cohort_checkout.details_title": "Deine Daten",
+  "forge.cohort_checkout.due_now": "Jetzt fällig",
+  "forge.cohort_checkout.email_placeholder": "E-Mail",
+  "forge.cohort_checkout.first_name_placeholder": "Vorname",
+  "forge.cohort_checkout.installment_note": "{count} Zahlungen insgesamt, zusammen {total}.",
+  "forge.cohort_checkout.last_name_placeholder": "Nachname",
+  "forge.cohort_checkout.no_plans": "Diese Kohorte ist noch nicht zur Anmeldung geöffnet.",
+  "forge.cohort_checkout.pay": "{amount} zahlen",
+  "forge.cohort_checkout.payment_not_configured": "Zahlung ist nicht konfiguriert.",
+  "forge.cohort_checkout.payment_subtitle": "Schließe deine Anmeldung ab, um der Kohorte beizutreten.",
+  "forge.cohort_checkout.payment_title": "Zahlung",
+  "forge.cohort_checkout.plan_in_full": "Auf einmal zahlen",
+  "forge.cohort_checkout.plan_installments": "{count} Zahlungen à {amount}, alle {days} Tage",
+  "forge.cohort_checkout.plan_subtitle": "Wähle, wie du zahlen möchtest.",
+  "forge.cohort_checkout.plan_title": "Plan wählen",
+  "forge.cohort_checkout.preparing_payment": "Zahlung wird vorbereitet...",
+  "forge.cohort_checkout.tax_added": "+ {amount} Steuer",
+  "forge.cohort_checkout.title": "Anmelden",
+  "forge.cohort_checkout.trigger": "Anmelden",
+  "forge.cohort_checkout.working": "Einen Moment...",
+  "forge.cohort_confirmation.body_confirmed": "Du bist dabei, {first_name}. Bis zum Start.",
+  "forge.cohort_confirmation.body_confirmed_no_name": "Du bist dabei. Bis zum Start.",
+  "forge.cohort_confirmation.body_incomplete": "Deine Anmeldung ist {status}. Von dir wird gerade nichts weiter gebraucht.",
+  "forge.cohort_confirmation.emailed": "Wir haben die Details an {email} geschickt.",
+  "forge.cohort_confirmation.explore": "Mehr entdecken",
+  "forge.cohort_confirmation.eyebrow_action_needed": "Aktion nötig",
+  "forge.cohort_confirmation.eyebrow_confirmed": "Angemeldet",
+  "forge.cohort_confirmation.free": "Kostenlos",
+  "forge.cohort_confirmation.loading": "Anmeldung wird bestätigt...",
+  "forge.cohort_confirmation.lost_body": "Dieser Browser kennt diese Anmeldung nicht, wir können sie hier nicht anzeigen. Falls du bezahlt hast, sieh in deinen E-Mails nach der Bestätigung.",
+  "forge.cohort_confirmation.lost_restart": "Zurück zur Kohorte",
+  "forge.cohort_confirmation.lost_title": "Wir können diese Anmeldung hier nicht öffnen",
+  "forge.cohort_confirmation.not_found": "Anmeldung nicht gefunden.",
+  "forge.cohort_confirmation.not_given": "Nicht angegeben",
+  "forge.cohort_confirmation.row_paid": "Heute gezahlt",
+  "forge.cohort_confirmation.row_reference": "Referenz",
+  "forge.cohort_confirmation.row_student": "Teilnehmer",
+  "forge.cohort_confirmation.title_confirmed": "Dein Platz ist sicher",
+  "forge.cohort_confirmation.title_incomplete": "Fast geschafft",
   "forge.cohort_page.curriculum_title": "Lehrplan",
   "forge.cohort_page.date_range": "{start} bis {end}",
   "forge.cohort_page.date_tbd": "Noch offen",

package/src/i18n/en.json

@@ -529,6 +529,51 @@
   "forge.coaching_detail.about_title": "About this session",
   "forge.coaching_detail.duration_minutes": "{minutes} minutes",
   "forge.coaching_detail.not_found": "Coaching session not found.",
+  "forge.cohort_checkout.aria_close": "Close",
+  "forge.cohort_checkout.authorise_future_payments": "Authorise the later payments on this plan.",
+  "forge.cohort_checkout.back": "Back",
+  "forge.cohort_checkout.confirm_leave": "Leave without finishing? Your seat is not held yet.",
+  "forge.cohort_checkout.continue_to_payment": "Continue to payment",
+  "forge.cohort_checkout.details_subtitle": "We will send your access to this address.",
+  "forge.cohort_checkout.details_title": "Your details",
+  "forge.cohort_checkout.due_now": "Due now",
+  "forge.cohort_checkout.email_placeholder": "Email",
+  "forge.cohort_checkout.first_name_placeholder": "First name",
+  "forge.cohort_checkout.installment_note": "{count} payments in total, {total} altogether.",
+  "forge.cohort_checkout.last_name_placeholder": "Last name",
+  "forge.cohort_checkout.no_plans": "This cohort is not open for enrolment yet.",
+  "forge.cohort_checkout.pay": "Pay {amount}",
+  "forge.cohort_checkout.payment_not_configured": "Payment is not configured.",
+  "forge.cohort_checkout.payment_subtitle": "Complete your enrolment to join the cohort.",
+  "forge.cohort_checkout.payment_title": "Payment",
+  "forge.cohort_checkout.plan_in_full": "Pay in full",
+  "forge.cohort_checkout.plan_installments": "{count} payments of {amount}, every {days} days",
+  "forge.cohort_checkout.plan_subtitle": "Choose how you would like to pay.",
+  "forge.cohort_checkout.plan_title": "Choose a plan",
+  "forge.cohort_checkout.preparing_payment": "Preparing payment...",
+  "forge.cohort_checkout.tax_added": "+ {amount} tax",
+  "forge.cohort_checkout.title": "Enrol",
+  "forge.cohort_checkout.trigger": "Enrol",
+  "forge.cohort_checkout.working": "Working...",
+  "forge.cohort_confirmation.body_confirmed": "You're in, {first_name}. See you at the start.",
+  "forge.cohort_confirmation.body_confirmed_no_name": "You're in. See you at the start.",
+  "forge.cohort_confirmation.body_incomplete": "Your enrolment is {status}. Nothing else is needed from you right now.",
+  "forge.cohort_confirmation.emailed": "We've emailed the details to {email}.",
+  "forge.cohort_confirmation.explore": "Browse more",
+  "forge.cohort_confirmation.eyebrow_action_needed": "Action needed",
+  "forge.cohort_confirmation.eyebrow_confirmed": "Enrolled",
+  "forge.cohort_confirmation.free": "Free",
+  "forge.cohort_confirmation.loading": "Confirming your enrolment...",
+  "forge.cohort_confirmation.lost_body": "This browser has no record of that enrolment, so we cannot show it. If you paid, check your email for the confirmation.",
+  "forge.cohort_confirmation.lost_restart": "Back to the cohort",
+  "forge.cohort_confirmation.lost_title": "We cannot open this enrolment here",
+  "forge.cohort_confirmation.not_found": "Enrolment not found.",
+  "forge.cohort_confirmation.not_given": "Not given",
+  "forge.cohort_confirmation.row_paid": "Paid today",
+  "forge.cohort_confirmation.row_reference": "Reference",
+  "forge.cohort_confirmation.row_student": "Student",
+  "forge.cohort_confirmation.title_confirmed": "You have your seat",
+  "forge.cohort_confirmation.title_incomplete": "Almost there",
   "forge.cohort_page.curriculum_title": "Curriculum",
   "forge.cohort_page.date_range": "{start} to {end}",
   "forge.cohort_page.date_tbd": "TBD",

package/src/index.ts

@@ -109,6 +109,7 @@ export * from "./data/queries/useForms";
 export * from "./data/queries/useReplay";
 export * from "./data/queries/useCoachingAvailability";
 export * from "./data/queries/useCohortPage";
+export * from "./data/queries/useCohortEnrolment";
 export * from "./data/queries/useCourseAccess";
 // Films and series: the catalogue, one title, the buyer's library, the rental
 // money legs, and the three playback-session calls. Everything a custom viewing

package/src/types/models.ts

@@ -101,6 +101,26 @@ export type PaymentStartResponse = {
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
   /** Authoritative sales-tax quote for this charge (all wired pillars). */
   taxQuote?: PublicTaxQuote;
+  /**
+   * COHORT ENROLMENT ONLY: what THIS charge takes, when the plan is paid in
+   * instalments. `totalAmount` above stays the whole plan, so a checkout that
+   * shows only the total tells an instalment buyer they are about to be charged
+   * three times what they will be. Equal to `totalAmount` on a single payment.
+   */
+  installmentAmount?: number;
+  /** COHORT ENROLMENT ONLY: how many payments the chosen plan is split into. */
+  installmentCount?: number;
+  /**
+   * COHORT ENROLMENT ONLY: the SECOND consent, taken before instalment 1.
+   *
+   * Instalments 2..n are charged months later by a cron with nobody present, so
+   * the payer has to agree to be charged off-session. When Stripe needs that
+   * confirmed in the browser, `setupRequiresAction` is true and
+   * `setupClientSecret` is what confirms it. A checkout that ignores these takes
+   * the first payment and then silently fails every later one.
+   */
+  setupRequiresAction?: boolean;
+  setupClientSecret?: string | null;
   /**
    * When the reserved stock goes back on sale, ISO-8601 — the RESTARTED clock,
    * measured from the card form rather than from when the cart was assembled,

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/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} />
         ) : (