@btst/stack 2.12.2 → 3.0.0-rc.2

package/src/__tests__/auth-provider.test.tsx

@@ -0,0 +1,404 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ComposedRoute } from "../client/components";
+import {
+	CanAccess,
+	StackProvider,
+	useCan,
+	useIdentity,
+	type StackAuthProvider,
+} from "../context";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => {
+		root.unmount();
+	});
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+async function render(ui: React.ReactElement) {
+	await act(async () => {
+		root.render(ui);
+	});
+}
+
+function provider(
+	overrides: Partial<StackAuthProvider> = {},
+): StackAuthProvider {
+	return {
+		getIdentity: () => ({ id: "user-1", name: "Test User" }),
+		...overrides,
+	};
+}
+
+function Providers({
+	auth,
+	router,
+	children,
+}: {
+	auth?: StackAuthProvider;
+	router?: { navigate?: (path: string) => void };
+	children: React.ReactNode;
+}) {
+	return (
+		<StackProvider basePath="/pages" auth={auth} router={router}>
+			{children}
+		</StackProvider>
+	);
+}
+
+describe("useIdentity", () => {
+	it("returns null identity and not pending without an auth provider", async () => {
+		let captured: any;
+		function Probe() {
+			captured = useIdentity();
+			return null;
+		}
+		await render(
+			<Providers>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured.identity).toBeNull();
+		expect(captured.isPending).toBe(false);
+	});
+
+	it("resolves identity from the provider", async () => {
+		let captured: any;
+		function Probe() {
+			captured = useIdentity();
+			return null;
+		}
+		await render(
+			<Providers auth={provider()}>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured.identity).toEqual({ id: "user-1", name: "Test User" });
+		expect(captured.isPending).toBe(false);
+	});
+
+	it("resolves to null identity when getIdentity throws", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		let captured: any;
+		function Probe() {
+			captured = useIdentity();
+			return null;
+		}
+		await render(
+			<Providers
+				auth={provider({
+					getIdentity: () => Promise.reject(new Error("boom")),
+				})}
+			>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured.identity).toBeNull();
+		expect(captured.isPending).toBe(false);
+	});
+});
+
+describe("useCan", () => {
+	it("allows everything without an auth provider", async () => {
+		let captured: any;
+		function Probe() {
+			captured = useCan({ resource: "blog:post", action: "delete" });
+			return null;
+		}
+		await render(
+			<Providers>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured).toEqual({ can: true, isPending: false });
+	});
+
+	it("allows everything when the provider has no can()", async () => {
+		let captured: any;
+		function Probe() {
+			captured = useCan({ resource: "blog:post", action: "delete" });
+			return null;
+		}
+		await render(
+			<Providers auth={provider()}>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured).toEqual({ can: true, isPending: false });
+	});
+
+	it("passes the resolved identity and params to can()", async () => {
+		const can = vi.fn().mockResolvedValue(true);
+		let captured: any;
+		function Probe() {
+			captured = useCan({
+				resource: "blog:post",
+				action: "delete",
+				params: { id: "p1" },
+			});
+			return null;
+		}
+		await render(
+			<Providers auth={provider({ can })}>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(can).toHaveBeenCalledWith({
+			resource: "blog:post",
+			action: "delete",
+			params: { id: "p1" },
+			identity: { id: "user-1", name: "Test User" },
+		});
+		expect(captured).toEqual({ can: true, isPending: false });
+	});
+
+	it("denies when can() resolves false", async () => {
+		let captured: any;
+		function Probe() {
+			captured = useCan({ resource: "blog:post", action: "delete" });
+			return null;
+		}
+		await render(
+			<Providers auth={provider({ can: () => false })}>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured).toEqual({ can: false, isPending: false });
+	});
+
+	it("does not return a stale result after the identity changes", async () => {
+		// First identity resolves to an admin whose can() allows; after
+		// refetch() the identity switches to a user whose can() never
+		// resolves — the hook must report pending, never the admin's `true`.
+		let currentUser = { id: "admin" };
+		const neverResolves = new Promise<boolean>(() => {});
+		const auth = provider({
+			getIdentity: () => currentUser,
+			can: ({ identity }) => (identity?.id === "admin" ? true : neverResolves),
+		});
+
+		let capturedCan: any;
+		let capturedIdentity: any;
+		function Probe() {
+			capturedCan = useCan({ resource: "blog:post", action: "delete" });
+			capturedIdentity = useIdentity();
+			return null;
+		}
+		await render(
+			<Providers auth={auth}>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(capturedCan).toEqual({ can: true, isPending: false });
+
+		currentUser = { id: "viewer" };
+		await act(async () => {
+			await capturedIdentity.refetch();
+		});
+
+		expect(capturedIdentity.identity).toEqual({ id: "viewer" });
+		expect(capturedCan).toEqual({ can: false, isPending: true });
+	});
+
+	it("denies when can() throws", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		let captured: any;
+		function Probe() {
+			captured = useCan({ resource: "blog:post", action: "delete" });
+			return null;
+		}
+		await render(
+			<Providers
+				auth={provider({ can: () => Promise.reject(new Error("boom")) })}
+			>
+				<Probe />
+			</Providers>,
+		);
+
+		expect(captured).toEqual({ can: false, isPending: false });
+	});
+});
+
+describe("CanAccess", () => {
+	it("renders children without an auth provider", async () => {
+		await render(
+			<Providers>
+				<CanAccess resource="blog:post" action="delete">
+					<button type="button">Delete</button>
+				</CanAccess>
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("Delete");
+	});
+
+	it("renders children when can() allows", async () => {
+		await render(
+			<Providers auth={provider({ can: () => true })}>
+				<CanAccess resource="blog:post" action="delete">
+					<button type="button">Delete</button>
+				</CanAccess>
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("Delete");
+	});
+
+	it("hides children and renders fallback when can() denies", async () => {
+		await render(
+			<Providers auth={provider({ can: () => false })}>
+				<CanAccess
+					resource="blog:post"
+					action="delete"
+					fallback={<span>No access</span>}
+				>
+					<button type="button">Delete</button>
+				</CanAccess>
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("No access");
+	});
+
+	it("renders nothing by default when denied", async () => {
+		await render(
+			<Providers auth={provider({ can: () => false })}>
+				<CanAccess resource="blog:post" action="delete">
+					<button type="button">Delete</button>
+				</CanAccess>
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("");
+	});
+
+	it("renders the loading node while the check is pending", async () => {
+		// A can() that never resolves keeps the check pending forever.
+		const pending = new Promise<boolean>(() => {});
+		await render(
+			<Providers auth={provider({ can: () => pending })}>
+				<CanAccess
+					resource="blog:post"
+					action="delete"
+					loading={<span>Checking...</span>}
+				>
+					<button type="button">Delete</button>
+				</CanAccess>
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("Checking...");
+	});
+});
+
+describe("SSR parity (no auth provider)", () => {
+	it("renderToString output is unchanged by the auth wiring", () => {
+		const html = renderToString(
+			<StackProvider basePath="/pages">
+				<CanAccess resource="x" action="read">
+					<span>child</span>
+				</CanAccess>
+			</StackProvider>,
+		);
+		expect(html).toContain("child");
+	});
+});
+
+describe("route gating (ComposedRoute permission)", () => {
+	const Page = () => <div>secret page</div>;
+	const Loading = () => <div>loading...</div>;
+	const ErrorUi = () => <div>error page</div>;
+
+	function GatedRoute() {
+		return (
+			<ComposedRoute
+				path="/blog/drafts"
+				PageComponent={Page}
+				LoadingComponent={Loading}
+				ErrorComponent={ErrorUi}
+				onError={() => {}}
+				permission={{ resource: "blog:draft", action: "read" }}
+			/>
+		);
+	}
+
+	it("renders the page unchanged when no auth provider is configured", async () => {
+		await render(
+			<Providers>
+				<GatedRoute />
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("secret page");
+	});
+
+	it("renders the page when can() allows", async () => {
+		await render(
+			<Providers auth={provider({ can: () => true })}>
+				<GatedRoute />
+			</Providers>,
+		);
+
+		expect(container.textContent).toBe("secret page");
+	});
+
+	it("redirects unauthenticated users to loginPath via router.navigate", async () => {
+		const navigate = vi.fn();
+		await render(
+			<Providers
+				auth={provider({
+					getIdentity: () => null,
+					can: () => false,
+					loginPath: "/login",
+				})}
+				router={{ navigate }}
+			>
+				<GatedRoute />
+			</Providers>,
+		);
+
+		expect(navigate).toHaveBeenCalledWith("/login");
+		// The gated page never renders while redirecting.
+		expect(container.textContent).toBe("loading...");
+	});
+
+	it("throws into the route ErrorBoundary when an authenticated user is denied", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		const navigate = vi.fn();
+		await render(
+			<Providers
+				auth={provider({ can: () => false, loginPath: "/login" })}
+				router={{ navigate }}
+			>
+				<GatedRoute />
+			</Providers>,
+		);
+
+		expect(navigate).not.toHaveBeenCalled();
+		expect(container.textContent).toBe("error page");
+	});
+});

package/src/__tests__/blog-query-keys.test.ts

@@ -0,0 +1,86 @@
+/**
+ * SSG guard: the factory-generated blog query keys must stay deep-equal to
+ * the `BLOG_QUERY_KEYS` builders used by `prefetchForRoute` (DB path).
+ * Key drift breaks React Query cache hydration silently during `next build`.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { BLOG_QUERY_KEYS } from "../plugins/blog/api/query-key-defs";
+import { createBlogQueryKeys } from "../plugins/blog/query-keys";
+
+const client = vi.fn() as any;
+
+describe("blog query keys match SSG prefetch keys", () => {
+	const queries = createBlogQueryKeys(client);
+
+	it("posts list keys match for default params", () => {
+		expect([...queries.posts.list({ published: true }).queryKey]).toEqual([
+			...BLOG_QUERY_KEYS.postsList({ published: true }),
+		]);
+	});
+
+	it("posts list keys match for drafts and custom limits", () => {
+		expect([
+			...queries.posts.list({ published: false, limit: 25 }).queryKey,
+		]).toEqual([...BLOG_QUERY_KEYS.postsList({ published: false, limit: 25 })]);
+	});
+
+	it("posts list keys match for tag filtering", () => {
+		expect([
+			...queries.posts.list({ published: true, tagSlug: "news" }).queryKey,
+		]).toEqual([
+			...BLOG_QUERY_KEYS.postsList({ published: true, tagSlug: "news" }),
+		]);
+	});
+
+	it("posts list defaults published to true like the SSR loader", () => {
+		expect([...queries.posts.list().queryKey]).toEqual([
+			...BLOG_QUERY_KEYS.postsList({ published: true }),
+		]);
+	});
+
+	it("normalizes a whitespace-only query the same way", () => {
+		expect([
+			...queries.posts.list({ published: true, query: "  " }).queryKey,
+		]).toEqual([...BLOG_QUERY_KEYS.postsList({ published: true })]);
+	});
+
+	it("post detail keys match", () => {
+		expect([...queries.posts.detail("my-post").queryKey]).toEqual([
+			...BLOG_QUERY_KEYS.postDetail("my-post"),
+		]);
+	});
+
+	it("tags list keys match", () => {
+		expect([...queries.tags.list().queryKey]).toEqual([
+			...BLOG_QUERY_KEYS.tagsList(),
+		]);
+	});
+
+	it("exposes the same _def prefixes as the previous factory", () => {
+		expect([...queries.posts._def]).toEqual(["posts"]);
+		expect([...queries.posts.list._def]).toEqual(["posts", "list"]);
+		expect([...queries.drafts.list._def]).toEqual(["drafts", "list"]);
+	});
+
+	it("drafts list keys keep the legacy limit-only shape", () => {
+		expect([...queries.drafts.list({ limit: 10 }).queryKey]).toEqual([
+			"drafts",
+			"list",
+			{ limit: 10 },
+		]);
+		expect([...queries.drafts.list().queryKey]).toEqual(["drafts", "list", {}]);
+	});
+
+	it("bespoke nextPrevious and recent keys keep their legacy shapes", () => {
+		const date = new Date("2024-01-01T00:00:00.000Z");
+		expect([...queries.posts.nextPrevious(date).queryKey]).toEqual([
+			"posts",
+			"nextPrevious",
+			"nextPrevious",
+			date,
+		]);
+		expect([
+			...queries.posts.recent({ limit: 5, excludeSlug: "a" }).queryKey,
+		]).toEqual(["posts", "recent", "recent", { limit: 5, excludeSlug: "a" }]);
+	});
+});

package/src/__tests__/client-plugin-ssr-loaders.test.ts

@@ -11,10 +11,13 @@ import { formBuilderClientPlugin } from "../plugins/form-builder/client";
 import type { FormBuilderApiRouter } from "../plugins/form-builder/api";
 import { createFormBuilderQueryKeys } from "../plugins/form-builder/query-keys";
 import { uiBuilderClientPlugin } from "../plugins/ui-builder/client";
-import { UI_BUILDER_TYPE_SLUG } from "../plugins/ui-builder";
+import { createUIBuilderQueryKeys } from "../plugins/ui-builder/query-keys";
 import { commentsClientPlugin } from "../plugins/comments/client";
 import type { CommentsApiRouter } from "../plugins/comments/api";
 import { createCommentsQueryKeys } from "../plugins/comments/query-keys";
+import { aiChatClientPlugin } from "../plugins/ai-chat/client";
+import type { AiChatApiRouter } from "../plugins/ai-chat/api";
+import { createAiChatQueryKeys } from "../plugins/ai-chat/query-keys";
 
 const API_BASE_URL = "http://localhost:3000";
 const API_BASE_PATH = "/api/data";
@@ -178,15 +181,10 @@ describe("client plugin SSR loaders", () => {
 			baseURL: API_BASE_URL,
 			basePath: API_BASE_PATH,
 		});
-		const queries = createCMSQueryKeys(client, TEST_HEADERS);
-		const listQuery = queries.cmsContent.list({
-			typeSlug: UI_BUILDER_TYPE_SLUG,
-			limit: 20,
-			offset: 0,
-		});
-		const uiBuilderQueryKey = [...listQuery.queryKey, "ui-builder"] as const;
+		const queries = createUIBuilderQueryKeys(client, TEST_HEADERS);
+		const listQuery = queries.cmsContent.list({ limit: 10, offset: 0 });
 
-		expect(getErrorMessage(queryClient, uiBuilderQueryKey)).toBe(
+		expect(getErrorMessage(queryClient, listQuery.queryKey)).toBe(
 			SSR_LOADER_ERROR_MESSAGE,
 		);
 	});
@@ -326,4 +324,75 @@ describe("client plugin SSR loaders", () => {
 		expect((errorArg as Error).message).toBe(apiErrorMessage);
 		expect(contextArg).toMatchObject({ currentUserId });
 	});
+
+	it("AI Chat list loader seeds a sanitized query error when a hook throws", async () => {
+		const queryClient = new QueryClient();
+		const plugin = aiChatClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadConversations: () => {
+					throw new Error("private loader detail");
+				},
+			},
+		});
+
+		await plugin.routes().chat().loader?.();
+
+		const client = createApiClient<AiChatApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const query = createAiChatQueryKeys(
+			client,
+			TEST_HEADERS,
+		).conversations.list();
+		expect(getErrorMessage(queryClient, query.queryKey)).toBe(
+			SSR_LOADER_ERROR_MESSAGE,
+		);
+	});
+
+	it("AI Chat detail loader seeds sanitized detail and list errors", async () => {
+		const queryClient = new QueryClient();
+		const id = "conv-1";
+		const plugin = aiChatClientPlugin({
+			apiBaseURL: API_BASE_URL,
+			apiBasePath: API_BASE_PATH,
+			siteBaseURL: SITE_BASE_URL,
+			siteBasePath: SITE_BASE_PATH,
+			queryClient,
+			headers: TEST_HEADERS,
+			hooks: {
+				beforeLoadConversation: () => {
+					throw new Error("private conversation detail");
+				},
+			},
+		});
+
+		const routes = plugin.routes();
+		const chatConversation = (
+			routes as unknown as {
+				chatConversation: (args: { params: { id: string } }) => {
+					loader?: () => Promise<void>;
+				};
+			}
+		).chatConversation;
+		await chatConversation({ params: { id } }).loader?.();
+
+		const client = createApiClient<AiChatApiRouter>({
+			baseURL: API_BASE_URL,
+			basePath: API_BASE_PATH,
+		});
+		const queries = createAiChatQueryKeys(client, TEST_HEADERS);
+		expect(
+			getErrorMessage(queryClient, queries.conversations.detail(id).queryKey),
+		).toBe(SSR_LOADER_ERROR_MESSAGE);
+		expect(
+			getErrorMessage(queryClient, queries.conversations.list().queryKey),
+		).toBe(SSR_LOADER_ERROR_MESSAGE);
+	});
 });

package/src/__tests__/cms-query-keys.test.ts

@@ -0,0 +1,62 @@
+/**
+ * SSG guard: the factory-generated CMS query keys must stay deep-equal to
+ * the `CMS_QUERY_KEYS` builders used by `prefetchForRoute` (DB path).
+ * Key drift breaks React Query cache hydration silently during `next build`.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { CMS_QUERY_KEYS } from "../plugins/cms/api/query-key-defs";
+import { createCMSQueryKeys } from "../plugins/cms/query-keys";
+
+const client = vi.fn() as any;
+
+describe("cms query keys match SSG prefetch keys", () => {
+	const queries = createCMSQueryKeys(client);
+
+	it("types list keys match", () => {
+		expect([...queries.cmsTypes.list().queryKey]).toEqual([
+			...CMS_QUERY_KEYS.typesList(),
+		]);
+	});
+
+	it("content list keys match for default params", () => {
+		expect([...queries.cmsContent.list({ typeSlug: "post" }).queryKey]).toEqual(
+			[...CMS_QUERY_KEYS.contentList({ typeSlug: "post" })],
+		);
+	});
+
+	it("content list keys match for custom limits and offsets", () => {
+		expect([
+			...queries.cmsContent.list({ typeSlug: "post", limit: 5, offset: 10 })
+				.queryKey,
+		]).toEqual([
+			...CMS_QUERY_KEYS.contentList({ typeSlug: "post", limit: 5, offset: 10 }),
+		]);
+	});
+
+	it("content list keys match for search terms", () => {
+		expect([
+			...queries.cmsContent.list({ typeSlug: "post", search: "hello" })
+				.queryKey,
+		]).toEqual([
+			...CMS_QUERY_KEYS.contentList({ typeSlug: "post", search: "hello" }),
+		]);
+	});
+
+	it("normalizes a whitespace-only search the same way", () => {
+		expect([
+			...queries.cmsContent.list({ typeSlug: "post", search: "  " }).queryKey,
+		]).toEqual([...CMS_QUERY_KEYS.contentList({ typeSlug: "post" })]);
+	});
+
+	it("content detail keys match", () => {
+		expect([...queries.cmsContent.detail("post", "abc").queryKey]).toEqual([
+			...CMS_QUERY_KEYS.contentDetail("post", "abc"),
+		]);
+	});
+
+	it("exposes the same _def prefixes as the previous factory", () => {
+		expect([...queries.cmsTypes._def]).toEqual(["cmsTypes"]);
+		expect([...queries.cmsTypes.list._def]).toEqual(["cmsTypes", "list"]);
+		expect([...queries.cmsContent.list._def]).toEqual(["cmsContent", "list"]);
+	});
+});