@btst/stack 2.0.1 → 2.2.0

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

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { kanbanSchema as dbSchema } from "../db";
 import type {
 	Board,
-	BoardWithKanbanColumn,
+	BoardWithColumns,
 	Column,
 	ColumnWithTasks,
 	Task,
@@ -23,6 +23,7 @@ import {
 	updateColumnSchema,
 	updateTaskSchema,
 } from "../schemas";
+import { getAllBoards, getBoardById } from "./getters";
 
 /**
  * Context passed to kanban API hooks
@@ -84,10 +85,12 @@ export interface KanbanBackendHooks {
 	) => Promise<boolean> | boolean;
 
 	/**
-	 * Called after boards are listed successfully
+	 * Called after boards are listed successfully.
+	 * Receives the items array (same shape as `board[]`) for consistency
+	 * with analogous hooks in other plugins (e.g. `onPostsRead`).
 	 */
 	onBoardsRead?: (
-		boards: Board[],
+		boards: BoardWithColumns[],
 		filter: z.infer<typeof BoardListQuerySchema>,
 		context: KanbanApiContext,
 	) => Promise<void> | void;
@@ -261,6 +264,12 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 
 		dbPlugin: dbSchema,
 
+		api: (adapter) => ({
+			getAllBoards: (params?: Parameters<typeof getAllBoards>[1]) =>
+				getAllBoards(adapter, params),
+			getBoardById: (id: string) => getBoardById(adapter, id),
+		}),
+
 		routes: (adapter: Adapter) => {
 			// ============ Board Endpoints ============
 
@@ -284,100 +293,10 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 							}
 						}
 
-						const whereConditions = [];
-
-						if (query.slug) {
-							whereConditions.push({
-								field: "slug",
-								value: query.slug,
-								operator: "eq" as const,
-							});
-						}
-
-						if (query.ownerId) {
-							whereConditions.push({
-								field: "ownerId",
-								value: query.ownerId,
-								operator: "eq" as const,
-							});
-						}
-
-						if (query.organizationId) {
-							whereConditions.push({
-								field: "organizationId",
-								value: query.organizationId,
-								operator: "eq" as const,
-							});
-						}
-
-						const boards = await adapter.findMany<BoardWithKanbanColumn>({
-							model: "kanbanBoard",
-							limit: query.limit ?? 50,
-							offset: query.offset ?? 0,
-							where: whereConditions,
-							sortBy: {
-								field: "createdAt",
-								direction: "desc",
-							},
-							join: {
-								kanbanColumn: true,
-							},
-						});
-
-						// Get all column IDs to fetch tasks
-						// Note: adapter returns joined data under schema key name ("column"), not model name
-						const columnIds: string[] = [];
-						for (const board of boards) {
-							if (board.column) {
-								for (const col of board.column) {
-									columnIds.push(col.id);
-								}
-							}
-						}
-
-						// Fetch tasks for each column in parallel (avoids loading all tasks from DB)
-						const tasksByColumn = new Map<string, Task[]>();
-						if (columnIds.length > 0) {
-							const taskQueries = columnIds.map((columnId) =>
-								adapter.findMany<Task>({
-									model: "kanbanTask",
-									where: [
-										{
-											field: "columnId",
-											value: columnId,
-											operator: "eq" as const,
-										},
-									],
-									sortBy: { field: "order", direction: "asc" },
-								}),
-							);
-							const taskResults = await Promise.all(taskQueries);
-							for (let i = 0; i < columnIds.length; i++) {
-								const columnId = columnIds[i];
-								const tasks = taskResults[i];
-								if (columnId && tasks) {
-									tasksByColumn.set(columnId, tasks);
-								}
-							}
-						}
-
-						// Map boards with columns and tasks
-						const result = boards.map((board) => {
-							const columns = (board.column || [])
-								.sort((a, b) => a.order - b.order)
-								.map((col) => ({
-									...col,
-									tasks: tasksByColumn.get(col.id) || [],
-								}));
-							const { column: _, ...boardWithoutJoin } = board;
-							return {
-								...boardWithoutJoin,
-								columns,
-							};
-						});
+						const result = await getAllBoards(adapter, query);
 
 						if (hooks?.onBoardsRead) {
-							await hooks.onBoardsRead(result, query, context);
+							await hooks.onBoardsRead(result.items, query, context);
 						}
 
 						return result;
@@ -409,61 +328,12 @@ export const kanbanBackendPlugin = (hooks?: KanbanBackendHooks) =>
 							}
 						}
 
-						const board = await adapter.findOne<BoardWithKanbanColumn>({
-							model: "kanbanBoard",
-							where: [
-								{ field: "id", value: params.id, operator: "eq" as const },
-							],
-							join: {
-								kanbanColumn: true,
-							},
-						});
+						const result = await getBoardById(adapter, params.id);
 
-						if (!board) {
+						if (!result) {
 							throw ctx.error(404, { message: "Board not found" });
 						}
 
-						// Fetch tasks for each column in parallel (avoids loading all tasks from DB)
-						// Note: adapter returns joined data under schema key name ("column"), not model name
-						const columnIds = (board.column || []).map((c) => c.id);
-						const tasksByColumn = new Map<string, Task[]>();
-						if (columnIds.length > 0) {
-							const taskQueries = columnIds.map((columnId) =>
-								adapter.findMany<Task>({
-									model: "kanbanTask",
-									where: [
-										{
-											field: "columnId",
-											value: columnId,
-											operator: "eq" as const,
-										},
-									],
-									sortBy: { field: "order", direction: "asc" },
-								}),
-							);
-							const taskResults = await Promise.all(taskQueries);
-							for (let i = 0; i < columnIds.length; i++) {
-								const columnId = columnIds[i];
-								const tasks = taskResults[i];
-								if (columnId && tasks) {
-									tasksByColumn.set(columnId, tasks);
-								}
-							}
-						}
-
-						const columns = (board.column || [])
-							.sort((a, b) => a.order - b.order)
-							.map((col) => ({
-								...col,
-								tasks: tasksByColumn.get(col.id) || [],
-							}));
-
-						const { column: _, ...boardWithoutJoin } = board;
-						const result = {
-							...boardWithoutJoin,
-							columns,
-						};
-
 						if (hooks?.onBoardRead) {
 							await hooks.onBoardRead(result, context);
 						}

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

@@ -437,7 +437,8 @@ export const kanbanClientPlugin = (config: KanbanClientConfig) =>
 					method: "GET",
 					query: { limit: 100 },
 				});
-				boards = ((res as { data?: unknown }).data ??
+				// /boards returns BoardListResult { items, total, limit, offset }
+				boards = ((res.data as any)?.items ??
 					[]) as SerializedBoardWithColumns[];
 			} catch {
 				// Ignore errors for sitemap

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

@@ -91,8 +91,10 @@ function createBoardsQueries(
 						throw toError(errorResponse.error);
 					}
 
-					return ((response as { data?: unknown }).data ??
-						[]) as unknown as SerializedBoardWithColumns[];
+					const envelope = (response as { data?: unknown }).data as
+						| { items?: SerializedBoardWithColumns[] }
+						| undefined;
+					return envelope?.items ?? ([] as SerializedBoardWithColumns[]);
 				} catch (error) {
 					throw error;
 				}
@@ -142,9 +144,10 @@ function createBoardsQueries(
 						throw toError(errorResponse.error);
 					}
 
-					const boards = ((response as { data?: unknown }).data ??
-						[]) as unknown as SerializedBoardWithColumns[];
-					return boards[0] ?? null;
+					const envelope = (response as { data?: unknown }).data as
+						| { items?: SerializedBoardWithColumns[] }
+						| undefined;
+					return envelope?.items?.[0] ?? null;
 				} catch (error) {
 					throw error;
 				}

package/src/types.ts

@@ -8,7 +8,7 @@ import type { Endpoint, Router } from "better-call";
  */
 export interface StackContext {
 	/** All registered backend plugins */
-	plugins: Record<string, BackendPlugin<any>>;
+	plugins: Record<string, BackendPlugin<any, any>>;
 	/** The API base path (e.g., "/api/data") */
 	basePath: string;
 	/** The database adapter */
@@ -40,9 +40,13 @@ export interface ClientStackContext<
  * You can optionally provide a base schema via the dbSchema config option.
  *
  * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and endpoint types)
+ * @template TApi - The shape of the server-side API surface exposed via `stack().api`.
+ *   Defaults to `never` so that plugins without an `api` factory are excluded from the
+ *   `stack().api` namespace entirely, preventing accidental access of `undefined` at runtime.
  */
 export interface BackendPlugin<
 	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
+	TApi extends Record<string, (...args: any[]) => any> = never,
 > {
 	name: string;
 
@@ -56,6 +60,15 @@ export interface BackendPlugin<
 	 */
 	routes: (adapter: Adapter, context?: StackContext) => TRoutes;
 	dbPlugin: DbPlugin;
+
+	/**
+	 * Optional factory that returns server-side getter functions bound to the adapter.
+	 * The returned object is merged into `stack().api.<pluginName>.*` for direct
+	 * server-side or SSG data access without going through HTTP.
+	 *
+	 * @param adapter - The adapter instance shared with `routes`
+	 */
+	api?: (adapter: Adapter) => TApi;
 }
 
 /**
@@ -87,13 +100,30 @@ export interface ClientPlugin<
 	sitemap?: () => Promise<Sitemap> | Sitemap;
 }
 
+/**
+ * Utility type that maps each plugin key to the return type of its `api` factory.
+ * Plugin keys whose `TApi` resolves to `never` (i.e. plugins with no `api` factory)
+ * are excluded from the resulting type via key remapping, preventing TypeScript from
+ * suggesting callable functions on what is actually `undefined` at runtime.
+ */
+export type PluginApis<
+	TPlugins extends Record<string, BackendPlugin<any, any>>,
+> = {
+	[K in keyof TPlugins as _ApiOf<TPlugins[K]> extends never
+		? never
+		: K]: _ApiOf<TPlugins[K]>;
+};
+
+/** @internal Extract the TApi parameter from a BackendPlugin type. */
+type _ApiOf<T> = T extends BackendPlugin<any, infer TApi> ? TApi : never;
+
 /**
  * Configuration for creating the backend library
  */
 export interface BackendLibConfig<
-	TPlugins extends Record<string, BackendPlugin<any>> = Record<
+	TPlugins extends Record<string, BackendPlugin<any, any>> = Record<
 		string,
-		BackendPlugin<any>
+		BackendPlugin<any, any>
 	>,
 > {
 	basePath: string;
@@ -150,11 +180,12 @@ export type PluginRoutes<
  * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
  */
 export type PrefixedPluginRoutes<
-	TPlugins extends Record<string, BackendPlugin<any>>,
+	TPlugins extends Record<string, BackendPlugin<any, any>>,
 > = UnionToIntersection<
 	{
 		[PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<
-			infer TRoutes
+			infer TRoutes,
+			any
 		>
 			? {
 					[RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
@@ -172,10 +203,18 @@ export type PrefixedPluginRoutes<
  */
 export interface BackendLib<
 	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
+	TApis extends Record<
+		string,
+		Record<string, (...args: any[]) => any>
+	> = Record<string, Record<string, (...args: any[]) => any>>,
 > {
 	handler: (request: Request) => Promise<Response>; // API route handler
 	router: Router; // Better-call router
 	dbSchema: DatabaseDefinition; // Better-db schema
+	/** The database adapter shared across all plugins */
+	adapter: Adapter;
+	/** Fully-typed server-side getter functions, namespaced per plugin */
+	api: TApis;
 }
 
 /**