@btst/stack 2.4.0 → 2.5.1

package/src/plugins/ai-chat/api/plugin.ts

@@ -21,6 +21,7 @@ import {
 	BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST,
 	BUILT_IN_PAGE_TOOL_SCHEMAS,
 } from "./page-tools";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Context passed to AI Chat API hooks
@@ -40,48 +41,46 @@ export interface ChatApiContext<TBody = any, TParams = any, TQuery = any> {
  */
 export interface AiChatBackendHooks {
 	// ============== Authorization Hooks ==============
-	// Return false to deny access
+	// Throw an error to deny access
 
 	/**
-	 * Called before processing a chat message. Return false to deny access.
+	 * Called before processing a chat message. Throw an error to deny access.
 	 * @param messages - Array of messages being sent
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeChat?: (
 		messages: Array<{ role: string; content: string }>,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before listing conversations. Return false to deny access.
+	 * Called before listing conversations. Throw an error to deny access.
 	 * @param context - Request context with headers, etc.
 	 */
-	onBeforeListConversations?: (
-		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	onBeforeListConversations?: (context: ChatApiContext) => Promise<void> | void;
 
 	/**
-	 * Called before getting a single conversation. Return false to deny access.
+	 * Called before getting a single conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being accessed
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeGetConversation?: (
 		conversationId: string,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before creating a conversation. Return false to deny access.
+	 * Called before creating a conversation. Throw an error to deny access.
 	 * @param data - Conversation data being created
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeCreateConversation?: (
 		data: { id?: string; title?: string },
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before updating a conversation. Return false to deny access.
+	 * Called before updating a conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being updated
 	 * @param data - Updated conversation data
 	 * @param context - Request context with headers, etc.
@@ -90,17 +89,17 @@ export interface AiChatBackendHooks {
 		conversationId: string,
 		data: { title?: string },
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before deleting a conversation. Return false to deny access.
+	 * Called before deleting a conversation. Throw an error to deny access.
 	 * @param conversationId - ID of the conversation being deleted
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeDeleteConversation?: (
 		conversationId: string,
 		context: ChatApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called after the structural routeName/allowlist validation, with the list
@@ -452,15 +451,11 @@ export const aiChatBackendPlugin = <
 								role: msg.role,
 								content: getMessageTextContent(msg),
 							}));
-							const canChat = await config.hooks.onBeforeChat(
-								messagesForHook,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeChat!(messagesForHook, context),
+								ctx.error,
+								"Unauthorized: Cannot start chat",
 							);
-							if (!canChat) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot start chat",
-								});
-							}
 						}
 
 						const firstMessage = uiMessages[0];
@@ -848,15 +843,15 @@ export const aiChatBackendPlugin = <
 
 						// Authorization hook
 						if (config.hooks?.onBeforeCreateConversation) {
-							const canCreate = await config.hooks.onBeforeCreateConversation(
-								{ id, title },
-								context,
+							await runHookWithShim(
+								() =>
+									config.hooks!.onBeforeCreateConversation!(
+										{ id, title },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot create conversation",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create conversation",
-								});
-							}
 						}
 
 						const newConv = await adapter.create<Conversation>({
@@ -914,13 +909,11 @@ export const aiChatBackendPlugin = <
 
 						// Authorization hook
 						if (config.hooks?.onBeforeListConversations) {
-							const canList =
-								await config.hooks.onBeforeListConversations(context);
-							if (!canList) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot list conversations",
-								});
-							}
+							await runHookWithShim(
+								() => config.hooks!.onBeforeListConversations!(context),
+								ctx.error,
+								"Unauthorized: Cannot list conversations",
+							);
 						}
 
 						// Build where conditions - filter by userId if set
@@ -991,15 +984,11 @@ export const aiChatBackendPlugin = <
 
 						// Authorization hook
 						if (config.hooks?.onBeforeGetConversation) {
-							const canGet = await config.hooks.onBeforeGetConversation(
-								id,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeGetConversation!(id, context),
+								ctx.error,
+								"Unauthorized: Cannot get conversation",
 							);
-							if (!canGet) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot get conversation",
-								});
-							}
 						}
 
 						// Fetch conversation with messages in a single query using join
@@ -1116,16 +1105,16 @@ export const aiChatBackendPlugin = <
 
 						// Authorization hook
 						if (config.hooks?.onBeforeUpdateConversation) {
-							const canUpdate = await config.hooks.onBeforeUpdateConversation(
-								id,
-								{ title },
-								context,
+							await runHookWithShim(
+								() =>
+									config.hooks!.onBeforeUpdateConversation!(
+										id,
+										{ title },
+										context,
+									),
+								ctx.error,
+								"Unauthorized: Cannot update conversation",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update conversation",
-								});
-							}
 						}
 
 						const updated = await adapter.update<Conversation>({
@@ -1211,15 +1200,11 @@ export const aiChatBackendPlugin = <
 
 						// Authorization hook
 						if (config.hooks?.onBeforeDeleteConversation) {
-							const canDelete = await config.hooks.onBeforeDeleteConversation(
-								id,
-								context,
+							await runHookWithShim(
+								() => config.hooks!.onBeforeDeleteConversation!(id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete conversation",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete conversation",
-								});
-							}
 						}
 
 						// Messages are automatically deleted via cascade (onDelete: "cascade")

package/src/plugins/ai-chat/client/plugin.tsx

@@ -1,6 +1,7 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -92,35 +93,33 @@ export interface AiChatClientConfig {
  */
 export interface AiChatClientHooks {
 	/**
-	 * Called before loading conversations list. Return false to cancel loading.
+	 * Called before loading conversations list. Throw an error to cancel loading.
 	 * @param context - Loader context with path, params, etc.
 	 */
-	beforeLoadConversations?: (
-		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	beforeLoadConversations?: (context: LoaderContext) => Promise<void> | void;
 
 	/**
-	 * Called after conversations are loaded. Return false to cancel further processing.
+	 * Called after conversations are loaded. Throw an error to cancel further processing.
 	 * @param conversations - Array of loaded conversations or null
 	 * @param context - Loader context
 	 */
 	afterLoadConversations?: (
 		conversations: SerializedConversation[] | null,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called before loading a single conversation. Return false to cancel loading.
+	 * Called before loading a single conversation. Throw an error to cancel loading.
 	 * @param id - Conversation ID being loaded
 	 * @param context - Loader context
 	 */
 	beforeLoadConversation?: (
 		id: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
-	 * Called after a conversation is loaded. Return false to cancel further processing.
+	 * Called after a conversation is loaded. Throw an error to cancel further processing.
 	 * @param conversation - Loaded conversation or null if not found
 	 * @param id - Conversation ID that was requested
 	 * @param context - Loader context
@@ -131,7 +130,7 @@ export interface AiChatClientHooks {
 			| null,
 		id: string,
 		context: LoaderContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called when a loading error occurs
@@ -163,10 +162,10 @@ function createConversationsLoader(config: AiChatClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadConversations) {
-					const canLoad = await hooks.beforeLoadConversations(context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadConversations hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadConversations!(context),
+						"Load prevented by beforeLoadConversations hook",
+					);
 				}
 
 				const client = createApiClient<AiChatApiRouter>({
@@ -185,13 +184,10 @@ function createConversationsLoader(config: AiChatClientConfig) {
 						queryClient.getQueryData<SerializedConversation[]>(
 							listQuery.queryKey,
 						) || null;
-					const canContinue = await hooks.afterLoadConversations(
-						conversations,
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadConversations!(conversations, context),
+						"Load prevented by afterLoadConversations hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadConversations hook");
-					}
 				}
 
 				// Check for errors
@@ -230,10 +226,10 @@ function createConversationLoader(id: string, config: AiChatClientConfig) {
 			try {
 				// Before hook
 				if (hooks?.beforeLoadConversation) {
-					const canLoad = await hooks.beforeLoadConversation(id, context);
-					if (!canLoad) {
-						throw new Error("Load prevented by beforeLoadConversation hook");
-					}
+					await runClientHookWithShim(
+						() => hooks.beforeLoadConversation!(id, context),
+						"Load prevented by beforeLoadConversation hook",
+					);
 				}
 
 				const client = createApiClient<AiChatApiRouter>({
@@ -258,14 +254,10 @@ function createConversationLoader(id: string, config: AiChatClientConfig) {
 						queryClient.getQueryData<
 							SerializedConversation & { messages: SerializedMessage[] }
 						>(conversationQuery.queryKey) || null;
-					const canContinue = await hooks.afterLoadConversation(
-						conversation,
-						id,
-						context,
+					await runClientHookWithShim(
+						() => hooks.afterLoadConversation!(conversation, id, context),
+						"Load prevented by afterLoadConversation hook",
 					);
-					if (canContinue === false) {
-						throw new Error("Load prevented by afterLoadConversation hook");
-					}
 				}
 
 				// Check for errors

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

@@ -10,6 +10,7 @@ import { getAllPosts, getPostBySlug, getAllTags } from "./getters";
 import { BLOG_QUERY_KEYS } from "./query-key-defs";
 import { serializePost, serializeTag } from "./serializers";
 import type { QueryClient } from "@tanstack/react-query";
+import { runHookWithShim } from "../../utils";
 
 /**
  * Route keys for the blog plugin — matches the keys returned by
@@ -131,25 +132,25 @@ export interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
  */
 export interface BlogBackendHooks {
 	/**
-	 * Called before listing posts. Return false to deny access.
+	 * Called before listing posts. Throw an error to deny access.
 	 * @param filter - Query parameters for filtering posts
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeListPosts?: (
 		filter: z.infer<typeof PostListQuerySchema>,
 		context: BlogApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before creating a post. Return false to deny access.
+	 * Called before creating a post. Throw an error to deny access.
 	 * @param data - Post data being created
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeCreatePost?: (
 		data: z.infer<typeof createPostSchema>,
 		context: BlogApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before updating a post. Return false to deny access.
+	 * Called before updating a post. Throw an error to deny access.
 	 * @param postId - ID of the post being updated
 	 * @param data - Updated post data
 	 * @param context - Request context with headers, etc.
@@ -158,16 +159,16 @@ export interface BlogBackendHooks {
 		postId: string,
 		data: z.infer<typeof updatePostSchema>,
 		context: BlogApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 	/**
-	 * Called before deleting a post. Return false to deny access.
+	 * Called before deleting a post. Throw an error to deny access.
 	 * @param postId - ID of the post being deleted
 	 * @param context - Request context with headers, etc.
 	 */
 	onBeforeDeletePost?: (
 		postId: string,
 		context: BlogApiContext,
-	) => Promise<boolean> | boolean;
+	) => Promise<void> | void;
 
 	/**
 	 * Called after posts are read successfully
@@ -350,12 +351,11 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeListPosts) {
-							const canList = await hooks.onBeforeListPosts(query, context);
-							if (!canList) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot list posts",
-								});
-							}
+							await runHookWithShim(
+								() => hooks.onBeforeListPosts!(query, context),
+								ctx.error,
+								"Unauthorized: Cannot list posts",
+							);
 						}
 
 						const result = await getAllPosts(adapter, query);
@@ -387,15 +387,11 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeCreatePost) {
-							const canCreate = await hooks.onBeforeCreatePost(
-								ctx.body,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeCreatePost!(ctx.body, context),
+								ctx.error,
+								"Unauthorized: Cannot create post",
 							);
-							if (!canCreate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot create post",
-								});
-							}
 						}
 
 						const { tags, ...postData } = ctx.body;
@@ -471,16 +467,12 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeUpdatePost) {
-							const canUpdate = await hooks.onBeforeUpdatePost(
-								ctx.params.id,
-								ctx.body,
-								context,
+							await runHookWithShim(
+								() =>
+									hooks.onBeforeUpdatePost!(ctx.params.id, ctx.body, context),
+								ctx.error,
+								"Unauthorized: Cannot update post",
 							);
-							if (!canUpdate) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot update post",
-								});
-							}
 						}
 
 						const { tags, slug: rawSlug, ...restPostData } = ctx.body;
@@ -598,15 +590,11 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 					try {
 						// Authorization hook
 						if (hooks?.onBeforeDeletePost) {
-							const canDelete = await hooks.onBeforeDeletePost(
-								ctx.params.id,
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeDeletePost!(ctx.params.id, context),
+								ctx.error,
+								"Unauthorized: Cannot delete post",
 							);
-							if (!canDelete) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot delete post",
-								});
-							}
 						}
 
 						await adapter.delete<Post>({
@@ -642,15 +630,11 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 
 					try {
 						if (hooks?.onBeforeListPosts) {
-							const canList = await hooks.onBeforeListPosts(
-								{ published: true },
-								context,
+							await runHookWithShim(
+								() => hooks.onBeforeListPosts!({ published: true }, context),
+								ctx.error,
+								"Unauthorized: Cannot list posts",
 							);
-							if (!canList) {
-								throw ctx.error(403, {
-									message: "Unauthorized: Cannot list posts",
-								});
-							}
 						}
 
 						const date = query.date;

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";