@tribe-nest/forge 3.59.0 → 3.61.0

package/src/data/queries/useMembership.ts

@@ -6,12 +6,13 @@ import type {
   QuestionnaireAnswer,
 } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
+import { useOptionalCommunityContext } from "../../contexts/CommunityContext";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 
 /**
  * The membership invite token this visitor arrived holding, read from the
- * `invite` search param of the CURRENT url (the invite email links to
- * `/i/membership/checkout?membershipTierId=X&invite=TOKEN`).
+ * `invite` search param of the CURRENT url (the invite email links to the
+ * community's About page, `/i/communities/<slug>?invite=TOKEN`).
  *
  * Deliberately not stored anywhere: it is a bearer credential, and the durable
  * copy is the email. Returns undefined on the server and when absent.
@@ -31,10 +32,17 @@ export interface UseGetMembershipTiersOptions {
    * `null` forwards nothing even when the url carries one.
    */
   inviteToken?: string | null;
+  /**
+   * The community whose tiers to list. Omitted, the surrounding
+   * `<CommunityProvider>` is used; outside one, every live tier on the profile
+   * comes back (a members-only gate on a product can name tiers from any
+   * community). Each tier carries its `communityId` either way.
+   */
+  communityId?: string | null;
 }
 
 /**
- * `opts.enabled` gates the request on top of the usual profile/client checks —
+ * `opts.enabled` gates the request on top of the usual profile/client checks:
  * for a caller that only needs tier NAMES when something is actually gated, and
  * must not add a request to every ungated storefront. Defaults to on, so every
  * existing caller is unchanged.
@@ -44,22 +52,34 @@ export interface UseGetMembershipTiersOptions {
  */
 export function useGetMembershipTiers(opts: UseGetMembershipTiersOptions = {}) {
   const { client, profileId } = useForge();
+  const context = useOptionalCommunityContext();
   const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
+  // `null` asks for the whole profile even inside a provider.
+  const communityId = opts.communityId === undefined ? context?.communityId : (opts.communityId ?? undefined);
+  // Inside a provider whose slug has not resolved yet, wait rather than list the whole profile.
+  const waitingForCommunity = opts.communityId === undefined && !!context && !context.communityId;
 
   return useQuery<MembershipTier[]>({
-    // The token is appended only when present, so the no-invite key stays the
-    // one every existing cache seed (SSR, specs) already writes.
-    queryKey: inviteToken ? ["membership-tiers", profileId, inviteToken] : ["membership-tiers", profileId],
+    // The community and the token are appended only when present, so the
+    // profile-wide key stays the one every existing cache seed (SSR, specs)
+    // already writes.
+    queryKey: [
+      "membership-tiers",
+      profileId,
+      ...(communityId ? [{ communityId }] : []),
+      ...(inviteToken ? [inviteToken] : []),
+    ],
     queryFn: async () => {
       const res = await client.get("/public/membership-tiers", {
         params: {
           profileId: profileId,
+          ...(communityId ? { communityId } : {}),
           ...(inviteToken ? { inviteToken } : {}),
         },
       });
       return res.data;
     },
-    enabled: !!profileId && !!client && opts.enabled !== false,
+    enabled: !!profileId && !!client && !waitingForCommunity && opts.enabled !== false,
   });
 }
 
@@ -109,6 +129,10 @@ export type ApplyForMembershipInput = {
   questionnaire?: QuestionnaireAnswer[];
   /** Where Stripe returns after a redirect-based card confirmation. */
   returnUrl?: string;
+  /** A per-email invite token (`?invite=`). The community comes from the tier. */
+  inviteToken?: string;
+  /** A shareable invite link token (`?join=`). */
+  joinToken?: string;
 };
 
 /** Invalidate everything an application changes: the tier cards and the fan's list. */
@@ -118,6 +142,7 @@ function useInvalidateApplications() {
     Promise.all([
       queryClient.invalidateQueries({ queryKey: ["membership-tiers"] }),
       queryClient.invalidateQueries({ queryKey: ["my-membership-applications"] }),
+      queryClient.invalidateQueries({ queryKey: ["public-communities"] }),
     ]);
 }
 

package/src/data/queries/useMembershipCalls.ts

@@ -1,12 +1,14 @@
 import { useQuery } from "@tanstack/react-query";
+import type { AxiosInstance } from "axios";
 import { useForge } from "../../provider/ForgeProvider";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../contexts/CommunityContext";
 
 /**
  * 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 now the classroom and cohort pages on both - and a
+ * exactly this - every community's calendar tab and the classroom and cohort
+ * pages - and a
  * second copy is how the two drift, as `useMyTickets` and `useMyBookings`
  * already document.
  *
@@ -37,6 +39,90 @@ import { useForge } from "../../provider/ForgeProvider";
 
 export type MembershipCallParticipation = "open" | "host_only";
 
+/** One speaker turn. Times are ms from the start of the recording, so they seek the video. */
+export interface MemberCallTranscriptSegment {
+  name: string;
+  startMs: number;
+  endMs: number;
+  text: string;
+}
+
+/**
+ * A recorded call's transcript, as a member sees it: the finished thing, or
+ * that it is being prepared. Never a failure: the member is shown nothing at
+ * all rather than a reason that is the business's to deal with. Null on the
+ * recording when there is nothing to show.
+ */
+export type MemberCallTranscript =
+  | { status: "processing" }
+  | {
+      status: "ready";
+      /** Null when the summary could not be written; the transcript still stands. */
+      summary: MemberCallTranscriptSummary | null;
+    };
+
+export interface MemberCallTranscriptSummary {
+  title: string;
+  summary: string;
+  decisions: string[];
+  actionItems: string[];
+}
+
+/**
+ * One finished transcript with every line. NOT on the calendar payload: a
+ * two-hour meeting is thousands of lines, so they are read one transcript at a
+ * time, when a member opens it or downloads it.
+ */
+export interface MemberCallTranscriptDetail {
+  recordingId: string;
+  callId: string;
+  title: string;
+  startsAt: string;
+  timezone: string | null;
+  durationSeconds: number | null;
+  /** Signed for SIXTY seconds. Refetch for a fresh one when playback fails. */
+  watchUrl: string | null;
+  transcript: {
+    status: "ready";
+    language: string | null;
+    segments: MemberCallTranscriptSegment[];
+    summary: MemberCallTranscriptSummary | null;
+  };
+}
+
+export const memberCallTranscriptKey = (profileId: string | undefined, recordingId: string) =>
+  ["membership-calls", "transcript", profileId, recordingId] as const;
+
+/** Read one transcript. Shared by the viewer and by Download, so both hit one cache entry. */
+export const fetchMemberCallTranscript = async (
+  client: AxiosInstance,
+  profileId: string | undefined,
+  recordingId: string,
+): Promise<MemberCallTranscriptDetail> => {
+  const res = await client.get(`/public/scheduled-calls/mine/recordings/${recordingId}/transcript`, {
+    params: { profileId },
+  });
+  return res.data as MemberCallTranscriptDetail;
+};
+
+/**
+ * One recording's transcript and a fresh video address, for the viewer.
+ *
+ * Never refetched in the background: the lines do not change, and a refetch
+ * would swap the video address under a playing player. The viewer refetches on
+ * purpose when the sixty-second address lapses.
+ */
+export function useMemberCallTranscript(recordingId: string | null) {
+  const { client, profileId } = useForge();
+  return useQuery<MemberCallTranscriptDetail>({
+    queryKey: memberCallTranscriptKey(profileId, recordingId ?? ""),
+    queryFn: () => fetchMemberCallTranscript(client, profileId, recordingId!),
+    enabled: !!profileId && !!client && !!recordingId,
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+  });
+}
+
 export interface MyMembershipCall {
   id: string;
   title: string;
@@ -84,6 +170,8 @@ export interface MyMembershipCall {
     durationSeconds: number | null;
     /** Signed per request and short-lived. Null while `processing`. */
     watchUrl: string | null;
+    /** Who said what, and a summary. Same access rule as the video. */
+    transcript: MemberCallTranscript | null;
   } | null;
 }
 
@@ -91,6 +179,21 @@ export const membershipCallKeys = {
   mine: (profileId: string | undefined) => ["membership-calls", "mine", profileId] as const,
 };
 
+/**
+ * The community a call read is scoped to, or null for a course or cohort scope.
+ *
+ * A community calendar must come from `<CommunityProvider>`: a fan in two
+ * communities must never see one's calls on the other's calendar. A course or
+ * cohort scope names its own audience and belongs to no community, so it needs
+ * no provider. Anything else is a developer error, and it throws.
+ */
+function useCallScopeCommunity(hookName: string, courseScoped: boolean): string | null | undefined {
+  const community = useOptionalCommunityContext();
+  if (courseScoped) return null;
+  if (!community) throw new MissingCommunityProviderError(hookName);
+  return community.communityId;
+}
+
 /**
  * @param options.from Inclusive lower bound. Absent means "from now on", which is
  * what a caller wanting only the next few calls sends.
@@ -121,6 +224,8 @@ export function useMyMembershipCalls(options?: {
   const to = options?.to?.toISOString();
   const courseId = options?.courseId || undefined;
   const cohortId = options?.cohortId || undefined;
+  // null = a course or cohort scope; a string = this community; undefined = still resolving.
+  const communityId = useCallScopeCommunity("useMyMembershipCalls()", !!(courseId || cohortId));
   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
@@ -134,14 +239,15 @@ export function useMyMembershipCalls(options?: {
       to ?? "open",
       courseId ?? "any-course",
       cohortId ?? "any-cohort",
+      communityId ?? "no-community",
     ],
     queryFn: async () => {
       const res = await client.get("/public/scheduled-calls/mine", {
-        params: { profileId, from, to, limit: options?.limit, courseId, cohortId },
+        params: { profileId, from, to, limit: options?.limit, courseId, cohortId, communityId: communityId ?? undefined },
       });
       return res.data;
     },
-    enabled: !!profileId && !!client && options?.enabled !== false,
+    enabled: !!profileId && !!client && communityId !== undefined && options?.enabled !== false,
     /**
      * A call opens fifteen minutes before it starts, and the member watching
      * this page is waiting for exactly that. Without a refetch the Join button
@@ -175,19 +281,22 @@ export interface MyMembershipCallRecording {
    * for long. Null while `status` is `processing`.
    */
   watchUrl: string | null;
+  /** Who said what, and a summary. Same access rule as the video. */
+  transcript: MemberCallTranscript | null;
 }
 
 export function useMyMembershipCallRecordings(options?: { limit?: number; enabled?: boolean }) {
   const { client, profileId } = useForge();
+  const communityId = useCallScopeCommunity("useMyMembershipCallRecordings()", false);
   return useQuery<MyMembershipCallRecording[]>({
-    queryKey: ["membership-calls", "recordings", profileId],
+    queryKey: ["membership-calls", "recordings", profileId, communityId],
     queryFn: async () => {
       const res = await client.get("/public/scheduled-calls/mine/recordings", {
-        params: { profileId, limit: options?.limit },
+        params: { profileId, communityId, limit: options?.limit },
       });
       return res.data;
     },
-    enabled: !!profileId && !!client && options?.enabled !== false,
+    enabled: !!profileId && !!communityId && !!client && options?.enabled !== false,
     /**
      * Slower than the upcoming list: nothing here changes on a fifteen-minute
      * boundary, and the only transition worth catching is `processing` ->

package/src/data/queries/useMyBookings.ts

@@ -1,4 +1,4 @@
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
 import type { PaginatedData } from "../../types/models";
 
@@ -279,3 +279,26 @@ export function useCancelMyBooking() {
     },
   });
 }
+
+/**
+ * Every session, a page at a time, for a list with a "Show more" button.
+ *
+ * Under the same `my-bookings` key prefix as `useMyBookings`, so cancelling or
+ * rescheduling refreshes this too.
+ */
+export function useMyBookingsPaged(accountId?: string, limit = 20) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery({
+    queryKey: ["my-bookings", accountId, profileId, "paged", limit],
+    initialPageParam: 1,
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/coaching/bookings/mine", { params: { profileId, page: pageParam, limit } });
+      return res.data as PaginatedData<MyBooking>;
+    },
+    getNextPageParam: (last, pages) => {
+      const loaded = pages.reduce((sum, p) => sum + p.data.length, 0);
+      return loaded < last.total && last.data.length > 0 ? pages.length + 1 : undefined;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}

package/src/data/queries/useMyTickets.ts

@@ -1,5 +1,5 @@
 import { useForge } from "../../provider/ForgeProvider";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { PaginatedData } from "../../types/models";
 
 /**
@@ -313,3 +313,26 @@ export function useCancelMyTicket() {
     },
   });
 }
+
+/**
+ * Every ticket, a page at a time, for a list with a "Show more" button.
+ *
+ * Under the same `my-tickets` key prefix as `useMyTickets`, so the cancel and
+ * transfer mutations that invalidate that prefix refresh this too.
+ */
+export function useMyTicketsPaged(accountId?: string, limit = 20) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery({
+    queryKey: ["my-tickets", accountId, profileId, "paged", limit],
+    initialPageParam: 1,
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/events/my-tickets", { params: { profileId, page: pageParam, limit } });
+      return res.data as PaginatedData<MyTicket>;
+    },
+    getNextPageParam: (last, pages) => {
+      const loaded = pages.reduce((sum, p) => sum + p.data.length, 0);
+      return loaded < last.total && last.data.length > 0 ? pages.length + 1 : undefined;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}

package/src/data/queries/useNotifications.ts

@@ -3,7 +3,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useState } from "react";
 
 /**
- * Member notification headless hooks — the FROZEN public contract that the
+ * Member notification headless hooks: the FROZEN public contract that the
  * apps/client PWA and every generated custom-code site consume. Speaks ONLY the
  * `/public/notifications/*` API (see docs/archive/shipped/membership-notifications-initiative.md
  * "API surface"). Moved here from apps/client so custom-code sites get push
@@ -56,6 +56,10 @@ export interface NotificationInboxItem {
     url?: string;
     actorName?: string;
     actorAccountId?: string;
+    /** A `mod` notice about the member's own post or reply: what the moderator decided. */
+    outcome?: "approved" | "rejected";
+    /** The moderator's reason for a rejection, when one was given. */
+    reason?: string | null;
   } | null;
 }
 
@@ -218,7 +222,7 @@ export function useNotificationUnreadCount(enabled = true) {
   });
 }
 
-/** Mark notifications read — omit ids to mark ALL unread as read. */
+/** Mark notifications read. Omit ids to mark ALL unread as read. */
 export function useMarkNotificationsRead() {
   const { client, profileId } = useForge();
   const queryClient = useQueryClient();

package/src/data/queries/useOrders.ts

@@ -1,4 +1,5 @@
 import { useForge } from "../../provider/ForgeProvider";
+import { readMetaSignals } from "../../utils/metaEvents";
 import { useMutation } from "@tanstack/react-query";
 
 /**
@@ -74,7 +75,7 @@ export function useCreateOrder() {
 
   return useMutation<CreateOrderResult, unknown, CreateOrderInput>({
     mutationFn: async (input) => {
-      const res = await client.post("/public/orders", { ...input, profileId });
+      const res = await client.post("/public/orders", { ...input, profileId, metaSignals: readMetaSignals() });
       return res.data;
     },
   });

package/src/data/queries/usePWA.ts

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useState } from "react";
+import { shareRuntimeValue } from "../../runtime/registry";
 
 /**
- * Headless PWA install-prompt hook — the versioned Forge primitive that powers
+ * Headless PWA install-prompt hook: the versioned Forge primitive that powers
  * `<InstallBanner/>` (forge/ui) and any custom install UI on a code site. Ported
  * from apps/client/src/lib/hooks/usePWA.ts, plus iOS + standalone detection
  * (Safari never fires `beforeinstallprompt`, so iOS needs the manual
@@ -22,7 +23,7 @@ export interface InstallPromptState {
   isInstallable: boolean;
   /** The app is running installed (standalone display-mode or iOS standalone). */
   isInstalled: boolean;
-  /** iOS Safari — no `beforeinstallprompt`; show the Add-to-Home-Screen guide. */
+  /** iOS Safari has no `beforeinstallprompt`: show the Add-to-Home-Screen guide. */
   isIOS: boolean;
   /** Currently rendered in standalone (installed) display mode. */
   isStandalone: boolean;
@@ -47,8 +48,108 @@ function detectStandalone(): boolean {
   return !!mm || iosStandalone;
 }
 
+// ---- The captured install prompt, shared ----------------------------------
+//
+// The browser fires `beforeinstallprompt` ONCE per page load, usually soon after
+// it. A listener added later (a prompt mounted after the fan joins a community)
+// would never hear it, so the event is captured the first time anything asks,
+// and every reader shares the one captured event.
+//
+// Shared through the runtime registry, not a module variable: a site and the
+// hosted `/i/` pages bundle each carry a copy of Forge, and the site's copy
+// (`<PwaRegistration>`, at the root) is the one that hears the event.
+
+interface InstallPromptStore {
+  prompt: BeforeInstallPromptEvent | null;
+  installed: boolean;
+  capturing: boolean;
+  listeners: Set<() => void>;
+}
+
+const store = (): InstallPromptStore =>
+  shareRuntimeValue<InstallPromptStore>("state:pwa-install-prompt", () => ({
+    prompt: null,
+    installed: false,
+    capturing: false,
+    listeners: new Set(),
+  }));
+
+const notifyPrompt = () => store().listeners.forEach((listener) => listener());
+
+/**
+ * Start listening for `beforeinstallprompt` (and `appinstalled`). Idempotent and
+ * SSR-safe. `<PwaRegistration enabled>` calls it at mount so the event is held
+ * from the first page a visitor sees.
+ */
+export function captureInstallPrompt(): void {
+  const state = store();
+  if (state.capturing || typeof window === "undefined") return;
+  state.capturing = true;
+  window.addEventListener("beforeinstallprompt", (event: Event) => {
+    event.preventDefault();
+    store().prompt = event as BeforeInstallPromptEvent;
+    notifyPrompt();
+  });
+  window.addEventListener("appinstalled", () => {
+    store().prompt = null;
+    store().installed = true;
+    notifyPrompt();
+  });
+}
+
+/** True when a native install prompt is held and can be shown. */
+export function hasStoredInstallPrompt(): boolean {
+  return !!store().prompt;
+}
+
+/** True once the app was installed during this page's life. */
+export function wasInstalledThisSession(): boolean {
+  return store().installed;
+}
+
+/** Be told when the held prompt arrives, is used, or the app is installed. */
+export function subscribeInstallPrompt(listener: () => void): () => void {
+  store().listeners.add(listener);
+  return () => {
+    store().listeners.delete(listener);
+  };
+}
+
+/**
+ * Show the held native prompt. Resolves true when the visitor accepted. A
+ * prompt can be shown once, so it is released either way.
+ */
+export async function promptStoredInstall(): Promise<boolean> {
+  const state = store();
+  const event = state.prompt;
+  if (!event) return false;
+  state.prompt = null;
+  notifyPrompt();
+  try {
+    await event.prompt();
+    const { outcome } = await event.userChoice;
+    if (outcome === "accepted") {
+      state.installed = true;
+      notifyPrompt();
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/** Test seam: forget whatever was captured, or hold `event` as if the browser had fired it. */
+export function resetInstallPromptForTests(event: Event | null = null): void {
+  const state = store();
+  state.prompt = event as BeforeInstallPromptEvent | null;
+  state.installed = false;
+  notifyPrompt();
+}
+
+export { detectIOS as isIOSDevice, detectStandalone as isStandaloneDisplay };
+
 export function useInstallPrompt(): InstallPromptState {
-  const [deferredPrompt, setDeferredPrompt] = useState<BeforeInstallPromptEvent | null>(null);
   const [isInstallable, setIsInstallable] = useState(false);
   const [isInstalled, setIsInstalled] = useState(false);
   const [isIOS, setIsIOS] = useState(false);
@@ -61,41 +162,16 @@ export function useInstallPrompt(): InstallPromptState {
     setIsStandalone(standalone);
     if (standalone) setIsInstalled(true);
 
-    const handleBeforeInstallPrompt = (e: Event) => {
-      e.preventDefault();
-      setDeferredPrompt(e as BeforeInstallPromptEvent);
-      setIsInstallable(true);
-    };
-    const handleAppInstalled = () => {
-      setIsInstalled(true);
-      setIsInstallable(false);
-      setDeferredPrompt(null);
-    };
-
-    window.addEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
-    window.addEventListener("appinstalled", handleAppInstalled);
-    return () => {
-      window.removeEventListener("beforeinstallprompt", handleBeforeInstallPrompt);
-      window.removeEventListener("appinstalled", handleAppInstalled);
+    captureInstallPrompt();
+    const sync = () => {
+      setIsInstallable(hasStoredInstallPrompt());
+      if (wasInstalledThisSession()) setIsInstalled(true);
     };
+    sync();
+    return subscribeInstallPrompt(sync);
   }, []);
 
-  const promptInstall = useCallback(async () => {
-    if (!deferredPrompt) return false;
-    try {
-      await deferredPrompt.prompt();
-      const { outcome } = await deferredPrompt.userChoice;
-      if (outcome === "accepted") {
-        setIsInstalled(true);
-        setIsInstallable(false);
-        setDeferredPrompt(null);
-        return true;
-      }
-      return false;
-    } catch {
-      return false;
-    }
-  }, [deferredPrompt]);
+  const promptInstall = useCallback(() => promptStoredInstall(), []);
 
   return { isInstallable, isInstalled, isIOS, isStandalone, promptInstall };
 }

package/src/data/queries/usePostCollections.ts

@@ -1,5 +1,5 @@
 import type { IPublicPostCollection, PaginatedData } from "../../types/models";
-import { useForge } from "../../provider/ForgeProvider";
+import { useCommunityScope } from "../../contexts/CommunityContext";
 import { useQuery } from "@tanstack/react-query";
 
 export interface GetPostCollectionsParams {
@@ -8,14 +8,15 @@ export interface GetPostCollectionsParams {
 }
 
 export function useGetPostCollections(params?: GetPostCollectionsParams) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useGetPostCollections()");
 
   return useQuery<PaginatedData<IPublicPostCollection>>({
-    queryKey: ["post-collections", profileId, params],
+    queryKey: ["post-collections", communityId, params],
     queryFn: async () => {
       const res = await client.get("/public/post-collections", {
         params: {
-          profileId: profileId,
+          profileId,
+          communityId,
           page: params?.page || 1,
           limit: 10,
           filter: {
@@ -25,24 +26,35 @@ export function useGetPostCollections(params?: GetPostCollectionsParams) {
       });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
+/**
+ * One collection, by id or slug. A collection that is missing, archived or in
+ * another community answers 404, which is an ANSWER, not a failure: this
+ * resolves `null` for it (and does not retry), so a page can say "not found"
+ * rather than falling over.
+ */
 export function useGetPostCollection(collectionId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useGetPostCollection()");
 
-  return useQuery<IPublicPostCollection>({
-    queryKey: ["post-collection", profileId, collectionId],
+  return useQuery<IPublicPostCollection | null>({
+    queryKey: ["post-collection", communityId, collectionId],
     queryFn: async () => {
-      const res = await client.get(`/public/post-collections/${collectionId}`, {
-        params: {
-          profileId: profileId,
-        },
-      });
-      return res.data;
+      try {
+        const res = await client.get(`/public/post-collections/${collectionId}`, {
+          params: {
+            profileId,
+            communityId,
+          },
+        });
+        return res.data ?? null;
+      } catch (error) {
+        if ((error as { response?: { status?: number } })?.response?.status === 404) return null;
+        throw error;
+      }
     },
-    enabled: !!profileId && !!client && !!collectionId,
+    enabled: !!profileId && !!communityId && !!client && !!collectionId,
   });
 }
-