@btst/stack 3.0.0-rc.2 → 3.0.0-rc.4

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

@@ -1,28 +1,48 @@
 import type { DBAdapter as Adapter } from "@btst/db";
-import { defineBackendPlugin } from "@btst/stack/plugins/api";
-import { createEndpoint } from "@btst/stack/plugins/api";
-import { z } from "zod";
+import { createEndpoint, defineBackendPlugin } from "@btst/stack/plugins/api";
+import type { QueryClient } from "@tanstack/react-query";
 import { blogSchema as dbSchema } from "../db";
-import type { Post, PostWithPostTag, Tag } from "../types";
-import { slugify } from "../utils";
-import { createPostSchema, updatePostSchema } from "../schemas";
-import { getAllPosts, getPostBySlug, getAllTags } from "./getters";
+import { getAllPosts, getAllTags, getPostBySlug } from "./getters";
 import {
-	createPost as createPostMutation,
-	updatePost as updatePostMutation,
-	deletePost as deletePostMutation,
-	type CreatePostInput,
-	type UpdatePostInput,
-} from "./mutations";
+	CreatePostOperationInputSchema,
+	NextPreviousPostsQuerySchema,
+	PostListQuerySchema,
+	UpdatePostOperationInputSchema,
+	createBlogOperations,
+	type BlogBackendHooks,
+} from "./operations";
 import { BLOG_QUERY_KEYS } from "./query-key-defs";
 import { serializePost, serializeTag } from "./serializers";
-import type { QueryClient } from "@tanstack/react-query";
-import { runHook } from "../../utils";
 
-/**
- * Route keys for the blog plugin — matches the keys returned by
- * `stackClient.router.getRoute(path).routeKey`.
- */
+export {
+	CreatePostOperationInputSchema,
+	NextPreviousPostsQuerySchema,
+	PostListQuerySchema,
+	UpdatePostOperationInputSchema,
+} from "./operations";
+export { BLOG_LIFECYCLE_HOOK_MIGRATIONS } from "./lifecycle-migrations";
+export type {
+	BlogBackendHooks,
+	BlogCreateErrorContext,
+	BlogCreateOperationContext,
+	BlogCreateResultContext,
+	BlogDeleteErrorContext,
+	BlogDeleteOperationContext,
+	BlogDeleteResultContext,
+	BlogListErrorContext,
+	BlogListOperationContext,
+	BlogListResultContext,
+	BlogNextPreviousErrorContext,
+	BlogNextPreviousOperationContext,
+	BlogNextPreviousResultContext,
+	BlogUpdateErrorContext,
+	BlogUpdateOperationContext,
+	BlogUpdateResultContext,
+	SerializedNextPreviousPostsResult,
+	SerializedPostListResult,
+} from "./operations";
+
+/** Route keys returned by the Blog client plugin. */
 export type BlogRouteKey =
 	| "posts"
 	| "drafts"
@@ -31,10 +51,6 @@ export type BlogRouteKey =
 	| "newPost"
 	| "editPost";
 
-/**
- * Overloaded signature for `prefetchForRoute`.
- * TypeScript enforces the correct params for each routeKey at call sites.
- */
 interface BlogPrefetchForRoute {
 	(key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
 	(
@@ -45,10 +61,16 @@ interface BlogPrefetchForRoute {
 	(key: "tag", qc: QueryClient, params: { tagSlug: string }): Promise<void>;
 }
 
+/**
+ * SSG is a raw-data path: it intentionally bypasses request
+ * authorization and seeds only the route data selected by the caller. Build
+ * protected routes only when the resulting artifact has equivalent deployment
+ * access controls; static output is commonly public.
+ */
 function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
 	return async function prefetchForRoute(
 		key: BlogRouteKey,
-		qc: QueryClient,
+		queryClient: QueryClient,
 		params?: Record<string, string>,
 	): Promise<void> {
 		switch (key) {
@@ -59,11 +81,17 @@ function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
 					getAllPosts(adapter, { published, limit: 10 }),
 					getAllTags(adapter),
 				]);
-				qc.setQueryData(BLOG_QUERY_KEYS.postsList({ published, limit: 10 }), {
-					pages: [result.items.map(serializePost)],
-					pageParams: [0],
-				});
-				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				queryClient.setQueryData(
+					BLOG_QUERY_KEYS.postsList({ published, limit: 10 }),
+					{
+						pages: [result.items.map(serializePost)],
+						pageParams: [0],
+					},
+				);
+				queryClient.setQueryData(
+					BLOG_QUERY_KEYS.tagsList(),
+					tags.map(serializeTag),
+				);
 				break;
 			}
 			case "post":
@@ -71,7 +99,7 @@ function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
 				const slug = params?.slug ?? "";
 				if (slug) {
 					const post = await getPostBySlug(adapter, slug);
-					qc.setQueryData(
+					queryClient.setQueryData(
 						BLOG_QUERY_KEYS.postDetail(slug),
 						post ? serializePost(post) : null,
 					);
@@ -84,14 +112,17 @@ function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
 					getAllPosts(adapter, { published: true, limit: 10, tagSlug }),
 					getAllTags(adapter),
 				]);
-				qc.setQueryData(
+				queryClient.setQueryData(
 					BLOG_QUERY_KEYS.postsList({ published: true, limit: 10, tagSlug }),
 					{
 						pages: [result.items.map(serializePost)],
 						pageParams: [0],
 					},
 				);
-				qc.setQueryData(BLOG_QUERY_KEYS.tagsList(), tags.map(serializeTag));
+				queryClient.setQueryData(
+					BLOG_QUERY_KEYS.tagsList(),
+					tags.map(serializeTag),
+				);
 				break;
 			}
 			default:
@@ -100,381 +131,64 @@ function createBlogPrefetchForRoute(adapter: Adapter): BlogPrefetchForRoute {
 	} as BlogPrefetchForRoute;
 }
 
-export const PostListQuerySchema = z.object({
-	slug: z.string().optional(),
-	tagSlug: z.string().optional(),
-	offset: z.coerce.number().int().min(0).optional(),
-	limit: z.coerce.number().int().min(1).max(100).optional(),
-	query: z.string().max(200).optional(),
-	published: z
-		.string()
-		.optional()
-		.transform((val) => {
-			if (val === undefined) return undefined;
-			if (val === "true") return true;
-			if (val === "false") return false;
-			return undefined;
-		}),
-});
-
-export const NextPreviousPostsQuerySchema = z.object({
-	date: z.coerce.date(),
-});
-
 /**
- * Context passed to blog API hooks
+ * Blog backend plugin. Every maintained HTTP endpoint adapts the same
+ * operation exposed by `forRequest(request).operations.blog` and `trusted.blog`.
  */
-export interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
-	body?: TBody;
-	params?: TParams;
-	query?: TQuery;
-	request?: Request;
-	headers?: Headers;
-	[key: string]: any;
+export interface BlogBackendOptions {
+	/** Post-authorization domain lifecycle hooks. */
+	hooks?: BlogBackendHooks;
 }
 
-/**
- * Configuration hooks for blog backend plugin
- * All hooks are optional and allow consumers to customize behavior
- */
-export interface BlogBackendHooks {
-	/**
-	 * 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<void> | void;
-	/**
-	 * 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<void> | void;
-	/**
-	 * 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.
-	 */
-	onBeforeUpdatePost?: (
-		postId: string,
-		data: z.infer<typeof updatePostSchema>,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-	/**
-	 * 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<void> | void;
-
-	/**
-	 * Called after posts are read successfully
-	 * @param posts - The list of posts returned by the query
-	 * @param filter - Query parameters used for filtering
-	 * @param context - Request context
-	 */
-	onPostsRead?: (
-		posts: Array<Post & { tags: Tag[] }>,
-		filter: z.infer<typeof PostListQuerySchema>,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-	/**
-	 * Called after a post is created successfully
-	 * @param post - The created post
-	 * @param context - Request context
-	 */
-	onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
-	/**
-	 * Called after a post is updated successfully
-	 * @param post - The updated post
-	 * @param context - Request context
-	 */
-	onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
-	/**
-	 * Called after a post is deleted successfully
-	 * @param postId - ID of the deleted post
-	 * @param context - Request context
-	 */
-	onPostDeleted?: (
-		postId: string,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-
-	/**
-	 * Called when listing posts fails
-	 * @param error - The error that occurred
-	 * @param context - Request context
-	 */
-	onListPostsError?: (
-		error: Error,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-	/**
-	 * Called when creating a post fails
-	 * @param error - The error that occurred
-	 * @param context - Request context
-	 */
-	onCreatePostError?: (
-		error: Error,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-	/**
-	 * Called when updating a post fails
-	 * @param error - The error that occurred
-	 * @param context - Request context
-	 */
-	onUpdatePostError?: (
-		error: Error,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-	/**
-	 * Called when deleting a post fails
-	 * @param error - The error that occurred
-	 * @param context - Request context
-	 */
-	onDeletePostError?: (
-		error: Error,
-		context: BlogApiContext,
-	) => Promise<void> | void;
-}
-
-/**
- * Blog backend plugin
- * Provides API endpoints for managing blog posts
- * Uses better-db adapter for database operations
- *
- * @param hooks - Optional configuration hooks for customizing plugin behavior
- */
-export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
+export const blogBackendPlugin = (options: BlogBackendOptions = {}) =>
 	defineBackendPlugin({
-		name: "blog",
-
+		id: "blog",
 		dbPlugin: dbSchema,
-
-		api: (adapter) => ({
-			getAllPosts: (params?: Parameters<typeof getAllPosts>[1]) =>
-				getAllPosts(adapter, params),
-			getPostBySlug: (slug: string) => getPostBySlug(adapter, slug),
-			getAllTags: () => getAllTags(adapter),
+		operations: (adapter: Adapter) =>
+			createBlogOperations(adapter, options.hooks),
+
+		/**
+		 * Explicit lower-level helper for SSG and infrastructure code.
+		 * These functions bypass authorization and lifecycle composition.
+		 */
+		raw: (adapter: Adapter) => ({
 			prefetchForRoute: createBlogPrefetchForRoute(adapter),
-			// Mutations
-			createPost: (input: CreatePostInput) =>
-				createPostMutation(adapter, input),
-			updatePost: (id: string, input: UpdatePostInput) =>
-				updatePostMutation(adapter, id, input),
-			deletePost: (id: string) => deletePostMutation(adapter, id),
 		}),
 
-		routes: (adapter: Adapter) => {
+		routes: (_adapter: Adapter, _context, operations) => {
 			const listPosts = createEndpoint(
 				"/posts",
-				{
-					method: "GET",
-					query: PostListQuerySchema,
-				},
-				async (ctx) => {
-					const { query, headers } = ctx;
-					const context: BlogApiContext = { query, headers };
-
-					try {
-						if (hooks?.onBeforeListPosts) {
-							await runHook(
-								() => hooks.onBeforeListPosts!(query, context),
-								ctx.error,
-								"Unauthorized: Cannot list posts",
-							);
-						}
-
-						const result = await getAllPosts(adapter, query);
-
-						if (hooks?.onPostsRead) {
-							await hooks.onPostsRead(result.items, query, context);
-						}
-
-						return result;
-					} catch (error) {
-						if (hooks?.onListPostsError) {
-							await hooks.onListPostsError(error as Error, context);
-						}
-						throw error;
-					}
-				},
+				{ method: "GET", query: PostListQuerySchema, requireRequest: true },
+				operations.listPosts.route((ctx) => ctx.query),
 			);
+
 			const createPost = createEndpoint(
 				"/posts",
 				{
 					method: "POST",
-					body: createPostSchema,
-				},
-				async (ctx) => {
-					const context: BlogApiContext = {
-						body: ctx.body,
-						headers: ctx.headers,
-					};
-
-					try {
-						if (hooks?.onBeforeCreatePost) {
-							await runHook(
-								() => hooks.onBeforeCreatePost!(ctx.body, context),
-								ctx.error,
-								"Unauthorized: Cannot create post",
-							);
-						}
-
-						// Destructure and discard createdAt/updatedAt — timestamps are always server-generated
-						const {
-							tags,
-							slug: rawSlug,
-							createdAt: _ca,
-							updatedAt: _ua,
-							...postData
-						} = ctx.body;
-
-						// Always slugify to ensure URL-safe slug, whether provided or generated from title
-						const slug = slugify(rawSlug || postData.title);
-
-						// Validate that slugification produced a non-empty result
-						if (!slug) {
-							throw ctx.error(400, {
-								message:
-									"Invalid slug: must contain at least one alphanumeric character",
-							});
-						}
-
-						const newPost = await createPostMutation(adapter, {
-							...postData,
-							slug,
-							tags: tags ?? [],
-							createdAt: new Date(),
-							updatedAt: new Date(),
-						});
-
-						if (hooks?.onPostCreated) {
-							await hooks.onPostCreated(newPost, context);
-						}
-
-						return newPost;
-					} catch (error) {
-						if (hooks?.onCreatePostError) {
-							await hooks.onCreatePostError(error as Error, context);
-						}
-						throw error;
-					}
+					body: CreatePostOperationInputSchema,
+					requireRequest: true,
 				},
+				operations.createPost.route((ctx) => ctx.body),
 			);
+
 			const updatePost = createEndpoint(
 				"/posts/:id",
 				{
 					method: "PUT",
-					body: updatePostSchema,
-				},
-				async (ctx) => {
-					const context: BlogApiContext = {
-						body: ctx.body,
-						params: ctx.params,
-						headers: ctx.headers,
-					};
-
-					try {
-						if (hooks?.onBeforeUpdatePost) {
-							await runHook(
-								() =>
-									hooks.onBeforeUpdatePost!(ctx.params.id, ctx.body, context),
-								ctx.error,
-								"Unauthorized: Cannot update post",
-							);
-						}
-
-						// Destructure and discard createdAt/updatedAt — timestamps are always server-generated
-						const {
-							tags,
-							slug: rawSlug,
-							createdAt: _ca,
-							updatedAt: _ua,
-							...restPostData
-						} = ctx.body;
-
-						// Sanitize slug if provided to ensure it's URL-safe
-						const slugified = rawSlug ? slugify(rawSlug) : undefined;
-
-						// Validate that slugification produced a non-empty result (if slug was provided)
-						if (rawSlug && !slugified) {
-							throw ctx.error(400, {
-								message:
-									"Invalid slug: must contain at least one alphanumeric character",
-							});
-						}
-
-						const updated = await updatePostMutation(adapter, ctx.params.id, {
-							...restPostData,
-							...(slugified ? { slug: slugified } : {}),
-							tags: tags ?? [],
-						});
-
-						if (!updated) {
-							throw ctx.error(404, { message: "Post not found" });
-						}
-
-						if (hooks?.onPostUpdated) {
-							await hooks.onPostUpdated(updated, context);
-						}
-
-						return updated;
-					} catch (error) {
-						if (hooks?.onUpdatePostError) {
-							await hooks.onUpdatePostError(error as Error, context);
-						}
-						throw error;
-					}
+					body: UpdatePostOperationInputSchema.shape.data,
+					requireRequest: true,
 				},
+				operations.updatePost.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
 			);
+
 			const deletePost = createEndpoint(
 				"/posts/:id",
-				{
-					method: "DELETE",
-				},
-				async (ctx) => {
-					const context: BlogApiContext = {
-						params: ctx.params,
-						headers: ctx.headers,
-					};
-
-					try {
-						// Authorization hook
-						if (hooks?.onBeforeDeletePost) {
-							await runHook(
-								() => hooks.onBeforeDeletePost!(ctx.params.id, context),
-								ctx.error,
-								"Unauthorized: Cannot delete post",
-							);
-						}
-
-						await deletePostMutation(adapter, ctx.params.id);
-
-						// Lifecycle hook
-						if (hooks?.onPostDeleted) {
-							await hooks.onPostDeleted(ctx.params.id, context);
-						}
-
-						return { success: true };
-					} catch (error) {
-						// Error hook
-						if (hooks?.onDeletePostError) {
-							await hooks.onDeletePostError(error as Error, context);
-						}
-						throw error;
-					}
-				},
+				{ method: "DELETE", requireRequest: true },
+				operations.deletePost.route((ctx) => ({ id: ctx.params.id })),
 			);
 
 			const getNextPreviousPosts = createEndpoint(
@@ -482,134 +196,15 @@ export const blogBackendPlugin = (hooks?: BlogBackendHooks) =>
 				{
 					method: "GET",
 					query: NextPreviousPostsQuerySchema,
+					requireRequest: true,
 				},
-				async (ctx) => {
-					const { query, headers } = ctx;
-					const context: BlogApiContext = { query, headers };
-
-					try {
-						if (hooks?.onBeforeListPosts) {
-							await runHook(
-								() => hooks.onBeforeListPosts!({ published: true }, context),
-								ctx.error,
-								"Unauthorized: Cannot list posts",
-							);
-						}
-
-						const date = query.date;
-
-						// Get previous post (createdAt < date, newest first)
-						const previousPosts = await adapter.findMany<PostWithPostTag>({
-							model: "post",
-							limit: 1,
-							where: [
-								{
-									field: "createdAt",
-									value: date,
-									operator: "lt" as const,
-								},
-								{
-									field: "published",
-									value: true,
-									operator: "eq" as const,
-								},
-							],
-							sortBy: {
-								field: "createdAt",
-								direction: "desc",
-							},
-							join: {
-								postTag: true,
-							},
-						});
-
-						const nextPosts = await adapter.findMany<PostWithPostTag>({
-							model: "post",
-							limit: 1,
-							where: [
-								{
-									field: "createdAt",
-									value: date,
-									operator: "gt" as const,
-								},
-								{
-									field: "published",
-									value: true,
-									operator: "eq" as const,
-								},
-							],
-							sortBy: {
-								field: "createdAt",
-								direction: "asc",
-							},
-							join: {
-								postTag: true,
-							},
-						});
-
-						// Collect unique tag IDs from joined data
-						const tagIds = new Set<string>();
-						const allPosts = [...previousPosts, ...nextPosts];
-						for (const post of allPosts) {
-							if (post.postTag) {
-								for (const pt of post.postTag) {
-									tagIds.add(pt.tagId);
-								}
-							}
-						}
-
-						// Fetch tags if needed
-						const tagMap = new Map<string, Tag>();
-						if (tagIds.size > 0) {
-							const tags = await adapter.findMany<Tag>({
-								model: "tag",
-							});
-							for (const tag of tags) {
-								if (tagIds.has(tag.id)) {
-									tagMap.set(tag.id, tag);
-								}
-							}
-						}
-
-						// Helper to map post with tags (spread to avoid circular references)
-						const mapPostWithTags = (post: PostWithPostTag) => {
-							const tags = (post.postTag || [])
-								.map((pt) => {
-									const tag = tagMap.get(pt.tagId);
-									return tag ? { ...tag } : undefined;
-								})
-								.filter((tag): tag is Tag => tag !== undefined);
-							const { postTag: _, ...postWithoutJoin } = post;
-							return {
-								...postWithoutJoin,
-								tags,
-							};
-						};
-
-						return {
-							previous: previousPosts[0]
-								? mapPostWithTags(previousPosts[0])
-								: null,
-							next: nextPosts[0] ? mapPostWithTags(nextPosts[0]) : null,
-						};
-					} catch (error) {
-						// Error hook
-						if (hooks?.onListPostsError) {
-							await hooks.onListPostsError(error as Error, context);
-						}
-						throw error;
-					}
-				},
+				operations.getNextPreviousPosts.route((ctx) => ctx.query),
 			);
 
 			const listTags = createEndpoint(
 				"/tags",
-				{
-					method: "GET",
-				},
-				async () => {
-					return await getAllTags(adapter);
-				},
+				{ method: "GET", requireRequest: true },
+				operations.listTags.route(() => ({})),
 			);
 
 			return {

package/src/plugins/blog/client/components/forms/image-field.tsx

@@ -16,6 +16,7 @@ import {
 import { Loader2, Upload } from "lucide-react";
 import { useRef, useState } from "react";
 import type { BlogPluginOverrides } from "../../overrides";
+import { BLOG_PLUGIN_ID } from "../../constants";
 
 export function FeaturedImageField({
 	isRequired,
@@ -37,7 +38,7 @@ export function FeaturedImageField({
 		uploadImage,
 		localization,
 		imageInputField: ImageInput,
-	} = usePluginOverrides<BlogPluginOverrides>("blog");
+	} = usePluginOverrides<BlogPluginOverrides>(BLOG_PLUGIN_ID);
 	const { router } = useStack();
 
 	const ImageComponent = router?.Image ?? DefaultImage;