@btst/stack 2.2.0 → 2.3.0

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

@@ -5,6 +5,7 @@ import {
 import type { BlogApiRouter } from "./api";
 import { createApiClient } from "@btst/stack/plugins/client";
 import type { SerializedPost, SerializedTag } from "./types";
+import { postsListDiscriminator } from "./api/query-key-defs";
 
 interface PostsListParams {
 	query?: string;
@@ -71,15 +72,12 @@ function createPostsQueries(
 	return createQueryKeys("posts", {
 		list: (params?: PostsListParams) => ({
 			queryKey: [
-				{
-					query:
-						params?.query !== undefined && params?.query?.trim() === ""
-							? undefined
-							: params?.query,
-					limit: params?.limit ?? 10,
+				postsListDiscriminator({
 					published: params?.published ?? true,
+					limit: params?.limit ?? 10,
 					tagSlug: params?.tagSlug,
-				},
+					query: params?.query,
+				}),
 			],
 			queryFn: async ({ pageParam }: { pageParam?: number }) => {
 				try {

package/src/plugins/client/index.ts

@@ -18,7 +18,7 @@ export type {
 	PluginOverrides,
 } from "../../types";
 
-export { createApiClient } from "../utils";
+export { createApiClient, isConnectionError } from "../utils";
 
 // Re-export Yar types needed for plugins
 export type { Route } from "@btst/yar";

package/src/plugins/cms/api/getters.ts

@@ -191,6 +191,30 @@ export async function getAllContentItems(
 	};
 }
 
+/**
+ * Retrieve a single content item by its ID.
+ * Returns null if the item is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param id - The content item ID (UUID)
+ */
+export async function getContentItemById(
+	adapter: Adapter,
+	id: string,
+): Promise<SerializedContentItemWithType | null> {
+	const item = await adapter.findOne<ContentItemWithType>({
+		model: "contentItem",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+		join: { contentType: true },
+	});
+	if (!item) return null;
+	return serializeContentItemWithType(item);
+}
+
 /**
  * Retrieve a single content item by its slug within a content type.
  * Returns null if the content type or item is not found.

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

@@ -1,6 +1,15 @@
-export { cmsBackendPlugin, type CMSApiRouter } from "./plugin";
+export {
+	cmsBackendPlugin,
+	type CMSApiRouter,
+	type CMSRouteKey,
+} from "./plugin";
 export {
 	getAllContentTypes,
 	getAllContentItems,
 	getContentItemBySlug,
+	getContentItemById,
+	serializeContentType,
+	serializeContentItem,
+	serializeContentItemWithType,
 } from "./getters";
+export { CMS_QUERY_KEYS } from "./query-key-defs";

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

@@ -25,10 +25,37 @@ import {
 	getAllContentTypes,
 	getAllContentItems,
 	getContentItemBySlug,
+	getContentItemById,
 	serializeContentType,
 	serializeContentItem,
 	serializeContentItemWithType,
 } from "./getters";
+import type { QueryClient } from "@tanstack/react-query";
+import { CMS_QUERY_KEYS } from "./query-key-defs";
+
+/**
+ * Route keys for the CMS plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type CMSRouteKey =
+	| "dashboard"
+	| "contentList"
+	| "newContent"
+	| "editContent";
+
+interface CMSPrefetchForRoute {
+	(key: "dashboard" | "newContent", qc: QueryClient): Promise<void>;
+	(
+		key: "contentList",
+		qc: QueryClient,
+		params: { typeSlug: string },
+	): Promise<void>;
+	(
+		key: "editContent",
+		qc: QueryClient,
+		params: { typeSlug: string; id: string },
+	): Promise<void>;
+}
 
 /**
  * Sync content types from config to database
@@ -443,6 +470,79 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 		return syncPromise;
 	};
 
+	const getContentTypesWithCounts = async (adapter: Adapter) => {
+		const contentTypes = await getAllContentTypes(adapter);
+		return Promise.all(
+			contentTypes.map(async (ct) => {
+				const count: number = await adapter.count({
+					model: "contentItem",
+					where: [
+						{ field: "contentTypeId", value: ct.id, operator: "eq" as const },
+					],
+				});
+				return { ...ct, itemCount: count };
+			}),
+		);
+	};
+
+	const createCMSPrefetchForRoute = (adapter: Adapter): CMSPrefetchForRoute => {
+		return async function prefetchForRoute(
+			key: CMSRouteKey,
+			qc: QueryClient,
+			params?: Record<string, string>,
+		): Promise<void> {
+			// Sync content types once at the top — idempotent for concurrent SSG calls
+			await ensureSynced(adapter);
+
+			switch (key) {
+				case "dashboard":
+				case "newContent": {
+					const typesWithCounts = await getContentTypesWithCounts(adapter);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), typesWithCounts);
+					break;
+				}
+				case "contentList": {
+					const typeSlug = params?.typeSlug ?? "";
+					const [contentTypes, contentItems] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						getAllContentItems(adapter, typeSlug, { limit: 20, offset: 0 }),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					qc.setQueryData(
+						CMS_QUERY_KEYS.contentList({ typeSlug, limit: 20, offset: 0 }),
+						{
+							pages: [
+								{
+									items: contentItems.items,
+									total: contentItems.total,
+									limit: contentItems.limit ?? 20,
+									offset: contentItems.offset ?? 0,
+								},
+							],
+							pageParams: [0],
+						},
+					);
+					break;
+				}
+				case "editContent": {
+					const typeSlug = params?.typeSlug ?? "";
+					const id = params?.id ?? "";
+					const [contentTypes, item] = await Promise.all([
+						getContentTypesWithCounts(adapter),
+						id ? getContentItemById(adapter, id) : Promise.resolve(null),
+					]);
+					qc.setQueryData(CMS_QUERY_KEYS.typesList(), contentTypes);
+					if (id) {
+						qc.setQueryData(CMS_QUERY_KEYS.contentDetail(typeSlug, id), item);
+					}
+					break;
+				}
+				default:
+					break;
+			}
+		} as CMSPrefetchForRoute;
+	};
+
 	return defineBackendPlugin({
 		name: "cms",
 
@@ -464,6 +564,11 @@ export const cmsBackendPlugin = (config: CMSBackendConfig) => {
 				await ensureSynced(adapter);
 				return getContentItemBySlug(adapter, contentTypeSlug, slug);
 			},
+			getContentItemById: async (id: string) => {
+				await ensureSynced(adapter);
+				return getContentItemById(adapter, id);
+			},
+			prefetchForRoute: createCMSPrefetchForRoute(adapter),
 		}),
 
 		routes: (adapter: Adapter) => {

package/src/plugins/cms/api/query-key-defs.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal query key constants for the CMS plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface ContentListDiscriminator {
+	typeSlug: string;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object used as the cache key for the content list.
+ * Mirrors the params object used in createContentQueries.list so both paths stay in sync.
+ */
+export function contentListDiscriminator(params: {
+	typeSlug: string;
+	limit?: number;
+	offset?: number;
+}): ContentListDiscriminator {
+	return {
+		typeSlug: params.typeSlug,
+		limit: params.limit ?? 20,
+		offset: params.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const CMS_QUERY_KEYS = {
+	/**
+	 * Key for the cmsTypes.list() query.
+	 * Full key: ["cmsTypes", "list", "list"]
+	 */
+	typesList: () => ["cmsTypes", "list", "list"] as const,
+
+	/**
+	 * Key for the cmsContent.list({ typeSlug, limit, offset }) query.
+	 * Full key: ["cmsContent", "list", { typeSlug, limit, offset }]
+	 */
+	contentList: (params: {
+		typeSlug: string;
+		limit?: number;
+		offset?: number;
+	}) => ["cmsContent", "list", contentListDiscriminator(params)] as const,
+
+	/**
+	 * Key for the cmsContent.detail(typeSlug, id) query.
+	 * Full key: ["cmsContent", "detail", typeSlug, id]
+	 */
+	contentDetail: (typeSlug: string, id: string) =>
+		["cmsContent", "detail", typeSlug, id] as const,
+};

package/src/plugins/cms/api/serializers.ts

@@ -0,0 +1,12 @@
+/**
+ * Re-exports serialization helpers from getters.ts for consumers who import
+ * from @btst/stack/plugins/cms/api.
+ *
+ * The actual implementations live in getters.ts alongside the DB functions
+ * they serialize so they stay in sync with the returned types.
+ */
+export {
+	serializeContentType,
+	serializeContentItem,
+	serializeContentItemWithType,
+} from "./getters";

package/src/plugins/cms/client/plugin.tsx

@@ -2,6 +2,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -181,6 +182,12 @@ function createDashboardLoader(config: CMSClientConfig) {
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -275,6 +282,12 @@ function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -357,6 +370,12 @@ function createContentEditorLoader(
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				// Let Error Boundaries handle errors when components render
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/cms] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

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

@@ -9,6 +9,7 @@ import type {
 	SerializedContentItemWithType,
 	PaginatedContentItems,
 } from "./types";
+import { contentListDiscriminator } from "./api/query-key-defs";
 
 interface ContentListParams {
 	limit?: number;
@@ -115,7 +116,7 @@ function createContentQueries(
 ) {
 	return createQueryKeys("cmsContent", {
 		list: (params: { typeSlug: string } & ContentListParams) => ({
-			queryKey: [params],
+			queryKey: [contentListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/content/:typeSlug", {

package/src/plugins/form-builder/api/getters.ts

@@ -116,6 +116,29 @@ export async function getAllForms(
 	};
 }
 
+/**
+ * Retrieve a single form by its ID (UUID).
+ * Returns null if the form is not found.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks are NOT called. The caller is
+ * responsible for any access-control checks before invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param id - The form UUID
+ */
+export async function getFormById(
+	adapter: Adapter,
+	id: string,
+): Promise<SerializedForm | null> {
+	const form = await adapter.findOne<Form>({
+		model: "form",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+	});
+	if (!form) return null;
+	return serializeForm(form);
+}
+
 /**
  * Retrieve a single form by its slug.
  * Returns null if the form is not found.

package/src/plugins/form-builder/api/index.ts

@@ -1,2 +1,15 @@
-export { formBuilderBackendPlugin, type FormBuilderApiRouter } from "./plugin";
-export { getAllForms, getFormBySlug, getFormSubmissions } from "./getters";
+export {
+	formBuilderBackendPlugin,
+	type FormBuilderApiRouter,
+	type FormBuilderRouteKey,
+} from "./plugin";
+export {
+	getAllForms,
+	getFormById,
+	getFormBySlug,
+	getFormSubmissions,
+	serializeForm,
+	serializeFormSubmission,
+	serializeFormSubmissionWithData,
+} from "./getters";
+export { FORM_QUERY_KEYS } from "./query-key-defs";

package/src/plugins/form-builder/api/plugin.ts

@@ -23,12 +23,101 @@ import {
 import { slugify, extractIpAddress, extractUserAgent } from "../utils";
 import {
 	getAllForms,
+	getFormById as getFormByIdFromDb,
 	getFormBySlug as getFormBySlugFromDb,
 	getFormSubmissions,
 	serializeForm,
 	serializeFormSubmission,
 	serializeFormSubmissionWithData,
 } from "./getters";
+import { FORM_QUERY_KEYS } from "./query-key-defs";
+import type { QueryClient } from "@tanstack/react-query";
+
+/**
+ * Route keys for the Form Builder plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+export type FormBuilderRouteKey =
+	| "formList"
+	| "newForm"
+	| "editForm"
+	| "submissions";
+
+interface FormBuilderPrefetchForRoute {
+	(key: "formList" | "newForm", qc: QueryClient): Promise<void>;
+	(
+		key: "editForm" | "submissions",
+		qc: QueryClient,
+		params: { id: string },
+	): Promise<void>;
+}
+
+function createFormBuilderPrefetchForRoute(
+	adapter: Parameters<typeof getAllForms>[0],
+): FormBuilderPrefetchForRoute {
+	return async function prefetchForRoute(
+		key: FormBuilderRouteKey,
+		qc: QueryClient,
+		params?: Record<string, string>,
+	): Promise<void> {
+		switch (key) {
+			case "formList": {
+				const result = await getAllForms(adapter, { limit: 20, offset: 0 });
+				qc.setQueryData(FORM_QUERY_KEYS.formsList({ limit: 20, offset: 0 }), {
+					pages: [
+						{
+							items: result.items,
+							total: result.total,
+							limit: result.limit ?? 20,
+							offset: result.offset ?? 0,
+						},
+					],
+					pageParams: [0],
+				});
+				break;
+			}
+			case "editForm": {
+				const id = params?.id ?? "";
+				if (id) {
+					const form = await getFormByIdFromDb(adapter, id);
+					qc.setQueryData(FORM_QUERY_KEYS.formById(id), form);
+				}
+				break;
+			}
+			case "submissions": {
+				const id = params?.id ?? "";
+				if (id) {
+					const [form, submissionsResult] = await Promise.all([
+						getFormByIdFromDb(adapter, id),
+						getFormSubmissions(adapter, id, { limit: 20, offset: 0 }),
+					]);
+					qc.setQueryData(FORM_QUERY_KEYS.formById(id), form);
+					qc.setQueryData(
+						FORM_QUERY_KEYS.submissionsList({
+							formId: id,
+							limit: 20,
+							offset: 0,
+						}),
+						{
+							pages: [
+								{
+									items: submissionsResult.items,
+									total: submissionsResult.total,
+									limit: submissionsResult.limit ?? 20,
+									offset: submissionsResult.offset ?? 0,
+								},
+							],
+							pageParams: [0],
+						},
+					);
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	} as FormBuilderPrefetchForRoute;
+}
 
 /**
  * Form Builder backend plugin
@@ -47,11 +136,13 @@ export const formBuilderBackendPlugin = (
 		api: (adapter) => ({
 			getAllForms: (params?: Parameters<typeof getAllForms>[1]) =>
 				getAllForms(adapter, params),
+			getFormById: (id: string) => getFormByIdFromDb(adapter, id),
 			getFormBySlug: (slug: string) => getFormBySlugFromDb(adapter, slug),
 			getFormSubmissions: (
 				formId: string,
 				params?: Parameters<typeof getFormSubmissions>[2],
 			) => getFormSubmissions(adapter, formId, params),
+			prefetchForRoute: createFormBuilderPrefetchForRoute(adapter),
 		}),
 
 		routes: (adapter: Adapter) => {

package/src/plugins/form-builder/api/query-key-defs.ts

@@ -0,0 +1,79 @@
+/**
+ * Internal query key constants for the Form Builder plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+
+export interface FormsListDiscriminator {
+	status?: "active" | "inactive" | "archived";
+	limit: number;
+	offset: number;
+}
+
+export interface SubmissionsListDiscriminator {
+	formId: string;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object for the forms list query key.
+ * Mirrors the params object used in createFormsQueries.list.
+ */
+export function formsListDiscriminator(params?: {
+	status?: "active" | "inactive" | "archived";
+	limit?: number;
+	offset?: number;
+}): FormsListDiscriminator {
+	return {
+		status: params?.status,
+		limit: params?.limit ?? 20,
+		offset: params?.offset ?? 0,
+	};
+}
+
+/**
+ * Builds the discriminator object for the submissions list query key.
+ * Mirrors the params object used in createSubmissionsQueries.list.
+ */
+export function submissionsListDiscriminator(params: {
+	formId: string;
+	limit?: number;
+	offset?: number;
+}): SubmissionsListDiscriminator {
+	return {
+		formId: params.formId,
+		limit: params.limit ?? 20,
+		offset: params.offset ?? 0,
+	};
+}
+
+/** Full query key builders — use these with queryClient.setQueryData() */
+export const FORM_QUERY_KEYS = {
+	/**
+	 * Key for forms.list(params) query.
+	 * Full key: ["forms", "list", "list", { status, limit, offset }]
+	 */
+	formsList: (params?: {
+		status?: "active" | "inactive" | "archived";
+		limit?: number;
+		offset?: number;
+	}) => ["forms", "list", "list", formsListDiscriminator(params)] as const,
+
+	/**
+	 * Key for forms.byId(id) query.
+	 * Full key: ["forms", "byId", "byId", id]
+	 */
+	formById: (id: string) => ["forms", "byId", "byId", id] as const,
+
+	/**
+	 * Key for formSubmissions.list(params) query.
+	 * Full key: ["formSubmissions", "list", { formId, limit, offset }]
+	 */
+	submissionsList: (params: {
+		formId: string;
+		limit?: number;
+		offset?: number;
+	}) =>
+		["formSubmissions", "list", submissionsListDiscriminator(params)] as const,
+};

package/src/plugins/form-builder/api/serializers.ts

@@ -0,0 +1,12 @@
+/**
+ * Re-exports serialization helpers from getters.ts for consumers who import
+ * from @btst/stack/plugins/form-builder/api.
+ *
+ * The actual implementations live in getters.ts alongside the DB functions
+ * they serialize so they stay in sync with the returned types.
+ */
+export {
+	serializeForm,
+	serializeFormSubmission,
+	serializeFormSubmissionWithData,
+} from "./getters";

package/src/plugins/form-builder/client/plugin.tsx

@@ -3,6 +3,7 @@ import { lazy } from "react";
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -197,6 +198,12 @@ function createFormListLoader(config: FormBuilderClientConfig) {
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -265,6 +272,12 @@ function createFormBuilderLoader(
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -364,6 +377,12 @@ function createSubmissionsLoader(
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/form-builder] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.formBuilder.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}

package/src/plugins/form-builder/query-keys.ts

@@ -10,6 +10,10 @@ import type {
 	PaginatedFormSubmissions,
 	SerializedFormSubmissionWithData,
 } from "./types";
+import {
+	formsListDiscriminator,
+	submissionsListDiscriminator,
+} from "./api/query-key-defs";
 
 interface FormListParams {
 	status?: "active" | "inactive" | "archived";
@@ -75,7 +79,7 @@ function createFormsQueries(
 ) {
 	return createQueryKeys("forms", {
 		list: (params: FormListParams = {}) => ({
-			queryKey: ["list", params],
+			queryKey: ["list", formsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/forms", {
@@ -147,7 +151,7 @@ function createSubmissionsQueries(
 ) {
 	return createQueryKeys("formSubmissions", {
 		list: (params: SubmissionListParams) => ({
-			queryKey: [params],
+			queryKey: [submissionsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response: unknown = await client("/forms/:formId/submissions", {

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

@@ -1,7 +1,10 @@
 export {
 	kanbanBackendPlugin,
 	type KanbanApiRouter,
+	type KanbanRouteKey,
 	type KanbanApiContext,
 	type KanbanBackendHooks,
 } from "./plugin";
 export { getAllBoards, getBoardById, type BoardListResult } from "./getters";
+export { serializeBoard, serializeColumn, serializeTask } from "./serializers";
+export { KANBAN_QUERY_KEYS } from "./query-key-defs";