@btst/stack 2.1.0 → 2.2.0

package/src/__tests__/stack-api.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import { stack } from "../api";
+import { defineBackendPlugin } from "../plugins/api";
+import { createDbPlugin } from "@btst/db";
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import type { Adapter, DatabaseDefinition } from "@btst/db";
+import { blogBackendPlugin } from "../plugins/blog/api";
+import { kanbanBackendPlugin } from "../plugins/kanban/api";
+
+const testAdapter = (db: DatabaseDefinition): Adapter =>
+	createMemoryAdapter(db)({});
+
+/**
+ * A minimal plugin with no `api` factory, to verify backward compatibility.
+ */
+const noApiPlugin = defineBackendPlugin({
+	name: "no-api",
+	dbPlugin: createDbPlugin("no-api", {}),
+	routes: () => ({}),
+});
+
+describe("stack.api surface", () => {
+	it("exposes adapter on the returned backend", () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: { blog: blogBackendPlugin() },
+			adapter: testAdapter,
+		});
+
+		expect(backend.adapter).toBeDefined();
+		expect(typeof backend.adapter.findMany).toBe("function");
+		expect(typeof backend.adapter.findOne).toBe("function");
+		expect(typeof backend.adapter.create).toBe("function");
+	});
+
+	it("exposes typed api namespace for plugins with api factory", () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: { blog: blogBackendPlugin() },
+			adapter: testAdapter,
+		});
+
+		expect(backend.api).toBeDefined();
+		expect(backend.api.blog).toBeDefined();
+		expect(typeof backend.api.blog.getAllPosts).toBe("function");
+		expect(typeof backend.api.blog.getPostBySlug).toBe("function");
+		expect(typeof backend.api.blog.getAllTags).toBe("function");
+	});
+
+	it("exposes kanban api namespace", () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: { kanban: kanbanBackendPlugin() },
+			adapter: testAdapter,
+		});
+
+		expect(backend.api.kanban).toBeDefined();
+		expect(typeof backend.api.kanban.getAllBoards).toBe("function");
+		expect(typeof backend.api.kanban.getBoardById).toBe("function");
+	});
+
+	it("plugins without api factory are not present in api", () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: { noApi: noApiPlugin },
+			adapter: testAdapter,
+		});
+
+		expect((backend.api as any).noApi).toBeUndefined();
+	});
+
+	it("api functions are bound to the shared adapter and return real data", async () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: { blog: blogBackendPlugin() },
+			adapter: testAdapter,
+		});
+
+		// Seed data via adapter directly
+		await backend.adapter.create({
+			model: "post",
+			data: {
+				title: "Hello World",
+				slug: "hello-world",
+				content: "Content",
+				excerpt: "",
+				published: true,
+				tags: [],
+				createdAt: new Date(),
+				updatedAt: new Date(),
+			},
+		});
+
+		// Retrieve via stack.api
+		const posts = await backend.api.blog.getAllPosts();
+		expect(posts.items).toHaveLength(1);
+		expect(posts.items[0]!.slug).toBe("hello-world");
+
+		// Verify same adapter - data is shared
+		const bySlug = await backend.api.blog.getPostBySlug("hello-world");
+		expect(bySlug).not.toBeNull();
+		expect(bySlug!.title).toBe("Hello World");
+	});
+
+	it("combines multiple plugins in a single stack call", () => {
+		const backend = stack({
+			basePath: "/api",
+			plugins: {
+				blog: blogBackendPlugin(),
+				kanban: kanbanBackendPlugin(),
+			},
+			adapter: testAdapter,
+		});
+
+		expect(typeof backend.api.blog.getAllPosts).toBe("function");
+		expect(typeof backend.api.kanban.getAllBoards).toBe("function");
+	});
+});

package/src/api/index.ts

@@ -3,6 +3,7 @@ import type {
 	BackendLibConfig,
 	BackendLib,
 	PrefixedPluginRoutes,
+	PluginApis,
 	StackContext,
 } from "../types";
 import { defineDb } from "@btst/db";
@@ -33,7 +34,9 @@ export function stack<
 	TPlugins extends Record<string, any>,
 	TRoutes extends
 		PrefixedPluginRoutes<TPlugins> = PrefixedPluginRoutes<TPlugins>,
->(config: BackendLibConfig<TPlugins>): BackendLib<TRoutes> {
+>(
+	config: BackendLibConfig<TPlugins>,
+): BackendLib<TRoutes, PluginApis<TPlugins>> {
 	const { plugins, adapter, dbSchema, basePath } = config;
 
 	// Collect all routes from all plugins with type-safe prefixed keys
@@ -67,6 +70,14 @@ export function stack<
 		}
 	}
 
+	// Build the typed api surface by calling each plugin's api factory
+	const pluginApis = {} as PluginApis<TPlugins>;
+	for (const [pluginKey, plugin] of Object.entries(plugins)) {
+		if (plugin.api) {
+			(pluginApis as any)[pluginKey] = plugin.api(adapterInstance);
+		}
+	}
+
 	// Create the composed router
 	const router = createRouter(allRoutes, {
 		basePath: basePath,
@@ -76,6 +87,8 @@ export function stack<
 		handler: router.handler,
 		router,
 		dbSchema: betterDbSchema,
+		adapter: adapterInstance,
+		api: pluginApis,
 	};
 }
 
@@ -83,5 +96,6 @@ export type {
 	BackendPlugin,
 	BackendLibConfig,
 	BackendLib,
+	PluginApis,
 	StackContext,
 } from "../types";

package/src/plugins/ai-chat/__tests__/getters.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { defineDb } from "@btst/db";
+import type { Adapter } from "@btst/db";
+import { aiChatSchema } from "../db";
+import { getAllConversations, getConversationById } from "../api/getters";
+
+const createTestAdapter = (): Adapter => {
+	const db = defineDb({}).use(aiChatSchema);
+	return createMemoryAdapter(db)({});
+};
+
+async function createConversation(
+	adapter: Adapter,
+	title: string,
+	userId?: string,
+): Promise<any> {
+	return adapter.create({
+		model: "conversation",
+		data: {
+			title,
+			...(userId ? { userId } : {}),
+			createdAt: new Date(),
+			updatedAt: new Date(),
+		},
+	});
+}
+
+describe("ai-chat getters", () => {
+	let adapter: Adapter;
+
+	beforeEach(() => {
+		adapter = createTestAdapter();
+	});
+
+	describe("getAllConversations", () => {
+		it("returns empty array when no conversations exist", async () => {
+			const convs = await getAllConversations(adapter);
+			expect(convs).toEqual([]);
+		});
+
+		it("returns all conversations sorted by updatedAt desc", async () => {
+			await createConversation(adapter, "First");
+			await createConversation(adapter, "Second");
+
+			const convs = await getAllConversations(adapter);
+			expect(convs).toHaveLength(2);
+		});
+
+		it("filters conversations by userId", async () => {
+			await createConversation(adapter, "Alice Conv", "user-alice");
+			await createConversation(adapter, "Bob Conv", "user-bob");
+			await createConversation(adapter, "No User Conv");
+
+			const aliceConvs = await getAllConversations(adapter, "user-alice");
+			expect(aliceConvs).toHaveLength(1);
+			expect(aliceConvs[0]!.title).toBe("Alice Conv");
+
+			const allConvs = await getAllConversations(adapter);
+			expect(allConvs).toHaveLength(3);
+		});
+	});
+
+	describe("getConversationById", () => {
+		it("returns null when conversation does not exist", async () => {
+			const conv = await getConversationById(adapter, "nonexistent");
+			expect(conv).toBeNull();
+		});
+
+		it("returns conversation with messages", async () => {
+			const conv = (await createConversation(adapter, "My Chat")) as any;
+
+			await adapter.create({
+				model: "message",
+				data: {
+					conversationId: conv.id,
+					role: "user",
+					content: JSON.stringify([{ type: "text", text: "Hello!" }]),
+					createdAt: new Date(Date.now() - 1000),
+				},
+			});
+			await adapter.create({
+				model: "message",
+				data: {
+					conversationId: conv.id,
+					role: "assistant",
+					content: JSON.stringify([{ type: "text", text: "Hi there!" }]),
+					createdAt: new Date(),
+				},
+			});
+
+			const result = await getConversationById(adapter, conv.id);
+			expect(result).not.toBeNull();
+			expect(result!.id).toBe(conv.id);
+			expect(result!.title).toBe("My Chat");
+			expect(result!.messages).toHaveLength(2);
+			expect(result!.messages[0]!.role).toBe("user");
+			expect(result!.messages[1]!.role).toBe("assistant");
+		});
+
+		it("returns conversation with empty messages array if none exist", async () => {
+			const conv = (await createConversation(adapter, "Empty Chat")) as any;
+
+			const result = await getConversationById(adapter, conv.id);
+			expect(result).not.toBeNull();
+			expect(result!.messages).toEqual([]);
+		});
+	});
+});

package/src/plugins/ai-chat/api/getters.ts

@@ -0,0 +1,71 @@
+import type { Adapter } from "@btst/db";
+import type { Conversation, ConversationWithMessages, Message } from "../types";
+
+/**
+ * Retrieve all conversations, optionally filtered by userId.
+ * Pure DB function - no hooks, no HTTP context. Safe for server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param userId - Optional user ID to filter conversations by owner
+ */
+export async function getAllConversations(
+	adapter: Adapter,
+	userId?: string,
+): Promise<Conversation[]> {
+	const whereConditions: Array<{
+		field: string;
+		value: string;
+		operator: "eq";
+	}> = [];
+
+	if (userId) {
+		whereConditions.push({
+			field: "userId",
+			value: userId,
+			operator: "eq" as const,
+		});
+	}
+
+	return adapter.findMany<Conversation>({
+		model: "conversation",
+		where: whereConditions.length > 0 ? whereConditions : undefined,
+		sortBy: { field: "updatedAt", direction: "desc" },
+	});
+}
+
+/**
+ * Retrieve a single conversation by its ID, including all messages.
+ * Returns null if the conversation is not found.
+ * Pure DB function - no hooks, no HTTP context. Safe for server-side use.
+ *
+ * @param adapter - The database adapter
+ * @param id - The conversation ID
+ */
+export async function getConversationById(
+	adapter: Adapter,
+	id: string,
+): Promise<(Conversation & { messages: Message[] }) | null> {
+	const conversations = await adapter.findMany<ConversationWithMessages>({
+		model: "conversation",
+		where: [{ field: "id", value: id, operator: "eq" as const }],
+		limit: 1,
+		join: {
+			message: true,
+		},
+	});
+
+	if (!conversations.length) {
+		return null;
+	}
+
+	const conversation = conversations[0]!;
+	const messages = (conversation.message || []).sort(
+		(a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
+	);
+
+	const { message: _, ...conversationWithoutJoin } = conversation;
+	return {
+		...conversationWithoutJoin,
+		messages,
+	};
+}

package/src/plugins/ai-chat/api/index.ts

@@ -1,2 +1,3 @@
 export * from "./plugin";
+export { getAllConversations, getConversationById } from "./getters";
 export { createAiChatQueryKeys } from "../query-keys";

package/src/plugins/ai-chat/api/plugin.ts

@@ -16,6 +16,7 @@ import {
 	updateConversationSchema,
 } from "../schemas";
 import type { Conversation, ConversationWithMessages, Message } from "../types";
+import { getAllConversations, getConversationById } from "./getters";
 
 /**
  * Context passed to AI Chat API hooks
@@ -286,6 +287,13 @@ export const aiChatBackendPlugin = (config: AiChatBackendConfig) =>
 		name: "ai-chat",
 		// Always include db schema - in public mode we just don't use it
 		dbPlugin: dbSchema,
+
+		api: (adapter) => ({
+			getAllConversations: (userId?: string) =>
+				getAllConversations(adapter, userId),
+			getConversationById: (id: string) => getConversationById(adapter, id),
+		}),
+
 		routes: (adapter: Adapter) => {
 			const mode = config.mode ?? "authenticated";
 			const isPublicMode = mode === "public";

package/src/plugins/api/index.ts

@@ -42,9 +42,11 @@ export { createDbPlugin } from "@btst/db";
  * ```
  *
  * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
+ * @template TApi - The shape of the server-side api surface (auto-inferred from api factory)
  */
 export function defineBackendPlugin<
 	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
->(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes> {
+	TApi extends Record<string, (...args: any[]) => any> = never,
+>(plugin: BackendPlugin<TRoutes, TApi>): BackendPlugin<TRoutes, TApi> {
 	return plugin;
 }