@tribe-nest/forge 3.52.0 → 3.53.0

package/package.json

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

package/src/data/queries/useMyCourses.ts

@@ -0,0 +1,42 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * The courses this fan can open on this site.
+ *
+ * `GET /public/courses/mine` resolves a grant by account OR by verified email,
+ * so a buyer who never clicked the claim link still sees what they paid for.
+ * That matters more here than anywhere: before this, a purchased course was the
+ * one thing a fan could buy and then not find, and the creator's only remedy
+ * was re-sending a claim link by hand.
+ */
+export type MyCourse = {
+  accessId: string;
+  courseId: string;
+  title: string;
+  description: string | null;
+  slug: string | null;
+  cohortId: string | null;
+  currentLessonId: string | null;
+  completedAt: string | null;
+  /** False when the claim link was never used. The course is theirs either way;
+   *  the flag exists so the UI can reassure rather than stay silent. */
+  claimed: boolean;
+  purchasedAt: string;
+};
+
+export function useMyCourses({ accountId, enabled = true }: { accountId?: string; enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+
+  return useQuery<MyCourse[]>({
+    // `accountId` is in the key so signing out and back in as someone else
+    // cannot serve the previous fan's courses from cache.
+    queryKey: ["my-courses", accountId, profileId],
+    enabled: Boolean(accountId) && enabled,
+    queryFn: async () => {
+      const res = await client.get("/public/courses/mine", { params: { profileId } });
+      return (res.data ?? []) as MyCourse[];
+    },
+  });
+}

package/src/data/queries/useWebsiteAgent.ts

@@ -8,6 +8,8 @@ export interface WebsiteAgentConfig {
   allowAnonymous?: boolean;
   allowOrderLookup?: boolean;
   allowLeadCapture?: boolean;
+  /** Paths the widget must not appear on. "/blog/*" covers every child. */
+  excludedPaths?: string[];
 }
 
 /** Widget bootstrap config for the profile. When `enabled` is false the widget

package/src/i18n/de.json

@@ -23,6 +23,11 @@
   "forge.account_dashboard.cancelling": "Wird storniert…",
   "forge.account_dashboard.close": "Schließen",
   "forge.account_dashboard.confirm_password": "Neues Passwort bestätigen",
+  "forge.account_dashboard.courses_completed": "Abgeschlossen",
+  "forge.account_dashboard.courses_continue": "Dort weitermachen, wo du aufgehört hast",
+  "forge.account_dashboard.courses_empty": "Noch nichts hier. Gekaufte Kurse erscheinen auf dieser Seite.",
+  "forge.account_dashboard.courses_start": "Starten",
+  "forge.account_dashboard.courses_title": "Deine Kurse",
   "forge.account_dashboard.current_password": "Aktuelles Passwort",
   "forge.account_dashboard.data_export_description": "Exportiere eine Kopie deiner persönlichen Daten.",
   "forge.account_dashboard.data_section_title": "Deine Daten",
@@ -78,6 +83,7 @@
   "forge.account_dashboard.sessions_title": "Meine Sessions",
   "forge.account_dashboard.tab_account": "Konto",
   "forge.account_dashboard.tab_bookings": "Buchungen",
+  "forge.account_dashboard.tab_courses": "Kurse",
   "forge.account_dashboard.tab_membership": "Mitgliedschaft",
   "forge.account_dashboard.tab_notifications": "Mitteilungen",
   "forge.account_dashboard.tab_orders": "Bestellungen",
@@ -1287,4 +1293,4 @@
   "forge.user_menu.create_account": "Konto erstellen",
   "forge.user_menu.log_in": "Anmelden",
   "forge.user_menu.log_out": "Abmelden"
-}
+}

package/src/i18n/en.json

@@ -23,6 +23,11 @@
   "forge.account_dashboard.cancelling": "Cancelling…",
   "forge.account_dashboard.close": "Close",
   "forge.account_dashboard.confirm_password": "Confirm new password",
+  "forge.account_dashboard.courses_completed": "Completed",
+  "forge.account_dashboard.courses_continue": "Continue where you left off",
+  "forge.account_dashboard.courses_empty": "Nothing here yet. Courses you buy appear on this page.",
+  "forge.account_dashboard.courses_start": "Start",
+  "forge.account_dashboard.courses_title": "Your courses",
   "forge.account_dashboard.current_password": "Current password",
   "forge.account_dashboard.data_export_description": "Export a copy of your personal data.",
   "forge.account_dashboard.data_section_title": "Your Data",
@@ -78,6 +83,7 @@
   "forge.account_dashboard.sessions_title": "My Sessions",
   "forge.account_dashboard.tab_account": "Account",
   "forge.account_dashboard.tab_bookings": "Bookings",
+  "forge.account_dashboard.tab_courses": "Courses",
   "forge.account_dashboard.tab_membership": "Membership",
   "forge.account_dashboard.tab_notifications": "Notifications",
   "forge.account_dashboard.tab_orders": "Orders",
@@ -1287,4 +1293,4 @@
   "forge.user_menu.create_account": "Create account",
   "forge.user_menu.log_in": "Log in",
   "forge.user_menu.log_out": "Log out"
-}
+}

package/src/index.ts

@@ -121,6 +121,7 @@ export * from "./data/queries/useAccount";
 export * from "./data/queries/useMyTickets";
 export * from "./data/queries/usePassTransfers";
 export * from "./data/queries/useMyBookings";
+export * from "./data/queries/useMyCourses";
 // The member's own call calendar. Beside `useMyBookings` and `useMyTickets`
 // because it answers the same shape of question: what have I got coming up
 // with this artist, and where do I go for it.

package/src/ui/headless/agent/_tests/pathExclusion.spec.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { isPathExcluded } from "../pathExclusion";
+
+/**
+ * The client half of the exclusion rule. It has to agree with the server half
+ * (`apps/backend/src/services/public/agent/pathExclusion.ts`) case for case:
+ * the server decides what gets stored, the browser decides what gets hidden,
+ * and a disagreement shows the widget on a page the artist excluded.
+ */
+describe("isPathExcluded", () => {
+  const patterns = ["/pricing", "/blog/*"];
+
+  it("shows the widget when nothing is excluded", () => {
+    expect(isPathExcluded("/pricing", [])).toBe(false);
+    expect(isPathExcluded("/pricing", undefined)).toBe(false);
+  });
+
+  it("hides it on an exactly named page", () => {
+    expect(isPathExcluded("/pricing", patterns)).toBe(true);
+  });
+
+  it("leaves a sibling that merely shares a prefix alone", () => {
+    expect(isPathExcluded("/pricing-guide", patterns)).toBe(false);
+    expect(isPathExcluded("/blogroll", patterns)).toBe(false);
+  });
+
+  it("hides it under a wildcard, index page included", () => {
+    expect(isPathExcluded("/blog", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/hello", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/2026/hello", patterns)).toBe(true);
+  });
+
+  it("ignores case, a trailing slash and a query string", () => {
+    expect(isPathExcluded("/Blog/Hello/", patterns)).toBe(true);
+    expect(isPathExcluded("/PRICING?ref=email", patterns)).toBe(true);
+  });
+
+  it("treats a bare /* as the whole site", () => {
+    expect(isPathExcluded("/", ["/*"])).toBe(true);
+    expect(isPathExcluded("/anything/deep", ["/*"])).toBe(true);
+  });
+
+  it("hides it on the home page only when '/' is listed", () => {
+    expect(isPathExcluded("/", ["/"])).toBe(true);
+    expect(isPathExcluded("/shop", ["/"])).toBe(false);
+  });
+
+  it("accepts a stored pattern the artist typed loosely", () => {
+    expect(isPathExcluded("/pricing", ["pricing"])).toBe(true);
+    expect(isPathExcluded("/blog/hello", ["/blog/"])).toBe(false);
+  });
+});

package/src/ui/headless/agent/_tests/useCurrentPath.spec.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useCurrentPath } from "../useCurrentPath";
+
+/**
+ * The widget hides itself per page, so it has to notice a page change. Forge
+ * has no router, and a site's in-app link is a `pushState` that fires no event
+ * of its own - which is exactly the case a `popstate`-only listener misses, and
+ * would leave the widget showing on an excluded page for the rest of the visit.
+ */
+describe("useCurrentPath", () => {
+  afterEach(() => {
+    window.history.pushState({}, "", "/");
+  });
+
+  it("reports the path the browser is on", () => {
+    window.history.pushState({}, "", "/pricing");
+    const { result } = renderHook(() => useCurrentPath());
+    expect(result.current).toBe("/pricing");
+  });
+
+  it("follows a pushState navigation, which is every in-app link", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/blog/hello");
+    });
+    expect(result.current).toBe("/blog/hello");
+  });
+
+  it("follows a replaceState navigation too", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.replaceState({}, "", "/shop");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("ignores the query string, which is not part of the path", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/shop?sort=new");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("leaves history working for everyone else - the wrap is additive", () => {
+    renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/one");
+    });
+    expect(window.location.pathname).toBe("/one");
+  });
+});

package/src/ui/headless/agent/pathExclusion.ts

@@ -0,0 +1,53 @@
+/**
+ * Client half of the concierge's "don't appear on these pages" rule.
+ *
+ * The artist stores paths in the admin; the widget hides itself when the page
+ * it is on matches one. Two forms:
+ *   "/pricing"   - that page only
+ *   "/blog/*"    - that page AND everything under it
+ *
+ * Matching is case-insensitive and ignores a trailing slash, so "/blog",
+ * "/Blog" and "/blog/" are one page here as they are to a visitor.
+ *
+ * This must stay in step with the server half,
+ * `apps/backend/src/services/public/agent/pathExclusion.ts`, which normalises
+ * what gets stored. Kept as a copy rather than an import because Forge ships to
+ * creator sites and cannot reach into the backend.
+ */
+
+/** Reduce one stored pattern or page path to the form both sides compare. */
+function normalize(raw: string): string {
+  let path = (raw || "").trim();
+  if (!path) return "";
+  const url = /^https?:\/\/[^/]+(\/.*)?$/i.exec(path);
+  if (url) path = url[1] || "/";
+  path = path.split("#")[0].split("?")[0];
+  if (!path.startsWith("/")) path = `/${path}`;
+  path = path.replace(/\/{2,}/g, "/");
+  const wildcard = path.endsWith("/*");
+  const base = wildcard ? path.slice(0, -2) : path;
+  const cleaned = base.length > 1 ? base.replace(/\/+$/, "") : base;
+  return wildcard ? `${cleaned}/*` : cleaned || "/";
+}
+
+/** Does `path` fall under any of `patterns`? */
+export function isPathExcluded(path: string, patterns: readonly string[] | null | undefined): boolean {
+  if (!patterns || patterns.length === 0) return false;
+  const normalizedTarget = normalize(path);
+  const target = (
+    normalizedTarget.endsWith("/*") ? normalizedTarget.slice(0, -2) || "/" : normalizedTarget
+  ).toLowerCase();
+  for (const raw of patterns) {
+    const pattern = normalize(raw).toLowerCase();
+    if (!pattern) continue;
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      // "/*" alone means the whole site.
+      if (prefix === "") return true;
+      if (target === prefix || target.startsWith(`${prefix}/`)) return true;
+      continue;
+    }
+    if (target === pattern) return true;
+  }
+  return false;
+}

package/src/ui/headless/agent/useAiAgent.ts

@@ -5,6 +5,8 @@ import {
   streamAgentMessage,
   useWebsiteAgentConfig,
 } from "../../../data/queries/useWebsiteAgent";
+import { isPathExcluded } from "./pathExclusion";
+import { useCurrentPath } from "./useCurrentPath";
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
@@ -35,6 +37,7 @@ function getVisitorId(): string {
 export function useAiAgent() {
   const { apiUrl, profileId, token } = useForge();
   const config = useWebsiteAgentConfig();
+  const path = useCurrentPath();
 
   const [messages, setMessages] = useState<AiAgentMessage[]>([]);
   const [sending, setSending] = useState(false);
@@ -94,9 +97,15 @@ export function useAiAgent() {
     [apiUrl, profileId, token, visitorId, sending, ensureConversation],
   );
 
+  // The artist can keep the assistant off named pages. Checked here rather than
+  // in the widget so every UI built on this hook obeys it, including custom
+  // ones. SSR reports no path, so the widget stays hidden until the browser can
+  // say where it is - appearing and then vanishing would be worse.
+  const excluded = !path || isPathExcluded(path, config.data?.excludedPaths);
+
   return {
     config: config.data,
-    isEnabled: !!config.data?.enabled,
+    isEnabled: !!config.data?.enabled && !excluded,
     loading: config.isLoading,
     messages,
     sending,

package/src/ui/headless/agent/useCurrentPath.ts

@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react";
+
+/**
+ * The browser's current path, kept up to date across client-side navigation.
+ *
+ * Forge has no router of its own and ships into sites that do, so it cannot
+ * subscribe to one. `popstate` alone misses a pushState navigation, which is
+ * every in-app link, so the two history methods are wrapped once per document
+ * to emit an event the hook listens for. The wrapping is additive: the original
+ * methods still run, and anything else that wrapped them keeps working.
+ *
+ * Returns "" during SSR, where there is no location to read.
+ */
+
+const EVENT = "forge:locationchange";
+let patched = false;
+
+function patchHistoryOnce() {
+  if (patched || typeof window === "undefined") return;
+  patched = true;
+  for (const method of ["pushState", "replaceState"] as const) {
+    const original = window.history[method];
+    window.history[method] = function patchedMethod(this: History, ...args: Parameters<History[typeof method]>) {
+      const result = original.apply(this, args);
+      window.dispatchEvent(new Event(EVENT));
+      return result;
+    };
+  }
+}
+
+export function useCurrentPath(): string {
+  const [path, setPath] = useState(() => (typeof window === "undefined" ? "" : window.location.pathname));
+
+  useEffect(() => {
+    patchHistoryOnce();
+    const update = () => setPath(window.location.pathname);
+    // A navigation that happened between first render and this effect would
+    // otherwise be missed.
+    update();
+    window.addEventListener("popstate", update);
+    window.addEventListener(EVENT, update);
+    return () => {
+      window.removeEventListener("popstate", update);
+      window.removeEventListener(EVENT, update);
+    };
+  }, []);
+
+  return path;
+}

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();