@tribe-nest/forge 1.13.0

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

@@ -0,0 +1,90 @@
+import { useEffect, useRef, useState } from "react";
+import type { IPublicPostCollection, MembershipTier } from "../../../types/models";
+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";
+
+export interface UsePostCollectionsListOptions extends UpsellPathOptions {
+  /** Debounce for the search input → query round trip (default 500ms, matching the craft members area). */
+  searchDebounceMs?: number;
+}
+
+/**
+ * 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
+ * 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();
+
+  // ── Search + paging ────────────────────────────────────────────────────────
+  const [search, setSearchState] = useState("");
+  const [debouncedSearch, setDebouncedSearch] = useState("");
+  const [page, setPage] = useState(1);
+  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);
+      setPage(1);
+    }, opts.searchDebounceMs ?? 500);
+  };
+  useEffect(
+    () => () => {
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    },
+    [],
+  );
+
+  const clearFilters = () => {
+    if (debounceTimer.current) clearTimeout(debounceTimer.current);
+    setSearchState("");
+    setDebouncedSearch("");
+    setPage(1);
+  };
+  const hasActiveFilters = !!search;
+
+  // ── Data ───────────────────────────────────────────────────────────────────
+  const { data: tiers } = useGetMembershipTiers();
+  const listQ = useGetPostCollections({ query: debouncedSearch || undefined, page });
+
+  const collections: IPublicPostCollection[] = listQ.data?.data ?? [];
+  const total = listQ.data?.total ?? 0;
+  const pageSize = listQ.data?.pageSize ?? 10;
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+
+  /** Locked-collection upsell: which tier unlocks it + the checkout/signup deep link. */
+  const getUpsell = (collection: IPublicPostCollection): PostUpsell =>
+    buildPostUpsell(collection, tiers, isAuthenticated, opts);
+
+  return {
+    collections,
+    total,
+    isLoading: listQ.isLoading,
+    isError: listQ.isError,
+    // Paging (numbered, server-side — matches the craft pagination).
+    page,
+    pageSize,
+    totalPages,
+    hasPrevPage: page > 1,
+    hasNextPage: page < totalPages,
+    setPage,
+    nextPage: () => setPage((p) => Math.min(p + 1, totalPages)),
+    prevPage: () => setPage((p) => Math.max(p - 1, 1)),
+    // Search.
+    search,
+    setSearch,
+    hasActiveFilters,
+    clearFilters,
+    /** Tiers for locked-card tier names. */
+    tiers: (tiers ?? []) as MembershipTier[],
+    isAuthenticated,
+    getUpsell,
+  };
+}

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

@@ -0,0 +1,81 @@
+import { useMemo } from "react";
+import type { IMedia, IPublicPost } from "../../../types/models";
+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";
+
+export interface UsePostItemOptions extends UpsellPathOptions {
+  /** 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;
+  /** Called when a logged-out visitor tries to like/save/comment. */
+  onRequireAuth?: () => void;
+}
+
+/** How the card body should render. */
+export type PostBodyKind = "locked" | "poll" | "media" | "text";
+
+const trackTitle = (caption: string) => (caption.length > 20 ? caption.substring(0, 20) + "…" : caption);
+
+const toTrack = (post: IPublicPost, media: IMedia, artistName?: string): AudioTrack => ({
+  id: media.id,
+  url: media.url,
+  title: trackTitle(post.caption ?? ""),
+  artist: artistName ?? "",
+});
+
+/**
+ * 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
+ * gated the post: `hasAccess === false` means no media was shipped.
+ */
+export function usePostItem(post: IPublicPost, opts: UsePostItemOptions = {}) {
+  const { isAuthenticated } = usePublicAuth();
+  const { data: tiers } = useGetMembershipTiers();
+
+  const engagement = usePostEngagement(post.id, "post", {
+    onRequireAuth: opts.onRequireAuth,
+    initialLikeCount: post.likes ?? 0,
+    initialCommentCount: post.comments ?? 0,
+  });
+
+  const isLocked = !post.hasAccess;
+  const media = !isLocked ? (post.media?.[0] ?? null) : null;
+
+  const kind: PostBodyKind = post.type === "poll" ? "poll" : isLocked ? "locked" : media ? "media" : "text";
+
+  /** The playable track when this is an accessible audio post. */
+  const audioTrack = useMemo(
+    () => (post.type === "audio" && media?.url ? toTrack(post, media, opts.artistName) : null),
+    [post, media, opts.artistName],
+  );
+
+  /** Queue built from the surrounding accessible audio posts (feed order). */
+  const audioQueue = useMemo(
+    () =>
+      (opts.otherAudioPosts ?? [])
+        .filter((p) => p.hasAccess && p.media?.[0]?.url)
+        .map((p) => toTrack(p, p.media![0]!, opts.artistName)),
+    [opts.otherAudioPosts, opts.artistName],
+  );
+
+  const upsell: PostUpsell = buildPostUpsell(post, tiers, isAuthenticated, opts);
+
+  return {
+    post,
+    kind,
+    isLocked,
+    /** First media item (null when locked — the server ships none). */
+    media,
+    audioTrack,
+    audioQueue,
+    upsell,
+    engagement,
+    isAuthenticated,
+  };
+}

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

@@ -0,0 +1,6 @@
+// Reviews headless primitives (Tier 1). NOTE: this is a lane-local aggregator —
+// the integrator re-exports it from `ui/headless/index.ts`
+// (`export * from "./reviews"`).
+export { useReviewsList, REVIEW_SORT_OPTIONS, type UseReviewsListOptions } from "./useReviewsList";
+export { useHelpfulVote } from "./useHelpfulVote";
+export { useReviewForm, type ReviewFormStatus } from "./useReviewForm";

package/src/ui/headless/reviews/useHelpfulVote.ts

@@ -0,0 +1,45 @@
+import { useContext, useEffect, useState } from "react";
+import type { IPublicReview } from "../../../types/models";
+import { useAddHelpfulVote, useRemoveHelpfulVote } from "../../../data/queries/useReviews";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+
+/**
+ * Headless helpful-vote toggle for one review. Voting requires a logged-in
+ * member (`canVote`); the voted state is session-local (the backend exposes no
+ * per-viewer vote flag on the list) — first toggle adds the vote, second
+ * removes it, and failures (e.g. expired session, duplicate vote) are
+ * swallowed non-fatally. The count re-syncs whenever the list refetches.
+ */
+export function useHelpfulVote(review: Pick<IPublicReview, "id" | "helpfulCount">) {
+  const auth = useContext(PublicAuthContext);
+  const canVote = !!auth?.isAuthenticated;
+
+  const addVote = useAddHelpfulVote();
+  const removeVote = useRemoveHelpfulVote();
+  const [voted, setVoted] = useState(false);
+  const [helpfulCount, setHelpfulCount] = useState(review.helpfulCount);
+
+  // Keep the local count in sync when the list refetches.
+  useEffect(() => setHelpfulCount(review.helpfulCount), [review.helpfulCount]);
+
+  const isPending = addVote.isPending || removeVote.isPending;
+
+  const toggle = async () => {
+    if (!canVote || isPending) return;
+    try {
+      if (voted) {
+        const res = await removeVote.mutateAsync({ reviewId: review.id });
+        setHelpfulCount(res.helpfulCount);
+        setVoted(false);
+      } else {
+        const res = await addVote.mutateAsync({ reviewId: review.id });
+        setHelpfulCount(res.helpfulCount);
+        setVoted(true);
+      }
+    } catch {
+      // Vote failures are non-fatal (e.g. session expired) — leave state as-is.
+    }
+  };
+
+  return { voted, helpfulCount, toggle, canVote, isPending };
+}

package/src/ui/headless/reviews/useReviewForm.ts

@@ -0,0 +1,108 @@
+import { useEffect, useState } from "react";
+import type { ISubmittedReview } from "../../../types/models";
+import { useReviewRequest, useSubmitReview } from "../../../data/queries/useReviews";
+
+/** Which screen the token-gated review form should render. */
+export type ReviewFormStatus =
+  | "loading" // request context still loading
+  | "invalid" // bad/unknown token
+  | "expired" // token valid but past its window
+  | "locked" // already reviewed and the 30-day edit window has passed
+  | "submitted" // this session just submitted — show the thank-you state
+  | "form"; // show the (possibly prefilled) form
+
+/**
+ * Headless review-submission form behind an emailed token link
+ * (`/reviews/:token` — the token proves the verified purchase, no login).
+ * Owns the whole state machine: invalid/expired links, already-reviewed
+ * locked, edit-within-30-days prefill, submit, and the spam-guard
+ * "held for moderation" outcome. The behavior core of `<ReviewForm/>`.
+ */
+export function useReviewForm(token?: string) {
+  const { data: request, isLoading, isError } = useReviewRequest(token);
+  const submitMutation = useSubmitReview();
+
+  const [rating, setRating] = useState(0);
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [reviewerName, setReviewerName] = useState("");
+  const [submitted, setSubmitted] = useState<ISubmittedReview | null>(null);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  // Prefill from the existing review (edit-within-window) or defaults.
+  useEffect(() => {
+    if (!request) return;
+    const existing = request.existingReview;
+    if (existing) {
+      setRating(existing.rating);
+      setTitle(existing.title ?? "");
+      setBody(existing.body ?? "");
+      setReviewerName(existing.reviewerName ?? request.defaultReviewerName ?? "");
+    } else {
+      setReviewerName((prev) => prev || request.defaultReviewerName || "");
+    }
+  }, [request]);
+
+  const existingReview = request?.existingReview ?? null;
+
+  const status: ReviewFormStatus = isLoading
+    ? "loading"
+    : isError || !request
+      ? "invalid"
+      : !request.valid || request.status === "expired"
+        ? "expired"
+        : submitted
+          ? "submitted"
+          : existingReview && !existingReview.canEdit
+            ? "locked"
+            : "form";
+
+  const canSubmit = rating >= 1 && !submitMutation.isPending;
+
+  const submit = async () => {
+    if (!canSubmit || !token) return;
+    setErrorMessage(null);
+    try {
+      const review = await submitMutation.mutateAsync({
+        token,
+        rating,
+        title: title.trim() || null,
+        body: body.trim() || null,
+        reviewerName: reviewerName.trim() || null,
+      });
+      setSubmitted(review);
+    } catch (error: unknown) {
+      const message =
+        (error as { response?: { data?: { message?: string } } })?.response?.data?.message ||
+        "Something went wrong submitting your review. Please try again.";
+      setErrorMessage(message);
+    }
+  };
+
+  return {
+    status,
+    /** The full request context (entity title, profile, existing review). */
+    request: request ?? null,
+    entityTitle: request?.entityTitle ?? null,
+    /** Prior review when the link was already used (prefills the form; read-only when locked). */
+    existingReview,
+    // Fields
+    rating,
+    setRating,
+    title,
+    setTitle,
+    body,
+    setBody,
+    reviewerName,
+    setReviewerName,
+    // Submission
+    canSubmit,
+    isSubmitting: submitMutation.isPending,
+    submit,
+    errorMessage,
+    /** The review returned by the submit, when status === "submitted". */
+    submitted,
+    /** True when the spam guard held the submitted review for moderation. */
+    isHeld: !!submitted && (submitted.heldReason === "held_for_review" || submitted.status === "pending"),
+  };
+}

package/src/ui/headless/reviews/useReviewsList.ts

@@ -0,0 +1,79 @@
+import { useEffect, useMemo, useState } from "react";
+import type { IPublicReview, IReviewAggregate, ReviewEntityType, ReviewSortOption } from "../../../types/models";
+import { usePublicReviews } from "../../../data/queries/useReviews";
+
+/** The sort options the public reviews endpoint supports, with display labels. */
+export const REVIEW_SORT_OPTIONS: { value: ReviewSortOption; label: string }[] = [
+  { value: "recent", label: "Most recent" },
+  { value: "rating", label: "Highest rating" },
+  { value: "helpful", label: "Most helpful" },
+];
+
+export interface UseReviewsListOptions {
+  /** Which kind of entity these reviews belong to. */
+  entityType: ReviewEntityType;
+  /** The entity's id (product/course/coaching product UUID). */
+  entityId?: string;
+  /** Reviews per page. Default 10. */
+  pageSize?: number;
+  /** Aggregate attached to the detail response — used for instant paint (SSR). */
+  initialAggregate?: IReviewAggregate | null;
+}
+
+/**
+ * Headless reviews list for an entity's detail page: sortable, "load more"
+ * accumulated pages, and the rating aggregate (average + count + star
+ * distribution). Changing sort resets to page 1. `isEmpty` is true until the
+ * entity has at least one published review — render nothing in that case to
+ * keep the page clean. The behavior core of `<ReviewsSection/>`.
+ */
+export function useReviewsList({ entityType, entityId, pageSize = 10, initialAggregate }: UseReviewsListOptions) {
+  const [sort, setSortState] = useState<ReviewSortOption>("recent");
+  const [page, setPage] = useState(1);
+  const [reviews, setReviews] = useState<IPublicReview[]>([]);
+
+  const { data, isFetching } = usePublicReviews(
+    { entityType, entityId: entityId ?? "", page, sort, limit: pageSize },
+    !!entityId,
+  );
+
+  // Accumulate pages ("load more"); page 1 replaces (fresh sort or refetch).
+  useEffect(() => {
+    if (!data) return;
+    setReviews((prev) =>
+      data.page === 1 ? data.data : [...prev, ...data.data.filter((r) => !prev.some((p) => p.id === r.id))],
+    );
+  }, [data]);
+
+  const setSort = (next: ReviewSortOption) => {
+    if (next === sort) return;
+    setSortState(next);
+    setPage(1);
+  };
+
+  const aggregate = data?.aggregate ?? initialAggregate ?? null;
+  const total = data?.total ?? aggregate?.reviewCount ?? 0;
+  const isEmpty = !aggregate || aggregate.reviewCount === 0;
+
+  /** Largest star-bucket count — the denominator for distribution bar widths. */
+  const distributionMax = useMemo(
+    () => (aggregate ? Math.max(1, ...Object.values(aggregate.distribution)) : 1),
+    [aggregate],
+  );
+
+  return {
+    reviews,
+    aggregate,
+    total,
+    isEmpty,
+    distributionMax,
+    // Sorting
+    sort,
+    setSort,
+    sortOptions: REVIEW_SORT_OPTIONS,
+    // Paging
+    hasMore: reviews.length < total,
+    loadMore: () => setPage((p) => p + 1),
+    isFetching,
+  };
+}

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

@@ -0,0 +1,25 @@
+// Work (project management) client-portal headless primitives.
+export {
+  useWorkPortalProjects,
+  useWorkProjectReport,
+  useWorkTokenReport,
+  useWorkTaskComments,
+  useWorkTaskAttachments,
+  useWorkInvite,
+  useAcceptWorkInvite,
+  useWorkProjectInvoices,
+  formatWorkMoney,
+  formatWorkDate,
+  type WorkProjectSummary,
+  type WorkMilestone,
+  type WorkTask,
+  type WorkTimeReportRow,
+  type WorkTimeReport,
+  type WorkProjectReportData,
+  type WorkTaskComment,
+  type WorkTaskAttachment,
+  type WorkInviteContext,
+  type WorkInviteAcceptResult,
+  type WorkProjectInvoice,
+  type UseWorkTaskCommentsResult,
+} from "./useWorkPortal";