@btst/stack 1.4.1 → 1.5.1

package/src/plugins/cms/query-keys.ts

@@ -0,0 +1,186 @@
+import {
+	mergeQueryKeys,
+	createQueryKeys,
+} from "@lukemorales/query-key-factory";
+import type { CMSApiRouter } from "./api";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type {
+	SerializedContentType,
+	SerializedContentItemWithType,
+	PaginatedContentItems,
+} from "./types";
+
+interface ContentListParams {
+	limit?: number;
+	offset?: number;
+}
+
+// Type guard for better-call error responses
+function isErrorResponse(
+	response: unknown,
+): response is { error: unknown; data?: never } {
+	if (typeof response !== "object" || response === null) {
+		return false;
+	}
+	const obj = response as Record<string, unknown>;
+	return "error" in obj && obj.error !== null && obj.error !== undefined;
+}
+
+// Helper to convert error to a proper Error object with meaningful message
+function toError(error: unknown): Error {
+	if (error instanceof Error) {
+		return error;
+	}
+
+	if (typeof error === "object" && error !== null) {
+		const errorObj = error as Record<string, unknown>;
+		const message =
+			(typeof errorObj.message === "string" ? errorObj.message : null) ||
+			(typeof errorObj.error === "string" ? errorObj.error : null) ||
+			JSON.stringify(error);
+
+		const err = new Error(message);
+		Object.assign(err, error);
+		return err;
+	}
+
+	return new Error(String(error));
+}
+
+/**
+ * Create CMS query keys for React Query
+ * Used by consumers to fetch content types and content items
+ */
+export function createCMSQueryKeys(
+	client: ReturnType<typeof createApiClient<CMSApiRouter>>,
+	headers?: HeadersInit,
+) {
+	const contentTypes = createContentTypesQueries(client, headers);
+	const content = createContentQueries(client, headers);
+
+	return mergeQueryKeys(contentTypes, content);
+}
+
+function createContentTypesQueries(
+	client: ReturnType<typeof createApiClient<CMSApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("cmsTypes", {
+		list: () => ({
+			queryKey: ["list"],
+			queryFn: async () => {
+				try {
+					const response: unknown = await client("/content-types", {
+						method: "GET",
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return ((response as { data?: unknown }).data ??
+						[]) as (SerializedContentType & { itemCount: number })[];
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		detail: (slug: string) => ({
+			queryKey: [slug],
+			queryFn: async () => {
+				if (!slug) return null;
+
+				try {
+					const response: unknown = await client("/content-types/:slug", {
+						method: "GET",
+						params: { slug },
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown })
+						.data as SerializedContentType | null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+	});
+}
+
+function createContentQueries(
+	client: ReturnType<typeof createApiClient<CMSApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("cmsContent", {
+		list: (params: { typeSlug: string } & ContentListParams) => ({
+			queryKey: [params],
+			queryFn: async () => {
+				try {
+					const response: unknown = await client("/content/:typeSlug", {
+						method: "GET",
+						params: { typeSlug: params.typeSlug },
+						query: {
+							limit: params.limit ?? 20,
+							offset: params.offset ?? 0,
+						},
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown }).data as PaginatedContentItems;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		detail: (typeSlug: string, id: string) => ({
+			queryKey: [typeSlug, id],
+			queryFn: async () => {
+				if (!typeSlug || !id) return null;
+
+				try {
+					const response: unknown = await client("/content/:typeSlug/:id", {
+						method: "GET",
+						params: { typeSlug, id },
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					return (response as { data?: unknown })
+						.data as SerializedContentItemWithType | null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+
+		bySlug: (typeSlug: string, slug: string) => ({
+			queryKey: ["bySlug", typeSlug, slug],
+			queryFn: async () => {
+				if (!typeSlug || !slug) return null;
+
+				try {
+					const response: unknown = await client("/content/:typeSlug", {
+						method: "GET",
+						params: { typeSlug },
+						query: { slug, limit: 1 },
+						headers,
+					});
+					if (isErrorResponse(response)) {
+						throw toError(response.error);
+					}
+					const data = (response as { data?: unknown })
+						.data as PaginatedContentItems;
+					return data.items[0] ?? null;
+				} catch (error) {
+					throw error;
+				}
+			},
+		}),
+	});
+}

package/src/plugins/cms/schemas.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+/**
+ * Schema for listing content items with pagination
+ */
+export const listContentQuerySchema = z.object({
+	slug: z.string().optional(),
+	limit: z.coerce.number().min(1).max(100).optional().default(20),
+	offset: z.coerce.number().min(0).optional().default(0),
+});
+
+/**
+ * Schema for creating a content item
+ * Note: The actual data validation is done dynamically based on the content type's schema
+ */
+export const createContentSchema = z.object({
+	slug: z.string().min(1, "Slug is required"),
+	// Use passthrough object instead of z.record(z.unknown()) due to Zod v4 bug
+	data: z.object({}).passthrough(),
+});
+
+/**
+ * Schema for updating a content item
+ * Note: The actual data validation is done dynamically based on the content type's schema
+ */
+export const updateContentSchema = z.object({
+	slug: z.string().min(1, "Slug is required").optional(),
+	// Use passthrough object instead of z.record(z.unknown()) due to Zod v4 bug
+	data: z.object({}).passthrough().optional(),
+});
+
+/**
+ * Schema for content type response
+ */
+export const contentTypeResponseSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	slug: z.string(),
+	description: z.string().nullable().optional(),
+	jsonSchema: z.string(),
+	fieldConfig: z.string().nullable().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+});
+
+/**
+ * Schema for content item response
+ */
+export const contentItemResponseSchema = z.object({
+	id: z.string(),
+	contentTypeId: z.string(),
+	slug: z.string(),
+	data: z.string(),
+	authorId: z.string().nullable().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+});
+
+/**
+ * Schema for content item with parsed data response
+ */
+export const contentItemWithDataResponseSchema =
+	contentItemResponseSchema.extend({
+		// Use passthrough object instead of z.record(z.unknown()) due to Zod v4 bug
+		parsedData: z.object({}).passthrough(),
+		contentType: contentTypeResponseSchema.optional(),
+	});
+
+/**
+ * Schema for paginated content items response
+ */
+export const paginatedContentResponseSchema = z.object({
+	items: z.array(contentItemWithDataResponseSchema),
+	total: z.number(),
+	limit: z.number(),
+	offset: z.number(),
+});
+
+export type ListContentQuery = z.infer<typeof listContentQuerySchema>;
+export type CreateContentInput = z.infer<typeof createContentSchema>;
+export type UpdateContentInput = z.infer<typeof updateContentSchema>;

package/src/plugins/cms/style.css

@@ -0,0 +1,19 @@
+@import "./client.css";
+
+/*
+ * CMS Plugin CSS - Includes Tailwind class scanning
+ * 
+ * When consumed from npm, Tailwind v4 will automatically scan this package's
+ * source files for Tailwind classes. Consumers only need:
+ *   @import "@btst/stack/plugins/cms/css";
+ */
+
+/* Scan this package's source files for Tailwind classes */
+@source "../../../src/**/*.{ts,tsx}";
+
+/* Scan UI package components (when installed as npm package the UI package will be in this dir) */
+@source "../../packages/ui/src";
+
+/*
+* alternatively consumer can use @source "../node_modules/@btst/stack/src/**\/*.{ts,tsx}";
+*/

package/src/plugins/cms/types.ts

@@ -0,0 +1,220 @@
+import type { z } from "zod";
+import type { AutoFormFieldType } from "@workspace/ui/components/ui/auto-form/types";
+
+/**
+ * Configuration for a content type defined by the developer
+ */
+export interface ContentTypeConfig {
+	/** Display name for the content type (e.g., "Product", "Testimonial") */
+	name: string;
+	/** URL-friendly slug (e.g., "product", "testimonial") */
+	slug: string;
+	/** Optional description shown in the admin UI */
+	description?: string;
+	/** Zod schema defining the content type's fields */
+	schema: z.ZodObject<z.ZodRawShape>;
+	/**
+	 * Optional field configuration for AutoForm customization.
+	 *
+	 * fieldType can be:
+	 * - A built-in AutoForm type: "checkbox", "date", "select", "radio", "switch", "textarea", "number", "file", "fallback"
+	 * - A custom type name that maps to a component provided via `fieldComponents` in overrides
+	 */
+	fieldConfig?: Record<
+		string,
+		{
+			fieldType?: AutoFormFieldType | (string & {});
+		}
+	>;
+}
+
+/**
+ * Content type stored in the database
+ */
+export type ContentType = {
+	id: string;
+	/** Display name */
+	name: string;
+	/** URL-friendly slug - unique identifier */
+	slug: string;
+	/** Optional description */
+	description?: string;
+	/** JSON Schema representation of the Zod schema (stringified) */
+	jsonSchema: string;
+	/** Optional field configuration JSON (stringified) */
+	fieldConfig?: string;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+/**
+ * Content item stored in the database
+ */
+export type ContentItem = {
+	id: string;
+	/** Reference to the content type */
+	contentTypeId: string;
+	/** URL-friendly slug - unique within content type */
+	slug: string;
+	/** JSON data matching the content type's schema (stringified) */
+	data: string;
+	/** Optional author ID for tracking who created/modified */
+	authorId?: string;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+/**
+ * Content item with its content type joined
+ */
+export type ContentItemWithType = ContentItem & {
+	contentType?: ContentType;
+};
+
+/**
+ * Serialized content type for API responses (dates as strings)
+ */
+export interface SerializedContentType
+	extends Omit<ContentType, "createdAt" | "updatedAt"> {
+	createdAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Serialized content item for API responses (dates as strings)
+ */
+export interface SerializedContentItem
+	extends Omit<ContentItem, "createdAt" | "updatedAt"> {
+	createdAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Serialized content item with parsed data and joined content type
+ * @template TData - The type of the parsed data (defaults to Record<string, unknown>)
+ */
+export interface SerializedContentItemWithType<TData = Record<string, unknown>>
+	extends SerializedContentItem {
+	/** Parsed data object (JSON.parse of data field) */
+	parsedData: TData;
+	/** Joined content type */
+	contentType?: SerializedContentType;
+}
+
+/**
+ * Paginated list response for content items
+ * @template TData - The type of the parsed data (defaults to Record<string, unknown>)
+ */
+export interface PaginatedContentItems<TData = Record<string, unknown>> {
+	items: SerializedContentItemWithType<TData>[];
+	total: number;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Type helper to define a map of content type slugs to their data types.
+ * Use with z.infer to get the type from your Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod"
+ *
+ * // Define your schemas
+ * export const ProductSchema = z.object({
+ *   name: z.string(),
+ *   price: z.number(),
+ * })
+ *
+ * export const TestimonialSchema = z.object({
+ *   author: z.string(),
+ *   quote: z.string(),
+ * })
+ *
+ * // Create the type map
+ * export type MyCMSTypes = {
+ *   product: z.infer<typeof ProductSchema>
+ *   testimonial: z.infer<typeof TestimonialSchema>
+ * }
+ *
+ * // Use in hooks for type-safe parsedData
+ * const { items } = useContent<MyCMSTypes, "product">("product")
+ * // items[0].parsedData.name is typed as string
+ * // items[0].parsedData.price is typed as number
+ * ```
+ */
+export type CMSContentTypeMap = Record<string, Record<string, unknown>>;
+
+/**
+ * Context passed to CMS backend hooks
+ */
+export interface CMSHookContext {
+	/** Content type slug */
+	typeSlug: string;
+	/** User ID if authenticated */
+	userId?: string;
+	/** Request headers */
+	headers?: Headers;
+}
+
+/**
+ * Hooks for customizing CMS backend behavior
+ */
+export interface CMSBackendHooks {
+	/** Called before creating a content item */
+	onBeforeCreate?: (
+		data: Record<string, unknown>,
+		context: CMSHookContext,
+	) =>
+		| Promise<Record<string, unknown> | false>
+		| Record<string, unknown>
+		| false;
+
+	/** Called after creating a content item */
+	onAfterCreate?: (
+		item: SerializedContentItem,
+		context: CMSHookContext,
+	) => Promise<void> | void;
+
+	/** Called before updating a content item */
+	onBeforeUpdate?: (
+		id: string,
+		data: Record<string, unknown>,
+		context: CMSHookContext,
+	) =>
+		| Promise<Record<string, unknown> | false>
+		| Record<string, unknown>
+		| false;
+
+	/** Called after updating a content item */
+	onAfterUpdate?: (
+		item: SerializedContentItem,
+		context: CMSHookContext,
+	) => Promise<void> | void;
+
+	/** Called before deleting a content item */
+	onBeforeDelete?: (
+		id: string,
+		context: CMSHookContext,
+	) => Promise<boolean> | boolean;
+
+	/** Called after deleting a content item */
+	onAfterDelete?: (id: string, context: CMSHookContext) => Promise<void> | void;
+
+	/** Called on any CMS error */
+	onError?: (
+		error: Error,
+		operation: "create" | "update" | "delete" | "list" | "get",
+		context: CMSHookContext,
+	) => Promise<void> | void;
+}
+
+/**
+ * Configuration for the CMS backend plugin
+ */
+export interface CMSBackendConfig {
+	/** Content types defined by the developer */
+	contentTypes: ContentTypeConfig[];
+	/** Optional hooks for customizing behavior */
+	hooks?: CMSBackendHooks;
+}

package/src/plugins/cms/utils.ts

@@ -0,0 +1,11 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import slug from "slug";
+
+export function slugify(text: string, locale: string = "en"): string {
+	return slug(text, { lower: true, locale });
+}
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/src/plugins/blog/client/components/shared/page-layout.tsx

@@ -1,23 +0,0 @@
-import { cn } from "../../../utils";
-
-export function PageLayout({
-	children,
-	className,
-	"data-testid": dataTestId,
-}: {
-	children: React.ReactNode;
-	className?: string;
-	"data-testid"?: string;
-}) {
-	return (
-		<div
-			className={cn(
-				"container mx-auto flex min-h-dvh flex-col items-center gap-12 px-4 py-18 lg:px-16",
-				className,
-			)}
-			data-testid={dataTestId}
-		>
-			{children}
-		</div>
-	);
-}

package/src/plugins/blog/client/components/shared/use-route-lifecycle.tsx

@@ -1,68 +0,0 @@
-"use client";
-
-import { useEffect } from "react";
-import { usePluginOverrides } from "@btst/stack/context";
-import type { BlogPluginOverrides, RouteContext } from "../../overrides";
-
-/**
- * Hook to handle route lifecycle events
- * - Calls authorization check before render
- * - Calls onRouteRender on mount
- * - Handles errors with onRouteError
- */
-export function useRouteLifecycle({
-	routeName,
-	context,
-	beforeRenderHook,
-}: {
-	routeName: string;
-	context: RouteContext;
-	beforeRenderHook?: (
-		overrides: BlogPluginOverrides,
-		context: RouteContext,
-	) => boolean;
-}) {
-	const overrides = usePluginOverrides<BlogPluginOverrides>("blog");
-
-	// Authorization check - runs synchronously before render
-	if (beforeRenderHook) {
-		const canRender = beforeRenderHook(overrides, context);
-		if (!canRender) {
-			const error = new Error(`Unauthorized: Cannot render ${routeName}`);
-			// Call error hook synchronously
-			if (overrides.onRouteError) {
-				try {
-					const result = overrides.onRouteError(routeName, error, context);
-					if (result instanceof Promise) {
-						result.catch(() => {}); // Ignore promise rejection
-					}
-				} catch {
-					// Ignore errors in error hook
-				}
-			}
-			throw error;
-		}
-	}
-
-	// Lifecycle hook - runs on mount
-	useEffect(() => {
-		if (overrides.onRouteRender) {
-			try {
-				const result = overrides.onRouteRender(routeName, context);
-				if (result instanceof Promise) {
-					result.catch((error) => {
-						// If onRouteRender throws, call onRouteError
-						if (overrides.onRouteError) {
-							overrides.onRouteError(routeName, error, context);
-						}
-					});
-				}
-			} catch (error) {
-				// If onRouteRender throws, call onRouteError
-				if (overrides.onRouteError) {
-					overrides.onRouteError(routeName, error as Error, context);
-				}
-			}
-		}
-	}, [routeName, overrides, context]);
-}

package/dist/shared/{stack.CcI4sYJP.d.cts → stack.DLhzx1-D.d.cts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CcI4sYJP.d.mts → stack.DLhzx1-D.d.mts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;

package/dist/shared/{stack.CcI4sYJP.d.ts → stack.DLhzx1-D.d.ts}

@@ -35,10 +35,10 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    title: z.ZodString;
     content: z.ZodString;
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;