@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/posts/usePostItem.ts

@@ -4,10 +4,10 @@ import type { AudioTrack } from "../../../contexts/AudioPlayerContext";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
 import { usePostEngagement } from "../engagement/usePostEngagement";
-import { buildPostUpsell, type PostUpsell, type UpsellPathOptions } from "./upsell";
+import { buildPostUpsell, useUpsellContext, type PostUpsell, type UpsellPathOptions } from "./upsell";
 
 export interface UsePostItemOptions extends UpsellPathOptions {
-  /** Other audio posts in the feed — becomes the continue-playing queue. */
+  /** Other audio posts in the feed: becomes the continue-playing queue. */
   otherAudioPosts?: IPublicPost[];
   /** Shown as the audio track artist (the craft members area uses the profile name). */
   artistName?: string;
@@ -28,7 +28,7 @@ const toTrack = (post: IPublicPost, media: IMedia, artistName?: string): AudioTr
 });
 
 /**
- * Headless single-post behavior — the Forge port of the craft `PostItem` minus
+ * Headless single-post behavior: the Forge port of the craft `PostItem` minus
  * rendering: engagement (like/save/comment via `usePostEngagement`), media
  * selection (image/video/audio/document), the audio track + queue for the
  * Forge audio player, and the locked-post upsell state. The server already
@@ -36,6 +36,7 @@ const toTrack = (post: IPublicPost, media: IMedia, artistName?: string): AudioTr
  */
 export function usePostItem(post: IPublicPost, opts: UsePostItemOptions = {}) {
   const { isAuthenticated } = usePublicAuth();
+  const upsellContext = useUpsellContext(opts);
   const { data: tiers } = useGetMembershipTiers();
 
   const engagement = usePostEngagement(post.id, "post", {
@@ -64,13 +65,13 @@ export function usePostItem(post: IPublicPost, opts: UsePostItemOptions = {}) {
     [opts.otherAudioPosts, opts.artistName],
   );
 
-  const upsell: PostUpsell = buildPostUpsell(post, tiers, isAuthenticated, opts);
+  const upsell: PostUpsell = buildPostUpsell(post, tiers, isAuthenticated, upsellContext.paths, upsellContext.unlockWith);
 
   return {
     post,
     kind,
     isLocked,
-    /** First media item (null when locked — the server ships none). */
+    /** First media item (null when locked: the server ships none). */
     media,
     audioTrack,
     audioQueue,

package/src/ui/headless/siteApp/appBar.ts

@@ -0,0 +1,102 @@
+import { internalPath } from "../../../runtime/pages";
+import {
+  SITE_APP_BAR_KEYS,
+  SITE_APP_BAR_MAX_ITEMS,
+  SITE_APP_DEFAULT_BAR,
+  type SiteAppBarKey,
+} from "../../../data/queries/useSiteApp";
+
+/**
+ * The site app's bottom bar: Home, then the creator's chosen items (at most
+ * three), then More, which opens a sheet with every other destination. Kept
+ * apart from how it is drawn so the bar, the sheet and a spec can never
+ * disagree about what goes where (the same split as `buildMemberHomeBar`).
+ */
+
+export type AppBarKey = "home" | SiteAppBarKey;
+
+export interface AppBarItem {
+  key: AppBarKey;
+  href: string;
+  active: boolean;
+}
+
+export interface AppBarModel {
+  /** Home first, then the configured items. More is not an item: it is always drawn last. */
+  bar: AppBarItem[];
+  /** Every destination not in the bar, in the canonical order. */
+  more: AppBarItem[];
+  /** The page being shown lives in the sheet, so More is the highlighted button. */
+  moreActive: boolean;
+}
+
+/** Where each destination goes. Inbox is the member's notifications. */
+export const APP_BAR_HREFS: Readonly<Record<SiteAppBarKey, string>> = {
+  communities: internalPath("communities"),
+  portal: internalPath("account"),
+  inbox: internalPath("account/notifications"),
+  events: internalPath("events"),
+  courses: internalPath("courses"),
+  shop: internalPath("store"),
+};
+
+/**
+ * The configured keys made safe: unknown keys and repeats dropped, at most
+ * three. A missing or empty list is the contract's default.
+ */
+export function normaliseBarItems(items: readonly string[] | null | undefined): SiteAppBarKey[] {
+  if (!items || items.length === 0) return [...SITE_APP_DEFAULT_BAR];
+  const known = new Set<string>(SITE_APP_BAR_KEYS);
+  const out: SiteAppBarKey[] = [];
+  for (const key of items) {
+    if (!known.has(key) || out.includes(key as SiteAppBarKey)) continue;
+    out.push(key as SiteAppBarKey);
+    if (out.length === SITE_APP_BAR_MAX_ITEMS) break;
+  }
+  return out;
+}
+
+/** Strip a query and hash, and a trailing slash, so `/i/events/` and `/i/events?x=1` compare equal. */
+function clean(path: string): string {
+  const bare = path.split(/[?#]/)[0] ?? "";
+  return bare.length > 1 ? bare.replace(/\/+$/, "") : bare;
+}
+
+/**
+ * Is `currentPath` this destination? Home matches only itself; the others match
+ * their own page and anything below it, except that the portal does not claim
+ * the inbox, which lives under it.
+ */
+export function isAppBarItemActive(key: AppBarKey, href: string, currentPath: string | null | undefined): boolean {
+  if (!currentPath) return false;
+  const here = clean(currentPath);
+  const target = clean(href);
+  if (key === "home") return here === target;
+  if (key === "portal" && isAppBarItemActive("inbox", APP_BAR_HREFS.inbox, here)) return false;
+  return here === target || here.startsWith(`${target}/`);
+}
+
+/**
+ * Decide what sits in the bar and what goes behind More. Pure.
+ *
+ * Every destination appears exactly once, in the bar or in the sheet.
+ */
+export function buildAppBar({
+  barItems,
+  homeHref,
+  currentPath,
+}: {
+  barItems: readonly string[] | null | undefined;
+  homeHref: string;
+  currentPath?: string | null;
+}): AppBarModel {
+  const chosen = normaliseBarItems(barItems);
+  const item = (key: AppBarKey, href: string): AppBarItem => ({
+    key,
+    href,
+    active: isAppBarItemActive(key, href, currentPath),
+  });
+  const bar = [item("home", homeHref), ...chosen.map((key) => item(key, APP_BAR_HREFS[key]))];
+  const more = SITE_APP_BAR_KEYS.filter((key) => !chosen.includes(key)).map((key) => item(key, APP_BAR_HREFS[key]));
+  return { bar, more, moreActive: more.some((entry) => entry.active) };
+}

package/src/ui/headless/siteApp/appHome.ts

@@ -0,0 +1,344 @@
+import { internalPath } from "../../../runtime/pages";
+import { bookingCallWindow } from "../../media/bookingWindow";
+import { SITE_APP_SECTION_KEYS, type SiteAppHomeSection, type SiteAppSectionKey } from "../../../data/queries/useSiteApp";
+import type { PortalAttentionItem, PortalSectionKey, PortalSummary } from "../portal/usePortal";
+import type { MyBooking } from "../../../data/queries/useMyBookings";
+import type { MyTicket } from "../../../data/queries/useMyTickets";
+import type { MyCourse } from "../../../data/queries/useMyCourses";
+import type { MyMembershipCall } from "../../../data/queries/useMembershipCalls";
+import type { CourseAccessData, IEvent, IPublicProduct, PublicCourse } from "../../../types/models";
+
+/**
+ * The site app's home (`/i/app`): the sections the creator configured, in their
+ * order, each drawn only when it has something to show. The portal is the one
+ * exception: it is always drawn, because it is where everything a member owns
+ * lives. Everything here is pure, so the order, the visibility and the
+ * empty-skip are decided in one place a spec can read.
+ */
+
+// ---- Portal tiles -------------------------------------------------------------------
+
+export type AppPortalTileKey = "projects" | "bookings" | "invoices" | "documents" | "courses" | "orders" | "tickets" | "saved" | "settings";
+
+export interface AppPortalTile {
+  key: AppPortalTileKey;
+  href: string;
+  /** How many things in this section need the person (the tile's badge). 0 draws none. */
+  attention: number;
+}
+
+/** The tiles, in the order the grid draws them, each with the summary count that decides it. */
+export const APP_PORTAL_TILES: ReadonlyArray<{ key: Exclude<AppPortalTileKey, "settings">; countKey: PortalSectionKey; href: string }> = [
+  { key: "projects", countKey: "projects", href: internalPath("account/projects") },
+  { key: "bookings", countKey: "bookings", href: internalPath("account/bookings") },
+  { key: "invoices", countKey: "invoices", href: internalPath("account/invoices") },
+  { key: "documents", countKey: "documents", href: internalPath("account/documents") },
+  { key: "courses", countKey: "courses", href: internalPath("account/courses") },
+  { key: "orders", countKey: "orders", href: internalPath("account/orders") },
+  { key: "tickets", countKey: "tickets", href: internalPath("account/tickets") },
+  { key: "saved", countKey: "saved", href: internalPath("account/saved") },
+];
+
+const ATTENTION_TILE: Record<PortalAttentionItem["kind"], AppPortalTileKey | null> = {
+  invoice_due: "invoices",
+  invoice_overdue: "invoices",
+  document_to_sign: "documents",
+  approval_requested: "projects",
+  membership_payment_failed: null,
+  message_unread: null,
+};
+
+/**
+ * The portal grid: a tile for each section the person has anything in, then
+ * Settings so a new fan's grid is never empty and a full one is exactly eight.
+ */
+export function buildPortalTiles(summary: PortalSummary | null | undefined): AppPortalTile[] {
+  const attention: Partial<Record<AppPortalTileKey, number>> = {};
+  for (const item of summary?.attention ?? []) {
+    const tile = ATTENTION_TILE[item.kind];
+    if (tile) attention[tile] = (attention[tile] ?? 0) + 1;
+  }
+  const tiles: AppPortalTile[] = APP_PORTAL_TILES.filter((tile) => (summary?.sections?.[tile.countKey] ?? 0) > 0).map(
+    (tile) => ({ key: tile.key, href: tile.href, attention: attention[tile.key] ?? 0 }),
+  );
+  if (tiles.length < APP_PORTAL_TILES.length) {
+    tiles.push({ key: "settings", href: internalPath("account/settings"), attention: 0 });
+  }
+  return tiles;
+}
+
+// ---- Needs you ----------------------------------------------------------------------
+
+export interface AppAttentionAction {
+  item: PortalAttentionItem;
+  /** Which verb the button says. */
+  action: "pay" | "review" | "reply" | "update";
+  href: string;
+}
+
+/** Where each portal attention item is acted on: the exact thing, one tap away. */
+export function attentionAction(item: PortalAttentionItem): AppAttentionAction {
+  switch (item.kind) {
+    case "invoice_due":
+    case "invoice_overdue":
+      return { item, action: "pay", href: internalPath("invoice/$invoiceId", { invoiceId: item.id }) };
+    case "approval_requested":
+      return {
+        item,
+        action: "review",
+        href: `${internalPath("account/projects/$projectId", { projectId: item.projectId })}#approvals`,
+      };
+    case "document_to_sign":
+      return { item, action: "review", href: internalPath("documents/$token", { token: item.token }) };
+    case "message_unread":
+      return { item, action: "reply", href: internalPath("account/messages") };
+    case "membership_payment_failed":
+      return { item, action: "update", href: internalPath("communities/$slug/home", { slug: item.communitySlug }) };
+  }
+}
+
+// ---- Coming up ----------------------------------------------------------------------
+
+export interface AppNextCall {
+  id: string;
+  title: string;
+  startsAt: string;
+  /** The call is open right now. */
+  joinable: boolean;
+  /** The room when joinable, else where the session is listed. */
+  href: string;
+  /** Who it is with: the audience label of a member call, or null for a booked session. */
+  context: string | null;
+}
+
+export interface AppNextTicket {
+  id: string;
+  title: string;
+  startsAt: string;
+  /** Passes on the order, at least 1. */
+  count: number;
+  href: string;
+}
+
+/**
+ * The next call: a member call or a booked session, whichever comes first and
+ * has not ended. An open one is joinable.
+ */
+export function pickNextCall(
+  calls: readonly MyMembershipCall[] | null | undefined,
+  bookings: readonly MyBooking[] | null | undefined,
+  now: Date,
+): AppNextCall | null {
+  const candidates: AppNextCall[] = [];
+  for (const call of calls ?? []) {
+    if (Date.parse(call.endsAt) < now.getTime()) continue;
+    const joinable = call.isOpen && !!call.callPublicId;
+    candidates.push({
+      id: `call:${call.id}`,
+      title: call.title,
+      startsAt: call.startsAt,
+      joinable,
+      // The call page itself says when the room opens, so it is the link either way.
+      href: call.callPublicId ? internalPath("video-calls/$callId", { callId: call.callPublicId }) : internalPath("account"),
+      context: call.audiences?.[0]?.label ?? null,
+    });
+  }
+  for (const booking of bookings ?? []) {
+    if (booking.status !== "confirmed") continue;
+    if (Date.parse(booking.sessionEndTime) < now.getTime()) continue;
+    const joinable = bookingCallWindow(booking, now).isOpen && !!booking.videoCallId;
+    candidates.push({
+      id: `booking:${booking.id}`,
+      title: booking.coachingProductTitle,
+      startsAt: booking.sessionStartTime,
+      joinable,
+      href: joinable ? internalPath("video-calls/$callId", { callId: booking.videoCallId! }) : internalPath("account/bookings"),
+      context: null,
+    });
+  }
+  candidates.sort((a, b) => Date.parse(a.startsAt) - Date.parse(b.startsAt));
+  return candidates[0] ?? null;
+}
+
+/** The next event the person holds a ticket for. Cancelled and refunded orders do not count. */
+export function pickNextTicket(tickets: readonly MyTicket[] | null | undefined, now: Date): AppNextTicket | null {
+  const upcoming = (tickets ?? [])
+    .filter((ticket) => !ticket.selfCancelledAt && ticket.status !== "cancelled" && ticket.status !== "refunded")
+    .filter((ticket) => Date.parse(ticket.eventEndDateTime ?? ticket.eventDateTime) >= now.getTime())
+    .sort((a, b) => Date.parse(a.eventDateTime) - Date.parse(b.eventDateTime));
+  const next = upcoming[0];
+  if (!next) return null;
+  const count = (next.items ?? []).reduce((sum, item) => sum + (Number(item.quantity) || 0), 0);
+  return {
+    id: next.id,
+    title: next.eventTitle,
+    startsAt: next.eventDateTime,
+    count: Math.max(1, count),
+    href: internalPath("account/tickets"),
+  };
+}
+
+// ---- Continue learning -------------------------------------------------------------
+
+/** The course to carry on with: one started and not finished, else the newest not finished. */
+export function pickLearningCourse(courses: readonly MyCourse[] | null | undefined): MyCourse | null {
+  const open = (courses ?? []).filter((course) => !course.completedAt);
+  return open.find((course) => !!course.currentLessonId) ?? open[0] ?? null;
+}
+
+export interface AppCourseProgress {
+  done: number;
+  total: number;
+  /** 0 to 1. */
+  ratio: number;
+}
+
+/** Lessons done out of lessons released, from the classroom read. Null when there are no lessons. */
+export function courseProgress(access: CourseAccessData | null | undefined): AppCourseProgress | null {
+  if (!access) return null;
+  const lessons = (access.course?.modules ?? []).flatMap((module) => module.lessons ?? []);
+  if (lessons.length === 0) return null;
+  const completed = new Set((access.progress ?? []).filter((row) => row.isCompleted).map((row) => row.lessonId));
+  const done = lessons.filter((lesson) => completed.has(lesson.id) || lesson.progress?.isCompleted).length;
+  return { done, total: lessons.length, ratio: done / lessons.length };
+}
+
+export interface AppLearningCourse {
+  accessId: string;
+  title: string;
+  href: string;
+  progress: AppCourseProgress | null;
+}
+
+// ---- Communities ---------------------------------------------------------------------
+
+export interface AppCommunityCard {
+  id: string;
+  name: string;
+  slug: string;
+  logoUrl: string | null;
+  coverUrl: string | null;
+  tierName: string | null;
+  memberCount: number | null;
+  href: string;
+  /** Explore only: how a visitor gets in, which names the button. */
+  joinMode?: "open" | "application" | "invite";
+}
+
+// ---- The sections ---------------------------------------------------------------------
+
+/** Everything the home can show, already fetched and shaped. Missing means none. */
+export interface AppHomeData {
+  attention?: readonly PortalAttentionItem[];
+  portalTiles?: readonly AppPortalTile[];
+  communities?: readonly AppCommunityCard[];
+  nextCall?: AppNextCall | null;
+  nextTicket?: AppNextTicket | null;
+  learning?: AppLearningCourse | null;
+  explore?: readonly AppCommunityCard[];
+  events?: readonly IEvent[];
+  courses?: readonly PublicCourse[];
+  products?: readonly IPublicProduct[];
+}
+
+export type AppHomeSectionView =
+  | { kind: "needs_you"; key: "needs_you"; actions: AppAttentionAction[] }
+  | { kind: "portal"; key: "portal"; tiles: AppPortalTile[] }
+  | { kind: "communities"; key: "communities"; communities: AppCommunityCard[] }
+  | { kind: "coming_up"; key: "coming_up"; call: AppNextCall | null; ticket: AppNextTicket | null }
+  | { kind: "learning"; key: "learning"; course: AppLearningCourse }
+  | { kind: "explore_communities"; key: "explore_communities"; communities: AppCommunityCard[] }
+  | { kind: "events"; key: "events"; events: IEvent[] }
+  | { kind: "courses"; key: "courses"; courses: PublicCourse[] }
+  | { kind: "shop"; key: "shop"; products: IPublicProduct[] }
+  | { kind: "link"; key: string; label: string; href: string };
+
+/** How many items a list section shows before "See all". */
+export const APP_HOME_LIST_LIMIT = { explore: 3, events: 4, courses: 3, products: 4 } as const;
+
+const KNOWN = new Set<string>(SITE_APP_SECTION_KEYS);
+
+/** A link section's address: a site path, or an absolute http(s) URL. Anything else is not drawn. */
+export function isSafeLinkHref(href: string | null | undefined): boolean {
+  const value = href?.trim() ?? "";
+  if (value.startsWith("/")) return !value.startsWith("//") && !value.startsWith("/\\");
+  return /^https?:\/\/[^\s]+$/i.test(value);
+}
+
+/**
+ * The sections to draw, in the configured order. Pure.
+ *
+ * Hidden entries, unknown keys, repeats and broken links are skipped. A
+ * section with nothing to show is skipped too, except the portal.
+ */
+export function buildAppHomeSections(
+  config: readonly SiteAppHomeSection[] | null | undefined,
+  data: AppHomeData,
+): AppHomeSectionView[] {
+  const out: AppHomeSectionView[] = [];
+  const seen = new Set<string>();
+  for (const entry of config ?? []) {
+    if (!entry || entry.visible === false) continue;
+    if (entry.type === "link") {
+      const label = entry.label?.trim();
+      if (!label || !isSafeLinkHref(entry.href) || seen.has(`link:${entry.id}`)) continue;
+      seen.add(`link:${entry.id}`);
+      out.push({ kind: "link", key: entry.id, label, href: entry.href.trim() });
+      continue;
+    }
+    if (entry.type !== "builtin" || !KNOWN.has(entry.key) || seen.has(entry.key)) continue;
+    seen.add(entry.key);
+    const view = builtinView(entry.key, data);
+    if (view) out.push(view);
+  }
+  return out;
+}
+
+function builtinView(key: SiteAppSectionKey, data: AppHomeData): AppHomeSectionView | null {
+  switch (key) {
+    case "needs_you": {
+      const actions = (data.attention ?? []).map(attentionAction);
+      return actions.length ? { kind: key, key, actions } : null;
+    }
+    case "portal":
+      // Always drawn: it is where everything the member owns lives.
+      return { kind: key, key, tiles: [...(data.portalTiles ?? buildPortalTiles(null))] };
+    case "communities":
+      return data.communities?.length ? { kind: key, key, communities: [...data.communities] } : null;
+    case "coming_up":
+      return data.nextCall || data.nextTicket
+        ? { kind: key, key, call: data.nextCall ?? null, ticket: data.nextTicket ?? null }
+        : null;
+    case "learning":
+      return data.learning ? { kind: key, key, course: data.learning } : null;
+    case "explore_communities":
+      return data.explore?.length
+        ? { kind: key, key, communities: data.explore.slice(0, APP_HOME_LIST_LIMIT.explore) }
+        : null;
+    case "events":
+      return data.events?.length ? { kind: key, key, events: data.events.slice(0, APP_HOME_LIST_LIMIT.events) } : null;
+    case "courses":
+      return data.courses?.length
+        ? { kind: key, key, courses: data.courses.slice(0, APP_HOME_LIST_LIMIT.courses) }
+        : null;
+    case "shop":
+      return data.products?.length
+        ? { kind: key, key, products: data.products.slice(0, APP_HOME_LIST_LIMIT.products) }
+        : null;
+  }
+}
+
+/** Events still to come, soonest first. Cancelled, completed and archived ones are left out. */
+export function upcomingEvents(events: readonly IEvent[] | null | undefined, now: Date): IEvent[] {
+  return (events ?? [])
+    .filter((event) => event.status !== "cancelled" && event.status !== "completed" && event.status !== "draft")
+    .filter((event) => !event.cancelledAt && !event.archivedAt)
+    .filter((event) => Date.parse(event.endDateTime ?? event.dateTime) >= now.getTime())
+    .sort((a, b) => Date.parse(a.dateTime) - Date.parse(b.dateTime));
+}
+
+/** The time-of-day part of the greeting. */
+export function greetingPart(now: Date): "morning" | "afternoon" | "evening" {
+  const hour = now.getHours();
+  return hour < 12 ? "morning" : hour < 18 ? "afternoon" : "evening";
+}