@tribe-nest/forge 3.59.0 → 3.60.0

package/src/ui/headless/communities/useCommunity.ts

@@ -0,0 +1,140 @@
+import { useContext, useMemo } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { useOptionalCommunityContext, MissingCommunityProviderError } from "../../../contexts/CommunityContext";
+import {
+  isNotFound,
+  usePublicCommunities,
+  usePublicCommunity,
+  useCommunityViewerState,
+  type CommunityTokens,
+  type CommunityViewerState,
+  type PublicCommunity,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+import { cycleFloor, cycleIsFree, defaultCycle, offeredCycles, type BillingCycle } from "../../format/membershipPwyw";
+
+/**
+ * Every community on the profile, for a list page.
+ *
+ * `only` is the one community when there is exactly one, so a list page can go
+ * straight to it rather than asking the fan to choose between one option.
+ */
+export function useCommunities() {
+  const query = usePublicCommunities();
+  const communities = query.data ?? [];
+  return {
+    communities,
+    only: communities.length === 1 ? communities[0]! : null,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    refetch: query.refetch,
+  };
+}
+
+/** What the About page's single Join button offers, decided from the creator's tiers. */
+export type CommunityJoinOffer =
+  | { kind: "free"; tier: PublicTier }
+  | { kind: "paid"; tier: PublicTier; amount: number; cycle: BillingCycle }
+  | { kind: "apply"; tier: PublicTier }
+  | null;
+
+/**
+ * The Join button reflects the creator's tiers (decision 8): "Join free" when a
+ * free tier exists, otherwise "Join" with the lowest price, and "Apply" when
+ * every tier is apply-to-join. Pure, so a custom About page words it the same.
+ */
+export function communityJoinOffer(tiers: PublicTier[]): CommunityJoinOffer {
+  if (!tiers.length) return null;
+  const joinable = tiers.filter((tier) => tier.joinMode !== "application");
+  const free = joinable.find((tier) => cycleIsFree(tier, defaultCycle(tier)));
+  if (free) return { kind: "free", tier: free };
+  let cheapest: { tier: PublicTier; amount: number; cycle: BillingCycle } | null = null;
+  for (const tier of joinable) {
+    const cycles = offeredCycles(tier);
+    // A pay-what-you-want tier with no floor sells no cycle at a price, and is
+    // still a paid join from nothing.
+    const candidates = (["month", "year"] as const).filter((cycle) => cycles[cycle]);
+    for (const cycle of candidates.length ? candidates : (["month"] as const)) {
+      const amount = cycleFloor(tier, cycle);
+      // Compare on a monthly footing so a yearly price is not mistaken for the dearer one.
+      const monthly = cycle === "year" ? amount / 12 : amount;
+      const best = cheapest ? (cheapest.cycle === "year" ? cheapest.amount / 12 : cheapest.amount) : Infinity;
+      if (monthly < best) cheapest = { tier, amount, cycle };
+    }
+  }
+  if (cheapest) return { kind: "paid", ...cheapest };
+  return { kind: "apply", tier: tiers[0]! };
+}
+
+/** The viewer states that hold access to member content. `past_due` keeps it through the grace window. */
+export const COMMUNITY_ACCESS_STATES: ReadonlyArray<CommunityViewerState["state"]> = ["member", "past_due"];
+
+/** Does this viewer state grant access to the community's member content. */
+export function viewerHasAccess(viewer: Pick<CommunityViewerState, "state"> | null | undefined): boolean {
+  return !!viewer && COMMUNITY_ACCESS_STATES.includes(viewer.state);
+}
+
+const NO_TIERS: PublicTier[] = [];
+
+export interface UseCommunityOptions extends CommunityTokens {
+  enabled?: boolean;
+}
+
+/**
+ * One community: what it is, the tiers this viewer may join, and where the
+ * viewer stands IN IT (`none`, `pending`, `member`, `past_due`, `cancelled`, or
+ * `anonymous`), plus the upgrade and pending details a custom page needs.
+ *
+ * `slug` is a slug or an id. Omitted, the surrounding `<CommunityProvider>` is
+ * read, and outside one this throws rather than guess a community.
+ *
+ * The viewer comes from `/me` once signed in, so it follows a sign-in that
+ * happened on this page (the join sheet) without a reload.
+ */
+export function useCommunity(slug?: string, opts: UseCommunityOptions = {}) {
+  const context = useOptionalCommunityContext();
+  const ref = slug ?? context?.ref;
+  if (!ref) throw new MissingCommunityProviderError("useCommunity()");
+  const tokens: CommunityTokens = { invite: opts.invite ?? null, join: opts.join ?? null };
+  const signedIn = !!useContext(PublicAuthContext)?.user;
+
+  const detail = usePublicCommunity(ref, tokens, { enabled: opts.enabled });
+  const me = useCommunityViewerState(ref, { enabled: signedIn && opts.enabled !== false });
+
+  const community: PublicCommunity | undefined = detail.data?.community ?? context?.community;
+  const tiers: PublicTier[] = detail.data?.tiers ?? NO_TIERS;
+  const viewer: CommunityViewerState | undefined = (signedIn ? me.data : undefined) ?? detail.data?.viewer;
+
+  return useMemo(() => {
+    const membership = viewer?.membership ?? null;
+    const currentTier = membership ? (tiers.find((tier) => tier.id === membership.tierId) ?? null) : null;
+    return {
+      community,
+      communityId: community?.id,
+      slug: community?.slug,
+      tiers,
+      viewer,
+      /** The invite the URL carried, as the community read resolved it. */
+      invite: detail.data?.invite ?? null,
+      isLoading: detail.isLoading || (signedIn && me.isLoading),
+      /** True while the viewer is being re-read, e.g. straight after signing in. */
+      viewerLoading: signedIn && (me.isLoading || me.isFetching),
+      isError: detail.isError,
+      notFound: isNotFound(detail.error),
+      /** An active member (including `past_due`, which keeps access through the grace window). */
+      isMember: viewerHasAccess(viewer),
+      /** Applied and waiting for the creator's decision: inside, but no member content. */
+      isPending: viewer?.state === "pending",
+      /** When the pending application was made, for a waiting screen. */
+      pendingSince: viewer?.state === "pending" ? (viewer.application?.createdAt ?? null) : null,
+      membership,
+      currentTier,
+      upgradeTiers: viewer?.upgradeTiers ?? [],
+      hasUpgrade: (viewer?.upgradeTiers?.length ?? 0) > 0,
+      canInteract: viewer?.canInteract ?? false,
+      joinOffer: communityJoinOffer(tiers),
+      refetch: () => Promise.all([detail.refetch(), signedIn ? me.refetch() : Promise.resolve()]),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [community, tiers, viewer, detail.data?.invite, detail.isLoading, detail.isError, detail.error, me.isLoading, me.isFetching, signedIn]);
+}

package/src/ui/headless/communities/useCommunityAbout.ts

@@ -0,0 +1,71 @@
+import { useEffect, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { useCommunity } from "./useCommunity";
+import { communityHomePath } from "./paths";
+
+/** What the About page's main button does for THIS viewer. */
+export type CommunityAboutAction = "join" | "enter" | "pending";
+
+export interface UseCommunityAboutOptions {
+  /** A per-email invite token (`?invite=`). Opens the join sheet straight away. */
+  invite?: string | null;
+  /** A shareable invite link token (`?join=`). Opens the join sheet straight away. */
+  join?: string | null;
+  /** A tier to preselect (`?tier=`). */
+  tierId?: string | null;
+  /** The host's router, for "go inside". Default a full-page visit. */
+  navigate?: (href: string) => void;
+}
+
+/**
+ * The About page: the community, what each tier gives, and ONE main action.
+ *
+ * - `join` opens the join sheet in place (it never leaves the page).
+ * - `enter` for a member, who skips Join and goes straight inside.
+ * - `pending` for a fan whose application is being reviewed; they go inside to
+ *   the pending screen.
+ *
+ * The sheet opens by itself when the URL carries an invite or a shareable
+ * link, already set to the invited tier. A signed-in member arriving on an
+ * invite link is still shown the sheet: accepting it may be a tier change.
+ */
+export function useCommunityAbout(opts: UseCommunityAboutOptions = {}) {
+  if (!useOptionalCommunityContext()) throw new MissingCommunityProviderError("useCommunityAbout()");
+  const community = useCommunity();
+  const hasToken = !!(opts.invite || opts.join);
+  const [sheetOpen, setSheetOpen] = useState(hasToken);
+  const [sheetTierId, setSheetTierId] = useState<string | null>(opts.tierId ?? null);
+
+  // A token that arrives after the first render (client-side navigation) still opens the sheet.
+  useEffect(() => {
+    if (hasToken) setSheetOpen(true);
+  }, [hasToken]);
+
+  const action: CommunityAboutAction = community.isMember ? "enter" : community.isPending ? "pending" : "join";
+  const homePath = community.slug ? communityHomePath(community.slug) : "";
+
+  const goInside = () => {
+    if (!homePath) return;
+    if (opts.navigate) opts.navigate(homePath);
+    else if (typeof window !== "undefined") window.location.assign(homePath);
+  };
+
+  return {
+    ...community,
+    action,
+    homePath,
+    /** Run the main action: open the sheet, or go inside. */
+    primary: () => (action === "join" ? (setSheetTierId(opts.tierId ?? null), setSheetOpen(true)) : goInside()),
+    goInside,
+    sheetOpen,
+    /** The tier the sheet opens on: a tier card's own Join, or `?tier=`. */
+    sheetTierId,
+    openJoin: (tierId?: string | null) => {
+      setSheetTierId(tierId ?? opts.tierId ?? null);
+      setSheetOpen(true);
+    },
+    setSheetOpen,
+    invite: opts.invite ?? null,
+    join: opts.join ?? null,
+  };
+}

package/src/ui/headless/communities/useCommunityHome.ts

@@ -0,0 +1,88 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { useConfirmLatestSubscription } from "../../../data/queries/useSubscriptions";
+import { useInvalidateCommunities } from "../../../data/queries/useCommunities";
+import { useCommunity } from "./useCommunity";
+import { communityAboutPath } from "./paths";
+
+export interface UseCommunityHomeOptions {
+  /** `?welcome=1`: the fan just joined. */
+  welcome?: boolean;
+  /** `?confirmSubscription=1`: back from Stripe. The subscription is reconciled here, inside the community. */
+  confirmSubscription?: boolean;
+}
+
+/**
+ * The state of a community's home shell: the header (name, tier badge,
+ * Upgrade), the one upgrade sheet every locked item opens, the Membership
+ * menu, a welcome after joining, and reconciling a paid join or upgrade on the
+ * way back from Stripe, which used to happen on the account page.
+ */
+export function useCommunityHome(opts: UseCommunityHomeOptions = {}) {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityHome()");
+  const community = useCommunity();
+  const confirmLatest = useConfirmLatestSubscription();
+  const invalidate = useInvalidateCommunities();
+
+  const [welcomeVisible, setWelcomeVisible] = useState(!!opts.welcome);
+  const [upgradeOpen, setUpgradeOpen] = useState(false);
+  const [upgradeTierId, setUpgradeTierId] = useState<string | null>(null);
+  const [membershipOpen, setMembershipOpen] = useState(false);
+
+  // Reconcile once per arrival, as soon as the community id is known.
+  //
+  // `confirming` is this component's own state, NOT `confirmLatest.isPending`.
+  // A mutation started from an effect loses its observer when React StrictMode
+  // unmounts and remounts the component in development, so `isPending` stayed
+  // true for ever and the home was stuck on "Confirming" although the request
+  // had answered. The promise itself always settles, so state set from it does.
+  const confirmed = useRef(false);
+  const [confirming, setConfirming] = useState(false);
+  const communityId = community.communityId ?? context.communityId;
+  useEffect(() => {
+    if (!opts.confirmSubscription || confirmed.current || !communityId) return;
+    confirmed.current = true;
+    setConfirming(true);
+    confirmLatest
+      .mutateAsync({ communityId })
+      .catch(() => undefined)
+      .finally(() => {
+        setConfirming(false);
+        void invalidate();
+      });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [opts.confirmSubscription, communityId]);
+
+  const opener = useMemo(
+    () => ({
+      openUpgrade: (tierId?: string | null) => {
+        setUpgradeTierId(tierId ?? null);
+        setUpgradeOpen(true);
+      },
+    }),
+    [],
+  );
+
+  return {
+    ...community,
+    /** Show the one-time welcome after a join. */
+    welcomeVisible: welcomeVisible && community.isMember,
+    dismissWelcome: () => setWelcomeVisible(false),
+    /** True while a Stripe return is being reconciled. */
+    confirming,
+    /** The header's Upgrade button shows only when a higher tier exists. */
+    showUpgrade: community.isMember && community.hasUpgrade,
+    /** The header's Join link, for a visitor who is not a member. */
+    showJoin: !community.isLoading && !community.isMember && !community.isPending,
+    joinPath: community.slug ? communityAboutPath(community.slug) : "",
+    upgradeOpen,
+    upgradeTierId,
+    /** Hand to `CommunityUpgradeOpenerProvider` so every locked item opens the same sheet. */
+    opener,
+    openUpgrade: opener.openUpgrade,
+    setUpgradeOpen,
+    membershipOpen,
+    setMembershipOpen,
+  };
+}

package/src/ui/headless/communities/useCommunityInvite.ts

@@ -0,0 +1,116 @@
+import { useContext, useMemo } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  useCommunityInviteState,
+  type CommunityInviteKind,
+  type CommunityInviteState,
+  type CommunityInviteStateName,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+
+/** Why an invite cannot be used. The About page says so and falls back to the normal Join. */
+export type CommunityInviteProblem = "expired" | "revoked" | "used" | "used_up" | "not_found";
+
+export interface CommunityInviteSummary {
+  /** `email` for a per-email invite (`?invite=`), `link` for a shareable one (`?join=`). Null with no token. */
+  kind: CommunityInviteKind | null;
+  /** The server's answer, adjusted for who is signed in right now. Null with no token or while loading. */
+  state: CommunityInviteStateName | null;
+  /** The invite can be accepted by this viewer as they are. */
+  isValid: boolean;
+  /** A per-email invite for a different address than the signed-in one. */
+  emailMismatch: boolean;
+  /** Set when the token is dead, and why. */
+  problem: CommunityInviteProblem | null;
+  /** The address a per-email invite was sent to: prefilled and locked in the join sheet. */
+  invitedEmail: string | null;
+  /** The tier the invite opens. Null for a dead token. */
+  tier: PublicTier | null;
+  /**
+   * The tokens to forward with the join. Only a usable token is forwarded: a
+   * dead one would turn the fallback Join into a refusal.
+   */
+  forward: { inviteToken?: string; joinToken?: string };
+}
+
+const DEAD: ReadonlyArray<CommunityInviteStateName> = ["expired", "revoked", "used", "used_up", "not_found"];
+
+/**
+ * What an invite is worth to this viewer. Pure, so the same rules drive the
+ * hosted sheet and a custom one.
+ *
+ * The server decides validity; this only adds what the server cannot know at
+ * read time: a fan who signed in on this page with a different address than
+ * the invite's is a mismatch now, even if the page loaded anonymous. A shareable
+ * link has no email lock, so it never mismatches.
+ */
+export function describeCommunityInvite(input: {
+  tokens: { invite?: string | null; join?: string | null };
+  answer: CommunityInviteState | null | undefined;
+  signedInEmail?: string | null;
+}): CommunityInviteSummary {
+  const { tokens, answer } = input;
+  const kind: CommunityInviteKind | null = tokens.invite ? "email" : tokens.join ? "link" : null;
+  if (!kind || !answer) {
+    return { kind, state: null, isValid: false, emailMismatch: false, problem: null, invitedEmail: null, tier: null, forward: {} };
+  }
+  let state = answer.state;
+  const invitedEmail = answer.invitedEmail;
+  if (
+    state === "valid" &&
+    answer.kind === "email" &&
+    invitedEmail &&
+    input.signedInEmail &&
+    input.signedInEmail.trim().toLowerCase() !== invitedEmail.trim().toLowerCase()
+  ) {
+    state = "email_mismatch";
+  }
+  const problem = DEAD.includes(state) ? (state as CommunityInviteProblem) : null;
+  // A mismatched invite is still forwarded: signing in as the invited address
+  // is the way through, and that sign-in happens in the same sheet.
+  const usable = state === "valid" || state === "email_mismatch";
+  return {
+    kind: answer.kind ?? kind,
+    state,
+    isValid: state === "valid",
+    emailMismatch: state === "email_mismatch",
+    problem,
+    invitedEmail: answer.kind === "email" ? invitedEmail : null,
+    tier: usable ? answer.tier : null,
+    forward: usable
+      ? kind === "email"
+        ? { inviteToken: tokens.invite! }
+        : { joinToken: tokens.join! }
+      : {},
+  };
+}
+
+/**
+ * The invite state for the surrounding community (`valid`, `expired`,
+ * `revoked`, `used`, `used_up`, `email_mismatch`, `not_found`), the invited
+ * email and the tier it opens. Pass `slug` to read a community other than the
+ * provider's.
+ */
+export function useCommunityInvite(opts: { invite?: string | null; join?: string | null; slug?: string } = {}) {
+  const context = useOptionalCommunityContext();
+  const ref = opts.slug ?? context?.ref;
+  if (!ref) throw new MissingCommunityProviderError("useCommunityInvite()");
+  const tokens = { invite: opts.invite ?? null, join: opts.invite ? null : (opts.join ?? null) };
+  const signedInEmail = useContext(PublicAuthContext)?.user?.email ?? null;
+  const query = useCommunityInviteState(ref, tokens);
+  const summary = useMemo(
+    () => describeCommunityInvite({ tokens, answer: query.data ?? (query.error ? NOT_FOUND(tokens) : undefined), signedInEmail }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tokens.invite, tokens.join, query.data, query.error, signedInEmail],
+  );
+  return { ...summary, isLoading: !!(tokens.invite || tokens.join) && query.isLoading };
+}
+
+/** A token the server could not resolve at all (a 404 or a failed read) reads as not found, never as valid. */
+const NOT_FOUND = (tokens: { invite?: string | null; join?: string | null }): CommunityInviteState => ({
+  kind: tokens.invite ? "email" : "link",
+  state: "not_found",
+  invitedEmail: null,
+  tier: null,
+});