@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/portal/usePortalFiles.ts

@@ -0,0 +1,68 @@
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+/**
+ * Every file this person has with the creator (`GET /public/portal/files`):
+ * project files shared with them, attachments on their project tasks, signed
+ * documents, invoice PDFs and their paid downloads, newest first across all.
+ *
+ * A row never carries a signed address. `open` says which endpoint serves it,
+ * and that endpoint checks ownership again on the click.
+ */
+
+export type PortalFileSource = "project" | "task" | "document" | "invoice" | "purchase";
+export type PortalFileSourceFilter = PortalFileSource | "all";
+
+export type PortalFileOpen =
+  /** Fetch a 60-second URL through `useWorkOpenSharedDocument(projectId)`. */
+  | { kind: "project_document"; projectId: string; documentId: string }
+  /** A public media address, safe to link directly. */
+  | { kind: "task_attachment"; projectId: string; taskId: string; url: string }
+  /** The recipient token: `GET /public/documents/:token/download`. */
+  | { kind: "signed_document"; token: string }
+  /** `GET /public/invoices/:id/pdf`. */
+  | { kind: "invoice_pdf"; invoiceId: string }
+  /** A paid download: the download page `/i/downloads/<token>`, which lets the owner straight through. */
+  | { kind: "purchase_download"; token: string };
+
+export interface PortalFile {
+  id: string;
+  source: PortalFileSource;
+  title: string;
+  filename: string | null;
+  mimeType: string | null;
+  size: number | null;
+  createdAt: string;
+  projectId: string | null;
+  projectName: string | null;
+  open: PortalFileOpen;
+}
+
+export interface PortalFilesPage {
+  data: PortalFile[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export const portalFilesKey = (profileId?: string, accountId?: string, source?: string, pageSize?: number) =>
+  ["portal-files", profileId, accountId, source, pageSize] as const;
+
+/** Paged newest first. `fetchNextPage` loads the next `pageSize` rows. */
+export function usePortalFiles(source: PortalFileSourceFilter = "all", pageSize = 30) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useInfiniteQuery({
+    queryKey: portalFilesKey(profileId, user?.id, source, pageSize),
+    initialPageParam: 1,
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/portal/files", {
+        params: { profileId, source, page: pageParam, pageSize },
+      });
+      return res.data as PortalFilesPage;
+    },
+    getNextPageParam: (last) => (last.page * last.pageSize < last.total ? last.page + 1 : undefined),
+    enabled: !!profileId && !!client && !!user,
+  });
+}

package/src/ui/headless/portal/usePortalMessages.ts

@@ -0,0 +1,189 @@
+import { useEffect, useMemo } from "react";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useChatSocket } from "../../../data/queries/useChat";
+import { useChatAttachmentUpload } from "../chat/useChatAttachmentUpload";
+
+/**
+ * Messages in the client portal (`/i/account/messages`): one conversation
+ * between this person and the creator (`/public/portal/messages`).
+ *
+ * The creator's replies arrive as the BRAND: `senderName` on a team message is
+ * the creator's name, never the team member who wrote it. Realtime rides the
+ * community chat socket (`chat:<threadId>`); when the socket is not connected,
+ * the open page re-reads every 10 seconds while it is visible.
+ */
+
+export interface PortalMessageAttachment {
+  url: string;
+  fileName: string;
+  fileSize: number;
+  fileType: string;
+}
+
+export interface PortalMessage {
+  id: string;
+  content: string | null;
+  attachments: PortalMessageAttachment[];
+  createdAt: string;
+  /** A reply from the creator's side. */
+  fromTeam: boolean;
+  /** The caller's own message. */
+  isMine: boolean;
+  /** The creator's name on a reply, the person's first name on their own. */
+  senderName: string;
+}
+
+export interface PortalThreadSummary {
+  id: string;
+  createdAt: string;
+  unreadCount: number;
+  lastMessageAt: string | null;
+  lastPreview: string | null;
+}
+
+export interface PortalThreadState {
+  /** May this person write (start a conversation, or keep writing in theirs)? */
+  allowed: boolean;
+  creator: { name: string };
+  /** Null until the first message. */
+  thread: PortalThreadSummary | null;
+}
+
+export interface PortalMessagesPage {
+  /** Oldest first inside the page. */
+  data: PortalMessage[];
+  /** Pass as `before` for the page before this one; null at the start. */
+  nextCursor: string | null;
+}
+
+/** How often an open Messages page re-reads while the socket is not connected. */
+export const PORTAL_MESSAGES_POLL_MS = 10_000;
+
+/** The endpoint that signs a portal attachment upload. */
+export const PORTAL_MESSAGES_PRESIGN_PATH = "/public/portal/messages/attachments/presigned-url";
+
+export const portalThreadKey = (profileId?: string, accountId?: string) =>
+  ["portal-messages-thread", profileId, accountId] as const;
+export const portalMessagesKey = (profileId?: string, accountId?: string) =>
+  ["portal-messages", profileId, accountId] as const;
+
+/** The conversation's header: whether the person may write, the creator, and the thread. */
+export function usePortalThread() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useQuery({
+    queryKey: portalThreadKey(profileId, user?.id),
+    queryFn: async () =>
+      (await client.get("/public/portal/messages", { params: { profileId } })).data as PortalThreadState,
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** The conversation, newest page first. Flatten with `portalMessagesInOrder`. */
+export function usePortalMessages(limit = 30) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useInfiniteQuery({
+    queryKey: portalMessagesKey(profileId, user?.id),
+    initialPageParam: undefined as string | undefined,
+    queryFn: async ({ pageParam }) =>
+      (
+        await client.get("/public/portal/messages/messages", {
+          params: { profileId, limit, ...(pageParam ? { before: pageParam } : {}) },
+        })
+      ).data as PortalMessagesPage,
+    getNextPageParam: (last) => last.nextCursor ?? undefined,
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** Every loaded message, oldest first: the pages are newest first, each oldest first inside. */
+export function portalMessagesInOrder(pages: PortalMessagesPage[] | undefined): PortalMessage[] {
+  return [...(pages ?? [])].reverse().flatMap((page) => page.data);
+}
+
+/** Send one message. The first one opens the conversation. */
+export function useSendPortalMessage() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { content: string; attachments: PortalMessageAttachment[] }) =>
+      (await client.post("/public/portal/messages/messages", { profileId, ...input })).data as PortalMessage,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: portalMessagesKey(profileId, user?.id) });
+      queryClient.invalidateQueries({ queryKey: portalThreadKey(profileId, user?.id) });
+    },
+  });
+}
+
+/** Mark the creator's replies read. */
+export function useMarkPortalMessagesRead() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async () =>
+      (await client.post("/public/portal/messages/read", { profileId })).data as {
+        marked: number;
+        unreadCount: number;
+      },
+    onSuccess: (result) => {
+      if (!result?.marked) return;
+      queryClient.invalidateQueries({ queryKey: portalThreadKey(profileId, user?.id) });
+      // The portal home's "needs you" list carries the unread count too.
+      queryClient.invalidateQueries({ queryKey: ["portal-summary"] });
+    },
+  });
+}
+
+/** Stage and upload attachments through the portal's own signing endpoint. */
+export function usePortalMessageAttachments() {
+  return useChatAttachmentUpload({ presignPath: PORTAL_MESSAGES_PRESIGN_PATH });
+}
+
+/**
+ * Follow the conversation live. Joins `chat:<threadId>` on the chat socket and
+ * re-reads on every new message; while the socket is down, re-reads every 10
+ * seconds as long as the page is visible.
+ */
+export function usePortalMessagesLive(threadId: string | null | undefined) {
+  const { profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const socket = useChatSocket(!!threadId && !!user);
+  const keys = useMemo(
+    () => [portalMessagesKey(profileId, user?.id), portalThreadKey(profileId, user?.id)],
+    [profileId, user?.id],
+  );
+
+  useEffect(() => {
+    if (!threadId) return undefined;
+    const refresh = () => keys.forEach((queryKey) => queryClient.invalidateQueries({ queryKey }));
+    const join = () => socket?.emit("chatJoinChannel", { channelId: threadId });
+    const onMessage = (envelope: { event: string; data: { channelId?: string } }) => {
+      if (envelope?.data?.channelId !== threadId) return;
+      if (envelope.event === "chatNewMessage") refresh();
+    };
+    if (socket) {
+      if (socket.connected) join();
+      socket.on("connect", join);
+      socket.on("message", onMessage);
+    }
+    const poll = setInterval(() => {
+      if (socket?.connected) return;
+      if (typeof document !== "undefined" && document.visibilityState !== "visible") return;
+      refresh();
+    }, PORTAL_MESSAGES_POLL_MS);
+    return () => {
+      clearInterval(poll);
+      if (socket) {
+        socket.off("connect", join);
+        socket.off("message", onMessage);
+        socket.emit("chatLeaveChannel", { channelId: threadId });
+      }
+    };
+  }, [threadId, socket, keys, queryClient]);
+}

package/src/ui/headless/portal/usePortalPreview.ts

@@ -0,0 +1,142 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import {
+  PUBLIC_ACCESS_TOKEN_KEY,
+  PUBLIC_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  storeTokenPair,
+} from "../../../client/tokenStorage";
+
+/**
+ * Preview as client, the site half.
+ *
+ * A creator clicks "Preview as client" in the admin and lands on
+ * `/i/account?preview=<code>`. The code is single use and lives 60 seconds; it
+ * is the only thing in the URL. This file trades it for a read-only, 15-minute
+ * session for that client, and exposes what the portal needs to say so.
+ *
+ * Two hooks, on purpose:
+ *
+ * - `usePortalPreviewRedeem()` does the exchange. Mount it ONCE, on the portal
+ *   page wrapper. Mounted twice, the second exchange would spend nothing (the
+ *   code is stripped from the address bar before the first request leaves) but
+ *   it is still one job with one owner.
+ * - `usePortalPreview()` is read-only state plus `exit()`. Mount it wherever the
+ *   portal needs to know (the banner, a write button that wants to explain
+ *   itself). The server refuses every write a preview makes regardless.
+ */
+
+const PREVIEW_PARAM = "preview";
+
+/** Codes this page has already tried, so a re-run effect never spends one twice. */
+const attempted = new Set<string>();
+let redeeming = false;
+
+const readCode = (): string | null => {
+  if (typeof window === "undefined") return null;
+  return new URLSearchParams(window.location.search).get(PREVIEW_PARAM);
+};
+
+/** Take the code out of the address bar (and so out of history and any Referer) at once. */
+const stripCode = () => {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has(PREVIEW_PARAM)) return;
+  url.searchParams.delete(PREVIEW_PARAM);
+  window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+};
+
+/**
+ * True while a preview code is in the URL or being exchanged. An auth guard
+ * checks this AT EFFECT TIME before sending a signed-out visitor to the login
+ * page: the visitor is about to be signed in as the client.
+ */
+export const isPortalPreviewPending = (): boolean => redeeming || readCode() !== null;
+
+export type PortalPreviewRedeemState = { pending: boolean; failed: boolean };
+
+export function usePortalPreviewRedeem(): PortalPreviewRedeemState {
+  const { client, profileId, setToken } = useForge();
+  const { initialize } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const [state, setState] = useState<PortalPreviewRedeemState>({ pending: false, failed: false });
+
+  useEffect(() => {
+    const code = readCode();
+    if (!code) return;
+    stripCode();
+    if (attempted.has(code) || !profileId) return;
+    attempted.add(code);
+    redeeming = true;
+    setState({ pending: true, failed: false });
+
+    client
+      .post("/public/sessions/preview/redeem", { code, profileId })
+      .then(async (res) => {
+        const { token } = res.data as { token: string };
+        // Replace whatever this browser held for the site. The REFRESH token goes
+        // too: left behind, an expired preview would refresh into the previous
+        // identity instead of ending.
+        clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
+        storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token);
+        setToken(token);
+        // Nothing cached for the previous identity may show under the client's name.
+        queryClient.clear();
+        await initialize();
+        redeeming = false;
+        setState({ pending: false, failed: false });
+      })
+      .catch(() => {
+        redeeming = false;
+        setState({ pending: false, failed: true });
+      });
+  }, [client, profileId, setToken, initialize, queryClient]);
+
+  return state;
+}
+
+export type PortalPreview = {
+  /** True while this browser is viewing the portal as a client. */
+  active: boolean;
+  /** The client being previewed. */
+  name: string;
+  /** Who started the preview (the creator or admin). */
+  previewedByName: string;
+  /** ISO time the preview ends. It is never extended. */
+  expiresAt: string | null;
+  /** End the preview, forget the token, and go to the site's home page. */
+  exit: () => Promise<void>;
+};
+
+export function usePortalPreview(): PortalPreview {
+  const { client, setToken } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const preview = user?.preview ?? null;
+
+  const exit = useCallback(async () => {
+    try {
+      await client.post("/public/sessions/preview/end");
+    } catch {
+      // Ending is best effort from here: the session dies at its expiry anyway,
+      // and the token is dropped from this browser below either way.
+    }
+    clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
+    setToken(null);
+    queryClient.clear();
+    if (typeof window !== "undefined") window.location.assign("/");
+  }, [client, setToken, queryClient]);
+
+  const name = [user?.firstName, user?.lastName].filter(Boolean).join(" ").trim() || user?.email || "";
+
+  return {
+    active: !!preview,
+    name,
+    previewedByName: preview?.previewedByName ?? "",
+    expiresAt: preview?.expiresAt ?? null,
+    exit,
+  };
+}

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

@@ -1,4 +1,6 @@
 import type { IPublicPost, MembershipTier } from "../../../types/models";
+import { useOptionalCommunityContext, useCommunityUpgradeOpener } from "../../../contexts/CommunityContext";
+import { communityAboutPath } from "../communities/paths";
 
 /** Where a locked post/collection sends the member to unlock it. */
 export interface PostUpsell {
@@ -6,36 +8,80 @@ export interface PostUpsell {
   tierId: string | null;
   /** Resolved tier (name/price) when the tiers list is available. */
   tier: MembershipTier | null;
-  /** Membership checkout deep link, e.g. `/membership/checkout?membershipTierId=…`. */
+  /**
+   * The join link: the community's About page with the tier preselected
+   * (`/i/communities/<slug>?tier=<id>`) inside a community, else `checkoutPath`.
+   */
   checkoutHref: string;
-  /** Signup-first link for anonymous visitors (redirects into checkout after signup). */
+  /** Signup-first link for anonymous visitors (redirects to `checkoutHref` after signup). */
   signupHref: string;
   /** The link to actually use: checkout when authenticated, signup otherwise. */
   href: string;
+  /**
+   * Opens the community's upgrade sheet on this tier ("Unlock with {tier}")
+   * when a community home provides one and the viewer is signed in. Null
+   * otherwise: follow `href`.
+   */
+  unlock: (() => void) | null;
 }
 
 export interface UpsellPathOptions {
-  /** Membership checkout path (default `/membership/checkout`; site-starter uses `/i/membership/checkout`). */
+  /**
+   * Where a locked item's CTA leads outside a community. Inside one it is the
+   * community's About page, which joins in place. Default `/i/communities`.
+   */
   checkoutPath?: string;
   /** Signup path (default `/signup`; site-starter uses `/i/signup`). */
   signupPath?: string;
+  /** The community's slug. Filled from `<CommunityProvider>` by the hooks. */
+  communitySlug?: string;
 }
 
-export const DEFAULT_CHECKOUT_PATH = "/membership/checkout";
+export const DEFAULT_CHECKOUT_PATH = "/i/communities";
 export const DEFAULT_SIGNUP_PATH = "/signup";
 
-/** Build the locked-content upsell state for a post. Pure — shared by the feed + item hooks. */
+/** Build the locked-content upsell state for a post. Pure: shared by the feed + item hooks. */
 export function buildPostUpsell(
   post: Pick<IPublicPost, "membershipTiers">,
   tiers: MembershipTier[] | undefined,
   isAuthenticated: boolean,
   opts: UpsellPathOptions = {},
+  unlockWith?: ((tierId: string | null) => void) | null,
 ): PostUpsell {
-  const checkoutPath = opts.checkoutPath ?? DEFAULT_CHECKOUT_PATH;
   const signupPath = opts.signupPath ?? DEFAULT_SIGNUP_PATH;
   const tierId = post.membershipTiers?.[0] ?? null;
   const tier = (tierId && tiers?.find((t) => t.id === tierId)) || null;
-  const checkoutHref = tierId ? `${checkoutPath}?membershipTierId=${tierId}` : checkoutPath;
+  let checkoutHref: string;
+  if (opts.communitySlug) {
+    checkoutHref = communityAboutPath(opts.communitySlug, tierId ? { tier: tierId } : undefined);
+  } else {
+    const checkoutPath = opts.checkoutPath ?? DEFAULT_CHECKOUT_PATH;
+    checkoutHref = tierId ? `${checkoutPath}${checkoutPath.includes("?") ? "&" : "?"}tier=${tierId}` : checkoutPath;
+  }
   const signupHref = `${signupPath}?redirect=${encodeURIComponent(checkoutHref)}`;
-  return { tierId, tier, checkoutHref, signupHref, href: isAuthenticated ? checkoutHref : signupHref };
+  return {
+    tierId,
+    tier,
+    checkoutHref,
+    signupHref,
+    href: isAuthenticated ? checkoutHref : signupHref,
+    unlock: unlockWith && isAuthenticated ? () => unlockWith(tierId) : null,
+  };
+}
+
+/**
+ * The upsell inputs a hook reads from the surrounding community: its slug (for
+ * the About page link) and the upgrade sheet opener, when a community home
+ * provides one. Explicit options win.
+ */
+export function useUpsellContext(opts: UpsellPathOptions = {}): {
+  paths: UpsellPathOptions;
+  unlockWith: ((tierId: string | null) => void) | null;
+} {
+  const community = useOptionalCommunityContext();
+  const opener = useCommunityUpgradeOpener();
+  return {
+    paths: { ...opts, communitySlug: opts.communitySlug ?? community?.slug },
+    unlockWith: opener ? (tierId) => opener.openUpgrade(tierId) : null,
+  };
 }

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

@@ -3,7 +3,7 @@ import type { IPublicPost, MembershipTier, PostType } from "../../../types/model
 import { useGetPostsInfinite, useGetSavedPosts } from "../../../data/queries/usePosts";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { buildPostUpsell, type PostUpsell, type UpsellPathOptions } from "./upsell";
+import { buildPostUpsell, useUpsellContext, type PostUpsell, type UpsellPathOptions } from "./upsell";
 
 export interface UseMemberPostsFeedOptions extends UpsellPathOptions {
   /** Posts per page (default 10). */
@@ -13,16 +13,17 @@ export interface UseMemberPostsFeedOptions extends UpsellPathOptions {
 }
 
 /**
- * Headless member posts feed — the Forge port of the craft members area's
+ * Headless member posts feed: the Forge port of the craft members area's
  * `PostsContent` semantics: gated infinite paging over `GET /public/posts`
  * (the server computes per-post `hasAccess` and ships no media for locked
- * posts — never re-gate client-side), debounced search, post-type filter,
+ * posts: never re-gate client-side), debounced search, post-type filter,
  * membership-tier filter, a saved-posts view (`GET /public/posts/saved`),
  * and the locked-post upsell target (which tier unlocks + membership
  * checkout deep link). Bring your own UI.
  */
 export function useMemberPostsFeed(opts: UseMemberPostsFeedOptions = {}) {
   const { isAuthenticated } = usePublicAuth();
+  const upsellContext = useUpsellContext(opts);
 
   // ── Filters ────────────────────────────────────────────────────────────────
   const [search, setSearchState] = useState("");
@@ -70,14 +71,14 @@ export function useMemberPostsFeed(opts: UseMemberPostsFeedOptions = {}) {
   );
   const total = savedOnly ? (saved.data?.total ?? 0) : (feed.data?.pages[0]?.total ?? 0);
 
-  /** Accessible audio posts in feed order — the play queue for audio playback. */
+  /** Accessible audio posts in feed order: the play queue for audio playback. */
   const audioPosts = useMemo(
     () => posts.filter((p) => p.type === "audio" && p.hasAccess && p.media?.[0]?.url),
     [posts],
   );
 
   /** Locked-post upsell: which tier unlocks it + the checkout/signup deep link. */
-  const getUpsell = (post: IPublicPost): PostUpsell => buildPostUpsell(post, tiers, isAuthenticated, opts);
+  const getUpsell = (post: IPublicPost): PostUpsell => buildPostUpsell(post, tiers, isAuthenticated, upsellContext.paths, upsellContext.unlockWith);
 
   return {
     posts,

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

@@ -3,12 +3,12 @@ import type { IPublicPost } from "../../../types/models";
 import { useGetPostCollection } from "../../../data/queries/usePostCollections";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { buildPostUpsell, type PostUpsell, type UpsellPathOptions } from "./upsell";
+import { buildPostUpsell, useUpsellContext, type PostUpsell, type UpsellPathOptions } from "./upsell";
 
 export type UsePostCollectionDetailOptions = UpsellPathOptions;
 
 /**
- * Headless single-collection drill-in — the Forge port of the craft members
+ * Headless single-collection drill-in: the Forge port of the craft members
  * area's `CollectionsContent` detail semantics over
  * `GET /public/post-collections/:id`. The server gates per-collection AND
  * per-post (`hasAccess`; locked posts ship no media), so a member who can see
@@ -19,6 +19,7 @@ export type UsePostCollectionDetailOptions = UpsellPathOptions;
  */
 export function usePostCollectionDetail(collectionId: string | undefined, opts: UsePostCollectionDetailOptions = {}) {
   const { isAuthenticated } = usePublicAuth();
+  const upsellContext = useUpsellContext(opts);
   const { data: tiers } = useGetMembershipTiers();
   const detailQ = useGetPostCollection(collectionId);
 
@@ -30,7 +31,7 @@ export function usePostCollectionDetail(collectionId: string | undefined, opts:
     [collection],
   );
 
-  /** Accessible audio posts in collection order — the play queue for audio playback. */
+  /** Accessible audio posts in collection order: the play queue for audio playback. */
   const audioPosts = useMemo(
     () => posts.filter((p) => p.type === "audio" && p.hasAccess && p.media?.[0]?.url),
     [posts],
@@ -40,7 +41,7 @@ export function usePostCollectionDetail(collectionId: string | undefined, opts:
   const cover = collection?.media?.[0] ?? null;
 
   /** Locked-collection upsell (null until the collection loads). */
-  const upsell: PostUpsell | null = collection ? buildPostUpsell(collection, tiers, isAuthenticated, opts) : null;
+  const upsell: PostUpsell | null = collection ? buildPostUpsell(collection, tiers, isAuthenticated, upsellContext.paths, upsellContext.unlockWith) : null;
 
   return {
     collection,
@@ -51,6 +52,8 @@ export function usePostCollectionDetail(collectionId: string | undefined, opts:
     upsell,
     isLoading: detailQ.isLoading,
     isError: detailQ.isError,
+    /** The collection does not exist in this community (or is archived). */
+    notFound: detailQ.isSuccess && detailQ.data === null,
     isAuthenticated,
   };
 }

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

@@ -3,7 +3,7 @@ import type { IPublicPostCollection, MembershipTier } from "../../../types/model
 import { useGetPostCollections } from "../../../data/queries/usePostCollections";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { buildPostUpsell, type PostUpsell, type UpsellPathOptions } from "./upsell";
+import { buildPostUpsell, useUpsellContext, type PostUpsell, type UpsellPathOptions } from "./upsell";
 
 export interface UsePostCollectionsListOptions extends UpsellPathOptions {
   /** Debounce for the search input → query round trip (default 500ms, matching the craft members area). */
@@ -11,15 +11,16 @@ export interface UsePostCollectionsListOptions extends UpsellPathOptions {
 }
 
 /**
- * Headless post-collections list — the Forge port of the craft members area's
+ * Headless post-collections list: the Forge port of the craft members area's
  * `CollectionsContent` list semantics: paginated `GET /public/post-collections`
  * (the server computes per-collection `hasAccess`; a locked collection can be
- * shown but not opened — never re-gate client-side), debounced search, and the
+ * shown but not opened: never re-gate client-side), debounced search, and the
  * locked-collection upsell target (which tier unlocks + membership checkout
  * deep link). Bring your own UI; drill-in uses `usePostCollectionDetail`.
  */
 export function usePostCollectionsList(opts: UsePostCollectionsListOptions = {}) {
   const { isAuthenticated } = usePublicAuth();
+  const upsellContext = useUpsellContext(opts);
 
   // ── Search + paging ────────────────────────────────────────────────────────
   const [search, setSearchState] = useState("");
@@ -61,14 +62,14 @@ export function usePostCollectionsList(opts: UsePostCollectionsListOptions = {})
 
   /** Locked-collection upsell: which tier unlocks it + the checkout/signup deep link. */
   const getUpsell = (collection: IPublicPostCollection): PostUpsell =>
-    buildPostUpsell(collection, tiers, isAuthenticated, opts);
+    buildPostUpsell(collection, tiers, isAuthenticated, upsellContext.paths, upsellContext.unlockWith);
 
   return {
     collections,
     total,
     isLoading: listQ.isLoading,
     isError: listQ.isError,
-    // Paging (numbered, server-side — matches the craft pagination).
+    // Paging (numbered, server-side: matches the craft pagination).
     page,
     pageSize,
     totalPages,