@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/membership/useMembershipCheckout.ts

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { communityHomePath, communitiesListPath } from "../communities/paths";
 import {
   readMembershipInviteFromUrl,
   useApplyForMembership,
@@ -55,9 +57,13 @@ export type { BillingCycle };
 export interface UseMembershipCheckoutOptions {
   /** Pre-select a tier (e.g. from a `?membershipTierId=` param). */
   initialTierId?: string;
-  /** Where the provider returns the member after a paid subscription. Default `/i/account?tab=membership&confirmSubscription=true`. */
+  /**
+   * Where the provider returns the member after a paid subscription. Default:
+   * the community home with `confirmSubscription=1` (the community comes from
+   * `<CommunityProvider>`), or `/i/communities` outside one. Never the account page.
+   */
   returnPath?: string;
-  /** Where free activations land. Default `/i/account?tab=membership`. */
+  /** Where free activations land. Default: the community home with `welcome=1`. */
   freeReturnPath?: string;
   /**
    * Called when the subscription completes IN-APP with nothing left to pay: a
@@ -73,13 +79,30 @@ export interface UseMembershipCheckoutOptions {
    * the current url is used; `null` sends none.
    */
   inviteToken?: string | null;
+  /**
+   * A shareable invite link token (`?join=`), sent with every join call. It
+   * opens an invite-only tier; a paid tier still charges.
+   */
+  joinToken?: string | null;
   /**
    * Where Stripe returns after a redirect-based card confirmation on an
-   * APPLICATION (a card that needed a bank redirect). Default
-   * `/i/account?tab=membership`, where the fan's applications are listed. The
-   * application id is appended as `confirmApplication`.
+   * APPLICATION (a card that needed a bank redirect). Default: the community
+   * home, where a pending application is shown. The application id is appended
+   * as `confirmApplication`.
    */
   applicationReturnPath?: string;
+  /**
+   * The tiers to offer, when the caller already has them (the community read
+   * returns exactly the tiers this viewer may join). Omitted, they are fetched.
+   */
+  tiers?: MembershipTier[];
+  /**
+   * The viewer's current membership IN THIS COMMUNITY, when the caller knows it.
+   * Decides whether subscribing is a tier change. Omitted, the signed-in
+   * account's single legacy `membership` is read, which knows nothing of
+   * communities, so a community surface always passes this.
+   */
+  current?: { tierId: string; status: string } | null;
 }
 
 const errMessage = (e: unknown) =>
@@ -106,8 +129,17 @@ const errMessage = (e: unknown) =>
  */
 export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const { user, refetchUser } = usePublicAuth();
+  const community = useOptionalCommunityContext();
   const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
-  const { data: tiers, isLoading } = useGetMembershipTiers({ inviteToken: inviteToken ?? null });
+  const joinToken = opts.joinToken ?? undefined;
+  const fetched = useGetMembershipTiers({ inviteToken: inviteToken ?? null, enabled: !opts.tiers });
+  const tiers = opts.tiers ?? fetched.data;
+  const isLoading = opts.tiers ? false : fetched.isLoading;
+  /** The landing paths, inside the community whenever there is one. */
+  const homeFor = (query?: { welcome?: 1; confirmSubscription?: 1 }) =>
+    community?.slug ? communityHomePath(community.slug, query) : communitiesListPath();
+  const paidReturnPath = opts.returnPath ?? homeFor({ confirmSubscription: 1 });
+  const freeReturnPath = opts.freeReturnPath ?? homeFor({ welcome: 1 });
   const createPaid = useCreateSubscription();
   const createFree = useCreateFreeSubscription();
   const confirmLatest = useConfirmLatestSubscription();
@@ -224,16 +256,29 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     [selectedTier, billingCycle, customAmount],
   );
 
+  /**
+   * The membership this checkout acts on. A fan holds one membership PER
+   * community, so inside a `CommunityProvider` only the caller's `current` (the
+   * viewer's membership in THAT community, as `useCommunityJoin` and the styled
+   * `MembershipCheckout` pass it) may name one. Without it the fan is treated as
+   * holding none here: `user.membership` is the newest membership on the whole
+   * profile and may belong to another community, where it would turn this join
+   * into a tier change. The server decides per community either way.
+   * `user.membership` remains the fallback only outside any community.
+   */
+  const current = opts.current !== undefined ? opts.current : community?.communityId ? null : undefined;
   const membership = user?.membership;
   /** The tier they are on now, so its card can say so instead of offering itself. */
-  const currentTierId = membership?.membershipTierId;
+  const currentTierId = current !== undefined ? (current?.tierId ?? undefined) : membership?.membershipTierId;
   /**
    * A member with a live provider subscription picking a PAID tier is changing,
    * not joining. The server settles it by proration on the subscription they
    * already have, so the button says so.
    */
   const isChange =
-    !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
+    current !== undefined
+      ? !!current && current.status === "active" && !isFreeCycle && !!selectedTier
+      : !!membership?.paymentProviderSubscriptionId && membership.status === "active" && !isFreeCycle && !!selectedTier;
 
   /**
    * The free trial this fan would start on the selected tier, in days, or 0.
@@ -264,9 +309,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     }
     if (typeof window !== "undefined") {
       const origin = window.location.origin;
-      const path = requiresConfirmation
-        ? (opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true")
-        : (opts.freeReturnPath ?? "/i/account?tab=membership");
+      const path = requiresConfirmation ? paidReturnPath : freeReturnPath;
       window.location.href = `${origin}${path}`;
     }
   };
@@ -275,7 +318,26 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
   const questionnaireBody = () =>
     questionnaire.length ? { questionnaire: buildQuestionnaireAnswers(questionnaire, questionnaireAnswers) } : {};
 
-  const subscribe = async () => {
+  /**
+   * How many join calls are running. `isProcessing` reads THIS, not the
+   * mutations' `isPending`: `subscribe` is started from an effect by the join
+   * sheet, and a mutation started from an effect loses its observer when React
+   * StrictMode unmounts and remounts in development, leaving `isPending` stuck
+   * true after the request answered. A settled promise always clears this.
+   */
+  const [inFlight, setInFlight] = useState(0);
+  const tracked =
+    <A extends unknown[]>(run: (...args: A) => Promise<void>) =>
+    async (...args: A) => {
+      setInFlight((n) => n + 1);
+      try {
+        await run(...args);
+      } finally {
+        setInFlight((n) => n - 1);
+      }
+    };
+
+  const subscribe = tracked(async () => {
     setError(null);
     setAmountRefusal(null);
     setTrial(null);
@@ -302,10 +364,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
       await submitApplication(origin);
       return;
     }
-    const returnUrl = `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`;
+    const returnUrl = `${origin}${paidReturnPath}`;
     const attributionRefId = readAttributionRef() ?? undefined;
     const landing = readLanding() ?? {};
-    const invite = inviteToken ? { inviteToken } : {};
+    const invite = { ...(inviteToken ? { inviteToken } : {}), ...(joinToken ? { joinToken } : {}) };
     const answers = questionnaireBody();
     try {
       if (isFreeCycle) {
@@ -371,7 +433,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   /**
    * Apply to an `application` tier. Free: the application is lodged and the
@@ -379,14 +441,16 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
    * moves to "payment" and the renderer saves the card; `confirmApplication()`
    * runs after it succeeds. Nothing is charged until the business approves.
    */
-  const applicationReturnBase = opts.applicationReturnPath ?? "/i/account?tab=membership";
-  const submitApplication = async (origin: string) => {
+  const applicationReturnBase = opts.applicationReturnPath ?? homeFor();
+  const submitApplication = tracked(async (origin: string) => {
     if (!selectedTier) return;
     try {
       const data = await applyMutation.mutateAsync({
         membershipTierId: selectedTier.id,
         ...(isFreeCycle ? {} : { billingCycle, amount }),
         ...questionnaireBody(),
+        ...(inviteToken ? { inviteToken } : {}),
+        ...(joinToken ? { joinToken } : {}),
         returnUrl: `${origin}${applicationReturnBase}`,
       });
       setApplication(data.application);
@@ -398,10 +462,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   /** Call after the card renderer confirmed the SetupIntent. Idempotent on the server. */
-  const confirmApplication = async () => {
+  const confirmApplication = tracked(async () => {
     if (!application) return;
     setError(null);
     setCardConfirmed(true);
@@ -411,7 +475,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     } catch (e) {
       setError(errMessage(e));
     }
-  };
+  });
 
   const applicationOutcome: MembershipApplicationOutcome | null = membershipApplicationOutcome(
     application,
@@ -478,8 +542,7 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
             onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
           })
         : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
-    isProcessing:
-      createPaid.isPending || createFree.isPending || applyMutation.isPending || confirmApplicationMutation.isPending,
+    isProcessing: inFlight > 0,
     error,
     /** Call on the return page to reconcile the latest subscription. */
     confirmLatest,
@@ -487,6 +550,10 @@ export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
     finish,
     /** The invite token this checkout forwards, if any. */
     inviteToken,
+    /** The shareable link token this checkout forwards, if any. */
+    joinToken,
+    /** Where a paid subscription returns: the community home with `confirmSubscription=1` by default. */
+    returnPath: paidReturnPath,
     /** True when subscribe() applies to the tier instead of joining it. */
     isApplication,
     /**

package/src/ui/headless/membership/useMembershipGateNotice.ts

@@ -1,6 +1,8 @@
 import { useMemo } from "react";
 import type { PublicMembershipGate } from "../../../types/models";
 import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import { usePublicCommunities } from "../../../data/queries/useCommunities";
+import { communityAboutPath } from "../communities/paths";
 import {
   buildMembershipGateNotice,
   isMembershipGateLocked,
@@ -13,11 +15,15 @@ export interface UseMembershipGateNoticeInput {
   gate?: PublicMembershipGate | null;
   /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate`. */
   refusal?: MembershipGateRefusal | null;
-  /** What the thing is, in the buyer's words — "This ticket", "This course". */
+  /** What the thing is, in the buyer's words: "This ticket", "This course". */
   itemLabel?: string;
   /** Where a signed-out visitor signs in. Code sites mount theirs under `/i`. */
   loginPath?: string;
-  /** Where a signed-in non-member goes to join — the tier listing. */
+  /**
+   * Where a signed-in non-member goes to join. Default: the About page of the
+   * community the first required tier belongs to, with that tier preselected
+   * (`/i/communities/<slug>?tier=<id>`), which joins in place.
+   */
   membershipPath?: string;
 }
 
@@ -29,14 +35,14 @@ export interface UseMembershipGateNoticeInput {
  * A gate comes down as `requiredTierIds`, and "you need tier 8f3c-…" is not a
  * sentence anyone can act on. The public tier list is already loaded by every
  * storefront that sells memberships, is cached by React Query under one key per
- * profile, and — unlike an id embedded in a ticket payload — stays correct when
+ * profile, and (unlike an id embedded in a ticket payload) stays correct when
  * the artist renames a tier. So the ids are resolved against it here, once, for
  * every surface.
  *
  * The names are best-effort by design: the query can be in flight, and a gating
  * tier can be one the public list does not carry (an archived or unlisted tier
  * still gates). `buildMembershipGateNotice` therefore degrades to "is for
- * members" rather than showing an id or rendering nothing — a badge with slightly
+ * members" rather than showing an id or rendering nothing: a badge with slightly
  * vaguer wording is a working funnel; a blank space is the bug this closes.
  *
  * Returns `null` when nothing is gated, which is also what every surface sees
@@ -44,22 +50,33 @@ export interface UseMembershipGateNoticeInput {
  */
 export function useMembershipGateNotice(input: UseMembershipGateNoticeInput): MembershipGateNotice | null {
   const locked = isMembershipGateLocked(input.gate) || !!input.refusal;
-  // Only pulled once something is actually locked — an ungated storefront must
+  // Only pulled once something is actually locked: an ungated storefront must
   // not acquire a request it never needed.
-  const { data: tiers } = useGetMembershipTiers({ enabled: locked });
+  // Profile-wide on purpose: a gate on a product can name a tier from any community.
+  const { data: tiers } = useGetMembershipTiers({ enabled: locked, communityId: null });
+  const { data: communities } = usePublicCommunities({ enabled: locked && !input.membershipPath });
 
   const requiredTierIds = input.refusal?.requiredTierIds ?? input.gate?.requiredTierIds ?? [];
 
   return useMemo(() => {
     if (!locked) return null;
     const byId = new Map((tiers ?? []).map((tier) => [tier.id, tier.name]));
+    // A tier belongs to exactly one community: its About page is where to join it.
+    const firstTier = (tiers ?? []).find((tier) => tier.id === requiredTierIds[0]) as
+      | { id: string; communityId?: string }
+      | undefined;
+    const community = firstTier?.communityId
+      ? communities?.find((candidate) => candidate.id === firstTier.communityId)
+      : undefined;
+    const membershipPath =
+      input.membershipPath ?? (community ? communityAboutPath(community.slug, { tier: firstTier!.id }) : undefined);
     return buildMembershipGateNotice({
       gate: input.gate,
       refusal: input.refusal,
       tierNames: requiredTierIds.map((id) => byId.get(id) ?? "").filter(Boolean),
       itemLabel: input.itemLabel,
       loginPath: input.loginPath,
-      membershipPath: input.membershipPath,
+      membershipPath,
       currentPath: currentPath(),
     });
     // `requiredTierIds` is a fresh array each render; its CONTENTS are the input.
@@ -67,6 +84,7 @@ export function useMembershipGateNotice(input: UseMembershipGateNoticeInput): Me
   }, [
     locked,
     tiers,
+    communities,
     requiredTierIds.join(","),
     input.gate?.reason,
     input.refusal?.reason,

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

@@ -0,0 +1,57 @@
+// Client portal (`/i/account/*`) headless primitives.
+export {
+  usePortalSummary,
+  usePortalInvoices,
+  usePortalDocuments,
+  usePortalActivity,
+  useWorkApprovalRequests,
+  useDecideApproval,
+  type PortalSectionKey,
+  type PortalAttentionItem,
+  type PortalSummary,
+  type PortalInvoice,
+  type PortalDocument,
+  type PortalActivityKind,
+  type PortalActivityItem,
+  type PortalActivityPage,
+  type ApprovalStatus,
+  type WorkApprovalRequest,
+  type WorkApprovalRequests,
+  type ApprovalDecision,
+} from "./usePortal";
+export {
+  usePortalFiles,
+  portalFilesKey,
+  type PortalFile,
+  type PortalFileOpen,
+  type PortalFilesPage,
+  type PortalFileSource,
+  type PortalFileSourceFilter,
+} from "./usePortalFiles";
+// Preview as client: redeem the one-time code, and read whether this is a preview.
+export {
+  usePortalPreview,
+  usePortalPreviewRedeem,
+  isPortalPreviewPending,
+  type PortalPreview,
+  type PortalPreviewRedeemState,
+} from "./usePortalPreview";
+// Messages: the one conversation with the creator.
+export {
+  usePortalThread,
+  usePortalMessages,
+  useSendPortalMessage,
+  useMarkPortalMessagesRead,
+  usePortalMessageAttachments,
+  usePortalMessagesLive,
+  portalMessagesInOrder,
+  portalThreadKey,
+  portalMessagesKey,
+  PORTAL_MESSAGES_POLL_MS,
+  PORTAL_MESSAGES_PRESIGN_PATH,
+  type PortalMessage,
+  type PortalMessageAttachment,
+  type PortalMessagesPage,
+  type PortalThreadState,
+  type PortalThreadSummary,
+} from "./usePortalMessages";

package/src/ui/headless/portal/usePortal.ts

@@ -0,0 +1,274 @@
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+/**
+ * Headless data layer for the client portal (`/i/account/*`).
+ *
+ * Speaks `/public/portal/*`, which answers for the signed-in account on this
+ * profile only: every list is "mine", and nothing here takes an account id. The
+ * styled portal is built on exactly these, so a creator can build a different
+ * portal on the same data.
+ *
+ * Contract: docs/proposals/unified-client-portal.md, "Backend contract".
+ */
+
+// ── Types (mirror PortalService responses) ───────────────────────────────────
+
+export type PortalSectionKey =
+  | "projects"
+  | "invoices"
+  | "documents"
+  | "bookings"
+  | "memberships"
+  | "courses"
+  | "films"
+  | "orders"
+  | "tickets"
+  | "waitlist"
+  | "saved"
+  /** 1 when the person may message the creator, else 0. */
+  | "messages"
+  | "files";
+
+export type PortalAttentionItem =
+  | {
+      kind: "invoice_due" | "invoice_overdue";
+      id: string;
+      invoiceNumber: string;
+      total: string;
+      currency: string;
+      dueDate: string | null;
+      projectId: string | null;
+      projectName: string | null;
+    }
+  | { kind: "document_to_sign"; id: string; title: string; token: string; sentAt: string; expiresAt: string | null }
+  | {
+      kind: "approval_requested";
+      id: string;
+      milestoneId: string;
+      milestoneName: string;
+      projectId: string;
+      projectName: string;
+      requestedAt: string;
+      note: string | null;
+    }
+  | { kind: "membership_payment_failed"; id: string; communityName: string; communitySlug: string }
+  | {
+      kind: "message_unread";
+      /** The conversation's id. */
+      id: string;
+      unreadCount: number;
+      lastMessageAt: string;
+      preview: string | null;
+    };
+
+export interface PortalSummary {
+  sections: Record<PortalSectionKey, number>;
+  /** The newest thing that happened in each group. Orders the navigation. */
+  lastActivity: { work: string | null; library: string | null };
+  /** Already ranked by the server: overdue first, then approvals, documents, due. */
+  attention: PortalAttentionItem[];
+}
+
+export interface PortalInvoice {
+  id: string;
+  invoiceNumber: string;
+  status: string;
+  total: string;
+  currency: string;
+  issueDate: string;
+  dueDate: string | null;
+  paidAt: string | null;
+  projectId: string | null;
+  projectName: string | null;
+}
+
+export interface PortalDocument {
+  documentId: string;
+  title: string;
+  kind: string;
+  documentStatus: string;
+  recipientStatus: string;
+  needsAction: boolean;
+  /** The recipient's own access token: the key to `/i/documents/$token`. */
+  token: string;
+  sentAt: string;
+  completedAt: string | null;
+  expiresAt: string | null;
+}
+
+export type PortalActivityKind =
+  | "invoice_issued"
+  | "invoice_paid"
+  | "document_sent"
+  | "document_signed"
+  | "milestone_completed"
+  | "comment_added"
+  | "approval_requested"
+  | "approval_decided"
+  | "order_placed"
+  | "booking_confirmed"
+  | "message_received";
+
+export interface PortalActivityItem {
+  id: string;
+  kind: PortalActivityKind;
+  occurredAt: string;
+  title: string;
+  projectId: string | null;
+  projectName: string | null;
+  entityId: string;
+  detail: string | null;
+}
+
+export interface PortalActivityPage {
+  items: PortalActivityItem[];
+  nextBefore: string | null;
+}
+
+export type ApprovalStatus = "pending" | "approved" | "changes_requested" | "cancelled";
+
+export interface WorkApprovalRequest {
+  id: string;
+  milestoneId: string;
+  milestoneName: string;
+  status: ApprovalStatus;
+  note: string | null;
+  requestedAt: string;
+  decidedAt: string | null;
+  decisionComment: string | null;
+  decidedByName: string | null;
+}
+
+export type ApprovalDecision = "approve" | "request_changes";
+
+// ── Keys ─────────────────────────────────────────────────────────────────────
+
+const keys = {
+  summary: (profileId?: string, accountId?: string) => ["portal-summary", profileId, accountId] as const,
+  invoices: (profileId?: string, accountId?: string, status?: string) =>
+    ["portal-invoices", profileId, accountId, status] as const,
+  documents: (profileId?: string, accountId?: string) => ["portal-documents", profileId, accountId] as const,
+  activity: (profileId?: string, accountId?: string, limit?: number) =>
+    ["portal-activity", profileId, accountId, limit] as const,
+  approvals: (profileId?: string, projectId?: string) => ["work-approvals", profileId, projectId] as const,
+};
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/** What needs the person, and which sections they have anything in. */
+export function usePortalSummary(): UseQueryResult<PortalSummary> {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useQuery({
+    queryKey: keys.summary(profileId, user?.id),
+    queryFn: async () => {
+      const res = await client.get("/public/portal/summary", { params: { profileId } });
+      return res.data as PortalSummary;
+    },
+    enabled: !!profileId && !!client && !!user,
+    // The rail and the bottom bar read this on every portal page; a person
+    // moving between sections should not watch the navigation reload.
+    staleTime: 30_000,
+  });
+}
+
+/** Every invoice the creator has sent this person, newest first. */
+export function usePortalInvoices(status: "open" | "paid" | "all" = "all", pageSize = 50) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useQuery({
+    queryKey: keys.invoices(profileId, user?.id, `${status}:${pageSize}`),
+    queryFn: async () => {
+      const res = await client.get("/public/portal/invoices", { params: { profileId, status, page: 1, pageSize } });
+      return res.data as { data: PortalInvoice[]; total: number; page: number; pageSize: number };
+    },
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** Documents sent to this person for signature or acceptance. */
+export function usePortalDocuments(): UseQueryResult<PortalDocument[]> {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useQuery({
+    queryKey: keys.documents(profileId, user?.id),
+    queryFn: async () => {
+      const res = await client.get("/public/portal/documents", { params: { profileId } });
+      return (res.data as { data: PortalDocument[] }).data;
+    },
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** The activity timeline, newest first, one page at a time. */
+export function usePortalActivity(limit = 20) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useInfiniteQuery({
+    queryKey: keys.activity(profileId, user?.id, limit),
+    initialPageParam: undefined as string | undefined,
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/portal/activity", {
+        params: { profileId, limit, ...(pageParam ? { before: pageParam } : {}) },
+      });
+      return res.data as PortalActivityPage;
+    },
+    getNextPageParam: (last) => last.nextBefore ?? undefined,
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+export interface WorkApprovalRequests {
+  /** Newest first, every status: the project's approval history. */
+  requests: WorkApprovalRequest[];
+  /**
+   * Whether THIS client may decide. A view-only seat reads the same history but
+   * must not be offered Approve, which the decision endpoint would refuse.
+   */
+  canApprove: boolean;
+}
+
+/** Every approval the creator has asked of this client on one project, and whether they may decide. */
+export function useWorkApprovalRequests(projectId: string): UseQueryResult<WorkApprovalRequests> {
+  const { client, profileId } = useForge();
+  return useQuery({
+    queryKey: keys.approvals(profileId, projectId),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/projects/${projectId}/approval-requests`, { params: { profileId } });
+      const body = res.data as { data: WorkApprovalRequest[]; canApprove?: boolean };
+      // An API build older than the flag decided nothing here; treat it as
+      // "may approve", which is exactly how the page behaved before.
+      return { requests: body.data, canApprove: body.canApprove ?? true };
+    },
+    enabled: !!profileId && !!client && !!projectId,
+  });
+}
+
+/**
+ * Approve a milestone, or send it back with a comment.
+ *
+ * Approving completes the milestone, so the project report, the summary and the
+ * activity timeline all change with it, and all three are refetched.
+ */
+export function useDecideApproval(projectId: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { requestId: string; decision: ApprovalDecision; comment?: string }) => {
+      const res = await client.post(
+        `/public/work/projects/${projectId}/approval-requests/${input.requestId}/decision`,
+        { decision: input.decision, comment: input.comment },
+        { params: { profileId } },
+      );
+      return res.data as WorkApprovalRequest;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: keys.approvals(profileId, projectId) });
+      void queryClient.invalidateQueries({ queryKey: ["portal-summary"] });
+      void queryClient.invalidateQueries({ queryKey: ["portal-activity"] });
+      void queryClient.invalidateQueries({ queryKey: ["work-portal-report", profileId, projectId] });
+    },
+  });
+}