@tribe-nest/forge 1.13.0

package/src/ui/headless/offer/Offer.tsx

@@ -0,0 +1,88 @@
+import type { CSSProperties, ReactNode } from "react";
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogPortal,
+  DialogOverlay,
+  DialogContent,
+  DialogClose,
+  DialogTitle,
+} from "../dialog";
+import { OfferProvider, useOfferContext, type OfferProviderProps } from "./OfferContext";
+
+/** Render-prop payload for `<Offer.PaymentStep>` (redirect-mode payment). */
+export interface OfferPaymentRenderProps {
+  clientSecret?: string;
+  returnUrl: string;
+  amount: number;
+}
+
+type OfferComponent = ((props: OfferProviderProps) => React.ReactElement) & {
+  Trigger: (props: { children: ReactNode; asChild?: boolean }) => React.ReactElement;
+  Modal: (props: {
+    children: ReactNode;
+    className?: string;
+    overlayClassName?: string;
+    style?: CSSProperties;
+    overlayStyle?: CSSProperties;
+  }) => React.ReactElement;
+  Title: (props: { children: ReactNode; className?: string }) => React.ReactElement;
+  Close: (props: { children: ReactNode; asChild?: boolean }) => React.ReactElement;
+  DetailsStep: (props: { children: ReactNode }) => React.ReactElement | null;
+  PaymentStep: (props: {
+    children: ReactNode | ((p: OfferPaymentRenderProps) => ReactNode);
+  }) => React.ReactElement | null;
+};
+
+function OfferRoot({ children }: { children: ReactNode }) {
+  const { open, setOpen } = useOfferContext();
+  return (
+    <DialogRoot open={open} onOpenChange={setOpen}>
+      {children}
+    </DialogRoot>
+  );
+}
+
+/** Headless single-product purchase flow (details → redirect payment). */
+export const Offer = (({ productId, finalisePath, onSuccess, children }: OfferProviderProps) => (
+  <OfferProvider productId={productId} finalisePath={finalisePath} onSuccess={onSuccess}>
+    <OfferRoot>{children}</OfferRoot>
+  </OfferProvider>
+)) as OfferComponent;
+
+Offer.Trigger = function OfferTrigger({ children, asChild }) {
+  return <DialogTrigger asChild={asChild}>{children}</DialogTrigger>;
+};
+
+Offer.Modal = function OfferModal({ children, className, overlayClassName, style, overlayStyle }) {
+  return (
+    <DialogPortal>
+      <DialogOverlay className={overlayClassName} style={overlayStyle} />
+      <DialogContent className={className} style={style}>
+        {children}
+      </DialogContent>
+    </DialogPortal>
+  );
+};
+
+Offer.Title = function OfferTitle({ children, className }) {
+  return <DialogTitle className={className}>{children}</DialogTitle>;
+};
+
+Offer.Close = function OfferClose({ children, asChild }) {
+  return <DialogClose asChild={asChild}>{children}</DialogClose>;
+};
+
+Offer.DetailsStep = function OfferDetailsStep({ children }) {
+  const { step } = useOfferContext();
+  return step === "details" ? <>{children}</> : null;
+};
+
+Offer.PaymentStep = function OfferPaymentStep({ children }) {
+  const ctx = useOfferContext();
+  if (ctx.step !== "payment") return null;
+  if (typeof children === "function") {
+    return <>{children({ clientSecret: ctx.clientSecret, returnUrl: ctx.returnUrl, amount: ctx.totalPrice })}</>;
+  }
+  return <>{children}</>;
+};

package/src/ui/headless/offer/OfferContext.tsx

@@ -0,0 +1,162 @@
+import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
+import type { IPublicProduct, IPublicProductVariant } from "../../../types/models";
+import { useGetProduct } from "../../../data/queries/useProducts";
+import { useCreateOrder } from "../../../data/queries/useOrders";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+
+export type OfferStep = "details" | "payment";
+
+export interface OfferContextValue {
+  product: IPublicProduct | undefined;
+  isLoading: boolean;
+
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  step: OfferStep;
+
+  variants: IPublicProductVariant[];
+  selectedVariantId: string;
+  setSelectedVariantId: (id: string) => void;
+  selectedVariant: IPublicProductVariant | undefined;
+  quantity: number;
+  setQuantity: (n: number) => void;
+  unitPrice: number;
+  totalPrice: number;
+
+  firstName: string;
+  setFirstName: (s: string) => void;
+  lastName: string;
+  setLastName: (s: string) => void;
+  email: string;
+  setEmail: (s: string) => void;
+  confirmEmail: string;
+  setConfirmEmail: (s: string) => void;
+
+  isProcessing: boolean;
+  error: string | null;
+  /** Payment intent once the order is created (Stripe). */
+  clientSecret?: string;
+  returnUrl: string;
+  continueToPayment: () => Promise<void>;
+}
+
+const OfferContext = createContext<OfferContextValue | null>(null);
+
+export function useOfferContext(): OfferContextValue {
+  const ctx = useContext(OfferContext);
+  if (!ctx) throw new Error("Offer components must be used within <Offer>.");
+  return ctx;
+}
+
+export interface OfferProviderProps {
+  productId: string;
+  children: ReactNode;
+  /** Base used for the post-payment return URL. Defaults to /checkout/finalise. */
+  finalisePath?: string;
+  onSuccess?: () => void;
+}
+
+export function OfferProvider({ productId, children, finalisePath }: OfferProviderProps) {
+  const { data: product, isLoading } = useGetProduct(productId);
+  const createOrder = useCreateOrder();
+  const flow = usePaymentFlow({ path: "/public/orders/start-payment", autoStart: false });
+
+  const [open, setOpen] = useState(false);
+  const [step, setStep] = useState<OfferStep>("details");
+  const variants = useMemo(() => product?.variants ?? [], [product?.variants]);
+  const [selectedVariantId, setSelectedVariantId] = useState("");
+  const [quantity, setQuantity] = useState(1);
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [email, setEmail] = useState("");
+  const [confirmEmail, setConfirmEmail] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [returnUrl, setReturnUrl] = useState("");
+
+  const selectedVariant = useMemo(
+    () => variants.find((v) => v.id === selectedVariantId) ?? variants[0],
+    [variants, selectedVariantId],
+  );
+  const unitPrice = selectedVariant?.price ?? 0;
+  const totalPrice = unitPrice * quantity;
+
+  const continueToPayment = async () => {
+    setError(null);
+    if (!product || !selectedVariant) return;
+    if (!firstName.trim() || !lastName.trim()) {
+      setError("Please enter your name.");
+      return;
+    }
+    if (!email.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setError("Please enter a valid email.");
+      return;
+    }
+    if (email !== confirmEmail) {
+      setError("Emails do not match.");
+      return;
+    }
+    try {
+      const created = await createOrder.mutateAsync({
+        amount: totalPrice,
+        email,
+        firstName,
+        lastName,
+        cartItems: [
+          {
+            productId: product.id,
+            productVariantId: selectedVariant.id,
+            quantity,
+            price: unitPrice,
+            title: product.title,
+            coverImage: product.media?.[0]?.url,
+          },
+        ],
+      });
+      const ru = `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath ?? "/checkout/finalise"}?orderId=${created.orderId}`;
+      setReturnUrl(ru);
+      // Free checkout — skip payment.
+      if (created.subTotal === 0 && typeof window !== "undefined") {
+        window.location.href = ru;
+        return;
+      }
+      const result = await flow.start({ orderId: created.orderId, returnUrl: ru });
+      // Paystack redirects itself; Stripe shows the payment step.
+      if (result.provider && result.provider !== "stripe") return;
+      setStep("payment");
+    } catch (e) {
+      const message = (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+      setError(message || "Something went wrong.");
+    }
+  };
+
+  const value: OfferContextValue = {
+    product,
+    isLoading,
+    open,
+    setOpen,
+    step,
+    variants,
+    selectedVariantId,
+    setSelectedVariantId,
+    selectedVariant,
+    quantity,
+    setQuantity,
+    unitPrice,
+    totalPrice,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    confirmEmail,
+    setConfirmEmail,
+    isProcessing: createOrder.isPending || flow.isStarting,
+    error,
+    clientSecret: flow.result?.paymentSecret,
+    returnUrl,
+    continueToPayment,
+  };
+
+  return <OfferContext.Provider value={value}>{children}</OfferContext.Provider>;
+}

package/src/ui/headless/offer/index.ts

@@ -0,0 +1,8 @@
+export { Offer, type OfferPaymentRenderProps } from "./Offer";
+export {
+  OfferProvider,
+  useOfferContext,
+  type OfferContextValue,
+  type OfferProviderProps,
+  type OfferStep,
+} from "./OfferContext";

package/src/ui/headless/paymentLink/usePaymentLinkPayment.ts

@@ -0,0 +1,46 @@
+import { usePaymentLink } from "../../../data/queries/usePaymentLink";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+
+export interface UsePaymentLinkPaymentOptions {
+  /** Return path after payment. Default `/i/payment-link/:id/finalise`. */
+  returnPath?: string;
+  /** Start payment as soon as the link loads (default true). */
+  autoStart?: boolean;
+}
+
+/**
+ * Headless payment-link checkout: loads the link and starts its payment.
+ * Composes `usePaymentLink` + `usePaymentFlow`. Stripe UI renders from
+ * `clientSecret`; finalize on the return page with `usePaymentLinkFinalize`.
+ */
+export function usePaymentLinkPayment(paymentLinkId?: string, opts: UsePaymentLinkPaymentOptions = {}) {
+  const link = usePaymentLink(paymentLinkId);
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const returnUrl = paymentLinkId
+    ? `${origin}${opts.returnPath ?? `/i/payment-link/${paymentLinkId}/finalise`}`
+    : "";
+
+  const flow = usePaymentFlow({
+    path: `/public/payment-links/${paymentLinkId}/start-payment`,
+    returnUrl,
+    autoStart: opts.autoStart ?? true,
+    enabled: !!paymentLinkId && !!link.data,
+  });
+
+  return {
+    link,
+    returnUrl,
+    clientSecret: flow.clientSecret,
+    paymentId: flow.paymentId,
+    provider: flow.provider,
+    /** Authoritative sales-tax quote from start-payment (display only). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    isStarting: flow.isStarting,
+    error: flow.error
+      ? ((flow.error as { response?: { data?: { message?: string } } })?.response?.data?.message ??
+        "Payment could not be started.")
+      : null,
+    pay: flow.start,
+  };
+}

package/src/ui/headless/podcast/usePodcastPlayer.ts

@@ -0,0 +1,96 @@
+"use client";
+import { useCallback, useMemo } from "react";
+import { useAudioPlayer } from "../../../contexts/AudioPlayerContext";
+import { episodeToTrack } from "../../../data/queries/usePodcast";
+import type { BlogPost, BlogCategory } from "../../../types/models";
+
+export interface UsePodcastPlayerOptions {
+  episodes: BlogPost[];
+  show?: BlogCategory | { title?: string; author?: string | null; coverImage?: { url: string } | null } | null;
+}
+
+export interface PodcastPlayerState {
+  /** The episode currently loaded in the shared player, if it belongs to this show. */
+  currentEpisode: BlogPost | null;
+  isPlaying: boolean;
+  isLoading: boolean;
+  currentTime: number;
+  duration: number;
+  /** Load an episode + the whole show as the queue, and play. next/previous then walk episodes. */
+  playEpisode: (episode: BlogPost) => void;
+  /** Play/pause toggle for a given episode (loads it if it isn't the current track). */
+  toggleEpisode: (episode: BlogPost) => void;
+  isCurrent: (episode: BlogPost) => boolean;
+  isEpisodePlaying: (episode: BlogPost) => boolean;
+  playNext: () => void;
+  playPrevious: () => void;
+  seek: (time: number) => void;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+/**
+ * A podcast player over the shared `AudioPlayerContext`. Loading an episode seeds
+ * the queue with the full show, so next/previous move between episodes and the
+ * page never has to navigate. Because the underlying player is a global provider,
+ * playback persists across route changes (episode ↔ show).
+ */
+export function usePodcastPlayer({ episodes, show }: UsePodcastPlayerOptions): PodcastPlayerState {
+  const a = useAudioPlayer();
+
+  const tracks = useMemo(
+    () => episodes.map((e) => episodeToTrack(e, show ?? null)).filter((t): t is NonNullable<typeof t> => !!t),
+    [episodes, show],
+  );
+
+  const currentEpisode = useMemo(
+    () => (a.currentTrack ? episodes.find((e) => e.id === a.currentTrack!.id) ?? null : null),
+    [a.currentTrack, episodes],
+  );
+
+  const playEpisode = useCallback(
+    (episode: BlogPost) => {
+      const track = episodeToTrack(episode, show ?? null);
+      if (!track) return;
+      a.loadAndPlay(track, tracks);
+    },
+    [a, tracks, show],
+  );
+
+  const isCurrent = useCallback((episode: BlogPost) => a.currentTrack?.id === episode.id, [a.currentTrack]);
+
+  const isEpisodePlaying = useCallback(
+    (episode: BlogPost) => a.currentTrack?.id === episode.id && a.isPlaying,
+    [a.currentTrack, a.isPlaying],
+  );
+
+  const toggleEpisode = useCallback(
+    (episode: BlogPost) => {
+      if (isCurrent(episode)) {
+        a.isPlaying ? a.pause() : a.play();
+      } else {
+        playEpisode(episode);
+      }
+    },
+    [a, isCurrent, playEpisode],
+  );
+
+  const currentIndex = currentEpisode ? episodes.findIndex((e) => e.id === currentEpisode.id) : -1;
+
+  return {
+    currentEpisode,
+    isPlaying: a.isPlaying,
+    isLoading: a.isLoading,
+    currentTime: a.currentTime,
+    duration: a.duration,
+    playEpisode,
+    toggleEpisode,
+    isCurrent,
+    isEpisodePlaying,
+    playNext: a.playNext,
+    playPrevious: a.playPrevious,
+    seek: a.seek,
+    hasNext: currentIndex >= 0 && currentIndex < episodes.length - 1,
+    hasPrevious: currentIndex > 0,
+  };
+}

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

@@ -0,0 +1,13 @@
+// Member posts pillar — headless primitives (port of the craft members area's
+// PostsContent/PostItem semantics; gating stays server-side).
+export { useMemberPostsFeed, type UseMemberPostsFeedOptions } from "./useMemberPostsFeed";
+export { usePostItem, type UsePostItemOptions, type PostBodyKind } from "./usePostItem";
+export { usePostCollectionsList, type UsePostCollectionsListOptions } from "./usePostCollectionsList";
+export { usePostCollectionDetail, type UsePostCollectionDetailOptions } from "./usePostCollectionDetail";
+export {
+  buildPostUpsell,
+  DEFAULT_CHECKOUT_PATH,
+  DEFAULT_SIGNUP_PATH,
+  type PostUpsell,
+  type UpsellPathOptions,
+} from "./upsell";

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

@@ -0,0 +1,41 @@
+import type { IPublicPost, MembershipTier } from "../../../types/models";
+
+/** Where a locked post/collection sends the member to unlock it. */
+export interface PostUpsell {
+  /** The first tier that unlocks the content (server orders `membershipTiers`). */
+  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=…`. */
+  checkoutHref: string;
+  /** Signup-first link for anonymous visitors (redirects into checkout after signup). */
+  signupHref: string;
+  /** The link to actually use: checkout when authenticated, signup otherwise. */
+  href: string;
+}
+
+export interface UpsellPathOptions {
+  /** Membership checkout path (default `/membership/checkout`; site-starter uses `/i/membership/checkout`). */
+  checkoutPath?: string;
+  /** Signup path (default `/signup`; site-starter uses `/i/signup`). */
+  signupPath?: string;
+}
+
+export const DEFAULT_CHECKOUT_PATH = "/membership/checkout";
+export const DEFAULT_SIGNUP_PATH = "/signup";
+
+/** 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 = {},
+): 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;
+  const signupHref = `${signupPath}?redirect=${encodeURIComponent(checkoutHref)}`;
+  return { tierId, tier, checkoutHref, signupHref, href: isAuthenticated ? checkoutHref : signupHref };
+}

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

@@ -0,0 +1,110 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { IPublicPost, MembershipTier, PostType } from "../../../types/models";
+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";
+
+export interface UseMemberPostsFeedOptions extends UpsellPathOptions {
+  /** Posts per page (default 10). */
+  pageSize?: number;
+  /** Debounce for the search input → query round trip (default 500ms, matching the craft members area). */
+  searchDebounceMs?: number;
+}
+
+/**
+ * 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,
+ * 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();
+
+  // ── Filters ────────────────────────────────────────────────────────────────
+  const [search, setSearchState] = useState("");
+  const [debouncedSearch, setDebouncedSearch] = useState("");
+  const [type, setType] = useState<PostType | "">("");
+  const [membershipTierId, setMembershipTierId] = useState("");
+  const [savedOnly, setSavedOnly] = useState(false);
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const setSearch = (value: string) => {
+    setSearchState(value);
+    if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    debounceTimer.current = setTimeout(() => setDebouncedSearch(value), opts.searchDebounceMs ?? 500);
+  };
+  useEffect(
+    () => () => {
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    },
+    [],
+  );
+
+  const clearFilters = () => {
+    if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    setSearchState("");
+    setDebouncedSearch("");
+    setType("");
+    setMembershipTierId("");
+    setSavedOnly(false);
+  };
+  const hasActiveFilters = !!(search || type || membershipTierId || savedOnly);
+
+  // ── Data ───────────────────────────────────────────────────────────────────
+  const { data: tiers } = useGetMembershipTiers();
+  const feed = useGetPostsInfinite({
+    query: debouncedSearch || undefined,
+    type: type || undefined,
+    membershipTierId: membershipTierId || undefined,
+    pageSize: opts.pageSize,
+  });
+  const saved = useGetSavedPosts(savedOnly && isAuthenticated);
+
+  const posts: IPublicPost[] = useMemo(
+    () => (savedOnly ? (saved.data?.data ?? []) : (feed.data?.pages.flatMap((p) => p.data) ?? [])),
+    [savedOnly, saved.data, feed.data],
+  );
+  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. */
+  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);
+
+  return {
+    posts,
+    total,
+    audioPosts,
+    isLoading: savedOnly ? saved.isLoading : feed.isLoading,
+    isError: savedOnly ? saved.isError : feed.isError,
+    // Paging (the saved view is a single page).
+    hasMore: savedOnly ? false : !!feed.hasNextPage,
+    isLoadingMore: !savedOnly && feed.isFetchingNextPage,
+    loadMore: () => {
+      if (!savedOnly && feed.hasNextPage && !feed.isFetchingNextPage) feed.fetchNextPage();
+    },
+    // Filters.
+    search,
+    setSearch,
+    type,
+    setType,
+    membershipTierId,
+    setMembershipTierId,
+    savedOnly,
+    setSavedOnly,
+    hasActiveFilters,
+    clearFilters,
+    /** Tiers for the tier-filter UI (and locked-card tier names). */
+    tiers: (tiers ?? []) as MembershipTier[],
+    isAuthenticated,
+    getUpsell,
+  };
+}

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

@@ -0,0 +1,56 @@
+import { useMemo } from "react";
+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";
+
+export type UsePostCollectionDetailOptions = UpsellPathOptions;
+
+/**
+ * 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
+ * the collection may still have locked posts inside it. Exposes the
+ * collection, its posts normalized for `usePostItem` (the collection payload
+ * carries no engagement counts), the accessible-audio play queue, and the
+ * locked-collection upsell. Bring your own UI.
+ */
+export function usePostCollectionDetail(collectionId: string | undefined, opts: UsePostCollectionDetailOptions = {}) {
+  const { isAuthenticated } = usePublicAuth();
+  const { data: tiers } = useGetMembershipTiers();
+  const detailQ = useGetPostCollection(collectionId);
+
+  const collection = detailQ.data ?? null;
+
+  /** Collection posts normalized to full `IPublicPost`s (counts default 0 like the craft port). */
+  const posts: IPublicPost[] = useMemo(
+    () => (collection?.posts ?? []).map((post) => ({ ...post, likes: post.likes ?? 0, comments: post.comments ?? 0 })),
+    [collection],
+  );
+
+  /** 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],
+  );
+
+  const hasAccess = collection?.hasAccess ?? false;
+  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;
+
+  return {
+    collection,
+    posts,
+    audioPosts,
+    cover,
+    hasAccess,
+    upsell,
+    isLoading: detailQ.isLoading,
+    isError: detailQ.isError,
+    isAuthenticated,
+  };
+}