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

package/src/__tests__/resource-factory.test.tsx

@@ -3,9 +3,11 @@ import { act, Suspense } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createClientStack } from "../client";
 import { StackProvider } from "../context";
 import {
 	createResourceQueryKeys,
+	defineClientPlugin,
 	runResourceMutation,
 	type ResourcesDeclaration,
 	type StackError,
@@ -333,11 +335,21 @@ describe("createResource hooks", () => {
 	}
 
 	async function render(ui: React.ReactElement) {
+		const stack = createClientStack({
+			api: { baseURL: "http://test.local", basePath: "/api/data" },
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				"test-plugin": defineClientPlugin<{ headers?: HeadersInit }>()({
+					id: "test-plugin",
+					resolve: () => ({ routes: () => ({}) }),
+				}),
+			},
+		});
 		await act(async () => {
 			root.render(
 				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					stack={stack}
 					router={{ refresh }}
 					overrides={{
 						"test-plugin": {
@@ -382,6 +394,71 @@ describe("createResource hooks", () => {
 		expect(url).toContain("id=1");
 	});
 
+	it("resolves a resource through its registration-bound provider runtime", async () => {
+		fetchMock.mockResolvedValueOnce(
+			jsonResponse({ items: [{ id: "1", name: "canonical" }] }),
+		);
+		fetchMock.mockResolvedValueOnce(jsonResponse({ id: "2", name: "created" }));
+		let canonicalItems!: typeof items;
+		const stack = createClientStack({
+			api: { baseURL: "http://test.local", basePath: "/api/data" },
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				canonicalProbe: defineClientPlugin({
+					id: "canonicalProbe",
+					resolve: (runtime) => {
+						canonicalItems = createResource({
+							plugin: runtime.id,
+							resources,
+						});
+						return { routes: () => ({}) };
+					},
+				}),
+			},
+			endpoints: {
+				canonicalProbe: {
+					api: {
+						basePath: "/api/canonical",
+						browserHeaders: { "x-canonical": "bound" },
+						credentials: "include",
+					},
+				},
+			},
+		});
+
+		let captured: any;
+		let create: any;
+		function Probe() {
+			captured = canonicalItems.items.detail.use(["1"]);
+			create = canonicalItems.items.create.use();
+			return null;
+		}
+		await act(async () => {
+			root.render(
+				<StackProvider stack={stack} router={{ refresh }}>
+					<Probe />
+				</StackProvider>,
+			);
+		});
+		await waitFor(() => captured.isSuccess);
+		await act(async () => {
+			await create.mutateAsync({ name: "created" });
+		});
+
+		expect(captured.data).toEqual({ id: "1", name: "canonical" });
+		expect(
+			stack.provider.queryClient.getQueryData(["items", "detail", "2"]),
+		).toEqual({ id: "2", name: "created" });
+		const [requestUrl, requestInit] = fetchMock.mock.calls[0] ?? [];
+		const init = requestInit as RequestInit | undefined;
+		expect(String(requestUrl)).toContain(
+			"http://test.local/api/canonical/items",
+		);
+		expect(new Headers(init?.headers).get("x-canonical")).toBe("bound");
+		expect(init?.credentials).toBe("include");
+	});
+
 	it("use() respects the enabled option", async () => {
 		let captured: any;
 		function Probe() {

package/src/__tests__/resource-use-form.test.tsx

@@ -7,6 +7,7 @@ import { StackProvider } from "../context";
 import type { ResourcesDeclaration } from "../plugins/client";
 import { createResource } from "../plugins/client/hooks";
 import type { ResourceFormResult } from "../plugins/client/hooks";
+import { createEmptyTestClientStack } from "./client-stack-test-utils";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -106,8 +107,7 @@ describe("resource useForm", () => {
 		await act(async () => {
 			root.render(
 				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					stack={createEmptyTestClientStack(queryClient)}
 					router={{ navigate, refresh }}
 					notify={{ success: notifySuccess, error: notifyError }}
 				>

package/src/__tests__/resource-use-select.test.tsx

@@ -7,6 +7,7 @@ import { StackProvider } from "../context";
 import type { ResourcesDeclaration } from "../plugins/client";
 import { createResource } from "../plugins/client/hooks";
 import type { ResourceSelectResult } from "../plugins/client/hooks";
+import { createEmptyTestClientStack } from "./client-stack-test-utils";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -97,10 +98,7 @@ describe("resource useSelect", () => {
 		}
 		await act(async () => {
 			root.render(
-				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
-				>
+				<StackProvider stack={createEmptyTestClientStack(queryClient)}>
 					<QueryClientProvider client={queryClient}>
 						<Probe />
 					</QueryClientProvider>

package/src/__tests__/router-overrides.test.tsx

@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { renderToString } from "react-dom/server";
 import type { ComponentType } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { createClientStack } from "../client";
 import { StackProvider, usePluginOverrides, useStack } from "../context";
 import type { StackApiConfig, StackRouterConfig } from "../context";
+import { defineClientPlugin } from "../plugins/client";
 
 function resolveProvider({
 	pluginName,
@@ -12,7 +15,7 @@ function resolveProvider({
 	defaultValues,
 }: {
 	pluginName: string;
-	overrides?: Record<string, any>;
+	overrides?: { blog?: Record<string, any> };
 	router?: StackRouterConfig;
 	api?: StackApiConfig;
 	defaultValues?: Record<string, any>;
@@ -26,14 +29,23 @@ function resolveProvider({
 		};
 		return null;
 	}
+	const stack = createClientStack({
+		api: {
+			baseURL: api?.baseURL ?? "https://example.com",
+			basePath: api?.basePath ?? "/api/data",
+		},
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins: {
+			blog: defineClientPlugin<Record<string, any>>()({
+				id: "blog",
+				resolve: () => ({ routes: () => ({}) }),
+			}),
+		},
+	});
 
 	renderToString(
-		<StackProvider
-			basePath="/pages"
-			overrides={overrides}
-			router={router}
-			api={api}
-		>
+		<StackProvider stack={stack} overrides={overrides} router={router}>
 			<Probe />
 		</StackProvider>,
 	);
@@ -78,7 +90,7 @@ describe("top-level router/api context", () => {
 			navigate,
 			refresh,
 		});
-		expect(resolved.stack.api).toBe(api);
+		expect(resolved.stack.api).toEqual(api);
 		expect(resolved.overrides).toEqual({});
 	});
 

package/src/__tests__/sitemap.test.ts

@@ -1,35 +1,49 @@
 import { describe, it, expect } from "vitest";
-import { createStackClient } from "../client";
+import { createClientStack } from "../client";
 import { defineClientPlugin } from "../plugins/client";
 import { createRoute } from "@btst/yar";
+import { QueryClient } from "@tanstack/react-query";
+
+function createStack(
+	plugins: Parameters<typeof createClientStack>[0]["plugins"],
+) {
+	return createClientStack({
+		api: { baseURL: "https://example.com", basePath: "/api" },
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins,
+	});
+}
 
 describe("Client sitemap generation", () => {
 	it("aggregates sitemaps from multiple plugins and de-duplicates by URL", async () => {
 		const pluginA = defineClientPlugin({
-			name: "a",
-			routes: () => ({
-				a: createRoute("/a", () => ({ PageComponent: () => null })),
+			id: "a",
+			resolve: () => ({
+				routes: () => ({
+					a: createRoute("/a", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: () => [
+					{ url: "https://example.com/a", priority: 0.8 },
+					{ url: "https://example.com/b", changeFrequency: "weekly" },
+				],
 			}),
-			sitemap: () => [
-				{ url: "https://example.com/a", priority: 0.8 },
-				{ url: "https://example.com/b", changeFrequency: "weekly" },
-			],
 		});
 
 		const pluginB = defineClientPlugin({
-			name: "b",
-			routes: () => ({
-				b: createRoute("/b", () => ({ PageComponent: () => null })),
+			id: "b",
+			resolve: () => ({
+				routes: () => ({
+					b: createRoute("/b", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: async () => [
+					{ url: "https://example.com/b", priority: 0.5 }, // duplicate
+					{ url: "https://example.com/c", changeFrequency: "monthly" },
+				],
 			}),
-			sitemap: async () => [
-				{ url: "https://example.com/b", priority: 0.5 }, // duplicate
-				{ url: "https://example.com/c", changeFrequency: "monthly" },
-			],
 		});
 
-		const client = createStackClient({
-			plugins: { a: pluginA, b: pluginB },
-		});
+		const client = createStack({ a: pluginA, b: pluginB });
 
 		const entries = await client.generateSitemap();
 		const urls = entries.map((e) => e.url).sort();
@@ -47,13 +61,15 @@ describe("Client sitemap generation", () => {
 
 	it("returns empty array when no plugins provide a sitemap", async () => {
 		const noop = defineClientPlugin({
-			name: "noop",
-			routes: () => ({
-				home: createRoute("/", () => ({ PageComponent: () => null })),
+			id: "noop",
+			resolve: () => ({
+				routes: () => ({
+					home: createRoute("/", () => ({ PageComponent: () => null })),
+				}),
 			}),
 		});
 
-		const client = createStackClient({ plugins: { noop } });
+		const client = createStack({ noop });
 		const entries = await client.generateSitemap();
 		expect(entries).toEqual([]);
 	});

package/src/__tests__/stack-api.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { stack } from "../api";
+import { createBackendStack } from "../api";
 import { defineBackendPlugin } from "../plugins/api";
 import { createDbPlugin } from "@btst/db";
 import { createMemoryAdapter } from "@btst/adapter-memory";
@@ -11,17 +11,17 @@ const testAdapter = (db: DatabaseDefinition): Adapter =>
 	createMemoryAdapter(db)({});
 
 /**
- * A minimal plugin with no `api` factory, to verify backward compatibility.
+ * A minimal plugin with no `raw` factory.
  */
-const noApiPlugin = defineBackendPlugin({
-	name: "no-api",
-	dbPlugin: createDbPlugin("no-api", {}),
+const noRawPlugin = defineBackendPlugin({
+	id: "noRaw",
+	dbPlugin: createDbPlugin("no-raw", {}),
 	routes: () => ({}),
 });
 
-describe("stack.api surface", () => {
+describe("stack.raw surface", () => {
 	it("exposes adapter on the returned backend", () => {
-		const backend = stack({
+		const backend = createBackendStack({
 			basePath: "/api",
 			plugins: { blog: blogBackendPlugin() },
 			adapter: testAdapter,
@@ -33,44 +33,41 @@ describe("stack.api surface", () => {
 		expect(typeof backend.adapter.create).toBe("function");
 	});
 
-	it("exposes typed api namespace for plugins with api factory", () => {
-		const backend = stack({
+	it("keeps stack.raw narrow for SSG prefetch helpers", () => {
+		const backend = createBackendStack({
 			basePath: "/api",
 			plugins: { blog: blogBackendPlugin() },
 			adapter: testAdapter,
 		});
 
-		expect(backend.api).toBeDefined();
-		expect(backend.api.blog).toBeDefined();
-		expect(typeof backend.api.blog.getAllPosts).toBe("function");
-		expect(typeof backend.api.blog.getPostBySlug).toBe("function");
-		expect(typeof backend.api.blog.getAllTags).toBe("function");
+		expect(backend.raw).toBeDefined();
+		expect(backend.raw.blog).toBeDefined();
+		expect(Object.keys(backend.raw.blog)).toEqual(["prefetchForRoute"]);
 	});
 
-	it("exposes kanban api namespace", () => {
-		const backend = stack({
+	it("exposes the Kanban raw namespace", () => {
+		const backend = createBackendStack({
 			basePath: "/api",
 			plugins: { kanban: kanbanBackendPlugin() },
 			adapter: testAdapter,
 		});
 
-		expect(backend.api.kanban).toBeDefined();
-		expect(typeof backend.api.kanban.getAllBoards).toBe("function");
-		expect(typeof backend.api.kanban.getBoardById).toBe("function");
+		expect(backend.raw.kanban).toBeDefined();
+		expect(Object.keys(backend.raw.kanban)).toEqual(["prefetchForRoute"]);
 	});
 
-	it("plugins without api factory are not present in api", () => {
-		const backend = stack({
+	it("omits plugins without a raw factory", () => {
+		const backend = createBackendStack({
 			basePath: "/api",
-			plugins: { noApi: noApiPlugin },
+			plugins: { noRaw: noRawPlugin },
 			adapter: testAdapter,
 		});
 
-		expect((backend.api as any).noApi).toBeUndefined();
+		expect((backend.raw as any).noRaw).toBeUndefined();
 	});
 
-	it("api functions are bound to the shared adapter and return real data", async () => {
-		const backend = stack({
+	it("uses trusted operations for explicitly trusted business calls", async () => {
+		const backend = createBackendStack({
 			basePath: "/api",
 			plugins: { blog: blogBackendPlugin() },
 			adapter: testAdapter,
@@ -91,19 +88,27 @@ describe("stack.api surface", () => {
 			},
 		});
 
-		// Retrieve via stack.api
-		const posts = await backend.api.blog.getAllPosts();
+		const posts = await backend.trusted.blog.listPosts({});
 		expect(posts.items).toHaveLength(1);
 		expect(posts.items[0]!.slug).toBe("hello-world");
+	});
+
+	it("does not retain ambiguous server aliases", () => {
+		const backend = createBackendStack({
+			basePath: "/api",
+			plugins: { blog: blogBackendPlugin() },
+			adapter: testAdapter,
+		});
+		const request = backend.forRequest(new Request("https://example.test/api"));
 
-		// Verify same adapter - data is shared
-		const bySlug = await backend.api.blog.getPostBySlug("hello-world");
-		expect(bySlug).not.toBeNull();
-		expect(bySlug!.title).toBe("Hello World");
+		expect("api" in backend).toBe(false);
+		expect("internal" in backend).toBe(false);
+		expect("api" in request).toBe(false);
+		expect(Object.keys(request)).toEqual(["operations"]);
 	});
 
 	it("combines multiple plugins in a single stack call", () => {
-		const backend = stack({
+		const backend = createBackendStack({
 			basePath: "/api",
 			plugins: {
 				blog: blogBackendPlugin(),
@@ -112,7 +117,7 @@ describe("stack.api surface", () => {
 			adapter: testAdapter,
 		});
 
-		expect(typeof backend.api.blog.getAllPosts).toBe("function");
-		expect(typeof backend.api.kanban.getAllBoards).toBe("function");
+		expect(typeof backend.raw.blog.prefetchForRoute).toBe("function");
+		expect(typeof backend.raw.kanban.prefetchForRoute).toBe("function");
 	});
 });

package/src/__tests__/stack-auth.test.ts

@@ -1,154 +1,41 @@
-import { createDbPlugin } from "@btst/db";
-import type { DBAdapter as Adapter, DatabaseDefinition } from "@btst/db";
 import { createMemoryAdapter } from "@btst/adapter-memory";
-import { describe, expect, it, vi } from "vitest";
-import { getRequestIdentity, stack } from "../api";
-import { createEndpoint, defineBackendPlugin } from "../plugins/api";
-import type { StackServerAuthProvider } from "../types";
-
-const testAdapter = (db: DatabaseDefinition): Adapter =>
-	createMemoryAdapter(db)({});
-
-/**
- * Minimal plugin whose route reads the request identity the way plugin
- * lifecycle hooks are expected to: via getRequestIdentity(ctx.headers).
- * It calls it twice to verify per-request memoization.
- */
-const whoamiPlugin = defineBackendPlugin({
-	name: "whoami",
-	dbPlugin: createDbPlugin("whoami", {}),
-	routes: () => ({
-		whoami: createEndpoint("/whoami", { method: "GET" }, async (ctx) => {
-			const first = await getRequestIdentity(ctx.headers);
-			const second = await getRequestIdentity(ctx.headers);
-			return { first, second };
-		}),
-	}),
+import { createDbPlugin, type DatabaseDefinition } from "@btst/db";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { createBackendStack } from "../api";
+import {
+	defineAuthorization,
+	definePermissions,
+	permission,
+} from "../authorization";
+import { createServerAuth, type ServerAuth } from "../authorization/server";
+import { defineBackendPlugin } from "../plugins/api";
+
+const testAdapter = (db: DatabaseDefinition) => createMemoryAdapter(db)({});
+const permissions = definePermissions("probe", { read: permission() });
+const authorization = defineAuthorization({
+	identity: z.object({ id: z.string() }),
+	permissions: [permissions] as const,
+	rules: ({ probe }) => [probe.read.allow()],
 });
 
-function makeStack(auth?: StackServerAuthProvider) {
-	return stack({
-		basePath: "/api",
-		plugins: { whoami: whoamiPlugin },
-		adapter: testAdapter,
-		auth,
-	});
-}
-
-async function callWhoami(backend: { handler: (r: Request) => any }) {
-	const res = await backend.handler(
-		new Request("http://localhost/api/whoami", {
-			headers: { "x-user-id": "user-1" },
-		}),
-	);
-	return res.json();
-}
-
-describe("stack() server-side identity resolution", () => {
-	it("resolves identity from the auth provider and memoizes it per request", async () => {
-		const getIdentity = vi.fn(({ headers }: { headers: Headers }) => ({
-			id: headers.get("x-user-id")!,
-		}));
-		const backend = makeStack({ getIdentity });
-
-		const body = await callWhoami(backend);
-
-		expect(body.first).toEqual({ id: "user-1" });
-		expect(body.second).toEqual({ id: "user-1" });
-		// Two getRequestIdentity calls, one provider invocation.
-		expect(getIdentity).toHaveBeenCalledTimes(1);
-	});
-
-	it("resolves identity again for each new request", async () => {
-		const getIdentity = vi.fn(() => ({ id: "user-1" }));
-		const backend = makeStack({ getIdentity });
-
-		await callWhoami(backend);
-		await callWhoami(backend);
-
-		expect(getIdentity).toHaveBeenCalledTimes(2);
-	});
-
-	it("treats getIdentity failures as unauthenticated instead of rejecting", async () => {
-		const consoleError = vi
-			.spyOn(console, "error")
-			.mockImplementation(() => {});
-		const backend = makeStack({
-			getIdentity: () => Promise.reject(new Error("session lookup failed")),
-		});
-
-		const body = await callWhoami(backend);
-
-		expect(body.first).toBeNull();
-		expect(body.second).toBeNull();
-		expect(consoleError).toHaveBeenCalledOnce();
-		consoleError.mockRestore();
-	});
-
-	it("treats synchronously throwing getIdentity as unauthenticated", async () => {
-		const consoleError = vi
-			.spyOn(console, "error")
-			.mockImplementation(() => {});
-		const backend = makeStack({
-			getIdentity: () => {
-				throw new Error("boom");
-			},
+describe("createBackendStack() server authorization boundary", () => {
+	it("exposes only a createServerAuth adapter to plugin composition", () => {
+		const auth = createServerAuth({
+			authorization,
+			getIdentity: () => null,
 		});
-
-		const body = await callWhoami(backend);
-		expect(body.first).toBeNull();
-		consoleError.mockRestore();
-	});
-
-	it("normalizes undefined identities to null", async () => {
-		const backend = makeStack({
-			getIdentity: () => undefined as any,
-		});
-
-		const body = await callWhoami(backend);
-		expect(body.first).toBeNull();
-	});
-
-	it("passes headers and request to getIdentity", async () => {
-		const getIdentity = vi.fn(
-			(_ctx: { headers: Headers; request: Request }) => null,
-		);
-		const backend = makeStack({ getIdentity });
-
-		await callWhoami(backend);
-
-		const ctx = getIdentity.mock.calls[0]![0];
-		expect(ctx.headers.get("x-user-id")).toBe("user-1");
-		expect(ctx.request.url).toBe("http://localhost/api/whoami");
-	});
-
-	it("returns null without an auth provider (handler untouched)", async () => {
-		const backend = makeStack();
-
-		const body = await callWhoami(backend);
-		expect(body.first).toBeNull();
-		expect(body.second).toBeNull();
-	});
-
-	it("returns null for headers outside any handled request", async () => {
-		const identity = await getRequestIdentity(new Headers());
-		expect(identity).toBeNull();
-	});
-
-	it("exposes the auth provider on the plugin StackContext", () => {
-		const auth: StackServerAuthProvider = { getIdentity: () => null };
-		let seenAuth: StackServerAuthProvider | undefined;
-
+		let seenAuth: ServerAuth<typeof authorization> | undefined;
 		const probePlugin = defineBackendPlugin({
-			name: "probe",
+			id: "probe",
 			dbPlugin: createDbPlugin("probe", {}),
 			routes: (_adapter, context) => {
-				seenAuth = context?.auth;
+				seenAuth = context?.auth as ServerAuth<typeof authorization>;
 				return {};
 			},
 		});
 
-		stack({
+		createBackendStack({
 			basePath: "/api",
 			plugins: { probe: probePlugin },
 			adapter: testAdapter,
@@ -157,4 +44,21 @@ describe("stack() server-side identity resolution", () => {
 
 		expect(seenAuth).toBe(auth);
 	});
+
+	it("rejects the removed structural provider shape at runtime", () => {
+		const plugin = defineBackendPlugin({
+			id: "probe",
+			dbPlugin: createDbPlugin("probe", {}),
+			routes: () => ({}),
+		});
+
+		expect(() =>
+			createBackendStack({
+				basePath: "/api",
+				plugins: { probe: plugin },
+				adapter: testAdapter,
+				auth: { getIdentity: () => null } as never,
+			}),
+		).toThrow("requires an adapter created by createServerAuth");
+	});
 });