@btst/stack 2.1.0 → 2.3.0

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

@@ -1,6 +1,7 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	isConnectionError,
 } from "@btst/stack/plugins/client";
 import { createRoute } from "@btst/yar";
 import type { QueryClient } from "@tanstack/react-query";
@@ -178,6 +179,12 @@ function createBoardsLoader(config: KanbanClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/kanban] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -241,6 +248,12 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 					await hooks.onLoadError(error, context);
 				}
 			} catch (error) {
+				if (isConnectionError(error)) {
+					console.warn(
+						"[btst/kanban] route.loader() failed — no server running at build time. " +
+							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+					);
+				}
 				if (hooks?.onLoadError) {
 					await hooks.onLoadError(error as Error, context);
 				}
@@ -437,7 +450,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

@@ -5,6 +5,7 @@ import {
 import type { KanbanApiRouter } from "./api";
 import { createApiClient } from "@btst/stack/plugins/client";
 import type { SerializedBoardWithColumns } from "./types";
+import { boardsListDiscriminator } from "./api/query-key-defs";
 
 interface BoardsListParams {
 	slug?: string;
@@ -63,15 +64,7 @@ function createBoardsQueries(
 ) {
 	return createQueryKeys("boards", {
 		list: (params?: BoardsListParams) => ({
-			queryKey: [
-				{
-					slug: params?.slug,
-					ownerId: params?.ownerId,
-					organizationId: params?.organizationId,
-					limit: params?.limit ?? 50,
-					offset: params?.offset ?? 0,
-				},
-			],
+			queryKey: [boardsListDiscriminator(params)],
 			queryFn: async () => {
 				try {
 					const response = await client("/boards", {
@@ -91,8 +84,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 +137,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/plugins/utils.ts

@@ -1,4 +1,23 @@
 import { createClient } from "better-call/client";
+
+/**
+ * Returns true when a fetch error is a connection-refused / no-server error.
+ * Used in SSR loaders to emit an actionable build-time warning when
+ * `route.loader()` is called during `next build` with no HTTP server running.
+ */
+export function isConnectionError(err: unknown): boolean {
+	if (!(err instanceof Error)) return false;
+	const code =
+		(err as unknown as { cause?: { code?: string } }).cause?.code ??
+		(err as unknown as { code?: string }).code;
+	return (
+		err.message.includes("ECONNREFUSED") ||
+		err.message.includes("fetch failed") ||
+		err.message.includes("ERR_CONNECTION_REFUSED") ||
+		code === "ECONNREFUSED" ||
+		code === "ERR_CONNECTION_REFUSED"
+	);
+}
 import type { Router, Endpoint } from "better-call";
 
 interface CreateApiClientOptions {

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;
 }
 
 /**

package/dist/shared/{stack.CbuN2zVV.d.cts → stack.CBON0dWL.d.cts}

@@ -35,6 +35,13 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -44,13 +51,6 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.CbuN2zVV.d.mts → stack.CBON0dWL.d.mts}

@@ -35,6 +35,13 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -44,13 +51,6 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;

package/dist/shared/{stack.CbuN2zVV.d.ts → stack.CBON0dWL.d.ts}

@@ -35,6 +35,13 @@ interface SerializedTag extends Omit<Tag, "createdAt" | "updatedAt"> {
 }
 
 declare const createPostSchema: z.ZodObject<{
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>]>>>>;
     slug: z.ZodOptional<z.ZodString>;
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
@@ -44,13 +51,6 @@ declare const createPostSchema: z.ZodObject<{
     excerpt: z.ZodString;
     image: z.ZodOptional<z.ZodString>;
     published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        name: z.ZodString;
-    }, z.core.$strip>, z.ZodObject<{
-        id: z.ZodString;
-        name: z.ZodString;
-        slug: z.ZodString;
-    }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 declare const updatePostSchema: z.ZodObject<{
     publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;