@btst/stack 2.2.0 → 2.4.0

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,16 @@
 export {
 	kanbanBackendPlugin,
 	type KanbanApiRouter,
+	type KanbanRouteKey,
 	type KanbanApiContext,
 	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" },
+	});
+}