@tribe-nest/forge 3.60.0 → 3.61.0

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] });
+    },
+  });
+}

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

@@ -0,0 +1,68 @@
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+/**
+ * Every file this person has with the creator (`GET /public/portal/files`):
+ * project files shared with them, attachments on their project tasks, signed
+ * documents, invoice PDFs and their paid downloads, newest first across all.
+ *
+ * A row never carries a signed address. `open` says which endpoint serves it,
+ * and that endpoint checks ownership again on the click.
+ */
+
+export type PortalFileSource = "project" | "task" | "document" | "invoice" | "purchase";
+export type PortalFileSourceFilter = PortalFileSource | "all";
+
+export type PortalFileOpen =
+  /** Fetch a 60-second URL through `useWorkOpenSharedDocument(projectId)`. */
+  | { kind: "project_document"; projectId: string; documentId: string }
+  /** A public media address, safe to link directly. */
+  | { kind: "task_attachment"; projectId: string; taskId: string; url: string }
+  /** The recipient token: `GET /public/documents/:token/download`. */
+  | { kind: "signed_document"; token: string }
+  /** `GET /public/invoices/:id/pdf`. */
+  | { kind: "invoice_pdf"; invoiceId: string }
+  /** A paid download: the download page `/i/downloads/<token>`, which lets the owner straight through. */
+  | { kind: "purchase_download"; token: string };
+
+export interface PortalFile {
+  id: string;
+  source: PortalFileSource;
+  title: string;
+  filename: string | null;
+  mimeType: string | null;
+  size: number | null;
+  createdAt: string;
+  projectId: string | null;
+  projectName: string | null;
+  open: PortalFileOpen;
+}
+
+export interface PortalFilesPage {
+  data: PortalFile[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export const portalFilesKey = (profileId?: string, accountId?: string, source?: string, pageSize?: number) =>
+  ["portal-files", profileId, accountId, source, pageSize] as const;
+
+/** Paged newest first. `fetchNextPage` loads the next `pageSize` rows. */
+export function usePortalFiles(source: PortalFileSourceFilter = "all", pageSize = 30) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useInfiniteQuery({
+    queryKey: portalFilesKey(profileId, user?.id, source, pageSize),
+    initialPageParam: 1,
+    queryFn: async ({ pageParam }) => {
+      const res = await client.get("/public/portal/files", {
+        params: { profileId, source, page: pageParam, pageSize },
+      });
+      return res.data as PortalFilesPage;
+    },
+    getNextPageParam: (last) => (last.page * last.pageSize < last.total ? last.page + 1 : undefined),
+    enabled: !!profileId && !!client && !!user,
+  });
+}

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

@@ -0,0 +1,189 @@
+import { useEffect, useMemo } from "react";
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useChatSocket } from "../../../data/queries/useChat";
+import { useChatAttachmentUpload } from "../chat/useChatAttachmentUpload";
+
+/**
+ * Messages in the client portal (`/i/account/messages`): one conversation
+ * between this person and the creator (`/public/portal/messages`).
+ *
+ * The creator's replies arrive as the BRAND: `senderName` on a team message is
+ * the creator's name, never the team member who wrote it. Realtime rides the
+ * community chat socket (`chat:<threadId>`); when the socket is not connected,
+ * the open page re-reads every 10 seconds while it is visible.
+ */
+
+export interface PortalMessageAttachment {
+  url: string;
+  fileName: string;
+  fileSize: number;
+  fileType: string;
+}
+
+export interface PortalMessage {
+  id: string;
+  content: string | null;
+  attachments: PortalMessageAttachment[];
+  createdAt: string;
+  /** A reply from the creator's side. */
+  fromTeam: boolean;
+  /** The caller's own message. */
+  isMine: boolean;
+  /** The creator's name on a reply, the person's first name on their own. */
+  senderName: string;
+}
+
+export interface PortalThreadSummary {
+  id: string;
+  createdAt: string;
+  unreadCount: number;
+  lastMessageAt: string | null;
+  lastPreview: string | null;
+}
+
+export interface PortalThreadState {
+  /** May this person write (start a conversation, or keep writing in theirs)? */
+  allowed: boolean;
+  creator: { name: string };
+  /** Null until the first message. */
+  thread: PortalThreadSummary | null;
+}
+
+export interface PortalMessagesPage {
+  /** Oldest first inside the page. */
+  data: PortalMessage[];
+  /** Pass as `before` for the page before this one; null at the start. */
+  nextCursor: string | null;
+}
+
+/** How often an open Messages page re-reads while the socket is not connected. */
+export const PORTAL_MESSAGES_POLL_MS = 10_000;
+
+/** The endpoint that signs a portal attachment upload. */
+export const PORTAL_MESSAGES_PRESIGN_PATH = "/public/portal/messages/attachments/presigned-url";
+
+export const portalThreadKey = (profileId?: string, accountId?: string) =>
+  ["portal-messages-thread", profileId, accountId] as const;
+export const portalMessagesKey = (profileId?: string, accountId?: string) =>
+  ["portal-messages", profileId, accountId] as const;
+
+/** The conversation's header: whether the person may write, the creator, and the thread. */
+export function usePortalThread() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useQuery({
+    queryKey: portalThreadKey(profileId, user?.id),
+    queryFn: async () =>
+      (await client.get("/public/portal/messages", { params: { profileId } })).data as PortalThreadState,
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** The conversation, newest page first. Flatten with `portalMessagesInOrder`. */
+export function usePortalMessages(limit = 30) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  return useInfiniteQuery({
+    queryKey: portalMessagesKey(profileId, user?.id),
+    initialPageParam: undefined as string | undefined,
+    queryFn: async ({ pageParam }) =>
+      (
+        await client.get("/public/portal/messages/messages", {
+          params: { profileId, limit, ...(pageParam ? { before: pageParam } : {}) },
+        })
+      ).data as PortalMessagesPage,
+    getNextPageParam: (last) => last.nextCursor ?? undefined,
+    enabled: !!profileId && !!client && !!user,
+  });
+}
+
+/** Every loaded message, oldest first: the pages are newest first, each oldest first inside. */
+export function portalMessagesInOrder(pages: PortalMessagesPage[] | undefined): PortalMessage[] {
+  return [...(pages ?? [])].reverse().flatMap((page) => page.data);
+}
+
+/** Send one message. The first one opens the conversation. */
+export function useSendPortalMessage() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: { content: string; attachments: PortalMessageAttachment[] }) =>
+      (await client.post("/public/portal/messages/messages", { profileId, ...input })).data as PortalMessage,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: portalMessagesKey(profileId, user?.id) });
+      queryClient.invalidateQueries({ queryKey: portalThreadKey(profileId, user?.id) });
+    },
+  });
+}
+
+/** Mark the creator's replies read. */
+export function useMarkPortalMessagesRead() {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async () =>
+      (await client.post("/public/portal/messages/read", { profileId })).data as {
+        marked: number;
+        unreadCount: number;
+      },
+    onSuccess: (result) => {
+      if (!result?.marked) return;
+      queryClient.invalidateQueries({ queryKey: portalThreadKey(profileId, user?.id) });
+      // The portal home's "needs you" list carries the unread count too.
+      queryClient.invalidateQueries({ queryKey: ["portal-summary"] });
+    },
+  });
+}
+
+/** Stage and upload attachments through the portal's own signing endpoint. */
+export function usePortalMessageAttachments() {
+  return useChatAttachmentUpload({ presignPath: PORTAL_MESSAGES_PRESIGN_PATH });
+}
+
+/**
+ * Follow the conversation live. Joins `chat:<threadId>` on the chat socket and
+ * re-reads on every new message; while the socket is down, re-reads every 10
+ * seconds as long as the page is visible.
+ */
+export function usePortalMessagesLive(threadId: string | null | undefined) {
+  const { profileId } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const socket = useChatSocket(!!threadId && !!user);
+  const keys = useMemo(
+    () => [portalMessagesKey(profileId, user?.id), portalThreadKey(profileId, user?.id)],
+    [profileId, user?.id],
+  );
+
+  useEffect(() => {
+    if (!threadId) return undefined;
+    const refresh = () => keys.forEach((queryKey) => queryClient.invalidateQueries({ queryKey }));
+    const join = () => socket?.emit("chatJoinChannel", { channelId: threadId });
+    const onMessage = (envelope: { event: string; data: { channelId?: string } }) => {
+      if (envelope?.data?.channelId !== threadId) return;
+      if (envelope.event === "chatNewMessage") refresh();
+    };
+    if (socket) {
+      if (socket.connected) join();
+      socket.on("connect", join);
+      socket.on("message", onMessage);
+    }
+    const poll = setInterval(() => {
+      if (socket?.connected) return;
+      if (typeof document !== "undefined" && document.visibilityState !== "visible") return;
+      refresh();
+    }, PORTAL_MESSAGES_POLL_MS);
+    return () => {
+      clearInterval(poll);
+      if (socket) {
+        socket.off("connect", join);
+        socket.off("message", onMessage);
+        socket.emit("chatLeaveChannel", { channelId: threadId });
+      }
+    };
+  }, [threadId, socket, keys, queryClient]);
+}

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

@@ -0,0 +1,142 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import {
+  PUBLIC_ACCESS_TOKEN_KEY,
+  PUBLIC_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  storeTokenPair,
+} from "../../../client/tokenStorage";
+
+/**
+ * Preview as client, the site half.
+ *
+ * A creator clicks "Preview as client" in the admin and lands on
+ * `/i/account?preview=<code>`. The code is single use and lives 60 seconds; it
+ * is the only thing in the URL. This file trades it for a read-only, 15-minute
+ * session for that client, and exposes what the portal needs to say so.
+ *
+ * Two hooks, on purpose:
+ *
+ * - `usePortalPreviewRedeem()` does the exchange. Mount it ONCE, on the portal
+ *   page wrapper. Mounted twice, the second exchange would spend nothing (the
+ *   code is stripped from the address bar before the first request leaves) but
+ *   it is still one job with one owner.
+ * - `usePortalPreview()` is read-only state plus `exit()`. Mount it wherever the
+ *   portal needs to know (the banner, a write button that wants to explain
+ *   itself). The server refuses every write a preview makes regardless.
+ */
+
+const PREVIEW_PARAM = "preview";
+
+/** Codes this page has already tried, so a re-run effect never spends one twice. */
+const attempted = new Set<string>();
+let redeeming = false;
+
+const readCode = (): string | null => {
+  if (typeof window === "undefined") return null;
+  return new URLSearchParams(window.location.search).get(PREVIEW_PARAM);
+};
+
+/** Take the code out of the address bar (and so out of history and any Referer) at once. */
+const stripCode = () => {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has(PREVIEW_PARAM)) return;
+  url.searchParams.delete(PREVIEW_PARAM);
+  window.history.replaceState(window.history.state, "", `${url.pathname}${url.search}${url.hash}`);
+};
+
+/**
+ * True while a preview code is in the URL or being exchanged. An auth guard
+ * checks this AT EFFECT TIME before sending a signed-out visitor to the login
+ * page: the visitor is about to be signed in as the client.
+ */
+export const isPortalPreviewPending = (): boolean => redeeming || readCode() !== null;
+
+export type PortalPreviewRedeemState = { pending: boolean; failed: boolean };
+
+export function usePortalPreviewRedeem(): PortalPreviewRedeemState {
+  const { client, profileId, setToken } = useForge();
+  const { initialize } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const [state, setState] = useState<PortalPreviewRedeemState>({ pending: false, failed: false });
+
+  useEffect(() => {
+    const code = readCode();
+    if (!code) return;
+    stripCode();
+    if (attempted.has(code) || !profileId) return;
+    attempted.add(code);
+    redeeming = true;
+    setState({ pending: true, failed: false });
+
+    client
+      .post("/public/sessions/preview/redeem", { code, profileId })
+      .then(async (res) => {
+        const { token } = res.data as { token: string };
+        // Replace whatever this browser held for the site. The REFRESH token goes
+        // too: left behind, an expired preview would refresh into the previous
+        // identity instead of ending.
+        clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
+        storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token);
+        setToken(token);
+        // Nothing cached for the previous identity may show under the client's name.
+        queryClient.clear();
+        await initialize();
+        redeeming = false;
+        setState({ pending: false, failed: false });
+      })
+      .catch(() => {
+        redeeming = false;
+        setState({ pending: false, failed: true });
+      });
+  }, [client, profileId, setToken, initialize, queryClient]);
+
+  return state;
+}
+
+export type PortalPreview = {
+  /** True while this browser is viewing the portal as a client. */
+  active: boolean;
+  /** The client being previewed. */
+  name: string;
+  /** Who started the preview (the creator or admin). */
+  previewedByName: string;
+  /** ISO time the preview ends. It is never extended. */
+  expiresAt: string | null;
+  /** End the preview, forget the token, and go to the site's home page. */
+  exit: () => Promise<void>;
+};
+
+export function usePortalPreview(): PortalPreview {
+  const { client, setToken } = useForge();
+  const { user } = usePublicAuth();
+  const queryClient = useQueryClient();
+  const preview = user?.preview ?? null;
+
+  const exit = useCallback(async () => {
+    try {
+      await client.post("/public/sessions/preview/end");
+    } catch {
+      // Ending is best effort from here: the session dies at its expiry anyway,
+      // and the token is dropped from this browser below either way.
+    }
+    clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
+    setToken(null);
+    queryClient.clear();
+    if (typeof window !== "undefined") window.location.assign("/");
+  }, [client, setToken, queryClient]);
+
+  const name = [user?.firstName, user?.lastName].filter(Boolean).join(" ").trim() || user?.email || "";
+
+  return {
+    active: !!preview,
+    name,
+    previewedByName: preview?.previewedByName ?? "",
+    expiresAt: preview?.expiresAt ?? null,
+    exit,
+  };
+}