@btst/stack 2.3.0 → 2.5.0

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

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

@@ -6,5 +6,11 @@ export {
 	type KanbanBackendHooks,
 } from "./plugin";
 export { getAllBoards, getBoardById, type BoardListResult } from "./getters";
+export {
+	createKanbanTask,
+	findOrCreateKanbanBoard,
+	getKanbanColumnsByBoardId,
+	type CreateKanbanTaskInput,
+} from "./mutations";
 export { serializeBoard, serializeColumn, serializeTask } from "./serializers";
 export { KANBAN_QUERY_KEYS } from "./query-key-defs";

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

@@ -0,0 +1,169 @@
+import type { Adapter } from "@btst/db";
+import type { Board, Column, Task, Priority } from "../types";
+
+/**
+ * Input for creating a new Kanban task.
+ */
+export interface CreateKanbanTaskInput {
+	title: string;
+	columnId: string;
+	description?: string;
+	priority?: Priority;
+	assigneeId?: string;
+}
+
+/**
+ * Create a new task in a Kanban column.
+ * Computes the next order value from existing tasks in the column.
+ *
+ * @remarks **Security:** No authorization hooks (onBeforeCreateTask) are called.
+ * The caller is responsible for any access-control checks before invoking this
+ * function.
+ *
+ * @param adapter - The database adapter
+ * @param input - Task creation input
+ */
+export async function createKanbanTask(
+	adapter: Adapter,
+	input: CreateKanbanTaskInput,
+): Promise<Task> {
+	const existingTasks = await adapter.findMany<Task>({
+		model: "kanbanTask",
+		where: [
+			{
+				field: "columnId",
+				value: input.columnId,
+				operator: "eq" as const,
+			},
+		],
+	});
+
+	const nextOrder =
+		existingTasks.length > 0
+			? Math.max(...existingTasks.map((t) => t.order)) + 1
+			: 0;
+
+	return adapter.create<Task>({
+		model: "kanbanTask",
+		data: {
+			title: input.title,
+			columnId: input.columnId,
+			description: input.description,
+			priority: input.priority ?? "MEDIUM",
+			order: nextOrder,
+			assigneeId: input.assigneeId,
+			isArchived: false,
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+/**
+ * Coalesces concurrent `findOrCreateKanbanBoard` calls within the same process.
+ * Keyed by slug; entries are removed once the creation promise settles.
+ */
+const _pendingBoardCreations = new Map<string, Promise<Board>>();
+
+/**
+ * Find a board by slug, or create it with the given name and custom column titles.
+ *
+ * Concurrency-safe at two levels:
+ * - **Same process**: concurrent calls with the same slug share a single in-flight
+ *   Promise (via `_pendingBoardCreations`), so only one DB write is attempted.
+ * - **Cross-instance**: the DB `unique` constraint on `slug` causes the losing
+ *   write to throw; the catch block re-fetches and returns the winner's board.
+ *
+ * @remarks **Security:** No authorization hooks are called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param slug - Unique URL-safe slug for the board
+ * @param name - Display name for the board (used only on creation)
+ * @param columnTitles - Ordered list of column names to create (used only on creation)
+ */
+export async function findOrCreateKanbanBoard(
+	adapter: Adapter,
+	slug: string,
+	name: string,
+	columnTitles: string[],
+): Promise<Board> {
+	const existing = await adapter.findOne<Board>({
+		model: "kanbanBoard",
+		where: [{ field: "slug", value: slug, operator: "eq" as const }],
+	});
+
+	if (existing) return existing;
+
+	// Coalesce same-process concurrent calls for this slug
+	const inflight = _pendingBoardCreations.get(slug);
+	if (inflight) return inflight;
+
+	const creation = (async () => {
+		try {
+			const board = await adapter.create<Board>({
+				model: "kanbanBoard",
+				data: {
+					name,
+					slug,
+					createdAt: new Date(),
+					updatedAt: new Date(),
+				},
+			});
+
+			await Promise.all(
+				columnTitles.map((title, index) =>
+					adapter.create<Column>({
+						model: "kanbanColumn",
+						data: {
+							title,
+							boardId: board.id,
+							order: index,
+							createdAt: new Date(),
+							updatedAt: new Date(),
+						},
+					}),
+				),
+			);
+
+			return board;
+		} catch (err) {
+			// Cross-instance race: another process won the unique-constraint race.
+			// Re-fetch so all callers return the same board.
+			const winner = await adapter.findOne<Board>({
+				model: "kanbanBoard",
+				where: [{ field: "slug", value: slug, operator: "eq" as const }],
+			});
+			if (winner) return winner;
+			throw err;
+		}
+	})();
+
+	_pendingBoardCreations.set(slug, creation);
+	try {
+		return await creation;
+	} finally {
+		_pendingBoardCreations.delete(slug);
+	}
+}
+
+/**
+ * Retrieve all columns for a given board, sorted by order.
+ * Co-located with mutations because it is primarily used alongside
+ * {@link createKanbanTask} to resolve column IDs before task creation.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ *
+ * @param adapter - The database adapter
+ * @param boardId - The board ID
+ */
+export async function getKanbanColumnsByBoardId(
+	adapter: Adapter,
+	boardId: string,
+): Promise<Column[]> {
+	return adapter.findMany<Column>({
+		model: "kanbanColumn",
+		where: [{ field: "boardId", value: boardId, operator: "eq" as const }],
+		sortBy: { field: "order", direction: "asc" },
+	});
+}