@btst/stack 2.4.0 → 2.5.0

package/src/plugins/blog/client/plugin.tsx

@@ -2,6 +2,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -91,16 +92,16 @@ export interface BlogClientConfig {
  */
 export interface BlogClientHooks {
 	/**
-	 * Called before loading posts list. Return false to cancel loading.
+	 * Called before loading posts list. Throw an error to cancel loading.
 	 * @param filter - Filter parameters including published status
 	 * @param context - Loader context with path, params, etc.
 	 */
 	beforeLoadPosts?: (
 		filter: { published: boolean },
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called after posts are loaded. Return false to cancel further processing.
+	 * Called after posts are loaded. Throw an error to cancel further processing.
 	 * @param posts - Array of loaded posts or null
 	 * @param filter - Filter parameters used
 	 * @param context - Loader context
@@ -109,18 +110,18 @@ export interface BlogClientHooks {
 		posts: Post[] | null,
 		filter: { published: boolean },
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading a single post. Return false to cancel loading.
+	 * Called before loading a single post. Throw an error to cancel loading.
 	 * @param slug - Post slug being loaded
 	 * @param context - Loader context
 	 */
 	beforeLoadPost?: (
 		slug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called after a post is loaded. Return false to cancel further processing.
+	 * Called after a post is loaded. Throw an error to cancel further processing.
 	 * @param post - Loaded post or null if not found
 	 * @param slug - Post slug that was requested
 	 * @param context - Loader context
@@ -129,17 +130,17 @@ export interface BlogClientHooks {
 		post: Post | null,
 		slug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before loading the new post page. Return false to cancel.
+	 * Called before loading the new post page. Throw an error to cancel.
 	 * @param context - Loader context
 	 */
-	beforeLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadNewPost?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called after the new post page is loaded. Return false to cancel.
+	 * Called after the new post page is loaded. Throw an error to cancel.
 	 * @param context - Loader context
 	 */
-	afterLoadNewPost?: (context: LoaderContext) => Promise<boolean> | boolean;
+	afterLoadNewPost?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called when a loading error occurs
 	 * @param error - The error that occurred
@@ -165,10 +166,10 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPosts) {
-					const canLoad = await hooks.beforeLoadPosts({ published }, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPosts hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPosts!({ published }, context),
+						"Load prevented by beforeLoadPosts hook",
+					);
 				}
 
 				const limit = 10;
@@ -202,14 +203,10 @@ function createPostsLoader(published: boolean, config: BlogClientConfig) {
 				if (hooks?.afterLoadPosts) {
 					const posts =
 						queryClient.getQueryData<Post[]>(listQuery.queryKey) || null;
-					const canContinue = await hooks.afterLoadPosts(
-						posts,
-						{ published },
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadPosts!(posts, { published }, context),
+						"Load prevented by afterLoadPosts hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadPosts hook");
-					}
 				}
 
 				// Check if there was an error after afterLoadPosts hook
@@ -263,10 +260,10 @@ function createPostLoader(
 			try {
 				// Before hook
 				if (hooks?.beforeLoadPost) {
-					const canLoad = await hooks.beforeLoadPost(slug, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadPost!(slug, context),
+						"Load prevented by beforeLoadPost hook",
+					);
 				}
 
 				const client = createApiClient<BlogApiRouter>({
@@ -285,10 +282,10 @@ function createPostLoader(
 				if (hooks?.afterLoadPost) {
 					const post =
 						queryClient.getQueryData<Post>(postQuery.queryKey) || null;
-					const canContinue = await hooks.afterLoadPost(post, slug, context);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.afterLoadPost!(post, slug, context),
+						"Load prevented by afterLoadPost hook",
+					);
 				}
 
 				// Check if there was an error after afterLoadPost hook
@@ -337,18 +334,18 @@ function createNewPostLoader(config: BlogClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadNewPost) {
-					const canLoad = await hooks.beforeLoadNewPost(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadNewPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadNewPost!(context),
+						"Load prevented by beforeLoadNewPost hook",
+					);
 				}
 
 				// After hook
 				if (hooks?.afterLoadNewPost) {
-					const canContinue = await hooks.afterLoadNewPost(context);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadNewPost hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.afterLoadNewPost!(context),
+						"Load prevented by afterLoadNewPost hook",
+					);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR

package/src/plugins/client/index.ts

@@ -18,7 +18,11 @@ export type {
 	PluginOverrides,
 } from "../../types";
 
-export { createApiClient, isConnectionError } from "../utils";
+export {
+	createApiClient,
+	isConnectionError,
+	runClientHookWithShim,
+} from "../utils";
 
 // Re-export Yar types needed for plugins
 export type { Route } from "@btst/yar";

package/src/plugins/cms/api/plugin.ts

@@ -33,6 +33,7 @@ import {
 import { createCMSContentItem } from "./mutations";
 import type { QueryClient } from "@tanstack/react-query";
 import { CMS_QUERY_KEYS } from "./query-key-defs";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Route keys for the CMS plugin — matches the keys returned by
@@ -779,13 +780,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validation.data as Record<string, unknown>;
 					if (config.hooks?.onBeforeCreate) {
-						const result = await config.hooks.onBeforeCreate(
-							processedData,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeCreate!(processedData, context),
+							ctx.error,
+							"Create operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Create operation denied" });
-						}
 					}
 
 					const item = await adapter.create<ContentItem>({
@@ -922,14 +921,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 					// Call before hook - may deny operation
 					const processedData = validatedData;
 					if (config.hooks?.onBeforeUpdate && validatedData) {
-						const result = await config.hooks.onBeforeUpdate(
-							id,
-							validatedData,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeUpdate!(id, validatedData, context),
+							ctx.error,
+							"Update operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Update operation denied" });
-						}
 					}
 
 					// Sync relations to junction table if data was updated
@@ -996,10 +992,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 
 					// Call before hook
 					if (config.hooks?.onBeforeDelete) {
-						const canDelete = await config.hooks.onBeforeDelete(id, context);
-						if (!canDelete) {
-							throw ctx.error(403, { message: "Delete operation denied" });
-						}
+						await runHookWithShim(
+							() => config.hooks!.onBeforeDelete!(id, context),
+							ctx.error,
+							"Delete operation denied",
+						);
 					}
 
 					await adapter.delete({

package/src/plugins/cms/client/plugin.tsx

@@ -3,6 +3,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -52,24 +53,24 @@ export interface LoaderContext {
  */
 export interface CMSClientHooks {
 	/**
-	 * Called before loading the dashboard page. Return false to cancel loading.
+	 * Called before loading the dashboard page. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadDashboard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadDashboard?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called after the dashboard is loaded.
 	 * @param context - Loader context
 	 */
 	afterLoadDashboard?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading a content list page. Return false to cancel loading.
+	 * Called before loading a content list page. Throw an error to cancel loading.
 	 * @param typeSlug - The content type slug
 	 * @param context - Loader context
 	 */
 	beforeLoadContentList?: (
 		typeSlug: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after a content list is loaded.
 	 * @param typeSlug - The content type slug
@@ -80,7 +81,7 @@ export interface CMSClientHooks {
 		context: LoaderContext,
 	) => Promise<void> | void;
 	/**
-	 * Called before loading the content editor page. Return false to cancel loading.
+	 * Called before loading the content editor page. Throw an error to cancel loading.
 	 * @param typeSlug - The content type slug
 	 * @param id - The content item ID (undefined for new items)
 	 * @param context - Loader context
@@ -89,7 +90,7 @@ export interface CMSClientHooks {
 		typeSlug: string,
 		id: string | undefined,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the content editor is loaded.
 	 * @param typeSlug - The content type slug
@@ -149,10 +150,10 @@ function createDashboardLoader(config: CMSClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadDashboard) {
-					const canLoad = await hooks.beforeLoadDashboard(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadDashboard hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadDashboard!(context),
+						"Load prevented by beforeLoadDashboard hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -217,10 +218,10 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadContentList) {
-					const canLoad = await hooks.beforeLoadContentList(typeSlug, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadContentList hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadContentList!(typeSlug, context),
+						"Load prevented by beforeLoadContentList hook",
+					);
 				}
 
 				const client = createApiClient<CMSApiRouter>({
@@ -321,14 +322,10 @@ function createContentEditorLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadContentEditor) {
-					const canLoad = await hooks.beforeLoadContentEditor(
-						typeSlug,
-						id,
-						context,
+					await runClientHookWithShim(
+						() => hooks.beforeLoadContentEditor!(typeSlug, id, context),
+						"Load prevented by beforeLoadContentEditor hook",
 					);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadContentEditor hook");
-					}
 				}
 
 				const client = createApiClient<CMSApiRouter>({

package/src/plugins/cms/types.ts

@@ -248,16 +248,16 @@ export interface CMSHookContext {
 /**
  * Hooks for customizing CMS backend behavior
  *
- * Note: Before hooks can only deny operations by returning `false`.
+ * Note: Before hooks deny operations by throwing an error.
  * They cannot modify the data being saved. This ensures consistency
  * between the stored content item data and relation junction tables.
  */
 export interface CMSBackendHooks {
-	/** Called before creating a content item. Return false to deny the operation. */
+	/** Called before creating a content item. Throw an error to deny the operation. */
 	onBeforeCreate?: (
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) => Promise<false | void> | false | void;
+	) => Promise<void> | void;
 
 	/** Called after creating a content item */
 	onAfterCreate?: (
@@ -265,12 +265,12 @@ export interface CMSBackendHooks {
 		context: CMSHookContext,
 	) => Promise<void> | void;
 
-	/** Called before updating a content item. Return false to deny the operation. */
+	/** Called before updating a content item. Throw an error to deny the operation. */
 	onBeforeUpdate?: (
 		id: string,
 		data: Record<string, unknown>,
 		context: CMSHookContext,
-	) => Promise<false | void> | false | void;
+	) => Promise<void> | void;
 
 	/** Called after updating a content item */
 	onAfterUpdate?: (
@@ -278,11 +278,11 @@ export interface CMSBackendHooks {
 		context: CMSHookContext,
 	) => Promise<void> | void;
 
-	/** Called before deleting a content item */
+	/** Called before deleting a content item. Throw an error to deny the operation. */
 	onBeforeDelete?: (
 		id: string,
 		context: CMSHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/** Called after deleting a content item */
 	onAfterDelete?: (id: string, context: CMSHookContext) => Promise<void> | void;

package/src/plugins/form-builder/api/plugin.ts

@@ -32,6 +32,7 @@ import {
 } from "./getters";
 import { FORM_QUERY_KEYS } from "./query-key-defs";
 import type { QueryClient } from "@tanstack/react-query";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Route keys for the Form Builder plugin — matches the keys returned by
@@ -177,10 +178,11 @@ export const formBuilderBackendPlugin = (
 					const context = createContext(ctx.headers);
 
 					if (config.hooks?.onBeforeListForms) {
-						const canList = await config.hooks.onBeforeListForms(context);
-						if (!canList) {
-							throw ctx.error(403, { message: "Access denied" });
-						}
+						await runHookWithShim(
+							() => config.hooks!.onBeforeListForms!(context),
+							ctx.error,
+							"Access denied",
+						);
 					}
 
 					return getAllForms(adapter, { status, limit, offset });
@@ -199,10 +201,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook for access check
 					if (config.hooks?.onBeforeGetForm) {
-						const canGet = await config.hooks.onBeforeGetForm(slug, context);
-						if (!canGet) {
-							throw ctx.error(403, { message: "Access denied" });
-						}
+						await runHookWithShim(
+							() => config.hooks!.onBeforeGetForm!(slug, context),
+							ctx.error,
+							"Access denied",
+						);
 					}
 
 					const form = await getFormBySlugFromDb(adapter, slug);
@@ -227,10 +230,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook for access check
 					if (config.hooks?.onBeforeGetForm) {
-						const canGet = await config.hooks.onBeforeGetForm(id, context);
-						if (!canGet) {
-							throw ctx.error(403, { message: "Access denied" });
-						}
+						await runHookWithShim(
+							() => config.hooks!.onBeforeGetForm!(id, context),
+							ctx.error,
+							"Access denied",
+						);
 					}
 
 					const form = await adapter.findOne<Form>({
@@ -297,15 +301,13 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook - may modify data or deny operation
 					if (config.hooks?.onBeforeFormCreated) {
-						const result = await config.hooks.onBeforeFormCreated(
-							formInput,
-							context,
+						const hookResult = await runHookWithShim(
+							() => config.hooks!.onBeforeFormCreated!(formInput, context),
+							ctx.error,
+							"Create operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Create operation denied" });
-						}
-						if (result && typeof result === "object") {
-							formInput = result;
+						if (hookResult && typeof hookResult === "object") {
+							formInput = hookResult as typeof formInput;
 						}
 					}
 
@@ -410,16 +412,14 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook - may modify data or deny operation
 					if (config.hooks?.onBeforeFormUpdated) {
-						const result = await config.hooks.onBeforeFormUpdated(
-							id,
-							updateInput,
-							context,
+						const hookResult = await runHookWithShim(
+							() =>
+								config.hooks!.onBeforeFormUpdated!(id, updateInput, context),
+							ctx.error,
+							"Update operation denied",
 						);
-						if (result === false) {
-							throw ctx.error(403, { message: "Update operation denied" });
-						}
-						if (result && typeof result === "object") {
-							updateInput = result;
+						if (hookResult && typeof hookResult === "object") {
+							updateInput = hookResult as typeof updateInput;
 						}
 					}
 
@@ -485,13 +485,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook
 					if (config.hooks?.onBeforeFormDeleted) {
-						const canDelete = await config.hooks.onBeforeFormDeleted(
-							id,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeFormDeleted!(id, context),
+							ctx.error,
+							"Delete operation denied",
 						);
-						if (!canDelete) {
-							throw ctx.error(403, { message: "Delete operation denied" });
-						}
 					}
 
 					// Delete associated submissions first (cascade)
@@ -574,32 +572,40 @@ export const formBuilderBackendPlugin = (
 						throw ctx.error(400, { message: "Invalid form data" });
 					}
 
-					// Call before submission hook - may modify data or deny
+					// Call before submission hook - may modify data or deny.
+					// We call the hook directly (not via runHookWithShim) so that
+					// onSubmissionError receives the original Error, not a wrapped HTTP error.
 					let finalData = data as Record<string, unknown>;
 					if (config.hooks?.onBeforeSubmission) {
+						let hookResult: unknown;
+						let originalError: Error | undefined;
 						try {
-							const result = await config.hooks.onBeforeSubmission(
+							hookResult = await config.hooks.onBeforeSubmission(
 								slug,
 								data as Record<string, unknown>,
 								submissionContext,
 							);
-							if (result === false) {
-								throw ctx.error(400, { message: "Submission rejected" });
-							}
-							if (result && typeof result === "object") {
-								finalData = result;
+							// Backward-compat: explicit false return → denial
+							if (hookResult === false) {
+								originalError = new Error("Submission rejected");
 							}
-						} catch (error) {
-							// Call error hook if submission is rejected
+						} catch (e) {
+							originalError =
+								e instanceof Error ? e : new Error("Submission rejected");
+						}
+						if (originalError) {
 							if (config.hooks?.onSubmissionError) {
 								await config.hooks.onSubmissionError(
-									error as Error,
+									originalError,
 									slug,
 									data as Record<string, unknown>,
 									submissionContext,
 								);
 							}
-							throw error;
+							throw ctx.error(400, { message: originalError.message });
+						}
+						if (hookResult && typeof hookResult === "object") {
+							finalData = hookResult as Record<string, unknown>;
 						}
 					}
 
@@ -662,13 +668,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook for auth check
 					if (config.hooks?.onBeforeListSubmissions) {
-						const canList = await config.hooks.onBeforeListSubmissions(
-							formId,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeListSubmissions!(formId, context),
+							ctx.error,
+							"Access denied",
 						);
-						if (!canList) {
-							throw ctx.error(403, { message: "Access denied" });
-						}
 					}
 
 					return getFormSubmissions(adapter, formId, { limit, offset });
@@ -687,13 +691,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook for access check
 					if (config.hooks?.onBeforeGetSubmission) {
-						const canGet = await config.hooks.onBeforeGetSubmission(
-							subId,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeGetSubmission!(subId, context),
+							ctx.error,
+							"Access denied",
 						);
-						if (!canGet) {
-							throw ctx.error(403, { message: "Access denied" });
-						}
 					}
 
 					const submission = await adapter.findOne<FormSubmissionWithForm>({
@@ -731,13 +733,11 @@ export const formBuilderBackendPlugin = (
 
 					// Call before hook
 					if (config.hooks?.onBeforeSubmissionDeleted) {
-						const canDelete = await config.hooks.onBeforeSubmissionDeleted(
-							subId,
-							context,
+						await runHookWithShim(
+							() => config.hooks!.onBeforeSubmissionDeleted!(subId, context),
+							ctx.error,
+							"Delete operation denied",
 						);
-						if (!canDelete) {
-							throw ctx.error(403, { message: "Delete operation denied" });
-						}
 					}
 
 					await adapter.delete({