feat: improve ama guest discovery

Author: didinele

apps/website/src/api/routes/guilds.ts

@@ -12,6 +12,7 @@ import type { BotId } from '@chatsift/core';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { apiFetch } from '../fetch';
 import { queryKeys } from '../queryClient';
+import { useGuildAccess } from '@/hooks/useGuildAccess';
 
 export type { GuildChannelInfo, GuildEmojiInfo, GuildRoleInfo } from '@chatsift/api';
 
@@ -29,8 +30,21 @@ type DeleteGrantContract = InferRouteContract<typeof deleteGrantRoute>;
 export type DeleteGrantBody = DeleteGrantContract['body'];
 
 export function useGuildInfo(guildId: string, forBot: BotId) {
+	// `GET /v3/guilds/:guildId` is hard manager-only (`isGuildManager: true` in the API's `isAuthed`) with no
+	// AMA-guest carve-out, and shouldn't have one -- it returns the guild's entire channel/role/emoji list,
+	// well beyond what being a guest on a single session is meant to expose (and the route takes no `amaId` to
+	// scope such a check against anyway). So skip the request outright for a non-manager rather than having
+	// every page that mounts this fire a guaranteed 403: an AMA guest viewing a session detail page hit exactly
+	// that. Gated here rather than at each call site so no future consumer has to remember. Consumers already
+	// cope with a missing result -- they read through `guildInfo?.x ?? []`, and the forms that genuinely need
+	// channels/roles (config editors, create flows) are `canManage`-gated or on manager-only pages regardless.
+	const { canManage } = useGuildAccess(guildId);
+
 	return useQuery({
 		queryKey: queryKeys.guilds.info(guildId, forBot),
+		// A disabled query stays `isPending` but never `isFetching`, so `isLoading` is `false` for a guest --
+		// call sites that disable controls on `isLoading` don't get stuck in a permanent loading state.
+		enabled: canManage,
 		queryFn: async () =>
 			apiFetch<GuildInfo>('get', `/v3/guilds/${guildId}`, {
 				query: { for_bot: forBot, force_fresh: false },

apps/website/src/app/dashboard/[id]/_components/GuildNav.tsx

@@ -47,7 +47,12 @@ export function GuildNav() {
 			const branding = resolveBotBranding(guild, bot);
 			return {
 				label: branding.label,
-				href: `/dashboard/${guild.id}/${bot.toLowerCase()}`,
+				// Skip the AMA hub for a guest -- `NavGateCheck` would only bounce them off it to the sessions
+				// list anyway, and a nav tab that visibly redirects reads as broken.
+				href:
+					isAmaGuestOnly && bot === 'AMA'
+						? `/dashboard/${guild.id}/ama/amas`
+						: `/dashboard/${guild.id}/${bot.toLowerCase()}`,
 				icon: <BotIcon bot={bot} branding={branding} height={16} width={16} />,
 			};
 		});

apps/website/src/app/dashboard/[id]/ama/amas/_components/AMASessionsHeading.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { useParams } from 'next/navigation';
+import { Heading } from '@/components/common/Heading';
+import { useGuildAccess } from '@/hooks/useGuildAccess';
+
+/**
+ * Thin client wrapper around `Heading`, purely so this page's subtitle can match the viewer's access tier.
+ * This is a guest's landing page (see `NavGateCheck`'s guest redirect) and the manager copy -- "create and
+ * manage AMAs in your community" -- describes nothing they can actually do: sessions are filtered server-side
+ * to the ones they're a guest on (`getAMAs.ts`), and every create/edit control is gated on `canManage`.
+ */
+export function AMASessionsHeading() {
+	const params = useParams<{ id: string }>();
+	const { isAmaGuestOnly } = useGuildAccess(params.id);
+
+	return (
+		<Heading
+			subtitle={
+				isAmaGuestOnly
+					? "AMA sessions you've been invited to answer questions in"
+					: 'Create and manage AMAs in your community'
+			}
+			title="AMA sessions"
+		/>
+	);
+}

apps/website/src/app/dashboard/[id]/ama/amas/_components/AMASessionsList.tsx

@@ -9,10 +9,10 @@ import type { SortOption } from './SortMenu';
 import { useSortOption } from './SortMenu';
 import type { AMASessionWithCount } from '@/api/routes/ama';
 import { useAMAs } from '@/api/routes/ama';
-import { useMe } from '@/api/routes/auth';
 import { EmptyState } from '@/components/common/EmptyState';
 import { Skeleton } from '@/components/common/Skeleton';
 import { UserErrorHandler } from '@/components/user/UserErrorHandler';
+import { useGuildAccess } from '@/hooks/useGuildAccess';
 
 function AMASessionSkeleton() {
 	return (
@@ -52,12 +52,10 @@ export function AMASessionsList() {
 	const includeEnded = searchParams.get('include_ended') === 'true';
 
 	const { data: sessions, isLoading, error } = useAMAs(params.id, includeEnded);
-	const { data: me } = useMe();
-	const guild = me?.guilds.find((g) => g.id === params.id);
 	// Creating a session is manager-only -- a guest only ever sees the specific AMA(s) they're scoped to
 	// (already filtered server-side, see `getAMAs.ts`), so there's nothing for a "create" card to do here.
-	const canCreate = Boolean(me?.isGlobalAdmin || guild?.meCanManage);
-	const createCardItem = canCreate ? (
+	const { canManage } = useGuildAccess(params.id);
+	const createCardItem = canManage ? (
 		<li>
 			<CreateAMACard />
 		</li>
@@ -101,8 +99,12 @@ export function AMASessionsList() {
 					{includeEnded ? (
 						<EmptyState
 							icon={<FaComments className="h-8 w-8 text-secondary dark:text-secondary-dark" />}
-							subtitle="Create your first AMA session to get started."
-							title="No AMA sessions yet"
+							subtitle={
+								canManage
+									? 'Create your first AMA session to get started.'
+									: 'Sessions show up here once a server manager adds you as a guest on one.'
+							}
+							title={canManage ? 'No AMA sessions yet' : 'No AMA sessions shared with you'}
 						/>
 					) : (
 						<EmptyState

apps/website/src/app/dashboard/[id]/ama/amas/page.tsx

@@ -1,7 +1,7 @@
+import { AMASessionsHeading } from './_components/AMASessionsHeading';
 import { AMASessionsList } from './_components/AMASessionsList';
 import { IncludeEndedToggle } from './_components/IncludeEndedToggle';
 import { SortMenu } from './_components/SortMenu';
-import { Heading } from '@/components/common/Heading';
 import { SearchBar } from '@/components/common/SearchBar';
 import { DashboardCrumbs } from '@/components/dashboard/DashboardCrumbs';
 
@@ -10,7 +10,7 @@ export default function AMAMangementPage() {
 		<>
 			<div className="flex flex-col [&>*:not(:first-of-type)]:mt-8 [&>*]:first-of-type:mb-4">
 				<DashboardCrumbs />
-				<Heading subtitle="Create and manage AMAs in your community" title="AMA sessions" />
+				<AMASessionsHeading />
 				<SearchBar placeholder="Search AMA sessions...">
 					<SortMenu />
 					<IncludeEndedToggle />

apps/website/src/app/dashboard/_components/GuildCard.tsx

@@ -9,29 +9,48 @@ import { cn } from '@/utils/util';
 
 interface GuildCardProps {
 	readonly data: MeGuild;
+	/**
+	 * True when the viewer's only access to this guild is AMA-guest access -- no `meCanManage`, just an entry
+	 * in some session's `guest_ids` (see `useGuildAccess`'s `isAmaGuestOnly`). The card then advertises only
+	 * AMA (other bots installed here are ones they can't open, and `GuildNav` hides them for the same reason)
+	 * and links straight at the sessions list rather than the manager-only guild root.
+	 */
+	readonly isGuest?: boolean;
 }
 
 const BOT_ICON_SIZE = 28;
 
-export default function GuildCard({ data }: GuildCardProps) {
-	const hasBots = data.bots.length > 0;
-	const url = hasBots ? `/dashboard/${data.id}` : undefined;
+export default function GuildCard({ data, isGuest }: GuildCardProps) {
+	const bots = isGuest ? data.bots.filter((bot) => bot === 'AMA') : data.bots;
+	const hasBots = bots.length > 0;
+	// A guest always has somewhere to go even with no bot icons to show -- their access comes from a session
+	// row, not from the AMA bot still being in this guild's `GuildList`.
+	const isLinked = isGuest || hasBots;
+	// Deliberately not the guild root: that page is the manager-only settings hub, and a guest landing there
+	// only gets bounced onwards by `NavGateCheck` anyway.
+	const url = isGuest ? `/dashboard/${data.id}/ama/amas` : hasBots ? `/dashboard/${data.id}` : undefined;
 
 	return (
 		<div
 			className={cn(
 				'relative flex h-[9.5rem] w-full min-w-0 flex-col gap-3 overflow-hidden rounded-lg border-[1px] border-on-secondary p-3 dark:border-on-secondary-dark',
-				hasBots ? 'bg-card dark:bg-card-dark' : 'group',
+				isLinked ? 'bg-card dark:bg-card-dark' : 'group',
 			)}
 		>
-			<GuildIcon data={data} disableLink={hasBots} hasBots={hasBots} />
+			<GuildIcon data={data} disableLink={isLinked} hasBots={isLinked} />
+
+			{isGuest && (
+				<span className="absolute right-3 top-3 rounded bg-misc-accent/10 px-2 py-1 text-xs font-medium text-misc-accent">
+					Guest
+				</span>
+			)}
 
 			<div className="flex min-w-0 flex-col gap-1">
 				<p className="truncate text-lg font-medium text-primary dark:text-primary-dark">{data.name}</p>
 
-				{hasBots ? (
+				{isLinked ? (
 					<ul className="flex flex-row items-center gap-1">
-						{data.bots.map((bot) => {
+						{bots.map((bot) => {
 							const branding = resolveBotBranding(data, bot);
 							return (
 								<li key={bot}>
@@ -68,7 +87,7 @@ export default function GuildCard({ data }: GuildCardProps) {
 				)}
 			</div>
 
-			{hasBots && url ? (
+			{isLinked && url ? (
 				<Link
 					className="absolute inset-0 rounded-lg focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-misc-accent"
 					href={url}

apps/website/src/app/dashboard/_components/GuildList.tsx

@@ -10,6 +10,7 @@ import { refreshMeMutationKey, useMe } from '@/api/routes/auth';
 import { EmptyState } from '@/components/common/EmptyState';
 import { Skeleton } from '@/components/common/Skeleton';
 import { Tooltip } from '@/components/common/Tooltip';
+import { resolveGuildAccess } from '@/hooks/useGuildAccess';
 import { cn, sortGuilds } from '@/utils/util';
 
 function GuildListSkeleton() {
@@ -31,17 +32,40 @@ export function GuildList() {
 
 	const searchQuery = searchParams.get('search') ?? '';
 
-	const manageable = useMemo(() => me?.guilds.filter((g) => g.meCanManage) ?? [], [me]);
+	// AMA guests belong here too, not just managers: a guest-only guild always has `meCanManage: false` (see
+	// `fetchMe`'s guest-guild synthesis), so filtering on that alone left a guest who manages nothing staring at
+	// the "no servers" empty state below -- with no way to reach the AMA they were invited to answer, even
+	// though every gate under `/dashboard/[id]/ama` already grants them access. Tiers come from the shared
+	// `resolveGuildAccess` rather than a local `meCanManage` read, so this list agrees with what `NavGateCheck`
+	// will actually let the viewer do when they click through (global admins included).
+	const visible = useMemo(
+		() =>
+			(me?.guilds ?? [])
+				.map((guild) => {
+					const { canManage, isAmaGuestOnly } = resolveGuildAccess(me, guild.id);
+					return { guild, canManage, isAmaGuestOnly };
+				})
+				.filter((entry) => entry.canManage || entry.isAmaGuestOnly),
+		[me],
+	);
+	const hasGuestGuilds = useMemo(() => visible.some((entry) => entry.isAmaGuestOnly), [visible]);
 	const sorted = useMemo(() => {
 		const lower = searchQuery.toLowerCase();
 
-		if (!manageable.length) {
+		if (!visible.length) {
 			return [];
 		}
 
-		const filtered = manageable.filter((guild) => guild.name.toLowerCase().includes(lower));
-		return sortGuilds(filtered);
-	}, [manageable, searchQuery]);
+		const filtered = visible.filter((entry) => entry.guild.name.toLowerCase().includes(lower));
+		// Managed servers first, then guest-only ones -- guest access is a much narrower thing (one or two
+		// sessions someone added you to) and shouldn't outrank a server you actually run. `sortGuilds` works on
+		// bare `MeGuild`s, so the tier flags are re-attached by id afterwards.
+		const byId = new Map(filtered.map((entry) => [entry.guild.id, entry]));
+		return [
+			...sortGuilds(filtered.filter((entry) => entry.canManage).map((entry) => entry.guild)),
+			...sortGuilds(filtered.filter((entry) => !entry.canManage).map((entry) => entry.guild)),
+		].map((guild) => ({ guild, isAmaGuestOnly: byId.get(guild.id)!.isAmaGuestOnly }));
+	}, [visible, searchQuery]);
 
 	// `me` is only `undefined` while the query is still in flight — a resolved-but-logged-out `me` never reaches
 	// this component (`NavGateProvider` gates the whole `/dashboard` tree on it), but guarding here too keeps
@@ -50,11 +74,11 @@ export function GuildList() {
 		return <GuildListSkeleton />;
 	}
 
-	if (manageable.length === 0) {
+	if (visible.length === 0) {
 		return (
 			<EmptyState
 				icon={<FaServer className="h-8 w-8 text-secondary dark:text-secondary-dark" />}
-				subtitle="You need Manage Server permissions on a Discord server to configure it here. Just got promoted? Hit Refresh above."
+				subtitle="You need Manage Server permissions on a Discord server to configure it here, or an invite to answer questions in someone's AMA. Just got promoted? Hit Refresh above."
 				title="No servers to manage yet"
 			/>
 		);
@@ -86,15 +110,21 @@ export function GuildList() {
 					</Tooltip>
 				</div>
 			)}
+			{hasGuestGuilds && (
+				<p className="mb-4 text-sm text-secondary dark:text-secondary-dark">
+					Servers marked <span className="font-medium text-primary dark:text-primary-dark">Guest</span> are ones you
+					were invited to answer an AMA in — you&apos;ll only see those sessions there, nothing else.
+				</p>
+			)}
 			<ul
 				className={cn(
 					'grid grid-cols-1 gap-4 transition-opacity md:grid-cols-3 lg:grid-cols-4',
 					isRefreshing && 'opacity-50',
 				)}
 			>
-				{sorted.map((guild) => (
+				{sorted.map(({ guild, isAmaGuestOnly }) => (
 					<li className="min-w-0" key={guild.id}>
-						<GuildCard data={guild} />
+						<GuildCard data={guild} isGuest={isAmaGuestOnly} />
 					</li>
 				))}
 			</ul>

apps/website/src/components/common/NavGate.tsx

@@ -111,7 +111,12 @@ export function NavGateCheck({ children, checkForGlobalAdmin, checkForGuildAcces
 			? resolveGuildAccess(user, params.id)
 			: { canManage: true, isAmaGuestOnly: false };
 	const isGuildRoot = /^\/dashboard\/[^/]+\/?$/.test(pathname ?? '');
-	const isAmaGuestOnlyOnGuildRoot = isAmaGuestOnly && isGuildRoot;
+	// The AMA hub (`/dashboard/[id]/ama`) is the same kind of dead end for a guest: manager-framed
+	// "configure AMA for your server" copy wrapped around a single link to the sessions list, which is the
+	// only thing under it they can open. Folded into the guild-root redirect rather than given its own
+	// guest-aware variant, so a guest only ever sees pages that were written for them.
+	const isAmaHub = /^\/dashboard\/[^/]+\/ama\/?$/.test(pathname ?? '');
+	const isAmaGuestOnlyOnHub = isAmaGuestOnly && (isGuildRoot || isAmaHub);
 
 	useEffect(() => {
 		if (!isAuthenticated) {
@@ -123,12 +128,12 @@ export function NavGateCheck({ children, checkForGlobalAdmin, checkForGuildAcces
 			return;
 		}
 
-		// Centralized here rather than in every page that could be the guild root, so none of them need to
+		// Centralized here rather than in every page that could be a guest dead end, so none of them need to
 		// know guest status exists at all -- they just never render while this is in flight.
-		if (isAmaGuestOnlyOnGuildRoot) {
-			router.replace(`/dashboard/${params.id}/ama`);
+		if (isAmaGuestOnlyOnHub) {
+			router.replace(`/dashboard/${params.id}/ama/amas`);
 		}
-	}, [isAuthenticated, checkForGlobalAdmin, user, router, isAmaGuestOnlyOnGuildRoot, params.id]);
+	}, [isAuthenticated, checkForGlobalAdmin, user, router, isAmaGuestOnlyOnHub, params.id]);
 
 	// Guild access is checked during render (not the effects above) and uses `notFound()` rather than a
 	// redirect: it needs to block the first render of `children` outright, since descendants
@@ -154,9 +159,9 @@ export function NavGateCheck({ children, checkForGlobalAdmin, checkForGuildAcces
 		}
 	}
 
-	// Render nothing on the guild root while the redirect effect above fires, instead of flashing the
-	// manager-only overview page's content at a guest-only viewer for one frame.
-	if (isAmaGuestOnlyOnGuildRoot) {
+	// Render nothing on those pages while the redirect effect above fires, instead of flashing manager-only
+	// content at a guest-only viewer for one frame.
+	if (isAmaGuestOnlyOnHub) {
 		return null;
 	}