@tribe-nest/forge 3.59.0 → 3.60.0

package/src/ui/headless/membership/useMembershipCheckout.ts

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { communityHomePath, communitiesListPath } from "../communities/paths";
 import {
   readMembershipInviteFromUrl,
   useApplyForMembership,
@@ -55,9 +57,13 @@ export type { BillingCycle };
 export interface UseMembershipCheckoutOptions {
   /** Pre-select a tier (e.g. from a `?membershipTierId=` param). */
   initialTierId?: string;
-  /** Where the provider returns the member after a paid subscription. Default `/i/account?tab=membership&confirmSubscription=true`. */
+  /**
+   * Where the provider returns the member after a paid subscription. Default:
+   * the community home with `confirmSubscription=1` (the community comes from
+   * `<CommunityProvider>`), or `/i/communities` outside one. Never the account page.
+   */
   returnPath?: string;
-  /** Where free activations land. Default `/i/account?tab=membership`. */
+  /** Where free activations land. Default: the community home with `welcome=1`. */
   freeReturnPath?: string;
   /**
    * Called when the subscription completes IN-APP with nothing left to pay: a
@@ -73,13 +79,30 @@ export interface UseMembershipCheckoutOptions {
    * the current url is used; `null` sends none.
    */
   inviteToken?: string | null;
+  /**
+   * A shareable invite link token (`?join=`), sent with every join call. It
+   * opens an invite-only tier; a paid tier still charges.
+   */
+  joinToken?: string | null;
   /**
    * Where Stripe returns after a redirect-based card confirmation on an
-   * APPLICATION (a card that needed a bank redirect). Default
-   * `/i/account?tab=membership`, where the fan's applications are listed. The
-   * application id is appended as `confirmApplication`.
+   * APPLICATION (a card that needed a bank redirect). Default: the community
+   * home, where a pending application is shown. The application id is appended
+   * as `confirmApplication`.
    */
   applicationReturnPath?: string;
+  /**
+   * The tiers to offer, when the caller already has them (the community read
+   * returns exactly the tiers this viewer may join). Omitted, they are fetched.
+   */
+  tiers?: MembershipTier[];
+  /**
+   * The viewer's current membership IN THIS COMMUNITY, when the caller knows it.
+   * Decides whether subscribing is a tier change. Omitted, the signed-in
+   * account's single legacy `membership` is read, which knows nothing of
+   * communities, so a community surface always passes this.
+   */
+  current?: { tierId: string; status: string } | null;
 }
 
 const errMessage = (e: unknown) =>
@@ -106,8 +129,17 @@ const errMessage = (e: unknown) =>
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user, refetchUser } = usePublicAuth();
+  const community = useOptionalCommunityContext();
   const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
-  const { data: tiers, isLoading } = useGetMembershipTiers({ inviteToken: inviteToken ?? null });
+  const joinToken = opts.joinToken ?? undefined;
+  const fetched = useGetMembershipTiers({ inviteToken: inviteToken ?? null, enabled: !opts.tiers });
+  const tiers = opts.tiers ?? fetched.data;
+  const isLoading = opts.tiers ? false : fetched.isLoading;
+  /** The landing paths, inside the community whenever there is one. */
+  const homeFor = (query?: { welcome?: 1; confirmSubscription?: 1 }) =>
+    community?.slug ? communityHomePath(community.slug, query) : communitiesListPath();
+  const paidReturnPath = opts.returnPath ?? homeFor({ confirmSubscription: 1 });
+  const freeReturnPath = opts.freeReturnPath ?? homeFor({ welcome: 1 });
   const createPaid = useCreateSubscription();
   const createFree = useCreateFreeSubscription();
   const confirmLatest = useConfirmLatestSubscription();
@@ -224,16 +256,29 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     [selectedTier, billingCycle, customAmount],
   );
 
+  /**
+   * The membership this checkout acts on. A fan holds one membership PER
+   * community, so inside a `CommunityProvider` only the caller's `current` (the
+   * viewer's membership in THAT community, as `useCommunityJoin` and the styled
+   * `MembershipCheckout` pass it) may name one. Without it the fan is treated as
+   * holding none here: `user.membership` is the newest membership on the whole
+   * profile and may belong to another community, where it would turn this join
+   * into a tier change. The server decides per community either way.
+   * `user.membership` remains the fallback only outside any community.
+   */
+  const current = opts.current !== undefined ? opts.current : community?.communityId ? null : undefined;
   const membership = user?.membership;
   /** The tier they are on now, so its card can say so instead of offering itself. */
-  const currentTierId = membership?.membershipTierId;
+  const currentTierId = current !== undefined ? (current?.tierId ?? undefined) : membership?.membershipTierId;
   /**
    * A member with a live provider subscription picking a PAID tier is changing,
    * not joining. The server settles it by proration on the subscription they
    * already have, so the button says so.
    */
   const isChange =
-    !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
+    current !== undefined
+      ? !!current && current.status === "active" && !isFreeCycle && !!selectedTier
+      : !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
 
   /**
    * The free trial this fan would start on the selected tier, in days, or 0.
@@ -264,9 +309,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
     if (typeof window !== "undefined") {
       const origin = window.location.origin;
-      const path = requiresConfirmation
-        ? (opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true")
-        : (opts.freeReturnPath ?? "/i/account?tab=membership");
+      const path = requiresConfirmation ? paidReturnPath : freeReturnPath;
       window.location.href = `${origin}${path}`;
     }
   };
@@ -275,7 +318,26 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const questionnaireBody = () =>
     questionnaire.length ? { questionnaire: buildQuestionnaireAnswers(questionnaire, questionnaireAnswers) } : {};
 
-  const subscribe = async () => {
+  /**
+   * How many join calls are running. `isProcessing` reads THIS, not the
+   * mutations' `isPending`: `subscribe` is started from an effect by the join
+   * sheet, and a mutation started from an effect loses its observer when React
+   * StrictMode unmounts and remounts in development, leaving `isPending` stuck
+   * true after the request answered. A settled promise always clears this.
+   */
+  const [inFlight, setInFlight] = useState(0);
+  const tracked =
+    <A extends unknown[]>(run: (...args: A) => Promise<void>) =>
+    async (...args: A) => {
+      setInFlight((n) => n + 1);
+      try {
+        await run(...args);
+      } finally {
+        setInFlight((n) => n - 1);
+      }
+    };
+
+  const subscribe = tracked(async () => {
     setError(null);
     setAmountRefusal(null);
     setTrial(null);
@@ -302,10 +364,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
       await submitApplication(origin);
       return;
     }
-    const returnUrl = `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`;
+    const returnUrl = `${origin}${paidReturnPath}`;
     const attributionRefId = readAttributionRef() ?? undefined;
     const landing = readLanding() ?? {};
-    const invite = inviteToken ? { inviteToken } : {};
+    const invite = { ...(inviteToken ? { inviteToken } : {}), ...(joinToken ? { joinToken } : {}) };
     const answers = questionnaireBody();
     try {
       if (isFreeCycle) {
@@ -371,7 +433,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   /**
    * Apply to an `application` tier. Free: the application is lodged and the
@@ -379,14 +441,16 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
    * moves to "payment" and the renderer saves the card; `confirmApplication()`
    * runs after it succeeds. Nothing is charged until the business approves.
    */
-  const applicationReturnBase = opts.applicationReturnPath ?? "/i/account?tab=membership";
-  const submitApplication = async (origin: string) => {
+  const applicationReturnBase = opts.applicationReturnPath ?? homeFor();
+  const submitApplication = tracked(async (origin: string) => {
     if (!selectedTier) return;
     try {
       const data = await applyMutation.mutateAsync({
         membershipTierId: selectedTier.id,
         ...(isFreeCycle ? {} : { billingCycle, amount }),
         ...questionnaireBody(),
+        ...(inviteToken ? { inviteToken } : {}),
+        ...(joinToken ? { joinToken } : {}),
         returnUrl: `${origin}${applicationReturnBase}`,
       });
       setApplication(data.application);
@@ -398,10 +462,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   /** Call after the card renderer confirmed the SetupIntent. Idempotent on the server. */
-  const confirmApplication = async () => {
+  const confirmApplication = tracked(async () => {
     if (!application) return;
     setError(null);
     setCardConfirmed(true);
@@ -411,7 +475,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   const applicationOutcome: MembershipApplicationOutcome | null = membershipApplicationOutcome(
     application,
@@ -478,8 +542,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
             onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
           })
         : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
-    isProcessing:
-      createPaid.isPending || createFree.isPending || applyMutation.isPending || confirmApplicationMutation.isPending,
+    isProcessing: inFlight > 0,
     error,
     /** Call on the return page to reconcile the latest subscription. */
     confirmLatest,
@@ -487,6 +550,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     finish,
     /** The invite token this checkout forwards, if any. */
     inviteToken,
+    /** The shareable link token this checkout forwards, if any. */
+    joinToken,
+    /** Where a paid subscription returns: the community home with `confirmSubscription=1` by default. */
+    returnPath: paidReturnPath,
     /** True when subscribe() applies to the tier instead of joining it. */
     isApplication,
     /**

package/src/ui/headless/membership/useMembershipGateNotice.ts

@@ -1,6 +1,8 @@
 import { useMemo } from "react";
 import type { PublicMembershipGate } from "../../../types/models";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import { usePublicCommunities } from "../../../data/queries/useCommunities";
+import { communityAboutPath } from "../communities/paths";
 import {
   buildMembershipGateNotice,
   isMembershipGateLocked,
@@ -13,11 +15,15 @@ export interface UseMembershipGateNoticeInput {
   gate?: PublicMembershipGate | null;
   /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate`. */
   refusal?: MembershipGateRefusal | null;
-  /** What the thing is, in the buyer's words — "This ticket", "This course". */
+  /** What the thing is, in the buyer's words: "This ticket", "This course". */
   itemLabel?: string;
   /** Where a signed-out visitor signs in. Code sites mount theirs under `/i`. */
   loginPath?: string;
-  /** Where a signed-in non-member goes to join — the tier listing. */
+  /**
+   * Where a signed-in non-member goes to join. Default: the About page of the
+   * community the first required tier belongs to, with that tier preselected
+   * (`/i/communities/<slug>?tier=<id>`), which joins in place.
+   */
   membershipPath?: string;
 }
 
@@ -29,14 +35,14 @@ export interface UseMembershipGateNoticeInput {
  * A gate comes down as `requiredTierIds`, and "you need tier 8f3c-…" is not a
  * sentence anyone can act on. The public tier list is already loaded by every
  * storefront that sells memberships, is cached by React Query under one key per
- * profile, and — unlike an id embedded in a ticket payload — stays correct when
+ * profile, and (unlike an id embedded in a ticket payload) stays correct when
  * the artist renames a tier. So the ids are resolved against it here, once, for
  * every surface.
  *
  * The names are best-effort by design: the query can be in flight, and a gating
  * tier can be one the public list does not carry (an archived or unlisted tier
  * still gates). `buildMembershipGateNotice` therefore degrades to "is for
- * members" rather than showing an id or rendering nothing — a badge with slightly
+ * members" rather than showing an id or rendering nothing: a badge with slightly
  * vaguer wording is a working funnel; a blank space is the bug this closes.
  *
  * Returns `null` when nothing is gated, which is also what every surface sees
@@ -44,22 +50,33 @@ export interface UseMembershipGateNoticeInput {
  */
 export function useMembershipGateNotice(input: UseMembershipGateNoticeInput): MembershipGateNotice | null {
   const locked = isMembershipGateLocked(input.gate) || !!input.refusal;
-  // Only pulled once something is actually locked — an ungated storefront must
+  // Only pulled once something is actually locked: an ungated storefront must
   // not acquire a request it never needed.
-  const { data: tiers } = useGetMembershipTiers({ enabled: locked });
+  // Profile-wide on purpose: a gate on a product can name a tier from any community.
+  const { data: tiers } = useGetMembershipTiers({ enabled: locked, communityId: null });
+  const { data: communities } = usePublicCommunities({ enabled: locked && !input.membershipPath });
 
   const requiredTierIds = input.refusal?.requiredTierIds ?? input.gate?.requiredTierIds ?? [];
 
   return useMemo(() => {
     if (!locked) return null;
     const byId = new Map((tiers ?? []).map((tier) => [tier.id, tier.name]));
+    // A tier belongs to exactly one community: its About page is where to join it.
+    const firstTier = (tiers ?? []).find((tier) => tier.id === requiredTierIds[0]) as
+      | { id: string; communityId?: string }
+      | undefined;
+    const community = firstTier?.communityId
+      ? communities?.find((candidate) => candidate.id === firstTier.communityId)
+      : undefined;
+    const membershipPath =
+      input.membershipPath ?? (community ? communityAboutPath(community.slug, { tier: firstTier!.id }) : undefined);
     return buildMembershipGateNotice({
       gate: input.gate,
       refusal: input.refusal,
       tierNames: requiredTierIds.map((id) => byId.get(id) ?? "").filter(Boolean),
       itemLabel: input.itemLabel,
       loginPath: input.loginPath,
-      membershipPath: input.membershipPath,
+      membershipPath,
       currentPath: currentPath(),
     });
     // `requiredTierIds` is a fresh array each render; its CONTENTS are the input.
@@ -67,6 +84,7 @@ export function useMembershipGateNotice(input: UseMembershipGateNoticeInput): Me
   }, [
     locked,
     tiers,
+    communities,
     requiredTierIds.join(","),
     input.gate?.reason,
     input.refusal?.reason,

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,

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,