@btst/stack 2.4.0 → 2.5.0

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?: (

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

@@ -30,6 +30,7 @@ import {
 	getKanbanColumnsByBoardId,
 } from "./mutations";
 import { KANBAN_QUERY_KEYS } from "./query-key-defs";
+import { runHookWithShim } from "../../utils";
 import { serializeBoard } from "./serializers";
 import type { QueryClient } from "@tanstack/react-query";
 
@@ -101,41 +102,41 @@ export interface KanbanApiContext<
 export interface KanbanBackendHooks {
 	// ============ Board Hooks ============
 	/**
-	 * Called before listing boards. Return false to deny access.
+	 * Called before listing boards. Throw an error to deny access.
 	 */
 	onBeforeListBoards?: (
 		filter: z.infer<typeof BoardListQuerySchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before creating a board. Return false to deny access.
+	 * Called before creating a board. Throw an error to deny access.
 	 */
 	onBeforeCreateBoard?: (
 		data: z.infer<typeof createBoardSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before reading a single board. Return false to deny access.
+	 * Called before reading a single board. Throw an error to deny access.
 	 */
 	onBeforeReadBoard?: (
 		boardId: string,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before updating a board. Return false to deny access.
+	 * Called before updating a board. Throw an error to deny access.
 	 */
 	onBeforeUpdateBoard?: (
 		boardId: string,
 		data: z.infer<typeof updateBoardSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before deleting a board. Return false to deny access.
+	 * Called before deleting a board. Throw an error to deny access.
 	 */
 	onBeforeDeleteBoard?: (
 		boardId: string,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called after boards are listed successfully.
@@ -214,27 +215,27 @@ export interface KanbanBackendHooks {
 
 	// ============ Column Hooks ============
 	/**
-	 * Called before creating a column. Return false to deny access.
+	 * Called before creating a column. Throw an error to deny access.
 	 */
 	onBeforeCreateColumn?: (
 		data: z.infer<typeof createColumnSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before updating a column. Return false to deny access.
+	 * Called before updating a column. Throw an error to deny access.
 	 */
 	onBeforeUpdateColumn?: (
 		columnId: string,
 		data: z.infer<typeof updateColumnSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before deleting a column. Return false to deny access.
+	 * Called before deleting a column. Throw an error to deny access.
 	 */
 	onBeforeDeleteColumn?: (
 		columnId: string,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called after a column is created successfully
@@ -260,27 +261,27 @@ export interface KanbanBackendHooks {
 
 	// ============ Task Hooks ============
 	/**
-	 * Called before creating a task. Return false to deny access.
+	 * Called before creating a task. Throw an error to deny access.
 	 */
 	onBeforeCreateTask?: (
 		data: z.infer<typeof createTaskSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before updating a task. Return false to deny access.
+	 * Called before updating a task. Throw an error to deny access.
 	 */
 	onBeforeUpdateTask?: (
 		taskId: string,
 		data: z.infer<typeof updateTaskSchema>,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before deleting a task. Return false to deny access.
+	 * Called before deleting a task. Throw an error to deny access.
 	 */
 	onBeforeDeleteTask?: (
 		taskId: string,
 		context: KanbanApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called after a task is created successfully
@@ -346,12 +347,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeListBoards) {
-							const canList = await hooks.onBeforeListBoards(query, context);
-							if (!canList) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot list boards",
-								});
-							}
+							await runHookWithShim(
+								() => hooks.onBeforeListBoards!(query, context),
+								ctx.error,
+								"Unauthorized: Cannot list boards",
+							);
 						}
 
 						const result = await getAllBoards(adapter, query);
@@ -381,12 +381,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeReadBoard) {
-							const canRead = await hooks.onBeforeReadBoard(params.id, context);
-							if (!canRead) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot read board",
-								});
-							}
+							await runHookWithShim(
+								() => hooks.onBeforeReadBoard!(params.id, context),
+								ctx.error,
+								"Unauthorized: Cannot read board",
+							);
 						}
 
 						const result = await getBoardById(adapter, params.id);
@@ -423,15 +422,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeCreateBoard) {
-							const canCreate = await hooks.onBeforeCreateBoard(
-								ctx.body,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeCreateBoard!(ctx.body, context),
+								ctx.error,
+								"Unauthorized: Cannot create board",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create board",
-								});
-							}
 						}
 
 						const { ...boardData } = ctx.body;
@@ -516,16 +511,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeUpdateBoard) {
-							const canUpdate = await hooks.onBeforeUpdateBoard(
-								ctx.params.id,
-								{ ...ctx.body, id: ctx.params.id },
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdateBoard!(
+										ctx.params.id,
+										{ ...ctx.body, id: ctx.params.id },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot update board",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update board",
-								});
-							}
 						}
 
 						const { slug: rawSlug, ...restBoardData } = ctx.body;
@@ -595,15 +590,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 						}
 
 						if (hooks?.onBeforeDeleteBoard) {
-							const canDelete = await hooks.onBeforeDeleteBoard(
-								ctx.params.id,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeDeleteBoard!(ctx.params.id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete board",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete board",
-								});
-							}
 						}
 
 						await adapter.delete<Board>({
@@ -641,15 +632,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeCreateColumn) {
-							const canCreate = await hooks.onBeforeCreateColumn(
-								ctx.body,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeCreateColumn!(ctx.body, context),
+								ctx.error,
+								"Unauthorized: Cannot create column",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create column",
-								});
-							}
 						}
 
 						// Get existing columns to determine order
@@ -704,16 +691,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeUpdateColumn) {
-							const canUpdate = await hooks.onBeforeUpdateColumn(
-								ctx.params.id,
-								{ ...ctx.body, id: ctx.params.id },
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdateColumn!(
+										ctx.params.id,
+										{ ...ctx.body, id: ctx.params.id },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot update column",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update column",
-								});
-							}
 						}
 
 						const updated = await adapter.update<Column>({
@@ -765,15 +752,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 						}
 
 						if (hooks?.onBeforeDeleteColumn) {
-							const canDelete = await hooks.onBeforeDeleteColumn(
-								ctx.params.id,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeDeleteColumn!(ctx.params.id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete column",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete column",
-								});
-							}
 						}
 
 						await adapter.delete<Column>({
@@ -810,16 +793,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 						for (let i = 0; i < columnIds.length; i++) {
 							const columnId = columnIds[i];
 							if (!columnId) continue;
-							const canUpdate = await hooks.onBeforeUpdateColumn(
-								columnId,
-								{ id: columnId, order: i },
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdateColumn!(
+										columnId,
+										{ id: columnId, order: i },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot reorder columns",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot reorder columns",
-								});
-							}
 						}
 					}
 
@@ -869,15 +852,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeCreateTask) {
-							const canCreate = await hooks.onBeforeCreateTask(
-								ctx.body,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeCreateTask!(ctx.body, context),
+								ctx.error,
+								"Unauthorized: Cannot create task",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create task",
-								});
-							}
 						}
 
 						// Get existing tasks in column to determine order
@@ -939,16 +918,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeUpdateTask) {
-							const canUpdate = await hooks.onBeforeUpdateTask(
-								ctx.params.id,
-								{ ...ctx.body, id: ctx.params.id },
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdateTask!(
+										ctx.params.id,
+										{ ...ctx.body, id: ctx.params.id },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot update task",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update task",
-								});
-							}
 						}
 
 						const updated = await adapter.update<Task>({
@@ -1000,15 +979,11 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 						}
 
 						if (hooks?.onBeforeDeleteTask) {
-							const canDelete = await hooks.onBeforeDeleteTask(
-								ctx.params.id,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeDeleteTask!(ctx.params.id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete task",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete task",
-								});
-							}
 						}
 
 						await adapter.delete<Task>({
@@ -1052,16 +1027,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 					// Check authorization before moving task
 					if (hooks?.onBeforeUpdateTask) {
-						const canUpdate = await hooks.onBeforeUpdateTask(
-							taskId,
-							{ id: taskId, columnId: targetColumnId, order: targetOrder },
-							context,
+						await runHookWithShim(
+							() =>
+								hooks.onBeforeUpdateTask!(
+									taskId,
+									{ id: taskId, columnId: targetColumnId, order: targetOrder },
+									context,
+								),
+							ctx.error,
+							"Unauthorized: Cannot move task",
 						);
-						if (!canUpdate) {
-							throw ctx.error(403, {
-								message: "Unauthorized: Cannot move task",
-							});
-						}
 					}
 
 					// Update task with new column and order
@@ -1105,16 +1080,16 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 						for (let i = 0; i < taskIds.length; i++) {
 							const taskId = taskIds[i];
 							if (!taskId) continue;
-							const canUpdate = await hooks.onBeforeUpdateTask(
-								taskId,
-								{ id: taskId, order: i },
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdateTask!(
+										taskId,
+										{ id: taskId, order: i },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot reorder tasks",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot reorder tasks",
-								});
-							}
 						}
 					}