@tribe-nest/forge 3.59.0 → 3.61.0

package/src/data/queries/useChat.ts

@@ -2,6 +2,7 @@ import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tansta
 import { useEffect, useRef, useState } from "react";
 import { io, type Socket } from "socket.io-client";
 import { useForge } from "../../provider/ForgeProvider";
+import { useCommunityScope } from "../../contexts/CommunityContext";
 import { getForgeWebSocketUrl } from "../../client/createForgeClient";
 import { PUBLIC_ACCESS_TOKEN_KEY } from "../../contexts/PublicAuthContext";
 
@@ -13,6 +14,11 @@ export interface ChatChannel {
   description: string | null;
   /** For DM channels, the counterpart participant (backend-enriched). */
   otherParticipant?: ChatDmPeer | null;
+  /**
+   * A DM's pair key. Null for the member and creator DM; `agent:...` for the
+   * member's DM with the community AI (see `isCommunityAgentDm`).
+   */
+  dmKey?: string | null;
 }
 
 export interface ChatAttachment {
@@ -26,7 +32,11 @@ export interface ChatMessage {
   id: string;
   channelId: string;
   content: string | null;
-  senderAccountId: string;
+  /** Null when the community AI sent it (`senderAgentId` is then set). */
+  senderAccountId: string | null;
+  /** The community AI, when it sent this message. `senderFirstName` is then its name. */
+  senderAgentId?: string | null;
+  senderAgentAvatarUrl?: string | null;
   senderFirstName: string;
   senderLastName: string;
   isPinned: boolean;
@@ -67,83 +77,85 @@ export interface ChatMessagesPage {
 // Query keys are exported so the realtime layer (and creators) can patch the
 // same caches the data hooks populate.
 export const chatKeys = {
-  channels: (profileId?: string) => ["public-chat-channels", profileId] as const,
+  // Channel lists, unread counts, DMs and the directory are per COMMUNITY: a
+  // profile runs several, and each has its own channels and members.
+  channels: (communityId?: string) => ["public-chat-channels", communityId] as const,
   messages: (channelId?: string) => ["public-chat-messages", channelId] as const,
   pinned: (channelId?: string) => ["public-chat-pinned", channelId] as const,
-  unread: (profileId?: string) => ["public-chat-unread-counts", profileId] as const,
-  dm: (profileId?: string) => ["public-chat-dm", profileId] as const,
+  unread: (communityId?: string) => ["public-chat-unread-counts", communityId] as const,
+  dm: (communityId?: string) => ["public-chat-dm", communityId] as const,
   replies: (parentMessageId?: string) => ["public-chat-replies", parentMessageId] as const,
-  memberDirectory: (profileId?: string) => ["public-chat-member-directory", profileId] as const,
+  memberDirectory: (communityId?: string) => ["public-chat-member-directory", communityId] as const,
 };
 
 // ── Data hooks ───────────────────────────────────────────────────────────────
 
 /** Channels visible to the current member (GET /public/chat/channels). */
 export function useChatChannels() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatChannels()");
   return useQuery<ChatChannel[]>({
-    queryKey: chatKeys.channels(profileId),
+    queryKey: chatKeys.channels(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/channels", { params: { profileId } });
+      const res = await client.get("/public/chat/channels", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Paginated messages for a channel, newest first (GET /public/chat/channels/:id/messages). */
 export function useChatMessages(channelId?: string, limit = 50) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMessages()");
   return useInfiniteQuery<ChatMessagesPage>({
     queryKey: chatKeys.messages(channelId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/chat/channels/${channelId}/messages`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) =>
       lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
-    enabled: !!channelId && !!client && !!profileId,
+    enabled: !!channelId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Pinned messages for a channel (GET /public/chat/channels/:id/pinned). */
 export function useChatPinnedMessages(channelId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatPinnedMessages()");
   return useQuery<ChatMessage[]>({
     queryKey: chatKeys.pinned(channelId),
     queryFn: async () => {
-      const res = await client.get(`/public/chat/channels/${channelId}/pinned`, { params: { profileId } });
+      const res = await client.get(`/public/chat/channels/${channelId}/pinned`, { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!channelId && !!client && !!profileId,
+    enabled: !!channelId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Per-channel unread counts, polled every 30s (GET /public/chat/unread-counts). */
 export function useChatUnreadCounts() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatUnreadCounts()");
   return useQuery<ChatUnreadCount[]>({
-    queryKey: chatKeys.unread(profileId),
+    queryKey: chatKeys.unread(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/unread-counts", { params: { profileId } });
+      const res = await client.get("/public/chat/unread-counts", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
     refetchInterval: 30000,
   });
 }
 
 /** Mark messages as read (POST /public/chat/read-receipts); invalidates unread counts. */
 export function useMarkChatRead() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useMarkChatRead()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (messageIds: string[]) => {
       if (messageIds.length === 0) return;
-      await client.post("/public/chat/read-receipts", { profileId, messageIds });
+      await client.post("/public/chat/read-receipts", { profileId, communityId, messageIds });
     },
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ["public-chat-unread-counts"] });
@@ -153,7 +165,7 @@ export function useMarkChatRead() {
 
 /** Send a message over REST (POST /public/chat/messages). Realtime path uses the socket. */
 export function useSendChatMessage() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useSendChatMessage()");
   return useMutation({
     mutationFn: async (input: {
       channelId: string;
@@ -161,7 +173,7 @@ export function useSendChatMessage() {
       attachments?: ChatAttachment[];
       parentMessageId?: string;
     }) => {
-      const res = await client.post("/public/chat/messages", { profileId, ...input });
+      const res = await client.post("/public/chat/messages", { profileId, communityId, ...input });
       return res.data as ChatMessage;
     },
   });
@@ -169,69 +181,69 @@ export function useSendChatMessage() {
 
 /** Paginated replies for a thread parent (GET /public/chat/messages/:id/replies), oldest first. */
 export function useChatMessageReplies(parentMessageId?: string, limit = 50) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMessageReplies()");
   return useInfiniteQuery<ChatMessagesPage>({
     queryKey: chatKeys.replies(parentMessageId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/chat/messages/${parentMessageId}/replies`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) =>
       lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
-    enabled: !!parentMessageId && !!client && !!profileId,
+    enabled: !!parentMessageId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Same-tier members the current member may start a DM with (GET /public/chat/dm/directory). */
 export function useChatMemberDirectory() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMemberDirectory()");
   return useQuery<ChatDirectoryMember[]>({
-    queryKey: chatKeys.memberDirectory(profileId),
+    queryKey: chatKeys.memberDirectory(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/dm/directory", { params: { profileId } });
+      const res = await client.get("/public/chat/dm/directory", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Open/create a DM with another member (POST /public/chat/dm/member). */
 export function useCreateMemberDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateMemberDm()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (targetAccountId: string) => {
-      const res = await client.post("/public/chat/dm/member", { profileId, targetAccountId });
+      const res = await client.post("/public/chat/dm/member", { profileId, communityId, targetAccountId });
       return res.data as ChatChannel;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: chatKeys.channels(profileId) });
+      queryClient.invalidateQueries({ queryKey: chatKeys.channels(communityId) });
     },
   });
 }
 
 /** The current member's DM channel, if any (GET /public/chat/dm). */
 export function useChatDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatDm()");
   return useQuery<ChatChannel | null>({
-    queryKey: chatKeys.dm(profileId),
+    queryKey: chatKeys.dm(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/dm", { params: { profileId } });
+      const res = await client.get("/public/chat/dm", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Open/create the member's DM channel (POST /public/chat/dm). */
 export function useCreateChatDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateChatDm()");
   return useMutation({
     mutationFn: async () => {
-      const res = await client.post("/public/chat/dm", { profileId });
+      const res = await client.post("/public/chat/dm", { profileId, communityId });
       return res.data as ChatChannel;
     },
   });
@@ -259,7 +271,7 @@ export function useChatSocket(enabled: boolean) {
     const next = io(getForgeWebSocketUrl(apiUrl), { auth: { token }, transports: ["websocket"] });
     socketRef.current = next;
     setSocket(next);
-    // Intentionally not disconnecting on unmount — mirrors the client app, where the
+    // Intentionally not disconnecting on unmount: mirrors the client app, where the
     // chat socket persists across channel selection. Callers manage room join/leave.
   }, [enabled, apiUrl]);
 

package/src/data/queries/useCheckouts.ts

@@ -1,4 +1,5 @@
 import { useMutation } from "@tanstack/react-query";
+import { readMetaSignals } from "../../utils/metaEvents";
 import { useForge } from "../../provider/ForgeProvider";
 import { bundleCouponRequestBody } from "../../ui/headless/checkout/bundleCoupon";
 import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
@@ -133,7 +134,7 @@ export function useCreateCheckout() {
 
   return useMutation<CreateCheckoutResult, unknown, Record<string, unknown>>({
     mutationFn: async (body) => {
-      const res = await client.post("/public/checkouts", { profileId, ...body });
+      const res = await client.post("/public/checkouts", { profileId, ...body, metaSignals: readMetaSignals() });
       return res.data;
     },
   });

package/src/data/queries/useCoachingAvailability.ts

@@ -1,4 +1,5 @@
 import type { BookingSlot, CancellationTermsView, PillarDiscountQuote } from "../../types/models";
+import { fireServerMetaEvent, readMetaSignals, type ServerMetaEvent } from "../../utils/metaEvents";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -44,6 +45,7 @@ export function useReserveCoachingBooking(productId?: string) {
     mutationFn: async ({ slotId }) => {
       const res = await client.post(`/public/coaching/products/${productId}/booking/reserve`, {
         slotId,
+        metaSignals: readMetaSignals(),
       });
       return res.data;
     },
@@ -71,6 +73,8 @@ export type UpdateCoachingBookingInput = {
 export type UpdateCoachingBookingResult = PillarDiscountQuote & {
   bookingId: string;
   isConfirmed: boolean;
+  /** Set when this call newly confirmed a free booking and the server queued Schedule. */
+  metaEvent?: ServerMetaEvent;
 };
 
 /**
@@ -87,9 +91,14 @@ export function useUpdateCoachingBooking(productId?: string) {
 
   return useMutation<UpdateCoachingBookingResult, unknown, UpdateCoachingBookingInput>({
     mutationFn: async (body) => {
-      const res = await client.post(`/public/coaching/products/${productId}/booking/update`, body);
+      const res = await client.post(`/public/coaching/products/${productId}/booking/update`, {
+        ...body,
+        metaSignals: readMetaSignals(),
+      });
       return res.data;
     },
+    // A free booking newly confirmed: the server queued Schedule; fire its pixel twin.
+    onSuccess: (data) => fireServerMetaEvent(data),
   });
 }
 

package/src/data/queries/useCommunities.ts

@@ -0,0 +1,345 @@
+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;
+  /** How a visitor gets in. Absent on older servers: treat as open. */
+  joinMode?: "open" | "application" | "invite";
+}
+
+/** 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;
+}