@btst/stack 2.4.0 → 2.5.1

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({

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

@@ -4,6 +4,7 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -53,24 +54,24 @@ export interface LoaderContext {
  */
 export interface FormBuilderClientHooks {
 	/**
-	 * Called before loading the form list page. Return false to cancel loading.
+	 * Called before loading the form list page. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadFormList?: (context: LoaderContext) => Promise<boolean> | boolean;
+	beforeLoadFormList?: (context: LoaderContext) => Promise<void> | void;
 	/**
 	 * Called after the form list is loaded.
 	 * @param context - Loader context
 	 */
 	afterLoadFormList?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading the form builder page. Return false to cancel loading.
+	 * Called before loading the form builder page. Throw an error to cancel loading.
 	 * @param id - The form ID (undefined for new forms)
 	 * @param context - Loader context
 	 */
 	beforeLoadFormBuilder?: (
 		id: string | undefined,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the form builder is loaded.
 	 * @param id - The form ID (undefined for new forms)
@@ -81,14 +82,14 @@ export interface FormBuilderClientHooks {
 		context: LoaderContext,
 	) => Promise<void> | void;
 	/**
-	 * Called before loading the submissions page. Return false to cancel loading.
+	 * Called before loading the submissions page. Throw an error to cancel loading.
 	 * @param formId - The form ID
 	 * @param context - Loader context
 	 */
 	beforeLoadSubmissions?: (
 		formId: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
 	 * Called after the submissions page is loaded.
 	 * @param formId - The form ID
@@ -146,10 +147,10 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadFormList) {
-					const canLoad = await hooks.beforeLoadFormList(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadFormList hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadFormList!(context),
+						"Load prevented by beforeLoadFormList hook",
+					);
 				}
 
 				const client = createApiClient<FormBuilderApiRouter>({
@@ -235,10 +236,10 @@ function createFormBuilderLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadFormBuilder) {
-					const canLoad = await hooks.beforeLoadFormBuilder(id, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadFormBuilder hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadFormBuilder!(id, context),
+						"Load prevented by beforeLoadFormBuilder hook",
+					);
 				}
 
 				const client = createApiClient<FormBuilderApiRouter>({
@@ -309,10 +310,10 @@ function createSubmissionsLoader(
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadSubmissions) {
-					const canLoad = await hooks.beforeLoadSubmissions(formId, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadSubmissions hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadSubmissions!(formId, context),
+						"Load prevented by beforeLoadSubmissions hook",
+					);
 				}
 
 				const client = createApiClient<FormBuilderApiRouter>({

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

@@ -167,23 +167,21 @@ export interface FormUpdate {
  * Backend hooks for Form Builder plugin
  *
  * All CRUD hooks receive ipAddress and headers for auth/rate limiting.
- * Return false from onBefore* hooks to reject the operation (throws 403).
+ * Throw an error from onBefore* hooks to reject the operation (throws 403).
  */
 export interface FormBuilderBackendHooks {
 	// ============================================================================
 	// FORM CRUD HOOKS (Admin operations)
 	// ============================================================================
 
-	/** Called before listing forms. Return false to deny access (403). */
-	onBeforeListForms?: (
-		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	/** Called before listing forms. Throw an error to deny access (403). */
+	onBeforeListForms?: (ctx: FormBuilderHookContext) => Promise<void> | void;
 
-	/** Called before creating a form. Return false to deny, or modified data. */
+	/** Called before creating a form. Throw an error to deny, or return modified data. */
 	onBeforeFormCreated?: (
 		data: FormInput,
 		ctx: FormBuilderHookContext,
-	) => Promise<FormInput | false> | FormInput | false;
+	) => Promise<FormInput | void> | FormInput | void;
 
 	/** Called after a form is created */
 	onAfterFormCreated?: (
@@ -191,18 +189,18 @@ export interface FormBuilderBackendHooks {
 		ctx: FormBuilderHookContext,
 	) => Promise<void> | void;
 
-	/** Called before getting a form by ID or slug. Return false to deny access. */
+	/** Called before getting a form by ID or slug. Throw an error to deny access. */
 	onBeforeGetForm?: (
 		idOrSlug: string,
 		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
-	/** Called before updating a form. Return false to deny, or modified data. */
+	/** Called before updating a form. Throw an error to deny, or return modified data. */
 	onBeforeFormUpdated?: (
 		id: string,
 		data: FormUpdate,
 		ctx: FormBuilderHookContext,
-	) => Promise<FormUpdate | false> | FormUpdate | false;
+	) => Promise<FormUpdate | void> | FormUpdate | void;
 
 	/** Called after a form is updated */
 	onAfterFormUpdated?: (
@@ -210,11 +208,11 @@ export interface FormBuilderBackendHooks {
 		ctx: FormBuilderHookContext,
 	) => Promise<void> | void;
 
-	/** Called before deleting a form. Return false to deny. */
+	/** Called before deleting a form. Throw an error to deny. */
 	onBeforeFormDeleted?: (
 		id: string,
 		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/** Called after a form is deleted */
 	onAfterFormDeleted?: (
@@ -230,16 +228,13 @@ export interface FormBuilderBackendHooks {
 	 * Called before processing a form submission.
 	 * Use for: spam protection, rate limiting, data validation/enrichment.
 	 *
-	 * @returns false to reject submission (400), or modified data to continue
+	 * Throw an error to reject submission (400), or return modified data to continue.
 	 */
 	onBeforeSubmission?: (
 		formSlug: string,
 		data: Record<string, unknown>,
 		ctx: SubmissionHookContext,
-	) =>
-		| Promise<Record<string, unknown> | false>
-		| Record<string, unknown>
-		| false;
+	) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
 
 	/**
 	 * Called after a submission is saved.
@@ -263,23 +258,23 @@ export interface FormBuilderBackendHooks {
 	// SUBMISSIONS MANAGEMENT HOOKS (Admin viewing submissions)
 	// ============================================================================
 
-	/** Called before listing submissions. Return false to deny access (403). */
+	/** Called before listing submissions. Throw an error to deny access (403). */
 	onBeforeListSubmissions?: (
 		formId: string,
 		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
-	/** Called before getting a submission. Return false to deny access. */
+	/** Called before getting a submission. Throw an error to deny access. */
 	onBeforeGetSubmission?: (
 		submissionId: string,
 		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
-	/** Called before deleting a submission. Return false to deny. */
+	/** Called before deleting a submission. Throw an error to deny. */
 	onBeforeSubmissionDeleted?: (
 		submissionId: string,
 		ctx: FormBuilderHookContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/** Called after a submission is deleted */
 	onAfterSubmissionDeleted?: (