@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/src/plugins/comments/__tests__/client-runtime.browser.test.tsx

@@ -0,0 +1,207 @@
+// @vitest-environment jsdom
+import { QueryClient, dehydrate, hydrate } from "@tanstack/react-query";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { StackProvider } from "@btst/stack/context";
+import { createApiClient } from "../../client";
+import type { CommentsApiRouter } from "../api";
+import { commentsClientPlugin } from "../client";
+import { useComments, useUpdateComment } from "../client/hooks";
+import { createCommentsQueryKeys } from "../query-keys";
+import type { SerializedComment } from "../types";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const comment = {
+	id: "comment-1",
+	resourceId: "post-1",
+	resourceType: "blog-post",
+	parentId: null,
+	authorId: "author-1",
+	resolvedAuthorName: "Alice",
+	resolvedAvatarUrl: null,
+	body: "Runtime comment",
+	status: "approved",
+	likes: 0,
+	isLikedByCurrentUser: false,
+	editedAt: null,
+	createdAt: "2026-01-01T00:00:00.000Z",
+	updatedAt: "2026-01-01T00:00:00.000Z",
+	replyCount: 0,
+} as SerializedComment;
+
+function jsonResponse(value: unknown) {
+	return new Response(JSON.stringify(value), {
+		status: 200,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+async function waitFor(check: () => boolean, timeout = 3000) {
+	const start = Date.now();
+	while (!check()) {
+		if (Date.now() - start > timeout) throw new Error("waitFor timed out");
+		await act(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		});
+	}
+}
+
+describe("Comments browser runtime", () => {
+	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();
+	});
+
+	it("hydrates Comments hooks through the resolved stack cache without refetching", async () => {
+		const params = {
+			resourceId: "post-1",
+			resourceType: "blog-post",
+			status: "approved" as const,
+		};
+		const serverQueryClient = new QueryClient();
+		const queryKeys = createCommentsQueryKeys(
+			createApiClient<CommentsApiRouter>({
+				baseURL: "https://app.example.com",
+				basePath: "/api/data",
+			}),
+		);
+		serverQueryClient.setQueryData(queryKeys.comments.list(params).queryKey, {
+			items: [comment],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+
+		const browserQueryClient = new QueryClient();
+		hydrate(browserQueryClient, dehydrate(serverQueryClient));
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: browserQueryClient,
+			plugins: { comments: commentsClientPlugin() },
+		});
+		const fetchMock = vi.spyOn(globalThis, "fetch");
+
+		function Probe() {
+			const { comments } = useComments(params);
+			return <span>{comments[0]?.body}</span>;
+		}
+
+		await act(async () => {
+			root.render(
+				<StackProvider stack={stack}>
+					<Probe />
+				</StackProvider>,
+			);
+		});
+
+		expect(container.textContent).toBe("Runtime comment");
+		expect(fetchMock).not.toHaveBeenCalled();
+		expect(stack.provider.queryClient).toBe(browserQueryClient);
+	});
+
+	it.each([
+		[
+			"same-origin path",
+			{ api: { basePath: "/api/comments" } },
+			/^https:\/\/app\.example\.com\/api\/comments\/comments/,
+		],
+		[
+			"cross-origin endpoint",
+			{
+				api: {
+					baseURL: "https://discussion.example.net",
+					basePath: "/btst/comments",
+					browserHeaders: { "x-public-client": "public-value" },
+					credentials: "include" as const,
+				},
+			},
+			/^https:\/\/discussion\.example\.net\/btst\/comments\/comments/,
+		],
+	] as const)(
+		"uses the resolved %s for browser queries and mutations",
+		async (_label, endpoint, expectedURL) => {
+			const requests: Array<{
+				url: string;
+				headers: Headers;
+				method: string;
+				credentials?: RequestCredentials;
+			}> = [];
+			vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+				const request = {
+					url: input instanceof Request ? input.url : String(input),
+					headers: new Headers(
+						input instanceof Request ? input.headers : init?.headers,
+					),
+					method:
+						input instanceof Request ? input.method : (init?.method ?? "GET"),
+					credentials:
+						input instanceof Request ? input.credentials : init?.credentials,
+				};
+				requests.push(request);
+				return request.method === "GET"
+					? jsonResponse({ items: [comment], total: 1, limit: 20, offset: 0 })
+					: jsonResponse({ ...comment, body: "Updated comment" });
+			});
+			const stack = createClientStack({
+				api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+				site: { baseURL: "https://app.example.com", basePath: "/pages" },
+				queryClient: new QueryClient(),
+				plugins: { comments: commentsClientPlugin() },
+				endpoints: { comments: endpoint },
+			});
+
+			let query: ReturnType<typeof useComments> | undefined;
+			let update: ReturnType<typeof useUpdateComment> | undefined;
+			function Probe() {
+				query = useComments({
+					resourceId: "post-1",
+					resourceType: "blog-post",
+				});
+				update = useUpdateComment();
+				return null;
+			}
+
+			await act(async () => {
+				root.render(
+					<StackProvider stack={stack}>
+						<Probe />
+					</StackProvider>,
+				);
+			});
+			await waitFor(() => query?.isLoading === false);
+			await act(async () => {
+				await update?.mutateAsync({
+					id: comment.id,
+					body: "Updated comment",
+				});
+			});
+
+			expect(query?.comments).toEqual([comment]);
+			expect(requests.some((request) => request.method === "GET")).toBe(true);
+			expect(requests.some((request) => request.method === "PATCH")).toBe(true);
+			for (const request of requests) {
+				expect(request.url).toMatch(expectedURL);
+				expect(request.headers.get("authorization")).toBeNull();
+				expect(request.headers.get("cookie")).toBeNull();
+				if (_label === "cross-origin endpoint") {
+					expect(request.headers.get("x-public-client")).toBe("public-value");
+					expect(request.credentials).toBe("include");
+				}
+			}
+		},
+	);
+});

package/src/plugins/comments/__tests__/client-runtime.test.ts

@@ -0,0 +1,224 @@
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { commentsClientPlugin, type CommentsClientConfig } from "../client";
+
+function requestDetails(input: RequestInfo | URL, init?: RequestInit) {
+	const request = input instanceof Request ? input : new Request(input, init);
+	return { url: request.url, headers: request.headers };
+}
+
+function jsonResponse(value: unknown, status = 200) {
+	return new Response(JSON.stringify(value), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe("Comments resolved client runtime", () => {
+	it("drives loaders, overridden metadata, inherited headers, and cache from one runtime", async () => {
+		const queryClient = new QueryClient();
+		const requests: Array<{ url: string; headers: Headers }> = [];
+		vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+			requests.push(requestDetails(input, init));
+			return jsonResponse({ items: [], total: 0, limit: 20, offset: 0 });
+		});
+
+		const stack = createClientStack({
+			api: {
+				baseURL: "https://app.example.com",
+				basePath: "/api/data",
+				headers: {
+					authorization: "Bearer server-token",
+					cookie: "session=server",
+					"x-request": "request-value",
+				},
+			},
+			site: { baseURL: "https://www.example.com", basePath: "/pages" },
+			queryClient,
+			plugins: { comments: commentsClientPlugin() },
+			endpoints: {
+				comments: {
+					api: { basePath: "/api/comments" },
+					site: {
+						baseURL: "https://community.example.net",
+						basePath: "/discussion",
+					},
+				},
+			},
+		});
+
+		await stack.router.getRoute("/comments/moderation")?.loader?.();
+
+		const metadata = stack.router.getRoute("/comments/moderation")?.meta?.();
+		expect(metadata).toEqual(
+			expect.arrayContaining([
+				{
+					property: "og:url",
+					content:
+						"https://community.example.net/discussion/comments/moderation",
+				},
+			]),
+		);
+		expect(stack.router.getRoute("/comments")?.meta?.()).toEqual(
+			expect.arrayContaining([
+				{
+					property: "og:url",
+					content: "https://community.example.net/discussion/comments",
+				},
+			]),
+		);
+		expect(stack.provider.queryClient).toBe(queryClient);
+		expect(queryClient.getQueryCache().getAll()).toHaveLength(1);
+		expect(requests).toHaveLength(1);
+		expect(requests[0]?.url).toMatch(
+			/^https:\/\/app\.example\.com\/api\/comments\/comments\?/,
+		);
+		expect(requests[0]?.headers.get("authorization")).toBe(
+			"Bearer server-token",
+		);
+		expect(requests[0]?.headers.get("cookie")).toBe("session=server");
+		expect(requests[0]?.headers.get("x-request")).toBe("request-value");
+	});
+
+	it.each([
+		{
+			label: "an inherited nested site mount",
+			basePath: "/pages",
+			expectedBase: "https://www.example.com/pages",
+		},
+		{
+			label: "an inherited root site mount",
+			basePath: "/",
+			expectedBase: "https://www.example.com",
+		},
+	])(
+		"normalizes metadata for every Comments route with $label",
+		({ basePath, expectedBase }) => {
+			const stack = createClientStack({
+				api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+				site: { baseURL: "https://www.example.com", basePath },
+				queryClient: new QueryClient(),
+				plugins: { comments: commentsClientPlugin() },
+			});
+
+			for (const routePath of ["/comments/moderation", "/comments"] as const) {
+				expect(stack.router.getRoute(routePath)?.meta?.()).toEqual(
+					expect.arrayContaining([
+						{
+							property: "og:url",
+							content: `${expectedBase}${routePath}`,
+						},
+					]),
+				);
+			}
+		},
+	);
+
+	it("isolates sensitive request headers across a Comments origin override", async () => {
+		const requests: Array<{ url: string; headers: Headers }> = [];
+		vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+			requests.push(requestDetails(input, init));
+			return jsonResponse({ items: [], total: 0, limit: 20, offset: 0 });
+		});
+
+		const stack = createClientStack({
+			api: {
+				baseURL: "https://app.example.com",
+				basePath: "/api/data",
+				headers: {
+					authorization: "Bearer server-token",
+					cookie: "session=server",
+					"x-request": "request-value",
+				},
+			},
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { comments: commentsClientPlugin() },
+			endpoints: {
+				comments: {
+					api: {
+						baseURL: "https://discussion.example.net",
+						basePath: "/btst/comments",
+						browserHeaders: { "x-public-client": "public-value" },
+					},
+				},
+			},
+		});
+
+		await stack.router.getRoute("/comments/moderation")?.loader?.();
+
+		expect(requests).toHaveLength(1);
+		expect(requests[0]?.url).toMatch(
+			/^https:\/\/discussion\.example\.net\/btst\/comments\/comments\?/,
+		);
+		expect(requests[0]?.headers.get("authorization")).toBeNull();
+		expect(requests[0]?.headers.get("cookie")).toBeNull();
+		expect(requests[0]?.headers.get("x-request")).toBeNull();
+		expect(requests[0]?.headers.get("x-public-client")).toBe("public-value");
+	});
+
+	it("does not revive removed transport fields from untyped plugin options", async () => {
+		const requests: Headers[] = [];
+		vi.spyOn(globalThis, "fetch").mockImplementation(async (input, init) => {
+			requests.push(requestDetails(input, init).headers);
+			return jsonResponse({ items: [], total: 0, limit: 20, offset: 0 });
+		});
+		const legacyConfig = {
+			headers: {
+				authorization: "Bearer hidden-plugin-token",
+				cookie: "session=hidden-plugin",
+			},
+		} as unknown as CommentsClientConfig;
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { comments: commentsClientPlugin(legacyConfig) },
+			endpoints: {
+				comments: {
+					api: {
+						baseURL: "https://discussion.example.net",
+						basePath: "/btst/comments",
+					},
+				},
+			},
+		});
+
+		await stack.router.getRoute("/comments/moderation")?.loader?.();
+
+		expect(requests).toHaveLength(1);
+		expect(requests[0]?.get("authorization")).toBeNull();
+		expect(requests[0]?.get("cookie")).toBeNull();
+	});
+
+	it("reports each loader failure once and contains reporter failures", async () => {
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			jsonResponse({ message: "comments unavailable" }, 500),
+		);
+		const onErrorLoad = vi.fn((_error: Error, _context: unknown) => {
+			throw new Error("reporter unavailable");
+		});
+		const stack = createClientStack({
+			api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+			site: { baseURL: "https://app.example.com", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { comments: commentsClientPlugin({ hooks: { onErrorLoad } }) },
+		});
+
+		await expect(
+			stack.router.getRoute("/comments/moderation")?.loader?.(),
+		).resolves.toBeUndefined();
+		expect(onErrorLoad).toHaveBeenCalledTimes(1);
+		expect(onErrorLoad.mock.calls[0]?.[1]).toMatchObject({
+			path: "/comments/moderation",
+			isSSR: true,
+			apiBaseURL: "https://app.example.com",
+			apiBasePath: "/api/data",
+		});
+	});
+});

package/src/plugins/comments/__tests__/client-runtime.typecheck.tsx

@@ -0,0 +1,85 @@
+import { QueryClient } from "@tanstack/react-query";
+import { createClientStack } from "../../../client";
+import { StackProvider } from "../../../context";
+import {
+	commentsClientPlugin,
+	type CommentsClientConfig,
+	type CommentsPluginOverrides,
+} from "../client";
+
+const queryClient = new QueryClient();
+const definition = commentsClientPlugin({
+	hooks: { onErrorLoad: () => undefined },
+});
+
+definition.id satisfies "comments";
+
+const stack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: { comments: definition },
+});
+
+<StackProvider stack={stack} />;
+<StackProvider
+	stack={stack}
+	overrides={{ comments: { allowPosting: false, defaultCommentSort: "asc" } }}
+/>;
+
+// @ts-expect-error Comments override values are inferred from registration.
+StackProvider({ stack, overrides: { comments: { allowPosting: "yes" } } });
+
+// @ts-expect-error Unregistered provider override keys are rejected.
+StackProvider({ stack, overrides: { blog: {} } });
+
+createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		// @ts-expect-error The registration key must match the literal Comments ID.
+		discussion: commentsClientPlugin(),
+	},
+});
+
+const pluginOptions: CommentsClientConfig = {};
+void pluginOptions;
+
+commentsClientPlugin({
+	// @ts-expect-error Shared API origins belong to createClientStack().
+	apiBaseURL: "https://api.example.com",
+});
+commentsClientPlugin({
+	// @ts-expect-error Shared API paths belong to createClientStack().
+	apiBasePath: "/api/comments",
+});
+commentsClientPlugin({
+	// @ts-expect-error Shared site origins belong to createClientStack().
+	siteBaseURL: "https://www.example.com",
+});
+commentsClientPlugin({
+	// @ts-expect-error Shared site paths belong to createClientStack().
+	siteBasePath: "/discussion",
+});
+commentsClientPlugin({
+	// @ts-expect-error The query client belongs to createClientStack().
+	queryClient,
+});
+commentsClientPlugin({
+	// @ts-expect-error Request headers belong to createClientStack().api.
+	headers: new Headers(),
+});
+commentsClientPlugin({
+	hooks: {
+		// @ts-expect-error The canonical loader error callback is onErrorLoad.
+		onLoadError: () => undefined,
+	},
+});
+
+const browserOverrides: CommentsPluginOverrides = {
+	allowEditing: false,
+	// @ts-expect-error Transport headers are endpoint configuration, not Comments overrides.
+	headers: { authorization: "secret" },
+};
+void browserOverrides;