@tribe-nest/forge 3.58.0 → 3.60.0

package/src/data/queries/useCommunities.ts

@@ -0,0 +1,343 @@
+import { useContext } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../contexts/PublicAuthContext";
+import type { MembershipTier } from "../../types/models";
+
+/**
+ * The public communities API (`/public/communities/*` and the fan's own
+ * memberships). Every creator can run several communities, each with its own
+ * tiers, members, feed, chat and calls, so a community is always NAMED by the
+ * caller: by slug in a URL, by id everywhere else.
+ *
+ * These are the raw data hooks. The step machines and state a page is built
+ * from live in `ui/headless/communities`, and the member-content hooks
+ * (spaces, feed, chat, calls, collections) read the community from
+ * `<CommunityProvider>` rather than taking it as an argument.
+ */
+
+// ---- Types (mirror docs/proposals/communities-build-contract.md section 3.2) ----
+
+/** A community as a visitor sees it. */
+export interface PublicCommunity {
+  id: string;
+  name: string;
+  slug: string;
+  description: string | null;
+  coverUrl: string | null;
+  logoUrl: string | null;
+  category: string | null;
+  tags: string[];
+  memberCount: number;
+}
+
+/** A tier the viewer may join: the public tier shape plus the community it belongs to. */
+export type PublicTier = MembershipTier & { communityId: string };
+
+/**
+ * Where the viewer stands in ONE community. Never read across communities: a
+ * member of community A is `none` in community B.
+ */
+export type CommunityViewerStateName = "anonymous" | "none" | "pending" | "member" | "past_due" | "cancelled";
+
+export interface CommunityViewerMembership {
+  id: string;
+  tierId: string;
+  tierName: string;
+  status: string;
+  cancelAtPeriodEnd: boolean;
+  currentPeriodEnd: string | null;
+  /** A downgrade waiting for the end of the paid period, or null. */
+  pendingDowngradeTierId: string | null;
+}
+
+export interface CommunityViewerApplication {
+  id: string;
+  tierId: string;
+  status: string;
+  createdAt: string;
+}
+
+export interface CommunityUpgradeTier {
+  id: string;
+  name: string;
+  priceMonthly: number | null;
+  priceYearly: number | null;
+}
+
+export interface CommunityViewerState {
+  state: CommunityViewerStateName;
+  membership: CommunityViewerMembership | null;
+  application: CommunityViewerApplication | null;
+  /** Tiers above the current one, in this community. Empty for a non-member. */
+  upgradeTiers: CommunityUpgradeTier[];
+  canInteract: boolean;
+}
+
+export type CommunityInviteKind = "email" | "link";
+export type CommunityInviteStateName =
+  | "valid"
+  | "expired"
+  | "revoked"
+  | "used"
+  | "used_up"
+  | "email_mismatch"
+  | "not_found";
+
+export interface CommunityInviteState {
+  kind: CommunityInviteKind;
+  state: CommunityInviteStateName;
+  /** The address a per-email invite was sent to. Null for a shareable link. */
+  invitedEmail: string | null;
+  /** The tier the invite opens, or null when the token is dead. */
+  tier: PublicTier | null;
+}
+
+/** `GET /public/communities/:slug` */
+export interface CommunityDetail {
+  community: PublicCommunity;
+  tiers: PublicTier[];
+  viewer: CommunityViewerState;
+  invite: CommunityInviteState | null;
+}
+
+/** The two invite credentials a URL can carry. Only one is ever set. */
+export interface CommunityTokens {
+  /** A per-email invite token (`?invite=`). */
+  invite?: string | null;
+  /** A shareable invite link token (`?join=`). */
+  join?: string | null;
+}
+
+export interface CommunityUpgradePreview {
+  amount: number;
+  currency: string;
+  interval: string;
+  /** True on Paystack: the upgrade collects the card again and replaces the subscription. */
+  requiresCard: boolean;
+  prorated: boolean;
+}
+
+export interface CommunityUpgradeResult {
+  status: "changed" | "requires_payment";
+  /** STRIPE: a PaymentIntent secret when the provider needs the card confirmed. */
+  clientSecret?: string;
+  /** PAYSTACK: the new subscription's inline checkout session. */
+  accessCode?: string;
+  /** PAYSTACK: hosted page fallback. */
+  checkoutUrl?: string;
+  membership: CommunityViewerMembership | null;
+}
+
+/** One entry of `GET /public/memberships/mine`: a membership in one community. */
+export interface MyCommunityMembership {
+  id: string;
+  tierId?: string;
+  membershipTierId?: string;
+  tierName?: string;
+  status: string;
+  cancelAtPeriodEnd?: boolean;
+  currentPeriodEnd?: string | null;
+  endDate?: string | null;
+  pendingDowngradeTierId?: string | null;
+  subscriptionAmount?: number | null;
+  subscriptionCurrency?: string | null;
+  billingCycle?: string | null;
+  trialEndsAt?: string | null;
+  membershipTier?: { id: string; name: string } | null;
+  community: { id: string; name: string; slug: string };
+}
+
+/**
+ * The signed-in account, read softly: these hooks also run on a page with no
+ * auth provider (a static About page), where the viewer is simply anonymous.
+ */
+export function useViewerAccountId(): string | null {
+  return useContext(PublicAuthContext)?.user?.id ?? null;
+}
+
+// ---- Keys ---------------------------------------------------------------------
+
+export const communitiesKeys = {
+  all: ["public-communities"] as const,
+  list: (profileId?: string) => ["public-communities", "list", profileId] as const,
+  detail: (profileId: string | undefined, ref: string | undefined, tokens: CommunityTokens, accountId?: string | null) =>
+    ["public-communities", "detail", profileId, ref, tokens.invite ?? null, tokens.join ?? null, accountId ?? null] as const,
+  me: (profileId: string | undefined, ref: string | undefined, accountId?: string | null) =>
+    ["public-communities", "me", profileId, ref, accountId ?? null] as const,
+  invite: (profileId: string | undefined, ref: string | undefined, tokens: CommunityTokens, accountId?: string | null) =>
+    ["public-communities", "invite", profileId, ref, tokens.invite ?? null, tokens.join ?? null, accountId ?? null] as const,
+  upgradePreview: (profileId: string | undefined, ref: string | undefined, tierId: string | undefined) =>
+    ["public-communities", "upgrade-preview", profileId, ref, tierId ?? null] as const,
+  mine: (profileId?: string, accountId?: string | null) => ["public-communities", "mine", profileId, accountId ?? null] as const,
+};
+
+const tokenParams = (tokens: CommunityTokens) => ({
+  ...(tokens.invite ? { invite: tokens.invite } : {}),
+  ...(tokens.join ? { join: tokens.join } : {}),
+});
+
+const enc = (ref: string) => encodeURIComponent(ref);
+
+// ---- Reads ----------------------------------------------------------------------
+
+/** Every live community on the profile (`GET /public/communities`). */
+export function usePublicCommunities(opts: { enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+  return useQuery<PublicCommunity[]>({
+    queryKey: communitiesKeys.list(profileId),
+    queryFn: async () => (await client.get("/public/communities", { params: { profileId } })).data,
+    enabled: !!profileId && !!client && opts.enabled !== false,
+  });
+}
+
+/**
+ * One community with its joinable tiers, the viewer's state and, when the URL
+ * carried a token, the invite (`GET /public/communities/:slug`). `ref` is a
+ * slug or an id. The token is part of the key because it changes which tiers
+ * come back: an invite-only tier is listed only with a token that opens it.
+ */
+export function usePublicCommunity(ref: string | undefined, tokens: CommunityTokens = {}, opts: { enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+  const accountId = useViewerAccountId();
+  return useQuery<CommunityDetail>({
+    queryKey: communitiesKeys.detail(profileId, ref, tokens, accountId),
+    queryFn: async () =>
+      (await client.get(`/public/communities/${enc(ref!)}`, { params: { profileId, ...tokenParams(tokens) } })).data,
+    enabled: !!ref && !!profileId && !!client && opts.enabled !== false,
+    retry: (count, error) => !isNotFound(error) && count < 2,
+  });
+}
+
+/** The viewer's state in one community (`GET /public/communities/:slug/me`). Keyed per account. */
+export function useCommunityViewerState(ref: string | undefined, opts: { enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+  const accountId = useViewerAccountId();
+  return useQuery<CommunityViewerState>({
+    queryKey: communitiesKeys.me(profileId, ref, accountId),
+    queryFn: async () => (await client.get(`/public/communities/${enc(ref!)}/me`, { params: { profileId } })).data,
+    enabled: !!ref && !!profileId && !!client && opts.enabled !== false,
+  });
+}
+
+/**
+ * What an invite token is worth (`GET /public/communities/:slug/invite`).
+ * Keyed per account because `email_mismatch` depends on who is signed in.
+ */
+export function useCommunityInviteState(ref: string | undefined, tokens: CommunityTokens) {
+  const { client, profileId } = useForge();
+  const accountId = useViewerAccountId();
+  const hasToken = !!(tokens.invite || tokens.join);
+  return useQuery<CommunityInviteState>({
+    queryKey: communitiesKeys.invite(profileId, ref, tokens, accountId),
+    queryFn: async () =>
+      (await client.get(`/public/communities/${enc(ref!)}/invite`, { params: { profileId, ...tokenParams(tokens) } })).data,
+    enabled: !!ref && hasToken && !!profileId && !!client,
+    retry: (count, error) => !isNotFound(error) && count < 2,
+  });
+}
+
+/** What moving to `membershipTierId` costs now (`GET /public/communities/:slug/upgrade-preview`). */
+export function useCommunityUpgradePreview(ref: string | undefined, membershipTierId: string | undefined) {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityUpgradePreview>({
+    queryKey: communitiesKeys.upgradePreview(profileId, ref, membershipTierId),
+    queryFn: async () =>
+      (
+        await client.get(`/public/communities/${enc(ref!)}/upgrade-preview`, {
+          params: { profileId, membershipTierId },
+        })
+      ).data,
+    enabled: !!ref && !!membershipTierId && !!profileId && !!client,
+  });
+}
+
+/** Every membership the signed-in fan holds with this creator, one per community. */
+export function useMyCommunityMemberships(opts: { enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+  const accountId = useViewerAccountId();
+  return useQuery<MyCommunityMembership[]>({
+    queryKey: communitiesKeys.mine(profileId, accountId),
+    // The server answers `[{ community, membership }]`; the hooks read one flat
+    // row per community, so the envelope is unwrapped here, in one place.
+    queryFn: async () => {
+      const rows = (await client.get("/public/memberships/mine", { params: { profileId } })).data as Array<{
+        community: MyCommunityMembership["community"];
+        membership: Record<string, unknown> & { amount?: number | null; currency?: string | null };
+      }>;
+      return rows.map(
+        ({ community, membership }) =>
+          ({
+            ...membership,
+            community,
+            subscriptionAmount: membership.amount ?? null,
+            subscriptionCurrency: membership.currency ?? null,
+          }) as unknown as MyCommunityMembership,
+      );
+    },
+    enabled: !!accountId && !!profileId && !!client && opts.enabled !== false,
+  });
+}
+
+// ---- Writes -----------------------------------------------------------------------
+
+/** Every community read goes stale together after a membership change. */
+export function useInvalidateCommunities() {
+  const queryClient = useQueryClient();
+  return () =>
+    Promise.all([
+      queryClient.invalidateQueries({ queryKey: communitiesKeys.all }),
+      queryClient.invalidateQueries({ queryKey: ["membership-tiers"] }),
+      queryClient.invalidateQueries({ queryKey: ["my-membership-applications"] }),
+    ]);
+}
+
+/** Move to a higher tier (`POST /public/communities/:slug/upgrade`). */
+export function useUpgradeCommunityTier(ref: string | undefined) {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateCommunities();
+  return useMutation<CommunityUpgradeResult, unknown, { membershipTierId: string; returnUrl?: string }>({
+    mutationFn: async (body) =>
+      (await client.post(`/public/communities/${enc(ref!)}/upgrade`, { profileId, ...body })).data,
+    onSuccess: (data) => {
+      if (data.status === "changed") void invalidate();
+    },
+  });
+}
+
+/** Cancel (`POST /public/communities/:slug/membership/cancel`). A paid period runs out first. */
+export function useCancelCommunityMembership(ref: string | undefined) {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateCommunities();
+  return useMutation<unknown, unknown, void>({
+    mutationFn: async () => (await client.post(`/public/communities/${enc(ref!)}/membership/cancel`, { profileId })).data,
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/** Downgrade at the end of the paid period (`POST /public/communities/:slug/membership/downgrade`). */
+export function useDowngradeCommunityMembership(ref: string | undefined) {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateCommunities();
+  return useMutation<unknown, unknown, { membershipTierId: string }>({
+    mutationFn: async (body) =>
+      (await client.post(`/public/communities/${enc(ref!)}/membership/downgrade`, { profileId, ...body })).data,
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/** Withdraw a pending downgrade (`POST /public/communities/:slug/membership/undo-downgrade`). */
+export function useUndoCommunityDowngrade(ref: string | undefined) {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateCommunities();
+  return useMutation<unknown, unknown, void>({
+    mutationFn: async () =>
+      (await client.post(`/public/communities/${enc(ref!)}/membership/undo-downgrade`, { profileId })).data,
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/** True when an error is a 404: an answer (no such community, dead token), not a transient failure. */
+export function isNotFound(error: unknown): boolean {
+  return (error as { response?: { status?: number } } | null)?.response?.status === 404;
+}