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

package/src/plugins/form-builder/client/plugin.tsx

@@ -4,6 +4,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	type ResolvedClientPluginRuntime,
 } from "@btst/stack/plugins/client";
 import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
@@ -11,6 +12,9 @@ import type { QueryClient } from "@tanstack/react-query";
 import { createSanitizedSSRLoaderError } from "../../utils";
 import type { FormBuilderApiRouter } from "../api";
 import { createFormBuilderQueryKeys } from "../query-keys";
+import type { PaginatedFormSubmissions } from "../types";
+import { FORM_BUILDER_PLUGIN_ID } from "./constants";
+import type { FormBuilderPluginOverrides } from "./overrides";
 
 // Lazy load page components for code splitting
 const FormListPageComponent = lazy(() =>
@@ -102,30 +106,18 @@ export interface FormBuilderClientHooks {
 	) => Promise<void> | void;
 	/**
 	 * Called when a loading error occurs.
-	 * Use this for redirects on authorization failures.
+	 * Use this to report loader failures. Router error handling remains authoritative.
 	 * @param error - The error that occurred
 	 * @param context - Loader context
 	 */
-	onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+	onErrorLoad?: (error: Error, context: LoaderContext) => Promise<void> | void;
 }
 
 /**
  * Configuration for Form Builder client plugin
  */
 export interface FormBuilderClientConfig {
-	/** Base URL for API calls (e.g., "http://localhost:3000") */
-	apiBaseURL: string;
-	/** Path where the API is mounted (e.g., "/api/data") */
-	apiBasePath: string;
-	/** Base URL of your site */
-	siteBaseURL: string;
-	/** Path where pages are mounted (e.g., "/pages") */
-	siteBasePath: string;
-	/** React Query client instance for caching */
-	queryClient: QueryClient;
-	/** Optional headers for SSR (e.g., forwarding cookies) */
-	headers?: Headers;
-	/** Optional hooks for customizing behavior (authorization, redirects, etc.) */
+	/** Optional hooks for route loading, redirects, and telemetry. */
 	hooks?: FormBuilderClientHooks;
 
 	/**
@@ -145,10 +137,67 @@ export interface FormBuilderClientConfig {
 	};
 }
 
+interface ResolvedFormBuilderClientConfig extends FormBuilderClientConfig {
+	apiBaseURL: string;
+	apiBasePath: string;
+	siteBaseURL: string;
+	siteBasePath: string;
+	queryClient: QueryClient;
+	headers?: Headers;
+	credentials?: RequestCredentials;
+}
+
+function resolveFormBuilderClientConfig(
+	config: FormBuilderClientConfig,
+	runtime: ResolvedClientPluginRuntime<typeof FORM_BUILDER_PLUGIN_ID>,
+): ResolvedFormBuilderClientConfig {
+	return {
+		hooks: config.hooks,
+		pageComponents: config.pageComponents,
+		apiBaseURL: runtime.api.baseURL,
+		apiBasePath: runtime.api.basePath,
+		siteBaseURL: runtime.site.baseURL,
+		siteBasePath: runtime.site.basePath,
+		queryClient: runtime.queryClient,
+		...(runtime.api.headers ? { headers: runtime.api.headers } : {}),
+		...(runtime.api.credentials
+			? { credentials: runtime.api.credentials }
+			: {}),
+	};
+}
+
+function createFormBuilderApiClient(config: ResolvedFormBuilderClientConfig) {
+	return createApiClient<FormBuilderApiRouter>({
+		baseURL: config.apiBaseURL,
+		basePath: config.apiBasePath,
+		headers: config.headers,
+		credentials: config.credentials,
+	});
+}
+
+function createLoadErrorReporter(
+	hooks: FormBuilderClientHooks | undefined,
+	context: LoaderContext,
+) {
+	let reported = false;
+	return async (error: unknown) => {
+		if (reported || !hooks?.onErrorLoad) return;
+		reported = true;
+		try {
+			await hooks.onErrorLoad(
+				error instanceof Error ? error : new Error(String(error)),
+				context,
+			);
+		} catch {
+			// Reporting hooks cannot make an SSR loader reject or run twice.
+		}
+	};
+}
+
 /**
  * Create form list loader for SSR
  */
-function createFormListLoader(config: FormBuilderClientConfig) {
+function createFormListLoader(config: ResolvedFormBuilderClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
 			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
@@ -160,16 +209,15 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 				apiBasePath,
 				headers,
 			};
-			const client = createApiClient<FormBuilderApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createFormBuilderQueryKeys(client, headers);
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createFormBuilderQueryKeys(
+				createFormBuilderApiClient(config),
+			);
 			const limit = 20;
 			const listQuery = queries.forms.list({ limit });
 
 			try {
-				// Before hook - authorization check
+				// Before-load lifecycle hook
 				if (hooks?.beforeLoadFormList) {
 					await hooks.beforeLoadFormList(context);
 				}
@@ -187,19 +235,15 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 
 				// Check if there was an error
 				const queryState = queryClient.getQueryState(listQuery.queryKey);
-				if (queryState?.error && hooks?.onLoadError) {
-					const error =
-						queryState.error instanceof Error
-							? queryState.error
-							: new Error(String(queryState.error));
-					await hooks.onLoadError(error, context);
+				if (queryState?.error) {
+					await reportError(queryState.error);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -212,9 +256,7 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 						retry: false,
 					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
@@ -225,7 +267,7 @@ function createFormListLoader(config: FormBuilderClientConfig) {
  */
 function createFormBuilderLoader(
 	id: string | undefined,
-	config: FormBuilderClientConfig,
+	config: ResolvedFormBuilderClientConfig,
 ) {
 	return async () => {
 		if (typeof window === "undefined") {
@@ -239,15 +281,14 @@ function createFormBuilderLoader(
 				apiBasePath,
 				headers,
 			};
-			const client = createApiClient<FormBuilderApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createFormBuilderQueryKeys(client, headers);
-			const formQuery = id ? queries.forms.byId(id) : undefined;
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createFormBuilderQueryKeys(
+				createFormBuilderApiClient(config),
+			);
+			const formQuery = id ? queries.forms.forUpdate(id) : undefined;
 
 			try {
-				// Before hook - authorization check
+				// Before-load lifecycle hook
 				if (hooks?.beforeLoadFormBuilder) {
 					await hooks.beforeLoadFormBuilder(id, context);
 				}
@@ -265,12 +306,8 @@ function createFormBuilderLoader(
 				// Check if there was an error
 				if (id) {
 					const queryState = queryClient.getQueryState(formQuery!.queryKey);
-					if (queryState?.error && hooks?.onLoadError) {
-						const error =
-							queryState.error instanceof Error
-								? queryState.error
-								: new Error(String(queryState.error));
-						await hooks.onLoadError(error, context);
+					if (queryState?.error) {
+						await reportError(queryState.error);
 					}
 				}
 			} catch (error) {
@@ -278,7 +315,7 @@ function createFormBuilderLoader(
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else if (formQuery) {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -290,9 +327,7 @@ function createFormBuilderLoader(
 						retry: false,
 					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
@@ -303,7 +338,7 @@ function createFormBuilderLoader(
  */
 function createSubmissionsLoader(
 	formId: string,
-	config: FormBuilderClientConfig,
+	config: ResolvedFormBuilderClientConfig,
 ) {
 	return async () => {
 		if (typeof window === "undefined") {
@@ -317,23 +352,20 @@ function createSubmissionsLoader(
 				apiBasePath,
 				headers,
 			};
-			const client = createApiClient<FormBuilderApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createFormBuilderQueryKeys(client, headers);
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createFormBuilderQueryKeys(
+				createFormBuilderApiClient(config),
+			);
 			const limit = 20;
-			const formQuery = queries.forms.byId(formId);
 			const submissionsQuery = queries.formSubmissions.list({ formId, limit });
 
 			try {
-				// Before hook - authorization check
+				// Before-load lifecycle hook
 				if (hooks?.beforeLoadSubmissions) {
 					await hooks.beforeLoadSubmissions(formId, context);
 				}
 
-				// Prefetch form and submissions
-				await queryClient.prefetchQuery(formQuery);
+				// The submission operation returns the form facts needed by the page.
 				await queryClient.prefetchInfiniteQuery({
 					...submissionsQuery,
 					initialPageParam: 0,
@@ -345,24 +377,19 @@ function createSubmissionsLoader(
 				}
 
 				// Check if there was an error
-				const formState = queryClient.getQueryState(formQuery.queryKey);
 				const submissionsState = queryClient.getQueryState(
 					submissionsQuery.queryKey,
 				);
-				const queryError = formState?.error || submissionsState?.error;
-				if (queryError && hooks?.onLoadError) {
-					const error =
-						queryError instanceof Error
-							? queryError
-							: new Error(String(queryError));
-					await hooks.onLoadError(error, context);
+				const queryError = submissionsState?.error;
+				if (queryError) {
+					await reportError(queryError);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/form-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.formBuilder.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -375,9 +402,7 @@ function createSubmissionsLoader(
 						retry: false,
 					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
@@ -402,21 +427,19 @@ function createFormListMeta() {
  */
 function createFormBuilderMeta(
 	id: string | undefined,
-	config: FormBuilderClientConfig,
+	config: ResolvedFormBuilderClientConfig,
 ) {
 	return () => {
-		const { queryClient, apiBasePath, apiBaseURL } = config;
+		const { queryClient } = config;
 
 		let formName = "";
 		if (id) {
-			const client = createApiClient<FormBuilderApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createFormBuilderQueryKeys(client);
-			const form = queryClient.getQueryData(queries.forms.byId(id).queryKey) as
-				| { name: string }
-				| undefined;
+			const queries = createFormBuilderQueryKeys(
+				createFormBuilderApiClient(config),
+			);
+			const form = queryClient.getQueryData(
+				queries.forms.forUpdate(id).queryKey,
+			) as { name: string } | undefined;
 			formName = form?.name || "";
 		}
 
@@ -435,18 +458,17 @@ function createFormBuilderMeta(
  */
 function createSubmissionsMeta(
 	formId: string,
-	config: FormBuilderClientConfig,
+	config: ResolvedFormBuilderClientConfig,
 ) {
 	return () => {
-		const { queryClient, apiBasePath, apiBaseURL } = config;
-		const client = createApiClient<FormBuilderApiRouter>({
-			baseURL: apiBaseURL,
-			basePath: apiBasePath,
-		});
-		const queries = createFormBuilderQueryKeys(client);
-		const form = queryClient.getQueryData(
-			queries.forms.byId(formId).queryKey,
-		) as { name: string } | undefined;
+		const { queryClient } = config;
+		const queries = createFormBuilderQueryKeys(
+			createFormBuilderApiClient(config),
+		);
+		const data = queryClient.getQueryData(
+			queries.formSubmissions.list({ formId, limit: 20 }).queryKey,
+		) as { pages?: PaginatedFormSubmissions[] } | undefined;
+		const form = data?.pages?.[0]?.form;
 
 		const title = form?.name ? `${form.name} Submissions` : "Submissions";
 
@@ -462,10 +484,10 @@ function createSubmissionsMeta(
  * Form Builder client plugin
  * Provides routes and components for the Form Builder admin interface
  */
-export const formBuilderClientPlugin = (config: FormBuilderClientConfig) =>
-	defineClientPlugin({
-		name: "form-builder",
-
+function createResolvedFormBuilderPlugin(
+	config: ResolvedFormBuilderClientConfig,
+) {
+	return {
 		routes: () =>
 			defineRoutes(
 				{
@@ -504,4 +526,14 @@ export const formBuilderClientPlugin = (config: FormBuilderClientConfig) =>
 			// Form Builder admin pages should NOT be in sitemap
 			return [];
 		},
+	};
+}
+
+export const formBuilderClientPlugin = (config: FormBuilderClientConfig = {}) =>
+	defineClientPlugin<FormBuilderPluginOverrides>()({
+		id: FORM_BUILDER_PLUGIN_ID,
+		resolve: (runtime) =>
+			createResolvedFormBuilderPlugin(
+				resolveFormBuilderClientConfig(config, runtime),
+			),
 	});

package/src/plugins/form-builder/permissions.ts

@@ -0,0 +1,94 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+const formStatusSchema = z.enum(["active", "inactive", "archived"]);
+
+const resolvedFormFacts = {
+	formId: z.string(),
+	ownerId: z.string().optional(),
+	status: formStatusSchema,
+};
+
+/** Browser-safe, schema-backed permissions published by Form Builder. */
+export const formBuilderPermissions = definePermissions("forms", {
+	form: {
+		/** Read the admin collection or one admin record. */
+		read: permission(
+			z.discriminatedUnion("scope", [
+				z.object({ scope: z.literal("collection") }),
+				z.object({
+					scope: z.literal("record"),
+					formId: z.string(),
+					exists: z.boolean(),
+					ownerId: z.string().optional(),
+					status: formStatusSchema.optional(),
+				}),
+			]),
+		),
+		/** Render one public form resolved by slug. */
+		render: permission(
+			z.object({
+				slug: z.string(),
+				exists: z.boolean(),
+				formId: z.string().optional(),
+				ownerId: z.string().optional(),
+				status: formStatusSchema.optional(),
+			}),
+		),
+		/** Create a form. */
+		create: permission(),
+		/** Update a server-resolved form. */
+		update: permission(
+			z.object({
+				...resolvedFormFacts,
+			}),
+		),
+		/** Delete a server-resolved form and its submissions. */
+		delete: permission(
+			z.object({
+				...resolvedFormFacts,
+			}),
+		),
+	},
+	submission: {
+		/** Submit to a public, server-resolved form. */
+		create: permission(
+			z.object({
+				slug: z.string(),
+				exists: z.boolean(),
+				formId: z.string().optional(),
+				ownerId: z.string().optional(),
+				status: formStatusSchema.optional(),
+			}),
+		),
+		/** Read a form's collection or one server-resolved submission. */
+		read: permission(
+			z.discriminatedUnion("scope", [
+				z.object({
+					scope: z.literal("collection"),
+					formId: z.string(),
+					formExists: z.boolean(),
+					ownerId: z.string().optional(),
+				}),
+				z.object({
+					scope: z.literal("record"),
+					formId: z.string(),
+					submissionId: z.string(),
+					exists: z.boolean(),
+					ownerId: z.string().optional(),
+					submittedBy: z.string().optional(),
+				}),
+			]),
+		),
+		/** Delete a server-resolved submission. */
+		delete: permission(
+			z.object({
+				formId: z.string(),
+				submissionId: z.string(),
+				exists: z.boolean(),
+				ownerId: z.string().optional(),
+				submittedBy: z.string().optional(),
+			}),
+		),
+	},
+});

package/src/plugins/form-builder/query-keys.ts

@@ -11,6 +11,7 @@ import type {
 	SerializedFormSubmission,
 	SerializedFormSubmissionWithData,
 } from "./types";
+import type { StackIdentity } from "@btst/stack/context";
 import {
 	formsListDiscriminator,
 	submissionsListDiscriminator,
@@ -133,6 +134,14 @@ export const formBuilderResources = {
 				select: (data: any, _id: string): SerializedForm | null => data ?? null,
 				skip: (id: string) => !id,
 			},
+
+			forUpdate: {
+				path: "/forms/id/:id/edit",
+				params: (id: string) => ({ id }),
+				key: (id: string) => ["forUpdate", id],
+				select: (data: any, _id: string): SerializedForm | null => data ?? null,
+				skip: (id: string) => !id,
+			},
 		},
 
 		mutations: {
@@ -205,14 +214,30 @@ export const formBuilderResources = {
 
 			detail: {
 				path: "/forms/:formId/submissions/:subId",
-				params: (formId: string, subId: string) => ({ formId, subId }),
-				key: (formId: string, subId: string) => [formId, subId],
+				params: (
+					formId: string,
+					subId: string,
+					_identityPartition?: StackIdentity | null,
+				) => ({ formId, subId }),
+				key: (
+					formId: string,
+					subId: string,
+					identityPartition?: StackIdentity | null,
+				) =>
+					identityPartition === undefined
+						? [formId, subId]
+						: [formId, subId, { identity: identityPartition }],
 				select: (
 					data: any,
 					_formId: string,
 					_subId: string,
+					_identityPartition?: StackIdentity | null,
 				): SerializedFormSubmissionWithData | null => data ?? null,
-				skip: (formId: string, subId: string) => !formId || !subId,
+				skip: (
+					formId: string,
+					subId: string,
+					_identityPartition?: StackIdentity | null,
+				) => !formId || !subId,
 			},
 		},
 

package/src/plugins/form-builder/schemas.ts

@@ -111,11 +111,19 @@ export const formSubmissionWithDataResponseSchema =
 		form: formResponseSchema.optional(),
 	});
 
+/** Non-sensitive submission metadata returned by collection reads. */
+export const formSubmissionSummaryResponseSchema = z.object({
+	id: z.string(),
+	formId: z.string(),
+	submittedAt: z.string(),
+	submittedBy: z.string().optional(),
+});
+
 /**
  * Schema for paginated submissions response
  */
 export const paginatedSubmissionsResponseSchema = z.object({
-	items: z.array(formSubmissionWithDataResponseSchema),
+	items: z.array(formSubmissionSummaryResponseSchema),
 	total: z.number(),
 	limit: z.number(),
 	offset: z.number(),