@tribe-nest/forge 2.2.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "2.2.0",
+  "version": "3.4.0",
   "publishConfig": {
     "access": "public"
   },

package/src/client/createForgeClient.ts

@@ -1,4 +1,21 @@
-import axios, { type AxiosInstance } from "axios";
+import axios, { type AxiosError, type AxiosInstance } from "axios";
+
+/**
+ * Access-token refresh (backend §7 cutover). Access tokens live ~15 minutes;
+ * when a request 401s the client exchanges the refresh token at `path` for a
+ * new pair and retries once. The refresh token ROTATES on every exchange, so
+ * `onRefreshed` must persist the new one.
+ */
+export interface ForgeClientRefreshOptions {
+  /** Exchange endpoint for this lane, e.g. "/public/sessions/refresh". */
+  path: string;
+  /** The current refresh token, or null when anonymous (no refresh attempted). */
+  getRefreshToken: () => string | null;
+  /** Persist the rotated pair and update whatever backs `getToken`. */
+  onRefreshed: (tokens: { token: string; refreshToken: string }) => void;
+  /** The chain is dead (revoked/expired/reused) — clear stored tokens. */
+  onFailed: () => void;
+}
 
 export interface ForgeClientOptions {
   /** Base URL of the TribeNest public API, e.g. https://api.tribenest.co */
@@ -13,6 +30,8 @@ export interface ForgeClientOptions {
    * place (Component 1) this is sent on every request to scope reads to the tenant.
    */
   publishableKey?: string;
+  /** Enable 401-triggered refresh-and-retry for this client's auth lane. */
+  refresh?: ForgeClientRefreshOptions;
 }
 
 /**
@@ -22,7 +41,12 @@ export interface ForgeClientOptions {
  * the base URL is injected (no `process.env`), the token is read per-request via a
  * closure, and `localStorage` access is SSR-guarded so the client is safe on Workers.
  */
-export const createForgeClient = ({ baseURL, getToken, publishableKey }: ForgeClientOptions): AxiosInstance => {
+export const createForgeClient = ({
+  baseURL,
+  getToken,
+  publishableKey,
+  refresh,
+}: ForgeClientOptions): AxiosInstance => {
   const client = axios.create({ baseURL });
 
   client.interceptors.request.use((config) => {
@@ -44,6 +68,65 @@ export const createForgeClient = ({ baseURL, getToken, publishableKey }: ForgeCl
     return config;
   });
 
+  if (refresh) {
+    // Single-flight: concurrent 401s (a page of queries expiring together) must
+    // produce ONE exchange — the refresh token rotates on use, so parallel
+    // exchanges would race each other through the server's grace window.
+    let inFlight: Promise<string | null> | null = null;
+
+    const exchange = (): Promise<string | null> => {
+      if (!inFlight) {
+        inFlight = (async () => {
+          const refreshToken = refresh.getRefreshToken();
+          if (!refreshToken) return null;
+          try {
+            // Bare axios on purpose — the shared client would recurse through
+            // this very interceptor.
+            const res = await axios.post(
+              `${baseURL}${refresh.path}`,
+              { refreshToken },
+              publishableKey ? { headers: { "x-forge-key": publishableKey } } : undefined,
+            );
+            const next = res.data as { token: string; refreshToken: string };
+            refresh.onRefreshed(next);
+            return next.token;
+          } catch {
+            refresh.onFailed();
+            return null;
+          } finally {
+            setTimeout(() => {
+              inFlight = null;
+            });
+          }
+        })();
+      }
+      return inFlight;
+    };
+
+    client.interceptors.response.use(
+      (response) => response,
+      async (error: AxiosError) => {
+        const config = error.config as (typeof error.config & { _retriedAfterRefresh?: boolean }) | undefined;
+        if (
+          error.response?.status === 401 &&
+          config &&
+          !config._retriedAfterRefresh &&
+          !config.url?.includes(refresh.path) &&
+          refresh.getRefreshToken()
+        ) {
+          const token = await exchange();
+          if (token) {
+            config._retriedAfterRefresh = true;
+            config.headers = config.headers ?? {};
+            config.headers["authorization"] = `Bearer ${token}`;
+            return client.request(config);
+          }
+        }
+        return Promise.reject(error);
+      },
+    );
+  }
+
   return client;
 };
 

package/src/client/tokenStorage.ts

@@ -0,0 +1,31 @@
+// localStorage keys for the two auth lanes a Forge site can carry. They live
+// here (not in the auth contexts) so the client factory and both contexts can
+// share them without an import cycle. The fan/member and app-user lanes are
+// deliberately separate pairs — an app-user session must never collide with a
+// profile session on the same site.
+//
+// Access tokens are ~15 minutes now (backend §7 cutover); the refresh token is
+// the long-lived credential and ROTATES on every exchange — always store the
+// one that came back, never re-use the one you sent.
+
+export const PUBLIC_ACCESS_TOKEN_KEY = "public-access-token";
+export const PUBLIC_REFRESH_TOKEN_KEY = "public-refresh-token";
+
+export const APP_ACCESS_TOKEN_KEY = "app-access-token";
+export const APP_REFRESH_TOKEN_KEY = "app-refresh-token";
+
+const canStore = () => typeof localStorage !== "undefined";
+
+export const readStoredToken = (key: string): string | null => (canStore() ? localStorage.getItem(key) : null);
+
+export const storeTokenPair = (accessKey: string, refreshKey: string, token: string, refreshToken?: string) => {
+  if (!canStore()) return;
+  localStorage.setItem(accessKey, token);
+  if (refreshToken) localStorage.setItem(refreshKey, refreshToken);
+};
+
+export const clearTokenPair = (accessKey: string, refreshKey: string) => {
+  if (!canStore()) return;
+  localStorage.removeItem(accessKey);
+  localStorage.removeItem(refreshKey);
+};

package/src/contexts/AppAuthContext.tsx

@@ -2,6 +2,13 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { useForge } from "../provider/ForgeProvider";
 import { createForgeClient } from "../client/createForgeClient";
+import {
+  APP_ACCESS_TOKEN_KEY as APP_ACCESS_KEY,
+  APP_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  readStoredToken,
+  storeTokenPair,
+} from "../client/tokenStorage";
 
 // App-user auth for a mini-app frontend (account_associations type='app'). This
 // is the app's OWN user base — distinct from TribeNest fans (usePublicAuth) and
@@ -9,7 +16,8 @@ import { createForgeClient } from "../client/createForgeClient";
 // client (its own localStorage key) so an app-user session never collides with a
 // profile session on the same site. Backed by /public/app-sessions/*.
 
-export const APP_ACCESS_TOKEN_KEY = "app-access-token";
+// Kept for compat — the canonical constant lives in client/tokenStorage.ts.
+export const APP_ACCESS_TOKEN_KEY = APP_ACCESS_KEY;
 
 export interface AppAuthUser {
   id: string;
@@ -38,9 +46,19 @@ export interface AppSignupInput {
   lastName?: string;
 }
 
-export type AppSignupResult =
-  | { status: "pending"; user: AppAuthUser }
-  | { status: "active"; user: AppAuthUser };
+/**
+ * What BOTH `signup` and `login` return: the platform emailed a 6-digit code and
+ * issued no session. Collect the code and call `verifyCode`. Neither entry point
+ * has a variant that logs a user straight in.
+ */
+export type AppAuthChallenge = { status: "verify_email"; email: string };
+
+/**
+ * The outcome of redeeming the code. `active` means signed in (token stored).
+ * `pending` means the address is proven but this app requires OWNER APPROVAL, so
+ * there is still no session — show a "waiting for approval" screen.
+ */
+export type AppAuthResult = { status: "pending"; user: AppAuthUser } | { status: "active"; user: AppAuthUser };
 
 interface AppAuthContextType {
   appId?: string;
@@ -49,10 +67,26 @@ interface AppAuthContextType {
   isInitialized: boolean;
   isLoading: boolean;
   errorMessage: string | null;
-  /** Sign up. When the app requires owner approval, returns status "pending" and
-   *  does NOT log the user in (no token) — show a "pending approval" screen. */
-  signup: (input: AppSignupInput) => Promise<AppSignupResult>;
-  login: (input: { email: string; password: string }) => Promise<void>;
+  /**
+   * Step 1 of 2. Creates the account and emails a 6-digit code; it NEVER logs the
+   * user in. Always returns `{ status: "verify_email" }` — including for an email
+   * the platform has never seen, so the response can't be used to discover which
+   * addresses are already registered. Collect the code, then call `verifyCode`.
+   */
+  signup: (input: AppSignupInput) => Promise<AppAuthChallenge>;
+  /**
+   * Step 1 of 2. Checks the password and emails a 6-digit code — it does NOT
+   * return a session. Collect the code and call `verifyCode`. (App login is
+   * two-factor by design; a wrong password still fails here, before any code.)
+   */
+  login: (input: { email: string; password: string }) => Promise<AppAuthChallenge>;
+  /**
+   * Step 2 of 2 for BOTH signup and login. Redeems the emailed code. On success
+   * the user is signed in (`active`) unless this app requires owner approval, in
+   * which case the address is proven but the session still waits (`pending`) —
+   * proving your email is not the owner approving you.
+   */
+  verifyCode: (input: { email: string; code: string }) => Promise<AppAuthResult>;
   logout: () => Promise<void>;
   refetch: () => Promise<void>;
   clearError: () => void;
@@ -80,7 +114,26 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
   // client (which carries the profile/member token).
   const tokenRef = useRef<string | null>(null);
   const client = useMemo(
-    () => createForgeClient({ baseURL: apiUrl, publishableKey, getToken: () => tokenRef.current }),
+    () =>
+      createForgeClient({
+        baseURL: apiUrl,
+        publishableKey,
+        getToken: () => tokenRef.current,
+        // App-user lane (backend §7): same 15-minute access tokens, own refresh
+        // chain on its own storage keys so it never collides with a fan session.
+        refresh: {
+          path: "/public/app-sessions/refresh",
+          getRefreshToken: () => readStoredToken(APP_REFRESH_TOKEN_KEY),
+          onRefreshed: ({ token: next, refreshToken }) => {
+            tokenRef.current = next;
+            storeTokenPair(APP_ACCESS_TOKEN_KEY, APP_REFRESH_TOKEN_KEY, next, refreshToken);
+          },
+          onFailed: () => {
+            tokenRef.current = null;
+            clearTokenPair(APP_ACCESS_TOKEN_KEY, APP_REFRESH_TOKEN_KEY);
+          },
+        },
+      }),
     [apiUrl, publishableKey],
   );
 
@@ -127,13 +180,41 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       setErrorMessage(null);
       try {
         const res = await client.post("/public/app-sessions/signup", { appId, ...input });
-        const { status, account, token } = res.data as { status: "pending" | "active"; account: AppAuthUser; token?: string };
+        const { email } = res.data as { status: "verify_email"; email: string };
+        // No token here, by design — see AppAuthChallenge.
+        return { status: "verify_email", email };
+      } catch (err) {
+        setErrorMessage(extractError(err));
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [appId, client],
+  );
+
+  const verifyCode = useCallback<AppAuthContextType["verifyCode"]>(
+    async ({ email, code }) => {
+      if (!appId) throw new Error("AppAuthProvider: no appId in Forge context.");
+      setIsLoading(true);
+      setErrorMessage(null);
+      try {
+        const res = await client.post("/public/app-sessions/verify", { appId, email, code });
+        const { status, account, token, refreshToken } = res.data as {
+          status: "pending" | "active";
+          account: AppAuthUser;
+          token?: string;
+          refreshToken?: string;
+        };
         if (status === "active" && token) {
           setToken(token);
+          if (refreshToken && typeof localStorage !== "undefined") {
+            localStorage.setItem(APP_REFRESH_TOKEN_KEY, refreshToken);
+          }
           setUser(account);
           return { status: "active", user: account };
         }
-        // Pending approval — no token issued.
+        // Email proven, but the owner still has to approve — no token issued.
         return { status: "pending", user: account };
       } catch (err) {
         setErrorMessage(extractError(err));
@@ -152,8 +233,10 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       setErrorMessage(null);
       try {
         const res = await client.post("/public/app-sessions", { appId, ...input });
-        setToken(res.data.token);
-        setUser(res.data.account);
+        // The password was checked, but no session is issued until the emailed
+        // code is redeemed — see AppAuthChallenge.
+        const { email } = res.data as { status: "verify_email"; email: string };
+        return { status: "verify_email", email };
       } catch (err) {
         setErrorMessage(extractError(err));
         throw err;
@@ -161,7 +244,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
         setIsLoading(false);
       }
     },
-    [appId, client, setToken],
+    [appId, client],
   );
 
   const logout = useCallback<AppAuthContextType["logout"]>(async () => {
@@ -171,6 +254,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       // best-effort — clear locally regardless
     }
     setToken(null);
+    if (typeof localStorage !== "undefined") localStorage.removeItem(APP_REFRESH_TOKEN_KEY);
     setUser(null);
   }, [client, setToken]);
 
@@ -184,6 +268,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       errorMessage,
       signup,
       login,
+      verifyCode,
       logout,
       refetch,
       clearError: () => setErrorMessage(null),
@@ -192,7 +277,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       // crash in a render guard is worse than a hidden button.
       hasPermission: (permission: string) => (user?.permissions ?? []).includes(permission),
     }),
-    [appId, user, isInitialized, isLoading, errorMessage, signup, login, logout, refetch],
+    [appId, user, isInitialized, isLoading, errorMessage, signup, login, verifyCode, logout, refetch],
   );
 
   return <AppAuthContext.Provider value={value}>{children}</AppAuthContext.Provider>;

package/src/contexts/PublicAuthContext.tsx

@@ -23,8 +23,16 @@ enum Types {
   UpdateUser = "UPDATE_USER",
   UpdateErrorMessage = "UPDATE_ERROR_MESSAGE",
 }
-export const ACCESS_TOKEN_KEY = "public-access-token";
-export const PUBLIC_ACCESS_TOKEN_KEY = "public-access-token";
+import {
+  PUBLIC_ACCESS_TOKEN_KEY,
+  PUBLIC_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  storeTokenPair,
+} from "../client/tokenStorage";
+
+// Kept for compat — the canonical constants live in client/tokenStorage.ts.
+export const ACCESS_TOKEN_KEY = PUBLIC_ACCESS_TOKEN_KEY;
+export { PUBLIC_ACCESS_TOKEN_KEY };
 
 type AuthPayload = {
   [Types.Initial]: { isAuthenticated: boolean; user: PublicAuthUser | null };
@@ -198,8 +206,8 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
     try {
       const response = await client.post("/public/sessions", data);
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
       dispatch({ type: Types.Login, payload: { user: account } });
       return { smartLinkPath };
@@ -220,8 +228,8 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
     try {
       const response = await client.post("/public/sessions/verify", { email, code, profileId });
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
       dispatch({ type: Types.Login, payload: { user: account } });
       return { smartLinkPath };
@@ -264,8 +272,36 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
       const response = await client.post("/public/accounts", {
         ...data,
       });
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      // No token: signup issues no session until the emailed code is redeemed
+      // (see PublicAuthChallenge). Keep the caller's data — `verifyRegistration`
+      // needs the coupon/consent flags again to finish the job.
+      const { email } = response.data as { status: "verify_email"; email: string };
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      return { status: "verify_email" as const, email };
+    } catch (err: unknown) {
+      const error = err as ApiError;
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      throw error;
+    }
+  };
+
+  const verifyRegistration = async (data: {
+    email: string;
+    code: string;
+    profileId?: string;
+    couponCode?: string;
+    acceptedTerms?: boolean;
+    acceptedPrivacy?: boolean;
+  }) => {
+    dispatch({ type: Types.Loading, payload: { isLoading: true } });
+
+    try {
+      const response = await client.post("/public/accounts/verify", {
+        ...data,
+        profileId: data.profileId ?? profileId,
+      });
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
 
       dispatch({ type: Types.Register, payload: { user: account } });
@@ -279,7 +315,7 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
   const logout = async (persist = true) => {
     try {
-      localStorage.removeItem(ACCESS_TOKEN_KEY);
+      clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
       dispatch({ type: Types.Logout });
       if (persist) await client.delete("/sessions");
     } catch (error) {
@@ -308,6 +344,7 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
         resendLoginCode,
         logout,
         register,
+        verifyRegistration,
         updateLocalUser,
         clearErrorMessage,
         refetchUser,

package/src/data/queries/useCheckouts.ts

@@ -1,5 +1,6 @@
 import { useMutation } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
+import { bundleCouponRequestBody } from "../../ui/headless/checkout/bundleCoupon";
 import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
 
 /** One line of a bundle, in the shape `POST /public/checkouts` expects. */
@@ -69,7 +70,35 @@ export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCa
   return [...ticketLines, ...productLines];
 }
 
-export type CreateCheckoutResult = { checkoutId: string; currency: string; subtotalCents: number };
+/**
+ * One discount that actually came off a bundle — entered or automatic.
+ *
+ * `discountAmount` is in MAJOR units, unlike everything else the bundle endpoint
+ * returns, because it is the same shape every other pillar's checkout answers
+ * with. Naming the coupon is what lets an AUTOMATIC bundle discount render as
+ * "SUMMER10 — $6.00 off" rather than an unexplained reduction; before the
+ * response carried this, only `discountCents` and a `couponId` came back and
+ * there is no public `couponId` → code lookup.
+ */
+export type AppliedBundleCoupon = {
+  code: string;
+  discountKind: string;
+  /** MAJOR units. */
+  discountAmount: number;
+};
+
+/** Note the units: the bundle endpoint is the only checkout answering in MINOR units. */
+export type CreateCheckoutResult = {
+  checkoutId: string;
+  currency: string;
+  /** GROSS, minor units. (Beware: `start-payment` returns a NET `subtotalCents`.) */
+  subtotalCents: number;
+  discountCents?: number;
+  couponId?: string | null;
+  /** NET = max(0, subtotalCents − discountCents), minor units. */
+  totalCents?: number;
+  appliedCoupons?: AppliedBundleCoupon[];
+};
 
 export function useCreateCheckout() {
   const { client, profileId } = useForge();
@@ -82,6 +111,60 @@ export function useCreateCheckout() {
   });
 }
 
+/**
+ * What `POST /public/checkouts/apply-coupon` answers with.
+ *
+ * The payment fields are populated only when the bundle had already started
+ * payment: applying re-prices the children AND re-mints the intent, so the
+ * caller swaps its payment element onto the new secret rather than re-running
+ * start-payment. An empty `paymentSecret` means there was no intent to replace.
+ */
+export type ApplyCheckoutCouponResult = {
+  checkoutId: string;
+  currency: string;
+  /** GROSS, minor units — what the goods cost undiscounted. */
+  subtotalCents: number;
+  discountCents: number;
+  couponId: string | null;
+  /** NET = max(0, subtotalCents − discountCents), minor units. */
+  totalCents: number;
+  appliedCoupons: AppliedBundleCoupon[];
+  paymentSecret: string;
+  paymentId: string;
+  chargedAmount: number;
+  chargedCurrency: string;
+  /** True when the re-price took the bundle to zero — it is already settled. */
+  isFreeCheckout: boolean;
+};
+
+/**
+ * Apply — or REMOVE — a discount code on a bundle that already exists.
+ *
+ * Omitting `couponCode` removes whatever is on it and restores the original
+ * total. This is the bundle's counterpart to `/public/orders/apply-coupon`, and
+ * it is why the code field on a bundle no longer has to freeze the moment the
+ * checkout is created.
+ */
+export function useApplyCheckoutCoupon() {
+  const { client, profileId } = useForge();
+
+  return useMutation<
+    ApplyCheckoutCouponResult,
+    unknown,
+    { checkoutId: string; returnUrl: string; couponCode?: string }
+  >({
+    mutationFn: async ({ checkoutId, returnUrl, couponCode }) => {
+      // The body is built by `bundleCouponRequestBody` so the "remove sends no
+      // code at all" rule is asserted in one place rather than trusted here.
+      const res = await client.post(
+        "/public/checkouts/apply-coupon",
+        bundleCouponRequestBody({ profileId, checkoutId, returnUrl, couponCode }),
+      );
+      return res.data;
+    },
+  });
+}
+
 export type FinalizeCheckoutResult = {
   checkoutId: string;
   status: string;

package/src/data/queries/useCoachingAvailability.ts

@@ -1,4 +1,4 @@
-import type { BookingSlot } from "../../types/models";
+import type { BookingSlot, PillarDiscountQuote } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -40,13 +40,28 @@ export type UpdateCoachingBookingInput = {
   confirmIfFree?: boolean;
   questionnaire?: unknown;
   attributionRefId?: string;
+  /** Omit (or send `undefined`) to CLEAR a previously applied code. */
+  couponCode?: string;
 };
 
-/** Attach buyer details to a reserved coaching booking (confirms it if free). */
+export type UpdateCoachingBookingResult = PillarDiscountQuote & {
+  bookingId: string;
+  isConfirmed: boolean;
+};
+
+/**
+ * Attach buyer details to a reserved coaching booking (confirms it if free) and
+ * (re-)price it.
+ *
+ * This doubles as the coaching pillar's quote: the gross price is re-derived
+ * from the PRODUCT on every call, so applying and then removing a discount code
+ * returns the buyer to exactly the original total instead of compounding off an
+ * already-netted figure. Only a still-`reserved` booking is re-priced.
+ */
 export function useUpdateCoachingBooking(productId?: string) {
   const { client } = useForge();
 
-  return useMutation<{ bookingId: string; isConfirmed: boolean }, unknown, UpdateCoachingBookingInput>({
+  return useMutation<UpdateCoachingBookingResult, unknown, UpdateCoachingBookingInput>({
     mutationFn: async (body) => {
       const res = await client.post(`/public/coaching/products/${productId}/booking/update`, body);
       return res.data;

package/src/data/queries/useCourseAccess.ts

@@ -38,7 +38,7 @@ export function useClaimCourseAccess() {
   const { client } = useForge();
 
   return useMutation<
-    { token?: string; accessId?: string },
+    { token?: string; refreshToken?: string; accessId?: string },
     unknown,
     { token: string; password: string; firstName: string; lastName: string }
   >({

package/src/data/queries/useCourses.ts

@@ -1,4 +1,4 @@
-import type { PaginatedData, PublicCourse } from "../../types/models";
+import type { PaginatedData, PillarDiscountQuote, PublicCourse } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -10,6 +10,47 @@ export type CreateCourseBookingInput = {
   attributionRefId?: string;
 };
 
+export type UpdateCourseBookingInput = {
+  bookingId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  /** Confirm the booking outright when nothing is left to charge. */
+  confirmIfFree?: boolean;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+  /** Omit (or send `undefined`) to CLEAR a previously applied code. */
+  couponCode?: string;
+};
+
+export type UpdateCourseBookingResult = PillarDiscountQuote & {
+  bookingId: string;
+  isConfirmed: boolean;
+};
+
+/**
+ * Attach buyer details to a course booking and (re-)price it.
+ *
+ * This is the course pillar's de-facto quote: it re-derives the gross price
+ * from the COURSE on every call — never from the booking's already-netted total
+ * — specifically so it can be fired repeatedly as the buyer edits the form.
+ * That is what makes apply/remove of a discount code safe here, and why
+ * removing one restores the original total rather than compounding.
+ *
+ * Only a still-`reserved` booking is re-priced; a confirmed one keeps the
+ * coupon and total it was actually charged at.
+ */
+export function useUpdateCourseBooking(courseId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<UpdateCourseBookingResult, unknown, UpdateCourseBookingInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/courses/${courseId}/booking/update`, { profileId, ...body });
+      return res.data;
+    },
+  });
+}
+
 /** Create a course booking (buyer details → bookingId; free courses skip payment). */
 export function useCreateCourseBooking(courseId?: string) {
   const { client, profileId } = useForge();