@tribe-nest/forge 3.48.0 → 3.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.48.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/data/queries/useMembershipCalls.ts

@@ -2,12 +2,23 @@ import { useQuery } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
 
 /**
- * The member's own call calendar (`GET /public/membership-calls/mine`).
+ * The viewer's own call calendar (`GET /public/scheduled-calls/mine`).
  *
  * Lives in Forge rather than in either app because BOTH rendering surfaces need
  * exactly this - the site-starter's `/i/members/calendar` and the client app's
- * `/i/members/calendar` - and a second copy is how the two drift, as
- * `useMyTickets` and `useMyBookings` already document.
+ * `/i/members/calendar`, and now the classroom and cohort pages on both - and a
+ * second copy is how the two drift, as `useMyTickets` and `useMyBookings`
+ * already document.
+ *
+ * ## It was never only memberships
+ *
+ * The server resolves the caller through every registered audience kind, so a
+ * course enrolment and a cohort seat come back alongside membership tiers. The
+ * endpoint answered on `/public/membership-calls/mine` for a year while doing
+ * exactly that; that path is kept as an alias for sites published against older
+ * Forge builds, and this file now calls the honest one. The names here keep the
+ * `MembershipCall` spelling because they are PUBLISHED exports that a code site
+ * may import; `useMyScheduledCalls` is the alias to write new code against.
  *
  * ## What the server owns and this file does not mirror
  *
@@ -84,24 +95,49 @@ export const membershipCallKeys = {
  * @param options.from Inclusive lower bound. Absent means "from now on", which is
  * what a caller wanting only the next few calls sends.
  * @param options.to Inclusive upper bound. Absent means "however far ahead".
+ * @param options.courseId Show only calls addressed to this course. See below.
+ * @param options.cohortId Show only calls addressed to this cohort. See below.
+ *
+ * ## `courseId` / `cohortId` narrow, they do not unlock
+ *
+ * Absent, this is the viewer's whole calendar and behaves as it always has.
+ * Present, the server INTERSECTS them with the audience keys it resolved for
+ * this caller, so they can only remove rows. Passing a course the viewer has no
+ * access to returns nothing, which is the same answer a stranger gets.
+ *
+ * The classroom and the cohort page pass them because a student enrolled in two
+ * cohorts opening one of them must not be shown the other's sessions.
  */
 export function useMyMembershipCalls(options?: {
   from?: Date;
   to?: Date;
   limit?: number;
   enabled?: boolean;
+  courseId?: string | null;
+  cohortId?: string | null;
 }) {
   const { client, profileId } = useForge();
   const from = options?.from?.toISOString();
   const to = options?.to?.toISOString();
+  const courseId = options?.courseId || undefined;
+  const cohortId = options?.cohortId || undefined;
   return useQuery<MyMembershipCall[]>({
     // The WINDOW is part of the key: paging back a month is a different question
     // with a different answer, and sharing one cache entry would show February's
-    // calls in March until a refetch landed.
-    queryKey: [...membershipCallKeys.mine(profileId), from ?? "now", to ?? "open"],
+    // calls in March until a refetch landed. The SCOPE is in it for the same
+    // reason - the classroom's answer and the members calendar's answer are two
+    // different lists, and sharing one entry would put one course's sessions on
+    // another course's page for as long as the cache held.
+    queryKey: [
+      ...membershipCallKeys.mine(profileId),
+      from ?? "now",
+      to ?? "open",
+      courseId ?? "any-course",
+      cohortId ?? "any-cohort",
+    ],
     queryFn: async () => {
-      const res = await client.get("/public/membership-calls/mine", {
-        params: { profileId, from, to, limit: options?.limit },
+      const res = await client.get("/public/scheduled-calls/mine", {
+        params: { profileId, from, to, limit: options?.limit, courseId, cohortId },
       });
       return res.data;
     },
@@ -146,7 +182,7 @@ export function useMyMembershipCallRecordings(options?: { limit?: number; enable
   return useQuery<MyMembershipCallRecording[]>({
     queryKey: ["membership-calls", "recordings", profileId],
     queryFn: async () => {
-      const res = await client.get("/public/membership-calls/mine/recordings", {
+      const res = await client.get("/public/scheduled-calls/mine/recordings", {
         params: { profileId, limit: options?.limit },
       });
       return res.data;
@@ -160,3 +196,17 @@ export function useMyMembershipCallRecordings(options?: { limit?: number; enable
     refetchInterval: 120_000,
   });
 }
+
+/**
+ * The honest names for the two hooks above.
+ *
+ * Aliases rather than renames: `useMyMembershipCalls` and its types are
+ * PUBLISHED exports that a code-built site may already import, and breaking
+ * those to fix a word would cost a site owner a build for nothing. New code
+ * should reach for these; the old names stay for as long as anything imports
+ * them.
+ */
+export const useMyScheduledCalls = useMyMembershipCalls;
+export const useMyScheduledCallRecordings = useMyMembershipCallRecordings;
+export type MyScheduledCall = MyMembershipCall;
+export type MyScheduledCallRecording = MyMembershipCallRecording;

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",
@@ -572,6 +617,7 @@
   "forge.course_access.secure_prompt_lead": "Jeder mit diesem Link kann deinen Kurs öffnen. Erstelle ein Konto mit",
   "forge.course_access.secure_prompt_tail": "damit er nur dir gehört.",
   "forge.course_access.signed_in_as": "Angemeldet als",
+  "forge.course_calls.title": "Live-Calls",
   "forge.course_checkout.aria_close": "Schließen",
   "forge.course_checkout.back": "Zurück",
   "forge.course_checkout.confirm_email_placeholder": "E-Mail bestätigen",

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",
@@ -572,6 +617,7 @@
   "forge.course_access.secure_prompt_lead": "Anyone with this link can open your course. Create an account with",
   "forge.course_access.secure_prompt_tail": "to keep it to yourself.",
   "forge.course_access.signed_in_as": "Signed in as",
+  "forge.course_calls.title": "Live calls",
   "forge.course_checkout.aria_close": "Close",
   "forge.course_checkout.back": "Back",
   "forge.course_checkout.confirm_email_placeholder": "Confirm email",

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,
@@ -1385,8 +1405,21 @@ export type CohortPageData = {
     title: string;
     description: string | null;
     order: number;
-    releaseOffsetDays: number | null;
-    releaseAt: string | null;
+    /**
+     * The drip schedule and the answer it produces. Present only on the
+     * ENROLLED read: the marketing payload gives a browser the shape of the
+     * course, and a student its calendar.
+     *
+     * Render `locked` / `unlocksAt` / `lockReason`, not the raw offset. The
+     * server computes them with the same expression the classroom uses, so a
+     * renderer that re-derives the answer from `releaseOffsetDays` will
+     * eventually disagree with the screen the student opens next.
+     */
+    releaseOffsetDays?: number | null;
+    releaseAt?: string | null;
+    locked?: boolean;
+    unlocksAt?: string | null;
+    lockReason?: "scheduled" | "cohort_not_started" | null;
     lessons?: Array<{
       id: string;
       title: string;
@@ -1402,12 +1435,21 @@ export type CohortPageData = {
     publishedAt: string | null;
     createdAt: string;
   }>;
-  sessions: Array<{
+  /**
+   * The cohort's scheduled calls. Renamed from `sessions` when
+   * `cohort_sessions` was dropped for the unified `scheduled_calls` table.
+   *
+   * Carries NO join address on purpose. The endpoint behind this payload is
+   * anonymous, so a `callPublicId` here would be a door into a live paid room.
+   * A student joins from the classroom, where they are authenticated.
+   */
+  calls: Array<{
     id: string;
     title: string;
     description: string | null;
-    scheduledAt: string;
-    durationMinutes: number;
+    startsAt: string;
+    endsAt: string;
+    timezone: string | null;
     status: string;
   }>;
   pricingPlans: Array<{
@@ -1653,6 +1695,18 @@ export type CourseAccessRecord = {
    * value as legacy (see `isLegacyCourseAccess`).
    */
   accountId?: string | null;
+  /**
+   * The cohort this enrolment is for, or `null` for a self-paced buy.
+   *
+   * Decides which MODULES the payload carries (a cohort holds its own cloned
+   * copy) and, on the client, which live calls belong on this classroom page: a
+   * student enrolled in two cohorts of one course has two grants and two
+   * classrooms, and each must show only its own sessions.
+   *
+   * Optional on the type because sites built against an older API still get
+   * payloads without the field.
+   */
+  cohortId?: string | null;
 };
 
 export type CourseLessonProgress = {
@@ -1683,6 +1737,25 @@ export type CourseModule = {
   description: string | null;
   order: number;
   lessons: CourseLesson[];
+  /**
+   * Drip state, on a cohort course. Optional because a self-paced course never
+   * carries it and every site built before drip existed predates these fields.
+   *
+   * `locked` means the module has not been released to this student yet. The
+   * server already strips `content` and `media` from a locked module's lessons,
+   * so a renderer that ignores these fields is not a content leak. It is a
+   * BROKEN SCREEN: the lessons render as normal, clickable, and open to
+   * nothing. Render the lock.
+   *
+   * `unlocksAt` is the EFFECTIVE moment, after the cohort's start date and the
+   * module's offset have been applied. It is null when the answer is not known
+   * yet, which is what `lockReason: "cohort_not_started"` means: the creator
+   * laid out the weeks before picking a start date. Say "opens when the cohort
+   * starts" there rather than showing an empty date.
+   */
+  locked?: boolean;
+  unlocksAt?: string | null;
+  lockReason?: "scheduled" | "cohort_not_started" | null;
 };
 
 export type CourseAccessCourse = {

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/headless/memberHome/useMemberCalls.ts

@@ -48,6 +48,17 @@ export interface UseMemberCallsOptions {
   now?: Date;
   /** Monday-first. The repo's `utils/recurrence` fixes the same convention. */
   weekStartsOn?: 0 | 1;
+  /**
+   * Narrow the month to ONE course, for a calendar rendered inside a classroom
+   * rather than in the members area.
+   *
+   * Absent on the members calendar, which is the viewer's whole schedule and
+   * must stay so. Present, the server intersects it with the audience keys it
+   * already resolved for this caller, so it can only ever remove rows.
+   */
+  courseId?: string | null;
+  /** The same, for one cohort. A student in two cohorts of one course sees only this one's sessions. */
+  cohortId?: string | null;
 }
 
 const dayKey = (date: Date): string => date.toLocaleDateString("en-CA");
@@ -90,6 +101,8 @@ export function useMemberCalls(options: UseMemberCallsOptions = {}) {
     to: gridEnd,
     limit: options.limit,
     enabled: options.enabled,
+    courseId: options.courseId,
+    cohortId: options.cohortId,
   });
 
   const days: MemberCalendarDay[] = useMemo(() => {