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

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

@@ -2,15 +2,43 @@
  * SSG guard: factory-generated Kanban query keys must stay deep-equal to the
  * builders used by `prefetchForRoute`. Key drift silently breaks hydration.
  */
-import { describe, expect, it, vi } from "vitest";
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
+import { createClientStack } from "../client";
+import {
+	getBoardSummaries,
+	serializeBoardSummary,
+	type SerializedBoardSummary,
+} from "../plugins/kanban/api";
 import { KANBAN_QUERY_KEYS } from "../plugins/kanban/api/query-key-defs";
-import { createKanbanQueryKeys } from "../plugins/kanban/query-keys";
+import { kanbanClientPlugin } from "../plugins/kanban/client/plugin";
+import {
+	type CreateBoardInput,
+	createKanbanQueryKeys,
+} from "../plugins/kanban/query-keys";
+import { createTanStackPageOptions } from "../tanstack";
 
 const client = vi.fn() as any;
 
 describe("kanban query keys match SSG prefetch keys", () => {
 	const queries = createKanbanQueryKeys(client);
 
+	it("derives board create input from the browser-safe runtime schema", () => {
+		expectTypeOf<CreateBoardInput>()
+			.toHaveProperty("slug")
+			.toEqualTypeOf<string | undefined>();
+		expectTypeOf<CreateBoardInput>().not.toHaveProperty("ownerId");
+		expectTypeOf<CreateBoardInput>().not.toHaveProperty("organizationId");
+	});
+
+	it("exports the collection-safe serializer from the public API", () => {
+		expect(getBoardSummaries).toBeTypeOf("function");
+		expect(serializeBoardSummary).toBeTypeOf("function");
+		expectTypeOf<
+			ReturnType<typeof serializeBoardSummary>
+		>().toMatchTypeOf<SerializedBoardSummary>();
+	});
+
 	it("board list keys match for default params", () => {
 		expect([...queries.boards.list().queryKey]).toEqual([
 			...KANBAN_QUERY_KEYS.boardsList(),
@@ -49,3 +77,162 @@ describe("kanban query keys match SSG prefetch keys", () => {
 		]);
 	});
 });
+
+describe("Kanban authenticated SSR hydration", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+		vi.unstubAllGlobals();
+	});
+
+	it("forwards request headers and seeds detail metadata under the hydrated identity key", async () => {
+		const queryClient = new QueryClient();
+		const identity = { id: "owner-1", role: "admin" };
+		const headers = new Headers({ cookie: "session=request-session" });
+		const board = {
+			id: "board-1",
+			name: "Private roadmap",
+			slug: "private-roadmap",
+			description: "",
+			ownerId: identity.id,
+			organizationId: null,
+			createdAt: "2026-01-01T00:00:00.000Z",
+			updatedAt: "2026-01-01T00:00:00.000Z",
+			columns: [],
+		};
+		const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response(JSON.stringify(board), {
+				status: 200,
+				headers: { "content-type": "application/json" },
+			}),
+		);
+		const stack = createClientStack({
+			api: {
+				baseURL: "http://test.local",
+				basePath: "/api/data",
+				headers,
+			},
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				kanban: kanbanClientPlugin({ identityPartition: identity }),
+			},
+		});
+
+		const route = stack.router.getRoute(`/kanban/${board.id}`);
+		await route?.loader?.();
+
+		const queries = createKanbanQueryKeys(client);
+		expect(
+			queryClient.getQueryData(
+				queries.boards.detail(board.id, identity).queryKey,
+			),
+		).toEqual(board);
+		expect(
+			queryClient.getQueryData(queries.boards.detail(board.id).queryKey),
+		).toBeUndefined();
+		expect(route?.meta?.()).toContainEqual({ title: board.name });
+		const [, init] = fetchMock.mock.calls[0] ?? [];
+		expect(new Headers(init?.headers).get("cookie")).toBe(
+			"session=request-session",
+		);
+	});
+
+	it("reads hydrated identity-partitioned metadata during TanStack client navigation", async () => {
+		const queryClient = new QueryClient();
+		const identity = { id: "owner-1", role: "admin" };
+		const board = {
+			id: "board-1",
+			name: "Hydrated private roadmap",
+			slug: "private-roadmap",
+			description: "",
+			ownerId: identity.id,
+			organizationId: null,
+			createdAt: "2026-01-01T00:00:00.000Z",
+			updatedAt: "2026-01-01T00:00:00.000Z",
+			columns: [],
+		};
+		queryClient.setQueryData(
+			createKanbanQueryKeys(client).boards.detail(board.id, identity).queryKey,
+			board,
+		);
+
+		const stackClient = (identityPartition?: typeof identity) =>
+			createClientStack({
+				api: { baseURL: "http://test.local", basePath: "/api/data" },
+				site: { baseURL: "http://test.local", basePath: "/pages" },
+				queryClient,
+				plugins: {
+					kanban: kanbanClientPlugin({ identityPartition }),
+				},
+			});
+		const page = createTanStackPageOptions<{ queryClient: QueryClient }>({
+			getStackClient: () => stackClient(),
+			getLoaderStackClient: () => stackClient(identity),
+		});
+		vi.stubGlobal("window", {});
+
+		const loaderData = await page.loader({
+			params: { _splat: "kanban/board-1" },
+			context: { queryClient },
+		});
+
+		expect(loaderData.meta).toContainEqual({ title: board.name });
+		expect(page.head({ loaderData }).meta).toContainEqual({
+			title: board.name,
+		});
+	});
+});
+
+describe("Kanban anonymous sitemap", () => {
+	afterEach(() => vi.restoreAllMocks());
+
+	function createClient() {
+		return createClientStack({
+			api: { baseURL: "http://test.local", basePath: "/api/data" },
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: {
+				kanban: kanbanClientPlugin(),
+			},
+		});
+	}
+
+	it("omits every route when anonymous collection authorization fails", async () => {
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response(JSON.stringify({ message: "Unauthorized" }), {
+				status: 401,
+				headers: { "content-type": "application/json" },
+			}),
+		);
+
+		await expect(createClient().generateSitemap()).resolves.toEqual([]);
+	});
+
+	it("publishes routes only after an explicit public collection succeeds", async () => {
+		vi.spyOn(globalThis, "fetch").mockResolvedValue(
+			new Response(
+				JSON.stringify({
+					items: [
+						{
+							id: "public-board",
+							updatedAt: "2026-01-01T00:00:00.000Z",
+							columns: [],
+						},
+					],
+					total: 1,
+				}),
+				{
+					status: 200,
+					headers: { "content-type": "application/json" },
+				},
+			),
+		);
+
+		expect(
+			(await createClient().generateSitemap()).map(({ url }) => url),
+		).toEqual([
+			"http://test.local/pages/kanban",
+			"http://test.local/pages/kanban/public-board",
+		]);
+	});
+});

package/src/__tests__/managed-origin-hydration.browser.test.tsx

@@ -0,0 +1,163 @@
+// @vitest-environment jsdom
+import {
+	dehydrate,
+	QueryClient,
+	QueryClientProvider,
+} from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { defineAuthorizationContract } from "../authorization";
+import { createClientStack } from "../client";
+import { StackProvider, useStack } from "../context";
+import { createNextLayout } from "../next/server";
+import { defineClientPlugin, defineRoute } from "../plugins/client";
+import { createReactRouterPage } from "../react-router";
+import { createTanStackPageOptions } from "../tanstack";
+
+const frameworkState = vi.hoisted(() => ({
+	queryClient: undefined as QueryClient | undefined,
+	reactRouterLoaderData: undefined as unknown,
+}));
+
+vi.mock("next/headers", () => ({
+	headers: async () => new Headers(),
+}));
+
+vi.mock("react-router", async (importOriginal) => ({
+	...(await importOriginal<typeof import("react-router")>()),
+	useLoaderData: () => frameworkState.reactRouterLoaderData,
+}));
+
+vi.mock("@tanstack/react-router", async (importOriginal) => ({
+	...(await importOriginal<typeof import("@tanstack/react-router")>()),
+	useParams: () => ({ _splat: "probe" }),
+	useRouteContext: () => ({ queryClient: frameworkState.queryClient }),
+}));
+
+const managedApiOrigin = "https://api.managed.example";
+const siteOrigin = "https://app.example";
+const browserFallbackOrigin = "https://app.example";
+
+function OriginProbe() {
+	return <span data-testid="runtime-origin">{useStack().api?.baseURL}</span>;
+}
+
+function createOriginStack(
+	queryClient: QueryClient,
+	apiOrigin: string,
+	useProviderOrigin: boolean,
+) {
+	const PageComponent = useProviderOrigin
+		? OriginProbe
+		: () => <span data-testid="runtime-origin">{browserFallbackOrigin}</span>;
+	return createClientStack({
+		api: { baseURL: apiOrigin, basePath: "/api/data" },
+		site: { baseURL: siteOrigin, basePath: "/pages" },
+		queryClient,
+		plugins: {
+			probe: defineClientPlugin({
+				id: "probe",
+				resolve: () => ({
+					routes: () => ({
+						probe: defineRoute("/probe", { page: PageComponent }),
+					}),
+				}),
+			}),
+		},
+	});
+}
+
+function renderManagedProvider(
+	queryClient: QueryClient,
+	stack: ReturnType<typeof createOriginStack>,
+	children: ReactNode,
+) {
+	return renderToString(
+		<QueryClientProvider client={queryClient}>
+			<StackProvider stack={stack}>{children}</StackProvider>
+		</QueryClientProvider>,
+	);
+}
+
+describe("managed API origin hydration", () => {
+	it("threads the distinct server origin through the Next client provider", async () => {
+		const queryClient = new QueryClient();
+		const contract = defineAuthorizationContract({
+			identity: z.object({ id: z.string() }),
+			permissions: [] as const,
+		});
+		const layout = createNextLayout({
+			auth: { contract, getIdentityFromHeaders: () => null },
+			resolveClientOrigins: () => ({
+				apiOrigin: managedApiOrigin,
+				siteOrigin,
+			}),
+			ClientLayout: ({ children, clientOrigins }) => {
+				if (!clientOrigins) throw new Error("Expected hydrated client origins");
+				const stack = createOriginStack(
+					queryClient,
+					clientOrigins.apiOrigin,
+					true,
+				);
+				return (
+					<QueryClientProvider client={queryClient}>
+						<StackProvider stack={stack}>
+							<OriginProbe />
+							{children}
+						</StackProvider>
+					</QueryClientProvider>
+				);
+			},
+		});
+
+		const html = renderToString(await layout.Layout({}));
+
+		expect(html).toContain(managedApiOrigin);
+		expect(html).not.toContain(`>${browserFallbackOrigin}<`);
+	});
+
+	it.each(["React Router", "TanStack Start"])(
+		"keeps the provider stack during %s hydration and navigation renders",
+		(framework) => {
+			const queryClient = new QueryClient();
+			frameworkState.queryClient = queryClient;
+			frameworkState.reactRouterLoaderData = {
+				path: "/probe",
+				dehydratedState: dehydrate(queryClient),
+			};
+			const providerStack = createOriginStack(
+				queryClient,
+				managedApiOrigin,
+				true,
+			);
+			const browserFallbackStack = createOriginStack(
+				queryClient,
+				browserFallbackOrigin,
+				false,
+			);
+			const getBrowserFallbackStack = vi.fn(() => browserFallbackStack);
+			const Component =
+				framework === "React Router"
+					? createReactRouterPage({
+							getStackClient: getBrowserFallbackStack,
+							getQueryClient: () => queryClient,
+						}).Component
+					: createTanStackPageOptions({
+							getStackClient: getBrowserFallbackStack,
+							getQueryClient: () => queryClient,
+						}).component;
+
+			const html = renderManagedProvider(
+				queryClient,
+				providerStack,
+				<Component />,
+			);
+
+			expect(html).toContain(managedApiOrigin);
+			expect(html).not.toContain(browserFallbackOrigin);
+			expect(getBrowserFallbackStack).not.toHaveBeenCalled();
+		},
+	);
+});

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

@@ -13,49 +13,105 @@ import {
 } from "../plugins/media/query-keys";
 import { ROOT_FOLDER_QUERY_VALUE } from "../plugins/media/schemas";
 
+const ENDPOINT = {
+	baseURL: "https://media.example.com",
+	basePath: "/api/data",
+};
+
 describe("media resource query keys", () => {
 	it("matches the shared asset-list builder and normalizes search", () => {
 		const client = vi.fn() as any;
 		const queries = createMediaQueryKeys(client);
 		const params = { folderId: "photos", query: "  beach  ", limit: 40 };
 
-		expect([...queries.mediaAssets.list(params).queryKey]).toEqual([
-			...MEDIA_QUERY_KEYS.assetsList(params),
-		]);
+		expect([
+			...queries.mediaAssets.list(params, undefined, ENDPOINT).queryKey,
+		]).toEqual([...MEDIA_QUERY_KEYS.assetsList(params, undefined, ENDPOINT)]);
 		expect(assetListDiscriminator(params).query).toBe("beach");
 	});
 
+	it("aligns SSR/browser keys for the hydrated identity", () => {
+		const client = vi.fn() as any;
+		const queries = createMediaQueryKeys(client);
+		const identity = { id: "member-a", role: "member" };
+		const params = { limit: 40 };
+
+		expect(
+			queries.mediaAssets.list(params, identity, ENDPOINT).queryKey,
+		).toEqual(MEDIA_QUERY_KEYS.assetsList(params, identity, ENDPOINT));
+		expect(
+			queries.mediaFolders.list(null, identity, ENDPOINT).queryKey,
+		).toEqual(MEDIA_QUERY_KEYS.foldersList(null, identity, ENDPOINT));
+	});
+
+	it("partitions asset and folder lists by Media origin and mount path", () => {
+		const client = vi.fn() as any;
+		const queries = createMediaQueryKeys(client);
+		const otherOrigin = { ...ENDPOINT, baseURL: "https://other.example.com" };
+		const otherPath = { ...ENDPOINT, basePath: "/media-api" };
+
+		for (const endpoint of [otherOrigin, otherPath]) {
+			expect(
+				queries.mediaAssets.list({}, undefined, ENDPOINT).queryKey,
+			).not.toEqual(queries.mediaAssets.list({}, undefined, endpoint).queryKey);
+			expect(
+				queries.mediaFolders.list(undefined, undefined, ENDPOINT).queryKey,
+			).not.toEqual(
+				queries.mediaFolders.list(undefined, undefined, endpoint).queryKey,
+			);
+		}
+		expect(
+			JSON.stringify(
+				queries.mediaAssets.list({}, undefined, ENDPOINT).queryKey,
+			),
+		).toBe(
+			JSON.stringify(MEDIA_QUERY_KEYS.assetsList({}, undefined, ENDPOINT)),
+		);
+		const noisyEndpoint = {
+			...ENDPOINT,
+			headers: { authorization: "Bearer server-secret" },
+			credentials: "include",
+		};
+		const serializedKey = JSON.stringify(
+			MEDIA_QUERY_KEYS.assetsList({}, undefined, noisyEndpoint),
+		);
+		expect(serializedKey).not.toContain("server-secret");
+		expect(serializedKey).not.toContain("credentials");
+	});
+
 	it("uses distinct keys for all folders, root folders, and a parent", () => {
 		const client = vi.fn() as any;
 		const queries = createMediaQueryKeys(client);
 
-		expect([...queries.mediaFolders.list(undefined).queryKey]).toEqual([
-			...MEDIA_QUERY_KEYS.foldersList(undefined),
-		]);
-		expect([...queries.mediaFolders.list(null).queryKey]).toEqual([
-			...MEDIA_QUERY_KEYS.foldersList(null),
+		expect([
+			...queries.mediaFolders.list(undefined, undefined, ENDPOINT).queryKey,
+		]).toEqual([
+			...MEDIA_QUERY_KEYS.foldersList(undefined, undefined, ENDPOINT),
 		]);
-		expect(queries.mediaFolders.list(undefined).queryKey).not.toEqual(
-			queries.mediaFolders.list(null).queryKey,
+		expect([
+			...queries.mediaFolders.list(null, undefined, ENDPOINT).queryKey,
+		]).toEqual([...MEDIA_QUERY_KEYS.foldersList(null, undefined, ENDPOINT)]);
+		expect(
+			queries.mediaFolders.list(undefined, undefined, ENDPOINT).queryKey,
+		).not.toEqual(
+			queries.mediaFolders.list(null, undefined, ENDPOINT).queryKey,
 		);
-		expect([...queries.mediaFolders.list("parent-1").queryKey]).toEqual([
-			"mediaFolders",
-			"list",
-			"parent-1",
-		]);
+		expect([
+			...queries.mediaFolders.list("parent-1", undefined, ENDPOINT).queryKey,
+		]).toEqual(MEDIA_QUERY_KEYS.foldersList("parent-1", undefined, ENDPOINT));
 	});
 
 	it("sends the root sentinel only for an explicit null parent", async () => {
 		const client = vi.fn().mockResolvedValue({ data: [] }) as any;
 		const queries = createMediaQueryKeys(client);
 
-		await queries.mediaFolders.list(undefined).queryFn();
+		await queries.mediaFolders.list(undefined, undefined, ENDPOINT).queryFn();
 		expect(client).toHaveBeenLastCalledWith(
 			"/media/folders",
 			expect.objectContaining({ query: {} }),
 		);
 
-		await queries.mediaFolders.list(null).queryFn();
+		await queries.mediaFolders.list(null, undefined, ENDPOINT).queryFn();
 		expect(client).toHaveBeenLastCalledWith(
 			"/media/folders",
 			expect.objectContaining({
@@ -64,6 +120,24 @@ describe("media resource query keys", () => {
 		);
 	});
 
+	it("normalizes relative asset URLs in the server-safe query pipeline", async () => {
+		const client = vi.fn().mockResolvedValue({
+			data: {
+				items: [{ url: "/uploads/asset.jpg" }],
+				total: 1,
+			},
+		}) as any;
+		const queries = createMediaQueryKeys(client);
+
+		const result = await queries.mediaAssets
+			.list({}, undefined, ENDPOINT)
+			.queryFn();
+
+		expect(result.items[0]?.url).toBe(
+			"https://media.example.com/uploads/asset.jpg",
+		);
+	});
+
 	it("stops infinite pagination after all rows are loaded", () => {
 		const nextPageParam = mediaResources.mediaAssets.queries.list.nextPageParam;
 		const first = { items: new Array(20), total: 25 };

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

@@ -3,6 +3,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { StackProvider, useNotify, type StackNotifyProvider } from "../context";
+import { createEmptyTestClientStack } from "./client-stack-test-utils";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -55,7 +56,7 @@ describe("useNotify", () => {
 			return null;
 		}
 		await render(
-			<StackProvider basePath="/pages">
+			<StackProvider stack={createEmptyTestClientStack()}>
 				<Probe />
 			</StackProvider>,
 		);
@@ -81,7 +82,7 @@ describe("useNotify", () => {
 
 		await render(
 			<StackProvider
-				basePath="/pages"
+				stack={createEmptyTestClientStack()}
 				notify={{ success: customSuccess, error: customError }}
 			>
 				<Probe />